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

# PHP SDK - Version history

> What changed in each release of the PHP SDK, and how to migrate across a breaking change.

Every release of `westyx/nexus`, newest first. The Laravel service provider and the OpenFeature provider ship inside the package and share its version. Where a release broke something, its **Migrating** section shows the change to make. The repository's [`CHANGELOG.md`](https://gitlab.com/westyx/nexus/sdk/php/-/blob/main/CHANGELOG.md) carries the same releases in full detail.

## v0.19.1 - 2026-11-19

* **OpenFeature `423 service_locked` hold:** uses a timed suppression window (default 5 minutes) matching `environment_disabled`, so `evaluateAb` recovers automatically once the lockdown is lifted.
* **Frontend service-kind guard:** adds `NexusServiceKindMismatchException` and enforces `service_kind === 'frontend'` in secret operations.

## v0.19.0 (2026-11-19)

* **HTTP 423 `service_locked`:** adds `NexusServiceLockedException`; `connectStream()` exits immediately on `423` and background sync retries halt until an explicit `sync()` succeeds.
* **OpenFeature provider:** suppresses repeated `evaluateAb` requests while the service is locked down, serving the cached snapshot as `STALE`.

## v0.18.0 - 2026-11-12

* **A switched-off environment is reported by name.** `403 {"error":"environment_disabled"}` throws `NexusEnvironmentDisabledException` on every request, the stream and the token exchange. The cached snapshot keeps serving; the background refresh, the polling fallback and the stream wait five minutes between attempts, one warning is logged, and the first successful sync clears it. The OpenFeature provider serves the snapshot as `STALE` meanwhile.
* **Every API error carries its status and code.** A status no narrower exception describes throws `NexusApiException` with `$operation`, `$status` (also `getCode()`) and `$errorCode`. The message never carries the response body.
* **The startup summary.** `nexus: client ready` names the configs, secrets and flags the first sync delivered - never a value. A client with no logger writes it to stderr when `WESTYX_NEXUS_LOG_STARTUP=1`.
* **`syncErrors()`** lists the resources the server did not deliver, each logged once as a warning; `logSyncErrors: false` keeps the list without the log lines.
* **A WIF refresh that fails while the session is still valid keeps the session** and logs a warning; an `auth_expiring` refresh failure no longer ends the stream connection.
* **The stream's error budget restarts after a connection that held for 30 seconds**, however it ended; a connection that ends sooner counts as an error, so a flapping endpoint backs off and falls back to polling.
* **`var_export()` of a WIF client carries no session token.**
* **`psr/http-factory` is required at `^1.1`**, the first release PHP 8.4 and later load without deprecation notices.

### Migrating to v0.18.0

* Code that matched the message of an unexpected status (`nexus: setSecret unexpected status 500`) reads `NexusApiException::$status` instead. `NexusApiException` extends `NexusException`, so a `catch (NexusException)` is unaffected.
* A refused token exchange other than `401` throws the same exception a request would (`NexusApiException`, `NexusNotFoundException`, ...) instead of a plain `NexusException`.
* A 403 `environment_disabled` from `evaluateAb()` is `NexusEnvironmentDisabledException`, not `NexusAbAddonNotAvailableException`.
* Secret key names now appear in log output; secret values never do. A log pipeline that treated a key name as sensitive filters `nexus: client ready` and `nexus: the server did not deliver a resource`.

## v0.17.0 - 2026-09-30

