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- neitherapiKeynorwifis configuredNexusException- 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.
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.
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:
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)
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.
null (does not throw) when:
- The key does not exist in the cache
- The secret has
type = 'file'- usegetSecretFilePathinstead
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.
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'- usegetSecretinstead
NexusPublicKeyException- client uses a public key
Write API (secret key only)
setSecret(string $key, string $value, string $type = 'text'): void
Creates or updates a secret. $type must be 'text' or 'file'.
NexusPublicKeyException- client uses a public keyNexusNotFoundException- 404 (unknown service)- any other exception of the status mapping, e.g.
NexusEnvironmentDisabledExceptionorNexusApiException
deleteSecret(string $key): void
Deletes all versions of a secret.
NexusPublicKeyException- client uses a public keyNexusNotFoundException- 404 (secret or service not found)- any other exception of the status mapping, e.g.
NexusEnvironmentDisabledExceptionorNexusApiException
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.
NexusPublicKeyException- client uses a public keyNexusNotFoundException- 404 (secret, version, or service not found)- any other exception of the status mapping, e.g.
NexusEnvironmentDisabledExceptionorNexusApiException
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 sentNexusAbAddonNotAvailableException- 403, the project does not have the AB Testing add-onNexusEnvironmentDisabledException- 403environment_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.
$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-curlis not loaded (TTL polling keeps working without it)NexusUnauthorizedException- the credentials are rejectedNexusBillingException- the account is suspended
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.
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.
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.
