Skip to main content
Every public method of NexusClient. A read (getConfig, getSecret, getFlag, findFlag, …) inside the TTL is served from the in-memory snapshot; the first read after the TTL elapses performs one sync first - see Caching behaviour. create, sync, refreshSession, evaluateAb, connectStream and the write methods always reach the network, and so does a targeted boolean evaluation through the OpenFeature provider, which calls evaluateAb for you.

Construction

NexusClient::create(NexusConfig $config, ?ClientInterface $http = null, ?RequestFactoryInterface $requestFactory = null, ?StreamFactoryInterface $streamFactory = null, ?SseTransport $sseTransport = null): self

Creates a client and runs a blocking initial sync. Returns the populated client. Throws on failure.
When WIF is configured, the session exchange runs first. On success the logger receives nexus: client ready - the startup summary. Throws:
  • \InvalidArgumentException - neither apiKey nor wif is configured
  • NexusException - no PSR-18 client or PSR-17 factory could be found, or the network failed
  • any exception of the status mapping - the initial sync or the session exchange was refused

Configs

getConfig(string $key, mixed $default = null): mixed

Returns the resolved config value, or $default when the key is absent.
The value mirrors the wire-level JSON type: string, int, float, bool, array, or null. Cast or validate as needed.

getAllConfigs(): array

Returns a snapshot copy of every config key-value pair currently in the cache. The returned array is independent of the SDK’s internal storage - mutating it has no effect.

Feature flags

getFlag(string $key, bool $default = false): bool

Returns the is_active state of a flag, or $default when the key is absent.
The server computes is_active (combining is_enabled, starts_at, ends_at); the SDK never makes that call itself.

findFlag(string $key): ?bool

Returns the is_active state, or null when the flag is not defined. getFlag() cannot express the difference between “the flag does not exist” and “it exists and is off” - both are false. Use this where the distinction matters:
It is what the OpenFeature provider uses to report FLAG_NOT_FOUND, and why an unknown key is never sent to evaluateAb(): the endpoint answers false for a key it does not know. getFlag() is expressed in terms of findFlag(), so the two cannot drift apart.

getAllFlags(): array

Returns a snapshot copy of every flag key-is_active pair in the cache. Keys are strings, values are booleans.

Secrets (secret key only)

All secret methods throw NexusPublicKeyException synchronously when the client uses a public key - before any network call.

getSecret(string $key): ?string

Returns the plaintext value of a text-type secret, or null when the key is absent or the secret is file-type.
Returns null (does not throw) when:
  • The key does not exist in the cache
  • The secret has type = 'file' - use getSecretFilePath instead
Throws:
  • NexusPublicKeyException - client uses a public key

getSecretFilePath(string $key): ?string

Returns the temp-file path holding the value of a file-type secret, or null when the key is absent or the secret is text-type.
The SDK materialises every file-type secret on each sync, into a directory the client owns: created with a runtime-chosen random name and mode 0700, with the files inside created 0600 and O_EXCL. The file name is a hash of the key, nothing in the path is derived from the value, and two clients holding the same secret get independent files. Files are removed in __destruct, with a process-exit hook as a backstop. Returns null when:
  • The key does not exist in the cache
  • The secret has type = 'text' - use getSecret instead
Throws:
  • NexusPublicKeyException - client uses a public key

Write API (secret key only)

Write methods require a secret key. A public key throws NexusPublicKeyException before making any network call. All write methods call the API directly and do not update the local cache - call sync() afterward if you need the new value immediately.

setSecret(string $key, string $value, string $type = 'text'): void

Creates or updates a secret. $type must be 'text' or 'file'.
Throws:
  • NexusPublicKeyException - client uses a public key
  • NexusNotFoundException - 404 (unknown service)
  • any other exception of the status mapping, e.g. NexusEnvironmentDisabledException or NexusApiException

deleteSecret(string $key): void

Deletes all versions of a secret.
Throws:
  • NexusPublicKeyException - client uses a public key
  • NexusNotFoundException - 404 (secret or service not found)
  • any other exception of the status mapping, e.g. NexusEnvironmentDisabledException or NexusApiException

deleteSecretVersion(string $key, int $version): void

Deletes a specific version of a secret. Version numbers are 1-based integers matching the server’s version sequence.
Throws:
  • NexusPublicKeyException - client uses a public key
  • NexusNotFoundException - 404 (secret, version, or service not found)
  • any other exception of the status mapping, e.g. NexusEnvironmentDisabledException or NexusApiException

A/B Testing

evaluateAb(array $keys, string $userId, array $attributes = []): array

Batch-evaluates feature flags through the AB Testing add-on against the supplied user context. Issues a single POST /v1/flags/evaluate-ab and returns the results map - flag key to evaluated boolean. Unlike getFlag, this method always performs a network call and does not consult the local cache.
Returns array<string, bool>, carrying every key you asked about. At most 200 keys per call. Attribute values must be strings. The endpoint binds them as a string-to-string map and cohort conditions compare them as strings, so a non-string value is rejected before the request is sent, with the attribute and the received type named. Nothing is stringified: no conversion is lossless, and a coerced value that then matches no cohort rule is harder to diagnose than one you were told about. A null value is treated as unset and dropped - kept as "" it could satisfy an eq "" rule. Throws:
  • \InvalidArgumentException - an attribute value is not a string; no request is sent
  • NexusAbAddonNotAvailableException - 403, the project does not have the AB Testing add-on
  • NexusEnvironmentDisabledException - 403 environment_disabled
  • any other exception of the status mapping

SSE

connectStream(int $maxErrors = 3): void

Follows the live-update stream. This method blocks and does not return. Call it only from CLI daemons and queue workers - never from FPM request handlers.
After $maxErrors consecutive errors the SDK syncs on the configured TTL for a cooldown window and then attempts the stream again. See SSE live updates for the backoff table, the refusals and the event reference. Throws:
  • NexusException - ext-curl is not loaded (TTL polling keeps working without it)
  • NexusUnauthorizedException - the credentials are rejected
  • NexusBillingException - the account is suspended
Do NOT call connectStream() inside a PHP-FPM request handler. It blocks the worker indefinitely, preventing it from serving further HTTP requests. Use it only in long-running CLI scripts started with php artisan queue:work, Swoole workers, or equivalent.

Sync

sync(): void

Forces an immediate sync, bypassing the TTL. ETag / If-None-Match is used automatically - a 304 resets the TTL without downloading data.
Throws any exception of the status mapping, a NexusException for a network failure, and NexusSessionExpiredException when an expired WIF session cannot be renewed.

syncErrors(): array

What the last sync reported it did not deliver - an empty array when everything arrived. Returns list<SyncError>; a 304 keeps the previous list.
The server leaves out a secret that has no value and a config whose secret reference does not resolve, so a read of either returns its default. Each new omission is also logged once as a warning; logSyncErrors: false keeps the list without the log lines. A SyncError never carries a value.

WIF

refreshSession(): void

Runs the WIF session exchange now, without waiting for the pre-emptive refresh window. The SDK calls it itself before a request when the session is within 60 seconds of expiry, and on the stream’s auth_expiring event. Throws NexusException when WIF is not configured, NexusTokenSourceException when your WifCredentialSource raises, and any exception of the status mapping when the exchange is refused. See Workload identity.

Metadata

getKeyType(): string

The credential class the last sync reported: 'sk', 'pk' or 'wif'. Before the first sync completes it is derived from the apiKey prefix.