* **The endpoint can come from the environment.** Leave `baseUrl` empty and `NexusConfig` reads `WESTYX_SERVICE_ENDPOINT` - `westyx dev run` sets it for the script's service, so a locally started application needs neither an endpoint nor a key in its code. A `baseUrl` you pass always wins, and an error about the variable's value names the variable. See [Configuration](https://docs.westyx.dev/sdks/php/configuration.md#service-endpoint).
* **Laravel works keyless.** With no `NEXUS_API_KEY` and `NEXUS_WIF_ENABLED` unset, the provider uses WIF, and `NEXUS_BASE_URL` falls back to the same variable - so `westyx dev run php artisan serve` needs no Nexus settings at all. See [Laravel](https://docs.westyx.dev/sdks/php/laravel.md#local-development).

### Migrating to v0.17.0

* A `config/nexus.php` published earlier carries `(bool) env('NEXUS_WIF_ENABLED', false)` and keeps WIF off unless it is set; change that line to `env('NEXUS_WIF_ENABLED')` to get the keyless default.

## v0.16.0 - 2026-08-29

* **`NexusProvider` reports its own name** (`Nexus`) on `open-feature/sdk >=2.1`, the new floor.
* **`aws_iam`'s signed request includes `Content-Type` in its signed headers** on `aws/aws-sdk-php >=3.386`, the new floor.
* **Every declared dependency floor builds and passes on PHP 8.5**, verified by a permanent CI leg.

## v0.15.0 - 2026-08-29

* **`var_export()` prints neither the API key nor a cached secret**, on the config, the cache or a live client: all three are held outside the object's property table (a `WeakMap` keyed by instance).

## v0.14.0 - 2026-08-23

* **`aws_iam` works on a non-default port.** The signed `X-Nexus-Server-ID` carries the port whenever it is not the scheme's default, matching the host the backend validates against.
* **A failing logger cannot break an SDK call.** A PSR-3 logger that throws - a Monolog handler on a full disk is the usual case - is contained. See [Custom logging](https://docs.westyx.dev/sdks/php/custom-logging.md).
* **Leaner package, and an `MIT` `LICENSE` file.** The published package carries `src/` and the Laravel `config/` only.
* **Raised baselines** - PHPStan at level 10, PHPUnit 12, code coverage and a SonarQube job.

## v0.13.0 - 2026-08-10

* **The `developer` provider.** A session `westyx dev setup` already issued is sent as the Bearer directly - no token exchange - so a laptop can authenticate to a WIF-enforced service. Probed last, behind every cloud provider.
* **`WifProvider` is a backed enum**, so an invalid provider is a `TypeError` at construction rather than a failure on the first request.
* **The credential extension point is an interface**, `WifCredentialSource`, which can express a credential that is not a bearer token and survives `php artisan config:cache`.
* **The Azure IMDS path**, for an Azure VM or App Service workload with no projected token file. Needs `audience: 'api://<client-id>'`.
* **A dumped client shows a redacted view** - `var_dump`, `print_r`, `json_encode` and `serialize` carry no credential, and a secret parameter never reaches an exception trace.

### Migrating to v0.13.0

| Was | Now |
| - | - |
| `new WifConfig(provider: 'kubernetes')` | `new WifConfig(provider: WifProvider::KUBERNETES)` |
| `new WifConfig(tokenSource: fn () => $jwt)` | `new WifConfig(credentialSource: CallableWifCredentialSource::oidc(fn () => $jwt))` |
| `WifProvider::getToken('gcp')` | `WifProvider::GCP->fetchToken($context)` |
| `WifProvider::detect()` | `WifProvider::detect($context)` |
| `$exchange->buildPayload()` (JSON string) | `$exchange->payload()` (array) |
| `$config->apiKey` | `$config->apiKey()` |

A provider string arriving from configuration keeps working: `WifConfig::fromArray()` and `WifProvider::fromWire()` accept it, and the Laravel service provider uses the former, so `NEXUS_WIF_PROVIDER=gcp` needs no change.

## v0.12.0 - 2026-08-03

* **Per-user targeting through OpenFeature.** A boolean evaluation whose `EvaluationContext` carries a `targetingKey` is evaluated for that identity through the AB Testing add-on and reports `TARGETING_MATCH`. One request covers every flag in the snapshot and the results are memoised per identity. See [OpenFeature](https://docs.westyx.dev/sdks/php/openfeature.md).
* **The OpenFeature provider ships inside `westyx/nexus`** as `WestyxNexus\OpenFeature\NexusProvider`, with `open-feature/sdk` as a Composer `suggest`. The earlier `westyx/nexus-openfeature` sub-package had no installable release, because a Composer package must sit at the root of its own repository.
* **`findFlag()`** returns `?bool`, so a flag that does not exist is distinguishable from one that is off.
* **`NexusAbAddonNotAvailableException`** - the 403 from `evaluateAb()` has its own type.
* **Attribute values are strings, and are checked** before the request goes out.
* **Numbers resolve as numbers** - the OpenFeature integer and float resolutions report `TYPE_MISMATCH` instead of coercing.
* **Available on Packagist** - `composer require westyx/nexus` works with no repository configuration.

## v0.11.0 - 2026-07-30

* **Bring your own HTTP client.** The SDK is built on PSR-18 and PSR-17, so it uses whatever HTTP stack your project already has; Guzzle is not required. See [HTTP client](https://docs.westyx.dev/sdks/php/http-client.md).
* **Laravel service provider** - `composer require westyx/nexus` in a Laravel app is the whole setup. See [Laravel](https://docs.westyx.dev/sdks/php/laravel.md).
* **PSR-3 logging** through the logger you pass, with values in the `$context` array.
* **File-type secrets live in a private directory** created `0700`, with the files inside created `0600` and `O_EXCL`.
* **Stream deadlines** - a connection deadline (10 s) and a liveness deadline (60 s) that resets on every byte.
* **The cache serves what it has** - a `304 Not Modified` and a brief network failure both keep serving the last snapshot.
* **One status-code contract** across every endpoint, with `Retry-After` and quarantine details preserved.

## v0.10.0 - 2026-07-05

* Version alignment across the Westyx Nexus SDK suite.

## v0.9.0 - 2026-07-03

* **The `aws_iam` WIF provider** for ECS/Fargate, Lambda and plain EC2: the SDK SigV4-signs an STS `GetCallerIdentity` request (never sent to AWS) and posts it to the token exchange. Requires `aws/aws-sdk-php`. See [Workload identity](https://docs.westyx.dev/sdks/php/workload-identity.md#aws-iam-non-eks-aws-compute).
* **Security hardening** - the base URL must be `https://` (loopback excepted); an expired WIF session refreshes on every request path and a WIF-only client fails closed; metadata and token-exchange reads are size-bounded; auto-detection checks that the token files exist; a non-positive `expires_in` is clamped.

## v0.8.2 - 2026-07-01

* **The `gcp` provider fetches a Google-signed OIDC identity token** from the GCE metadata server, and auto-detection follows the actual token sources.

## v0.8.1 - 2026-06-17

* Documentation: the example service base URL is `https://<slug>.westyx.dev`.

## v0.8.0 - 2026-06-16

* **An OpenFeature provider**, wrapping an existing `NexusClient`.

## v0.6.0 - 2026-06-11

* **The stream reconnects after the polling fallback**, after the cooldown `sseReconnectCooldown` sets.

## v0.5.1 - 2026-06-03

* **Requires PHP 8.3+.** PHP 8.1 and 8.2 are end-of-life.
* **Exception messages carry the status code, not the response body**, and a file-type secret's path is hashed.
* **The stream waits out a quarantine** without counting it as a transport error.

## v0.5.0 - 2026-06-01

* **API paths use `/v1/`**, and the base URL is `https://<slug>.westyx.dev`.
* **Quarantine handling** - a `429` quarantine response pauses syncing until it expires; `NexusQuarantinedException` carries `$reason` and `$expiresAt`.
* **The write API** - `setSecret`, `deleteSecret`, `deleteSecretVersion` for a secret key.
* **A public key receives every config and flag.**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.