Skip to content

feat(flags): support known-absent property keys in local evaluation - #328

Open
marandaneto wants to merge 7 commits into
mainfrom
feat/flags-known-absent-property-keys
Open

marandaneto wants to merge 7 commits into
mainfrom
feat/flags-known-absent-property-keys

Conversation

@marandaneto

@marandaneto marandaneto commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

💡 Motivation and Context

Local flag evaluation treats a property key that the caller left out of $personProperties as unknown. The SDK can't tell "this person has no plan" apart from "the caller didn't send plan". So any condition on plan is 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 /flags result 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:

New input

Every flag method that takes $personProperties and $groupProperties now 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() and fetchFeatureVariants(). It also covers the deprecated getFeatureFlag(), getFeatureFlagResult(), isFeatureEnabled() and getFeatureFlagPayload(). The static PostHog:: methods and the Laravel manager forward both parameters. The Laravel manager's evaluateFlags() snapshot cache key includes them.

$flags = PostHog::evaluateFlags(
    distinctId: 'user-123',
    groups: ['company' => 'acme'],
    personProperties: ['email' => 'jane@example.com'],
    personPropertyKeysKnownAbsent: ['plan'],
    groupPropertyKeysKnownAbsent: ['company' => ['tier']],
);

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_with and not_regex match.
  • is_set and every other supported operator don't match. This includes exact, icontains, regex, the number and date comparisons, and all semver_* operators.
  • A listed key counts as absent even when the caller also passed a value for it. This also overrides values the SDK adds itself, such as distinct_id and $group_key.
  • Unsupported operators and malformed filters are checked first, as before. They stay inconclusive and still fall back to /flags, even for a listed key.
  • Operator support is checked before the known-absent table, in flag conditions and in dynamic cohort leaves, as required by the latest spec revision (docs(flags): specify known-absent property keys sdk-specs#233). testDynamicCohortUnsupportedLeafOnKnownAbsentKeyFallsBack covers a not_between [1, 2] cohort leaf on a listed key, with and without negation.
  • A key that is left out and not listed stays inconclusive, exactly as today.
  • Person keys that start with __posthog_person_metadata__ are ignored.
  • Group keys only apply to their own group type. This includes conditions inside a flag that targets more than one aggregation.
  • Property filters inside a dynamic cohort use the listed keys. The filter's negation is applied after that.
  • Flag dependencies are evaluated with the same listed keys. Static cohorts and holdouts are not affected.

/flags request body

When the SDK calls /flags and the caller passed keys, it adds person_property_keys_known_absent (a list) and group_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 InvalidArgumentException before 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 and PostHogFake::evaluateFlags() run the same check before they return early, for example when there is no distinct ID.

Not included

Release note

The changeset marks both posthog-php and posthog-laravel as 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 example disableGeoip in #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:

  • the operator table for a listed key
  • a listed key overriding a supplied value and the injected distinct_id and $group_key
  • an unlisted missing key staying inconclusive
  • the metadata prefix being ignored
  • group-type scoping, including a flag that targets more than one aggregation
  • unsupported operators on a listed key still falling back, in flag conditions and in dynamic cohort leaves
  • cohort negation and a flag dependency
  • the /flags body including the fields on fallback and leaving them out when not passed
  • the deprecated methods
  • the 1000-key limit and invalid input failing without a request

New tests in packages/laravel/tests/RuntimeTest.php cover forwarding and snapshot caching. They also check that the 1000-key limit applies with no identity and in PostHogFake.

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 on main.
  • CI picked up PHP 8.4.28 and 8.5.13, which broke JsonEncoderTest::testMalformedKeysRetainErrorsAndNativeCallbackOrdering for 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 match main.
  • ./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:check and composer api:check:laravel: both snapshots are up to date.
  • bash scripts/test-laravel.sh 12 and bash 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 /health only declares capture_v0 and encoding_gzip, not feature_flags_local_evaluation_v1 and feature_flags_known_absent_v1.

📝 Checklist

  • All commits are signed (see Commit signing)
  • I reviewed the submitted code.
  • I added tests to verify the changes.
  • I updated the docs if needed.
  • No breaking change or entry added to the changelog.

If releasing new changes

  • Ran pnpm change to generate a change intent file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

  • Written with Pi agents running Claude. A separate review model (GPT) reviewed the branch diff three times.
  • Review fixes: the Laravel manager and PostHogFake::evaluateFlags() now check the key limit before their early returns. To share that check, Client::assertKnownAbsentKeysValid() is a public static method marked @internal.
  • Rejected review findings: the review said the minor bump breaks old subclass overrides. This repo has shipped the same kind of change as minor before. The review also said Laravel needs a newer minimum core version. Laravel already pins an exact core version, and the release process sets it to the new core version.

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.
@marandaneto marandaneto self-assigned this Nov 19, 2026
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

posthog-php-lib_curl Compliance Report

Date: 2026-11-20T10:48:33.380274+00:00
Duration: 118924ms

✅ All Tests Passed!

47/47 tests passed


Capture Tests

✅ 30/30 tests passed

View Details
Test Status Duration
Format Validation.Event Has Required Fields ✅ 29ms
Format Validation.Event Has Uuid ✅ 526ms
Format Validation.Event Has Lib Properties ✅ 525ms
Format Validation.Distinct Id Is String ✅ 526ms
Format Validation.Token Is Present ✅ 526ms
Format Validation.Custom Properties Preserved ✅ 526ms
Format Validation.Event Has Timestamp ✅ 525ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc ✅ 526ms
Retry Behavior.Retries On 503 ✅ 5834ms
Retry Behavior.Does Not Retry On 400 ✅ 2527ms
Retry Behavior.Does Not Retry On 401 ✅ 2530ms
Retry Behavior.Respects Retry After Header ✅ 8534ms
Retry Behavior.Implements Backoff ✅ 16248ms
Retry Behavior.Retries On 500 ✅ 5633ms
Retry Behavior.Retries On 502 ✅ 5635ms
Retry Behavior.Retries On 504 ✅ 5634ms
Retry Behavior.Max Retries Respected ✅ 17048ms
Deduplication.Generates Unique Uuids ✅ 233ms
Deduplication.Preserves Uuid On Retry ✅ 5634ms
Deduplication.Preserves Uuid And Timestamp On Retry ✅ 10833ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 5142ms
Deduplication.No Duplicate Events In Batch ✅ 532ms
Deduplication.Different Events Have Different Uuids ✅ 529ms
Compression.Sends Gzip When Enabled ✅ 526ms
Batch Format.Uses Proper Batch Structure ✅ 527ms
Batch Format.Flush With No Events Sends Nothing ✅ 521ms
Batch Format.Multiple Events Batched Together ✅ 513ms
Error Handling.Does Not Retry On 403 ✅ 2528ms
Error Handling.Does Not Retry On 413 ✅ 2528ms
Error Handling.Retries On 408 ✅ 5636ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id ✅ 526ms
Request Payload.Flags Request Uses V2 Query Param ✅ 524ms
Request Payload.Flags Request Hits Flags Path Not Decide ✅ 523ms
Request Payload.Flags Request Omits Authorization Header ✅ 523ms
Request Payload.Token In Flags Body Matches Init ✅ 526ms
Request Payload.Groups Round Trip ✅ 523ms
Request Payload.Groups Default To Empty Object ✅ 523ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False ✅ 523ms
Request Payload.Disable Geoip Omitted Defaults To False ✅ 524ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key ✅ 524ms
Request Lifecycle.No Flags Request On Init Alone ✅ 520ms
Request Lifecycle.No Flags Request On Normal Capture ✅ 509ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests ✅ 528ms
Request Lifecycle.Mock Response Value Is Returned To Caller ✅ 525ms
Retry Behavior.Retries Flags On 502 ✅ 626ms
Retry Behavior.Retries Flags On 504 ✅ 626ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event ✅ 527ms

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

posthog-php-fork_curl Compliance Report

Date: 2026-11-20T10:48:09.167099+00:00
Duration: 118313ms

✅ All Tests Passed!

47/47 tests passed


Capture Tests

✅ 30/30 tests passed

View Details
Test Status Duration
Format Validation.Event Has Required Fields ✅ 33ms
Format Validation.Event Has Uuid ✅ 532ms
Format Validation.Event Has Lib Properties ✅ 528ms
Format Validation.Distinct Id Is String ✅ 528ms
Format Validation.Token Is Present ✅ 528ms
Format Validation.Custom Properties Preserved ✅ 528ms
Format Validation.Event Has Timestamp ✅ 529ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc ✅ 528ms
Retry Behavior.Retries On 503 ✅ 5850ms
Retry Behavior.Does Not Retry On 400 ✅ 2529ms
Retry Behavior.Does Not Retry On 401 ✅ 2529ms
Retry Behavior.Respects Retry After Header ✅ 8543ms
Retry Behavior.Implements Backoff ✅ 16274ms
Retry Behavior.Retries On 500 ✅ 5644ms
Retry Behavior.Retries On 502 ✅ 5640ms
Retry Behavior.Retries On 504 ✅ 5644ms
Retry Behavior.Max Retries Respected ✅ 16272ms
Deduplication.Generates Unique Uuids ✅ 535ms
Deduplication.Preserves Uuid On Retry ✅ 5643ms
Deduplication.Preserves Uuid And Timestamp On Retry ✅ 10849ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 5152ms
Deduplication.No Duplicate Events In Batch ✅ 532ms
Deduplication.Different Events Have Different Uuids ✅ 530ms
Compression.Sends Gzip When Enabled ✅ 530ms
Batch Format.Uses Proper Batch Structure ✅ 527ms
Batch Format.Flush With No Events Sends Nothing ✅ 518ms
Batch Format.Multiple Events Batched Together ✅ 518ms
Error Handling.Does Not Retry On 403 ✅ 2530ms
Error Handling.Does Not Retry On 413 ✅ 2531ms
Error Handling.Retries On 408 ✅ 5642ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id ✅ 521ms
Request Payload.Flags Request Uses V2 Query Param ✅ 521ms
Request Payload.Flags Request Hits Flags Path Not Decide ✅ 521ms
Request Payload.Flags Request Omits Authorization Header ✅ 521ms
Request Payload.Token In Flags Body Matches Init ✅ 520ms
Request Payload.Groups Round Trip ✅ 522ms
Request Payload.Groups Default To Empty Object ✅ 521ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False ✅ 521ms
Request Payload.Disable Geoip Omitted Defaults To False ✅ 521ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key ✅ 521ms
Request Lifecycle.No Flags Request On Init Alone ✅ 517ms
Request Lifecycle.No Flags Request On Normal Capture ✅ 514ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests ✅ 523ms
Request Lifecycle.Mock Response Value Is Returned To Caller ✅ 522ms
Retry Behavior.Retries Flags On 502 ✅ 624ms
Retry Behavior.Retries Flags On 504 ✅ 623ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event ✅ 529ms

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

posthog-php-socket Compliance Report

Date: 2026-11-20T10:48:48.208313+00:00
Duration: 118769ms

✅ All Tests Passed!

47/47 tests passed


Capture Tests

✅ 30/30 tests passed

View Details
Test Status Duration
Format Validation.Event Has Required Fields ✅ 27ms
Format Validation.Event Has Uuid ✅ 523ms
Format Validation.Event Has Lib Properties ✅ 526ms
Format Validation.Distinct Id Is String ✅ 524ms
Format Validation.Token Is Present ✅ 525ms
Format Validation.Custom Properties Preserved ✅ 526ms
Format Validation.Event Has Timestamp ✅ 524ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc ✅ 524ms
Retry Behavior.Retries On 503 ✅ 5832ms
Retry Behavior.Does Not Retry On 400 ✅ 2528ms
Retry Behavior.Does Not Retry On 401 ✅ 2527ms
Retry Behavior.Respects Retry After Header ✅ 8533ms
Retry Behavior.Implements Backoff ✅ 16244ms
Retry Behavior.Retries On 500 ✅ 5635ms
Retry Behavior.Retries On 502 ✅ 5634ms
Retry Behavior.Retries On 504 ✅ 5633ms
Retry Behavior.Max Retries Respected ✅ 16248ms
Deduplication.Generates Unique Uuids ✅ 532ms
Deduplication.Preserves Uuid On Retry ✅ 5634ms
Deduplication.Preserves Uuid And Timestamp On Retry ✅ 10840ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 5636ms
Deduplication.No Duplicate Events In Batch ✅ 530ms
Deduplication.Different Events Have Different Uuids ✅ 527ms
Compression.Sends Gzip When Enabled ✅ 525ms
Batch Format.Uses Proper Batch Structure ✅ 525ms
Batch Format.Flush With No Events Sends Nothing ✅ 520ms
Batch Format.Multiple Events Batched Together ✅ 512ms
Error Handling.Does Not Retry On 403 ✅ 2526ms
Error Handling.Does Not Retry On 413 ✅ 2530ms
Error Handling.Retries On 408 ✅ 5632ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id ✅ 525ms
Request Payload.Flags Request Uses V2 Query Param ✅ 523ms
Request Payload.Flags Request Hits Flags Path Not Decide ✅ 523ms
Request Payload.Flags Request Omits Authorization Header ✅ 523ms
Request Payload.Token In Flags Body Matches Init ✅ 523ms
Request Payload.Groups Round Trip ✅ 523ms
Request Payload.Groups Default To Empty Object ✅ 523ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False ✅ 522ms
Request Payload.Disable Geoip Omitted Defaults To False ✅ 523ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key ✅ 523ms
Request Lifecycle.No Flags Request On Init Alone ✅ 518ms
Request Lifecycle.No Flags Request On Normal Capture ✅ 509ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests ✅ 527ms
Request Lifecycle.Mock Response Value Is Returned To Caller ✅ 525ms
Retry Behavior.Retries Flags On 502 ✅ 624ms
Retry Behavior.Retries Flags On 504 ✅ 626ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event ✅ 525ms

@marandaneto
marandaneto marked this pull request as ready for review November 20, 2026 10:28
@marandaneto
marandaneto requested a review from a team as a code owner November 20, 2026 10:28
@veria-ai

veria-ai Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

PR overview

No security issues were found in this pull request.

Reviews

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread lib/Client.php
Comment on lines +1826 to +1835
$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);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant