> ## Documentation Index
> Fetch the complete documentation index at: https://docs.westyx.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# PHP SDK - Configuration

> NexusConfig field reference, API key types, TTL guidance, and WifConfig overview for the PHP SDK.

`NexusConfig` is a constructor-promoted value object holding every setting required to build a client. Pass it to `NexusClient::create`.

```php theme={null}
use WestyxNexus\NexusClient;
use WestyxNexus\NexusConfig;

$client = NexusClient::create(new NexusConfig(
    baseUrl: 'https://<slug>.westyx.dev', // required
    apiKey:  'wxs_...',               // required unless using WIF
    ttl:     60,                          // optional, default 60 seconds
    logger:  $myLogger,                   // optional PSR-3 LoggerInterface
));
```

## Field reference

| Field                   | Type               | Default | Description                                                                                                                                                                                                |
| ----------------------- | ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseUrl`               | `string`           | -       | Full service URL, e.g. `https://<slug>.westyx.dev`. The slug in the host is also sent as the `Host` header on every request (Double-Gate requirement).                                                     |
| `apiKey`                | `string`           | `''`    | Raw `wxs_...` or `wxp_...` key. Sent in `X-Nexus-API-Key`. Optional when `wif` is set.                                                                                                                     |
| `ttl`                   | `int`              | `60`    | Local cache TTL in seconds. After this elapses, the next read triggers a one-shot sync while still serving the stale cache.                                                                                |
| `logger`                | `?LoggerInterface` | `null`  | PSR-3 logger. `null` suppresses all SDK log output. See [Custom logging](custom-logging).                                                                                                                  |
| `wif`                   | `?WifConfig`       | `null`  | Optional Workload Identity Federation config. When non-null, the SDK exchanges a workload OIDC token for a Nexus session JWT and uses `Authorization: Bearer`. See [Workload identity](workload-identity). |
| `$sseReconnectCooldown` | `int\|array\|null` | `null`  | Schedule for reconnecting SSE after falling back to TTL polling. Unit: **minutes**. `null` = default `[5, 10, 20, 40, 60]` min. `int` = fixed interval. `array` = custom schedule (stays at last value).   |

## API key types

| Prefix    | Access                                                                                                                |
| --------- | --------------------------------------------------------------------------------------------------------------------- |
| `wxs_...` | Full - all configs, all secrets, all flags. Write API (`setSecret`, `deleteSecret`, `deleteSecretVersion`) available. |
| `wxp_...` | Restricted - configs and flags only. `getSecret` throws `NexusPublicKeyException` synchronously.                      |

<Warning>
  Calling `getSecret(...)` or `getSecretFilePath(...)` with a public key throws `NexusPublicKeyException` before any network call is made.
</Warning>

## Where to keep the API key

Use environment variables - never hardcode the key in source:

```php theme={null}
$client = NexusClient::create(new NexusConfig(
    baseUrl: (string) getenv('NEXUS_URL'),
    apiKey:  (string) getenv('NEXUS_API_KEY'),
));
```

In Laravel or Symfony, use the application's config system:

```php theme={null}
// Laravel - config/services.php
'nexus' => [
    'url' => env('NEXUS_URL'),
    'key' => env('NEXUS_API_KEY'),
],
```

The SDK never logs the raw key. Log lines reference the key type only:

```
[nexus] Client ready. key_type=sk ttl=60s
```

## Choosing the TTL

The TTL controls how long the in-memory cache is considered fresh before a background sync is triggered. With SSE enabled (`connectStream()`), **changes propagate within milliseconds regardless of the TTL** - the TTL only matters as a fallback when the stream is not running (FPM request handlers, for example).

| Use case                                            | Suggested TTL  |
| --------------------------------------------------- | -------------- |
| FPM request handler (cache is per-request anyway)   | `60` (default) |
| Frequently-changing flags, latency-sensitive daemon | `30`           |
| Standard configs with SSE daemon                    | `60` (default) |
| Stable production secrets                           | `300`          |
| Boot-time only, never rechecked                     | `3600`         |

<Info>
  In PHP-FPM, each request creates a fresh PHP process, so the cache is always empty at the start of a request and the TTL has no staleness effect across requests. The TTL is relevant only for long-running CLI daemons and queue workers.
</Info>

## Custom Guzzle client

The factory method accepts an optional Guzzle client as its second argument:

```php theme={null}
use GuzzleHttp\Client as GuzzleClient;

$http = new GuzzleClient([
    'timeout'  => 5.0,
    'verify'   => '/path/to/ca-bundle.crt',
    'proxy'    => 'http://proxy.internal:3128',
]);

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

If no Guzzle client is provided, the SDK constructs one with a 10-second timeout.

<Note>
  Do not set a `timeout` that is too short - the initial sync is blocking and must complete before `create` returns. 10 seconds is a sensible minimum.
</Note>

## WifConfig overview

When you pass a `WifConfig` to `NexusConfig::$wif`, the SDK skips the static `apiKey` on every request and instead exchanges a workload OIDC token for a Nexus session JWT:

```php theme={null}
use WestyxNexus\NexusConfig;
use WestyxNexus\WifConfig;

$client = NexusClient::create(new NexusConfig(
    baseUrl: $_ENV['NEXUS_URL'],
    wif: new WifConfig(provider: 'auto'),
));
```

See [Workload identity](workload-identity) for the full provider table, custom `tokenSource` closure, and token exchange details.