[hidingmyname]

Requirements

• I have added test coverage for new or changed functionality
• I have followed the repository's pull request submission guidelines
• I have validated my changes against all supported platform versions

Related issues

Fixes #284.

Describe the solution you've provided

• Add EvaluationReason::exception(\Throwable) and getException(): ?\Throwable, retaining the original object for EXCEPTION reasons. Existing reason factories remain unchanged.
• Preserve the exception through withBigSegmentsEvaluationStatus() without adding it to the reason's JSON representation or analytics events.
• Use the factory in the evaluator's unexpected-error catch, the client's unexpected-error catch, and the UnrecoverableHTTPStatusException catch for HTTP 401/403. Existing fallback values and the client's offline transition are preserved.
• Put reason, evaluator, and client regressions in the existing test files, as requested. Cover PHP Error, both HTTP status codes, serialization privacy, and the post-authentication-error offline state.
• Document the new accessor and add a release note. Register the external accessor beside the existing reason getters in the Psalm baseline, since src-only analysis cannot see SDK consumers.

Describe alternatives you've considered

Leaving the cause only in the PSR-3 logs does not let the caller associate the original exception with its failed variationDetail() call. A separate exception() factory also keeps exceptions out of unrelated error kinds.

Validation

PHP 8.4.27 / PHPUnit 9.6.38:

• Before propagation was fixed: the evaluator case and all four client cases failed because getException() returned null.
• After the fix: the targeted regressions passed. Full PHPUnit run: 538 tests, 1,406 assertions, 16 integration tests skipped, no failures. The external WireMock integration suite was not run locally.
• Standalone smoke with the real Guzzle requester against a local HTTP server: both 401 and 403 expose UnrecoverableHTTPStatusException, keep reason JSON unchanged, and switch subsequent evaluations offline; the server observed exactly one request per client.
• PHP CS Fixer: no changes required.
• Psalm: no new errors; it reports the existing UnusedClass for NullEventProcessor, also reproduced on unmodified upstream 6df19b5 with the same dependency set. I have not suppressed or changed that unrelated issue.

Only PHP 8.4 was exercised locally; the existing CI matrix covers the other supported PHP versions and platforms.

Additional context

AI disclosure: this contribution was implemented and submitted by the omp AI coding assistant in the omp harness on behalf of @hidingmyname, at their request. No review reminder or reviewer assignment is requested.

---

Note

Overview
Failed flag evaluations can now surface the original Throwable on the evaluation reason, without changing analytics JSON or serialized payloads.

EvaluationReason gains exception(\Throwable) and getException(): ?\Throwable. The cause is kept for ERROR / EXCEPTION reasons (including through withBigSegmentsEvaluationStatus()), but is omitted from jsonSerialize(), __sleep() / unserialize(), and reason strings—error(EXCEPTION_ERROR) still leaves getException() null.

Evaluator and LDClient (variationDetail paths, including UnrecoverableHTTPStatusException on 401/403) now build reasons with EvaluationReason::exception($e) instead of a bare EXCEPTION error kind, while existing default-value fallbacks and the client’s offline transition after auth errors stay the same.

Tests cover serialization privacy, prerequisite lookup failures, and several exception types on the client.

^{Reviewed by Cursor Bugbot for commit e814356. Bugbot is set up for automated code reviews on this repo. Configure here.}

[keelerm84]

Thank you @hidingmyname for getting this PR put up. I appreciate your contribution, and you should receive a notice once the release has gone out.