feat: add hooks support

[keelerm84]

Implements the Hooks specification (evaluation series + track series) to
give users and LaunchDarkly integration packages an extension point for
observing flag evaluations and track calls.

• Public API under LaunchDarkly\Hooks: Hook (abstract base class),
  Metadata, EvaluationSeriesContext, TrackSeriesContext.
• LDClient accepts a hooks option at construction and exposes
  addHook() for runtime registration.
• beforeEvaluation / afterEvaluation fire around every variation,
  variationDetail, and migrationVariation call, with afterEvaluation
  running in reverse registration order per spec 1.3.4.
• afterTrack fires after a custom event is enqueued. It does not fire
  for trackMigrationOperation (not a custom event) or for track calls
  rejected due to an invalid context.
• Hook exceptions are caught and logged at the error level; when a stage
  errors, subsequent stages receive the previous successful stage's data
  (spec 1.3.7.1).
• environmentId is intentionally omitted from the series contexts until
  the SDK can populate it reliably; the spec lists it as optional.
• Identify series (1.4) and configuration handlers (1.5) are skipped
  because they are client-side only.
• Contract test service declares evaluation-hooks and track-hooks
  capabilities and wires harness-provided hook configs through a new
  PostingHook implementation.

---

Note

Medium Risk
Touches core LDClient evaluation/track paths by adding hook dispatch and refactoring evaluation into evaluateInternal, which could affect ordering/performance and error handling if hooks misbehave. Failures are isolated and logged, but this introduces new execution around every flag evaluation and custom event.

Overview
Adds a new public hooks API (LaunchDarkly\Hooks\Hook, Metadata, EvaluationSeriesContext, TrackSeriesContext) and an internal HookRunner to run hook stages with defined ordering and exception isolation.

LDClient now accepts a hooks constructor option and exposes addHook(). It wraps variation, variationDetail, and migrationVariation with beforeEvaluation/afterEvaluation (after runs in reverse registration order) and invokes afterTrack after successful custom track() enqueues, while intentionally not firing hooks for invalid-track calls or trackMigrationOperation.

Updates the contract test service to advertise hook capabilities and to construct a PostingHook from harness config; adds unit tests covering ordering, data propagation, and logging behavior. Updates psalm-baseline.xml accordingly.

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

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8f7b5e0. Configure here.}

[cursor]

Test asserts wrong index, trivially passes always

Medium Severity

The assertion $a->calls[0]['data'] checks the beforeEvaluation record (index 0), whose data field is always [] because HookRunner::beforeEvaluation unconditionally passes an empty array to every hook. The comment says "Hook A's afterEvaluation receives [] because its beforeEvaluation failed," so the assertion needs to use $a->calls[1]['data'] (the afterEvaluation record) to actually verify the error recovery behavior described by spec 1.3.7.1. As written, this test passes regardless of whether the fallback-on-error logic works correctly.

 

^{Reviewed by Cursor Bugbot for commit 8f7b5e0. Configure here.}