feat: add evaluateFlags() API for single-call flag evaluation

[dmarticus]

Summary

Adds evaluateFlags(), a single-call flag evaluation API that returns a FeatureFlagEvaluations snapshot for one distinct id, and deprecates the legacy single-flag entry points in favor of it:

• One /flags request per call; reads on the snapshot make zero further requests.
• isEnabled($key) / getFlag($key) fire a deduped $feature_flag_called event with full metadata (id, version, reason, request_id, plus combined response-level errors) on first access. getFlagPayload($key) is silent.
• only([...]) / onlyAccessed() return filtered clones for scoping which flags attach to a captured event.
• capture(['flags' => $snapshot, …]) attaches $feature/<key> and $active_feature_flags without a fresh /flags round trip; warns when both flags and send_feature_flags are passed.
• isFeatureEnabled(), getFeatureFlag(), getFeatureFlagPayload(), and the send_feature_flags capture option now emit E_USER_DEPRECATED pointing at evaluateFlags(). Existing callers keep working unchanged until the next major.

RFC · reference SDK PRs: posthog-python#539, posthog-js#3476.

Design decisions

• Snapshot takes a tiny FeatureFlagEvaluationsHost interface (captureFlagCalledIfNeeded, logWarning) instead of a full Client, so unit tests can use a fake without spinning up the SDK.
• Filtered clones get a fresh access set; reads on the child never back-propagate to the parent.
• onlyAccessed() returns an empty snapshot when nothing has been accessed (no warning, no fallback). The earlier "warn + return all flags" fallback was contradictory with the method's name and surprised callers doing capture(flags: $snapshot->onlyAccessed()) early in a request.
• Empty-distinct_id snapshots short-circuit event emission inside recordAccess rather than at every call site, so isEnabled / getFlag still return sane values without leaking events with empty actors.
• Locally-evaluated records omit $feature_flag_request_id (it's per-/flags-response) but emit locally_evaluated=true and reason "Evaluated locally" to match the existing single-flag local path.
• Response-level errors (errorsWhileComputingFlags, quota_limited) are tracked at snapshot construction and combined with per-flag flag_missing in $feature_flag_error (e.g. errors_while_computing_flags,flag_missing), matching the granularity the legacy single-flag path emits today.
• flags= on capture() takes precedence over send_feature_flags; passing both logs a warning so the conflict isn't silent.
• isFeatureEnabled() calls getFeatureFlagResult() directly (skipping the public getFeatureFlag()) so a single user-level call surfaces exactly one deprecation warning, not two.
• getFeatureFlagResult() and getAllFlags() are intentionally not deprecated — they expose data (rich single-flag result, arbitrary key list) the snapshot API doesn't yet cover.
• Drive-by fix: SizeLimitedHash::contains/add were comparing values to keys and pushing onto the outer map, so the per-distinct_id $feature_flag_called dedup never matched after the first event. The new snapshot path requires real dedup, so it's fixed here.

Out of scope (explicit non-goals)

• Removing the deprecated methods — that's the next major.
• Plumbing flag_definitions_loaded_at through the snapshot. posthog-php doesn't track that timestamp on the local poller today; left for a follow-up.

Note: this supersedes #130 (stale base, blocked from rebase by a signature rule on a pre-existing unsigned ancestor).

---

Created with PostHog Code