fix(flags): honor versioned local property matching

[marandaneto]

💡 Motivation and Context

Local feature flag evaluation needs to honor the matching version returned with flag definitions. This follows the backend behavior in PostHog/posthog#90694 and shared contract in PostHog/sdk-specs#59.

• Missing metadata, version 1, and unsupported selectors keep released legacy matching. Only integer version 2 enables explicit scalar equality and member equality for nonempty filter arrays, using existing string and Unicode normalization. Empty filters retain recursive truthiness. For known properties, is_not complements exact. Missing properties still allow remote fallback.
• The API response projection and external cache provider projection both retain property_matching_version. Providers receive the complete normalized snapshot for storage. Cache reads without the selector reset to legacy matching. The existing groupTypeMapping alias remains supported for group mapping, not for version metadata.
• Each local evaluation captures definitions, their index, group mapping, cohorts, and matching version together. Person, group, mixed-group, cohort, and dependency evaluation use that snapshot. Version-only reloads take effect on the next evaluation. Failed loads and HTTP 304 responses preserve the previous snapshot.
• Five public FeatureFlag evaluation helpers gain a trailing optional propertyMatchingVersion parameter defaulting to 1. Existing calls remain compatible, and the public API snapshot records the additions. The external cache provider contract documents preserving the metadata. The existing patch change intent is included.

Related optional harness coverage is PostHog/posthog-sdk-test-harness#53. This PR does not opt a PHP adapter into that coverage.

💚 How did you test it?

Reran these checks on the source tree committed as 65ca15245e9c4d19b5311e285a3833fec6c0d2ad with PHP 8.5.10 and PHPUnit 11.5.55:

./vendor/bin/phpunit --bootstrap vendor/autoload.php --configuration phpunit.xml --no-coverage --filter 'VersionedPropertyMatchingTest|testMatchingVersionSurvivesApiAndProviderRoundTrip|testVersionOnly|testReloadDuringEvaluation|testVersionedMissing'
php scripts/check-public-api.php
./vendor/bin/phpcs --standard=phpcs.xml -n lib/FeatureFlag.php lib/Client.php lib/FlagDefinitionCacheProvider.php test/VersionedPropertyMatchingTest.php test/FlagDefinitionCacheProviderTest.php
git diff --check

All exited successfully. The focused run passed 195 tests and 613 assertions, with 42 existing PHPUnit metadata deprecations. Tests exercise the real Client and evaluator with mocked HTTP/provider boundaries, including cache round-trips, version-only transitions, nested conditions, reentrant reloads, and remote fallback. Positive local cases permit fallback and assert that no remote flag request occurs.

Earlier implementation validation passed the broader flag suite with 471 tests and 3819 assertions. That earlier run reported four existing SDK deprecated-method notices as well as the metadata deprecations. PHPCS without -n previously reported 13 unchanged-line length warnings and no errors. The complete unrelated suite, coverage, and live-service integration were not run in this publication pass. Local checks are not a CI result.

The required isolated committed-branch autoreview passed for this exact commit against origin/main at 6da44cd256743e9ba08c14a685dc8e8c5ac1e561, with no actionable findings.

📝 Checklist

• 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

The existing .changeset/versioned-property-matching.md records a patch intent. It was preserved without rerunning the generator or adding a duplicate.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Pi agents assisted implementation and publication under human direction. Tools used included Git, PHP, PHPUnit, PHP_CodeSniffer, GitHub CLI, and the isolated Pi autoreview helper with TruffleHog. The local agent session is not publicly shared.

The implementation preserves legacy defaults and optional helper arguments while keeping matching metadata with each definition snapshot. Publication retained the approved changes and used a new signed commit without rewriting history. Human review is required before merging.

[github-actions]

posthog-php Compliance Report

Date: 2026-09-05 11:56:30 UTC
Duration: 95333ms

✅ All Tests Passed!

46/46 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	12ms
Format Validation.Event Has Uuid	✅	5ms
Format Validation.Event Has Lib Properties	✅	6ms
Format Validation.Distinct Id Is String	✅	6ms
Format Validation.Token Is Present	✅	6ms
Format Validation.Custom Properties Preserved	✅	6ms
Format Validation.Event Has Timestamp	✅	6ms
Retry Behavior.Retries On 503	✅	5315ms
Retry Behavior.Does Not Retry On 400	✅	2009ms
Retry Behavior.Does Not Retry On 401	✅	2010ms
Retry Behavior.Respects Retry After Header	✅	8014ms
Retry Behavior.Implements Backoff	✅	15730ms
Retry Behavior.Retries On 500	✅	5114ms
Retry Behavior.Retries On 502	✅	5115ms
Retry Behavior.Retries On 504	✅	5115ms
Retry Behavior.Max Retries Respected	✅	16530ms
Deduplication.Generates Unique Uuids	✅	12ms
Deduplication.Preserves Uuid On Retry	✅	5115ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10322ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5116ms
Deduplication.No Duplicate Events In Batch	✅	12ms
Deduplication.Different Events Have Different Uuids	✅	6ms
Compression.Sends Gzip When Enabled	✅	6ms
Batch Format.Uses Proper Batch Structure	✅	5ms
Batch Format.Flush With No Events Sends Nothing	✅	4ms
Batch Format.Multiple Events Batched Together	✅	10ms
Error Handling.Does Not Retry On 403	✅	2008ms
Error Handling.Does Not Retry On 413	✅	2009ms
Error Handling.Retries On 408	✅	5115ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

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

[greptile-apps]

_{Reviews (1): Last reviewed commit: "fix(flags): honor versioned local proper..." | Re-trigger Greptile}