fix(flags): handle empty evaluation key scopes

[marandaneto]

💡 Motivation and Context

The feature flag evaluation scope needs to distinguish between a scope that was not provided and a scope that was explicitly empty. This follows the behavior defined in sdk-specs PR #47.

When the flag key list is omitted or null, the SDK continues to evaluate all applicable flags. When the caller provides an empty list, the SDK now returns an empty snapshot without local evaluation or a /flags request. When the caller provides a non-empty list, the SDK continues to evaluate and request only those keys.

The change adds an early return for the explicit empty-list case, documents that behavior on evaluateFlags, and includes regression coverage that verifies no evaluation request is made.

💚 How did you test it?

• vendor/bin/phpunit --no-coverage --display-phpunit-deprecations --filter '/(testEvaluateFlagsReturnsSnapshotAndMakesOneFlagsRequest|testEmptyFlagKeysReturnsEmptySnapshotWithoutEvaluationRequests|testFlagKeysIsForwardedInRequestBody)$/' test/FeatureFlagEvaluationsTest.php passed 3 tests with 10 assertions. One unrelated existing doc-comment metadata deprecation remains.
• vendor/bin/phpcs -n lib/Client.php test/FeatureFlagEvaluationsTest.php passed.
• php -l lib/Client.php && php -l test/FeatureFlagEvaluationsTest.php passed.
• git diff --check origin/main...HEAD passed.
• pnpm change status recognized the patch intent and planned posthog-php 4.13.4.

📝 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

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

OpenAI Codex (gpt-5.6-sol) through Pi applied the requested PR workflow and ran the Pi autoreview tool. The Pi session is local and does not have a shareable URL. The implementation keeps the omitted and non-empty behavior unchanged and only short-circuits an explicitly empty key list.

[github-actions]

posthog-php Compliance Report

Date: 2026-08-25 12:48:36 UTC
Duration: 95154ms

✅ All Tests Passed!

46/46 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	9ms
Format Validation.Event Has Uuid	✅	4ms
Format Validation.Event Has Lib Properties	✅	5ms
Format Validation.Distinct Id Is String	✅	4ms
Format Validation.Token Is Present	✅	5ms
Format Validation.Custom Properties Preserved	✅	4ms
Format Validation.Event Has Timestamp	✅	4ms
Retry Behavior.Retries On 503	✅	5314ms
Retry Behavior.Does Not Retry On 400	✅	2007ms
Retry Behavior.Does Not Retry On 401	✅	2007ms
Retry Behavior.Respects Retry After Header	✅	8013ms
Retry Behavior.Implements Backoff	✅	15727ms
Retry Behavior.Retries On 500	✅	5113ms
Retry Behavior.Retries On 502	✅	5113ms
Retry Behavior.Retries On 504	✅	5113ms
Retry Behavior.Max Retries Respected	✅	16527ms
Deduplication.Generates Unique Uuids	✅	9ms
Deduplication.Preserves Uuid On Retry	✅	5112ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10320ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5113ms
Deduplication.No Duplicate Events In Batch	✅	9ms
Deduplication.Different Events Have Different Uuids	✅	5ms
Compression.Sends Gzip When Enabled	✅	5ms
Batch Format.Uses Proper Batch Structure	✅	4ms
Batch Format.Flush With No Events Sends Nothing	✅	3ms
Batch Format.Multiple Events Batched Together	✅	7ms
Error Handling.Does Not Retry On 403	✅	2007ms
Error Handling.Does Not Retry On 413	✅	2007ms
Error Handling.Retries On 408	✅	5114ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

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

[greptile-apps]

_{Reviews (1): Last reviewed commit: "fix(flags): handle empty evaluation key ..." | Re-trigger Greptile}