Repository navigation
feat(flags): support known-absent property keys in local evaluation - #328
marandaneto wants to merge 7 commits into
Conversation
Flag evaluation methods on Client and the static PostHog facade take optional personPropertyKeysKnownAbsent and groupPropertyKeysKnownAbsent arguments. Local evaluation treats a listed key as absent, even over a supplied or SDK-injected value: is_not_set, is_not and the not_* string operators match, every other operator doesn't. Unsupported operators and malformed filters still fall back. Person-metadata keys are ignored and group keys apply only to their group type. Dynamic cohort leaves and flag dependencies use the same listing. Remote /flags requests carry the keys only when provided, and a list over 1000 keys throws InvalidArgumentException before any request. Spec: PostHog/sdk-specs#233
The Laravel manager's flag forwarders mirror the core Client signatures, so they take and forward personPropertyKeysKnownAbsent and groupPropertyKeysKnownAbsent. The request-scoped evaluateFlags snapshot is keyed by these lists too, and PostHogFake::evaluateFlags accepts them.
posthog-php-lib_curl Compliance ReportDate: 2026-11-20T10:48:33.380274+00:00 ✅ All Tests Passed!47/47 tests passed Capture Tests✅ 30/30 tests passed View Details
Feature_Flags Tests✅ 17/17 tests passed View Details
|
posthog-php-fork_curl Compliance ReportDate: 2026-11-20T10:48:09.167099+00:00 ✅ All Tests Passed!47/47 tests passed Capture Tests✅ 30/30 tests passed View Details
Feature_Flags Tests✅ 17/17 tests passed View Details
|
posthog-php-socket Compliance ReportDate: 2026-11-20T10:48:48.208313+00:00 ✅ All Tests Passed!47/47 tests passed Capture Tests✅ 30/30 tests passed View Details
Feature_Flags Tests✅ 17/17 tests passed View Details
|
There was a problem hiding this comment.
PostHog Review · Standard · reviewed 3692184: 1 Should fix, 1 Consider.
See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.
| @@ -0,0 +1,6 @@ | |||
| --- | |||
| "posthog-php": minor | |||
There was a problem hiding this comment.
P2 · Use a major core release for incompatible method signatures
An application subclass overriding Client::getFeatureFlag() or another changed non-final method with its existing signature now fails PHP's declaration compatibility check when loaded. Marking this release minor delivers that fatal error through existing Composer ^4 constraints, even without using the new arguments. Preserve override compatibility or select a major core bump.
| $personKnownAbsentKeys = []; | ||
| foreach ($personPropertyKeysKnownAbsent ?? [] as $absentKey) { | ||
| // Known absence never hides a persons-table field read through the metadata prefix. | ||
| if (!str_starts_with($absentKey, self::PERSON_METADATA_KEY_PREFIX)) { | ||
| $personKnownAbsentKeys[$absentKey] = true; | ||
| } | ||
| } | ||
| $groupKnownAbsentKeys = []; | ||
| foreach ($groupPropertyKeysKnownAbsent ?? [] as $groupType => $absentKeys) { | ||
| $groupKnownAbsentKeys[$groupType] = array_fill_keys($absentKeys, true); |
There was a problem hiding this comment.
P3 · Build known-absent lookup maps once per evaluation
When evaluateFlags() or getAllFlags() evaluates many local flags with known-absent keys, computeFlagLocally() rebuilds the same person and group lookup maps for every flag, including inactive flags. This adds O(flags × supplied keys) preprocessing and repeated allocations to each call. Normalize these maps once before iterating over the flags and pass them through.
…eleases (cherry picked from commit 5707c7c)
💡 Motivation and Context
Local flag evaluation treats a property key that the caller left out of
$personPropertiesas unknown. The SDK can't tell "this person has noplan" apart from "the caller didn't sendplan". So any condition onplanis inconclusive, and the SDK falls back to/flags. When the caller does know the key is missing, there is no way to say so. Local results and the/flagsresult can then disagree for the same person.This PR adds an optional list of property keys the caller knows are absent. Local evaluation uses it to give a final answer. The SDK also sends it to
/flags, so both paths agree.Public API change: this adds two optional trailing parameters to the flag methods. The API comes from the published spec in PostHog/sdk-specs#233, so there is no separate issue.
Links:
feat/flags-known-absent-property-keys)New input
Every flag method that takes
$personPropertiesand$groupPropertiesnow also takes:?array $personPropertyKeysKnownAbsent = null. A list of person property keys.?array $groupPropertyKeysKnownAbsent = null. A map from group type name to a list of group property keys.This covers
evaluateFlags(),getAllFlags(),flags()andfetchFeatureVariants(). It also covers the deprecatedgetFeatureFlag(),getFeatureFlagResult(),isFeatureEnabled()andgetFeatureFlagPayload(). The staticPostHog::methods and the Laravel manager forward both parameters. The Laravel manager'sevaluateFlags()snapshot cache key includes them.Local evaluation
For a listed key, local evaluation gives a final answer and doesn't fall back to
/flags:is_not_set,is_not,not_icontains,not_starts_with,not_ends_withandnot_regexmatch.is_setand every other supported operator don't match. This includesexact,icontains,regex, the number and date comparisons, and allsemver_*operators.distinct_idand$group_key./flags, even for a listed key.testDynamicCohortUnsupportedLeafOnKnownAbsentKeyFallsBackcovers anot_between [1, 2]cohort leaf on a listed key, with and withoutnegation.__posthog_person_metadata__are ignored.negationis applied after that./flagsrequest bodyWhen the SDK calls
/flagsand the caller passed keys, it addsperson_property_keys_known_absent(a list) andgroup_property_keys_known_absent(an object from group type to list). This applies to the local fallback and to remote-only calls. A field is left out when the caller passed nothing for it or passed an empty list.Limits
Each list can hold at most 1000 keys, counting duplicates. For groups, the limit applies to each group type. The SDK throws
InvalidArgumentExceptionbefore it evaluates anything or sends a request. It never truncates the list. It also throws for a non-string key or a group entry that is not a list. The Laravel manager andPostHogFake::evaluateFlags()run the same check before they return early, for example when there is no distinct ID.Not included
$feature_enrollment/<flag key>keys get no special local handling. Only posthog-python evaluates enrollment locally today. That work is tracked in Support local feature enrollment evaluation across server SDKs posthog#138580.icontains_multi,not_icontains_multi,betweenandnot_betweenoperators are still unsupported. A listed key under one of them still falls back to/flags. They are tracked in Support icontains_multi and between operators in SDK local flag evaluation posthog#138581.Release note
The changeset marks both
posthog-phpandposthog-laravelas minor. Existing calls keep working. A subclass that overrides one of the changed non-final methods with the old signature would fail PHP's signature compatibility check when the class loads. The repo has added optional trailing parameters in minor releases before, for exampledisableGeoipin #263. Please call it out if you think this one needs a different bump.💚 How did you test it?
New tests in
test/FeatureFlagKnownAbsentTest.php:distinct_idand$group_key/flagsbody including the fields on fallback and leaving them out when not passedNew tests in
packages/laravel/tests/RuntimeTest.phpcover forwarding and snapshot caching. They also check that the 1000-key limit applies with no identity and inPostHogFake.Commands run locally on PHP 8.5, all passing:
php -d memory_limit=-1 ./vendor/bin/phpunit --bootstrap vendor/autoload.php --configuration phpunit.xml: 2905 tests passed, 1 skipped, after adding the cohort leaf test. The new test passed on its first run, so no production change was needed. The 2 deprecation notices and the missing coverage driver warning also show up onmain.JsonEncoderTest::testMalformedKeysRetainErrorsAndNativeCallbackOrderingfor every PR. This branch includes the fix from test: accept the native jsonSerialize call count on newer PHP patch releases #329 as a cherry-picked commit (dc196fe), so phpunit passes on both versions. Once test: accept the native jsonSerialize call count on newer PHP patch releases #329 merges, that commit will matchmain../vendor/bin/phpcs --standard=phpcs.xml --extensions=php lib test: 0 errors. The 19 warnings are in files this PR doesn't change.composer api:checkandcomposer api:check:laravel: both snapshots are up to date.bash scripts/test-laravel.sh 12andbash scripts/test-laravel.sh 13: 249 package tests and 30 example tests passed on each.CI now runs SDK test harness 1.34.0 (all three profiles passed 47/47). The known-absent suite doesn't run because the PHP adapter's
/healthonly declarescapture_v0andencoding_gzip, notfeature_flags_local_evaluation_v1andfeature_flags_known_absent_v1.📝 Checklist
If releasing new changes
pnpm changeto generate a change intent file🤖 Agent context
Autonomy: Human-driven (agent-assisted)
PostHogFake::evaluateFlags()now check the key limit before their early returns. To share that check,Client::assertKnownAbsentKeysValid()is a public static method marked@internal.