PHP SDK - API Reference

Every public symbol in westyx/nexus. All read methods (getConfig, getSecret, getFlag, findFlag, etc.) are non-blocking - they hit the in-memory cache. Only NexusClient::create, sync, and evaluateAb make network calls - plus 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): self`

Creates a client and runs a blocking initial sync. Returns the populated client. Throws on failure.

use WestyxNexus\NexusClient;
use WestyxNexus\NexusConfig;

$client = NexusClient::create(new NexusConfig(
    baseUrl: $_ENV['NEXUS_URL'],
    apiKey:  $_ENV['NEXUS_API_KEY'],
));

Parameter	Type	Description
`$config`	`NexusConfig`	Required. See Configuration.
`$http`	`?Psr\Http\Client\ClientInterface`	Optional. Any PSR-18 client. Discovered from the project when `null`.
`$requestFactory`	`?Psr\Http\Message\RequestFactoryInterface`	Optional. Discovered when `null`.
`$streamFactory`	`?Psr\Http\Message\StreamFactoryInterface`	Optional. Discovered when `null`.

Throws:

NexusUnauthorizedException - initial sync returned 401
NexusBillingException - initial sync returned 402
NexusNotFoundException - initial sync returned 404

Configs

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

Returns the resolved config value, or $default when the key is absent.

$dbUrl = $client->getConfig('database.url');          // null if not found
$port  = $client->getConfig('server.port', 8080);    // 8080 if not found

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.

foreach ($client->getAllConfigs() as $key => $value) {
    echo "{$key}: " . json_encode($value) . PHP_EOL;
}

Feature flags

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

Returns the is_active state of a flag, or $default when the key is absent.

$isOn = $client->getFlag('checkout.v2', false);

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:

match ($client->findFlag('checkout.v2')) {
    true  => 'on',
    false => 'off',
    null  => 'no such flag - check the key',
};

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.

$flags = $client->getAllFlags();
// ['checkout.v2' => true, 'dark-mode' => false, ...]

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.

$password = $client->getSecret('DB_PASSWORD');
if ($password === null) {
    throw new \RuntimeException('nexus: missing DB_PASSWORD secret');
}

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.

$certPath = $client->getSecretFilePath('TLS_CERT');
if ($certPath === null) {
    throw new \RuntimeException('nexus: TLS_CERT is missing or not a file-type secret');
}
// Pass $certPath to openssl, curl CURLOPT_SSLCERT, etc.

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. Nothing in the path is derived from the key name or 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'.

$client->setSecret('STRIPE_KEY', 'sk_live_abc123');
$client->setSecret('TLS_CERT', $certPem, 'file');

Throws:

NexusPublicKeyException - client uses a public key
NexusUnauthorizedException - 401
NexusBillingException - 402
NexusNotFoundException - 404 (unknown service)
NexusRateLimitedException - 429

`deleteSecret(string $key): void`

Deletes all versions of a secret.

$client->deleteSecret('OLD_API_KEY');

Throws:

NexusPublicKeyException - client uses a public key
NexusUnauthorizedException - 401
NexusBillingException - 402
NexusNotFoundException - 404 (secret or service not found)
NexusRateLimitedException - 429

`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.

$client->deleteSecretVersion('DB_PASSWORD', 3);

Throws:

NexusPublicKeyException - client uses a public key
NexusUnauthorizedException - 401
NexusBillingException - 402
NexusNotFoundException - 404 (secret, version, or service not found)
NexusRateLimitedException - 429

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.

$results = $client->evaluateAb(
    keys:       ['checkout.v2', 'homepage.banner'],
    userId:     'user-42',
    attributes: ['country' => 'HU', 'plan' => 'pro'],
);

if ($results['checkout.v2'] ?? false) {
    // bucketed into the new checkout
}

Parameter	Type	Description
`$keys`	`array`	Flag keys to evaluate.
`$userId`	`string`	Stable user/session identifier for bucketing.
`$attributes`	`array`	Key-value context for targeting rules (plan, country, etc.).

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
NexusUnauthorizedException - 401
NexusBillingException - 402
NexusNotFoundException - 404
NexusRateLimitedException - 429

SSE

`connectStream(int $maxErrors = 3): void`

Opens the SSE live-update connection. This method blocks indefinitely. It must only be called from CLI daemons and queue workers - never from FPM request handlers.

// CLI daemon
$client->connectStream();

The method returns when:

$maxErrors consecutive transport errors have occurred, at which point the SDK syncs on the configured TTL for a cooldown window and then attempts the stream again. The call itself does not return.

After returning, the SDK falls back to TTL polling automatically. See SSE live updates for the full backoff table and event reference.

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.

$client->sync(); // force refresh
$value = $client->getConfig('feature.threshold');

Throws:

NexusUnauthorizedException - 401
NexusBillingException - 402
NexusNotFoundException - 404
NexusRateLimitedException - 429
NexusQuarantinedException - 429 quarantine body

Metadata

`getKeyType(): string`

Returns 'sk' or 'pk' based on the configured apiKey prefix. Returns '' when authentication is exclusively via WIF and no static apiKey is set.

if ($client->getKeyType() === 'pk') {
    // public-key client - secrets not available
}

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

PHP SDK - API Reference

Construction

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

Configs

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

`getAllConfigs(): array`

Feature flags

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

`findFlag(string $key): ?bool`

`getAllFlags(): array`

Secrets (secret key only)

`getSecret(string $key): ?string`

`getSecretFilePath(string $key): ?string`

Write API (secret key only)

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

`deleteSecret(string $key): void`

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

A/B Testing

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

SSE

`connectStream(int $maxErrors = 3): void`

Sync

`sync(): void`

Metadata

`getKeyType(): string`

​Construction

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

​Configs

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

​getAllConfigs(): array

​Feature flags

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

​findFlag(string $key): ?bool

​getAllFlags(): array

​Secrets (secret key only)

​getSecret(string $key): ?string

​getSecretFilePath(string $key): ?string

​Write API (secret key only)

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

​deleteSecret(string $key): void

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

​A/B Testing

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

​SSE

​connectStream(int $maxErrors = 3): void

​Sync

​sync(): void

​Metadata

​getKeyType(): string

Construction

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

Configs

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

`getAllConfigs(): array`

Feature flags

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

`findFlag(string $key): ?bool`

`getAllFlags(): array`

Secrets (secret key only)

`getSecret(string $key): ?string`

`getSecretFilePath(string $key): ?string`

Write API (secret key only)

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

`deleteSecret(string $key): void`

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

A/B Testing

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

SSE

`connectStream(int $maxErrors = 3): void`

Sync

`sync(): void`

Metadata

`getKeyType(): string`