PHP SDK - API Reference

Every public symbol in westyx/nexus. All read methods (getConfig, getSecret, getFlag, etc.) are non-blocking - they hit the in-memory cache. Only NexusClient::create, sync, and evaluateAb make network calls.

Construction

`NexusClient::create(NexusConfig $config, ?GuzzleClient $http = null): static`

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`	`?GuzzleClient`	Optional. Custom Guzzle client. SDK builds a default (10 s timeout) 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.

`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 to a temp file on every sync. The file path includes a hash of the value - when the secret changes on the server the path changes and the old file is removed. Files are written mode 0600. Temp files are deleted in __destruct. 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>. Missing keys in the response default to false. Throws:

NexusUnauthorizedException - 401
NexusBillingException - 402
NexusNotFoundException - 404
NexusRateLimitedException - 429 (no AB Testing add-on returns 403 which is surfaced as NexusNotFoundException)

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 (TTL polling continues)

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, ?GuzzleClient $http = null): static`

Configs

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

`getAllConfigs(): array`

Feature flags

`getFlag(string $key, bool $default = false): 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, ?GuzzleClient $http = null): static

​Configs

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

​getAllConfigs(): array

​Feature flags

​getFlag(string $key, bool $default = false): 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, ?GuzzleClient $http = null): static`

Configs

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

`getAllConfigs(): array`

Feature flags

`getFlag(string $key, bool $default = false): 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`