From 4647db124ddd05b1d779ffa12edf84941f940fb3 Mon Sep 17 00:00:00 2001 From: "posthog[bot]" <206114724+posthog[bot]@users.noreply.github.com> Date: Tue, 17 Nov 2026 14:09:34 +0000 Subject: [PATCH 1/2] feat(flags): accept a caller default on FeatureFlagEvaluations::isEnabled() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The is-feature-enabled contract requires the SDK to accept a caller-supplied boolean default and return it whenever the flag has no value — unknown key, flags never loaded, failed request — while any value the flag does have, including false, wins over it. The snapshot's isEnabled() hardcoded false for every miss, so a genuinely disabled flag and a flag with no value at all were indistinguishable. Add an optional $defaultValue parameter, returned only when the snapshot holds no record for the key. The default stays false, so existing callers are unchanged. The deprecated Client::isFeatureEnabled() is left as is. Co-Authored-By: Claude Opus 5 Generated-By: PostHog Desktop Task-Id: 8e05f524-d4d3-4802-be50-f997b9c60502 --- .changeset/every-cases-sleep.md | 5 +++++ api/public-api.json | 10 +++++++++ lib/FeatureFlagEvaluations.php | 10 ++++++--- test/FeatureFlagEvaluationsTest.php | 33 +++++++++++++++++++++++++++++ 4 files changed, 55 insertions(+), 3 deletions(-) create mode 100644 .changeset/every-cases-sleep.md diff --git a/.changeset/every-cases-sleep.md b/.changeset/every-cases-sleep.md new file mode 100644 index 00000000..fa02346b --- /dev/null +++ b/.changeset/every-cases-sleep.md @@ -0,0 +1,5 @@ +--- +"posthog-php": minor +--- + +FeatureFlagEvaluations::isEnabled() takes an optional defaultValue, returned when the snapshot holds no value for the flag; a flag that has a value, including false, still wins. diff --git a/api/public-api.json b/api/public-api.json index 689550f8..67827cb7 100644 --- a/api/public-api.json +++ b/api/public-api.json @@ -3458,6 +3458,16 @@ "default": null, "defaultConstant": null, "hasDefault": false + }, + { + "name": "defaultValue", + "type": "bool", + "byReference": false, + "variadic": false, + "optional": true, + "default": false, + "defaultConstant": null, + "hasDefault": true } ] }, diff --git a/lib/FeatureFlagEvaluations.php b/lib/FeatureFlagEvaluations.php index 5ac53e89..1951d98d 100644 --- a/lib/FeatureFlagEvaluations.php +++ b/lib/FeatureFlagEvaluations.php @@ -72,17 +72,21 @@ public function getUnresolvedFlags(): array } /** - * Whether the flag is enabled for the snapshot's distinct id. Returns false for unknown keys. + * Whether the flag is enabled for the snapshot's distinct id. Returns $defaultValue for keys + * the snapshot holds no value for. * * @param string $key Feature flag key. + * @param bool $defaultValue Returned when the snapshot has no value for $key: the flag is + * unknown, the flags request failed, or local evaluation stayed unresolved. A flag that + * has a value — including false — always wins over this default. * @return bool */ - public function isEnabled(string $key): bool + public function isEnabled(string $key, bool $defaultValue = false): bool { $record = $this->flags[$key] ?? null; $this->recordAccess($key, $record); - return $record?->enabled ?? false; + return $record?->enabled ?? $defaultValue; } /** diff --git a/test/FeatureFlagEvaluationsTest.php b/test/FeatureFlagEvaluationsTest.php index b61b66fa..f8dc1e5e 100644 --- a/test/FeatureFlagEvaluationsTest.php +++ b/test/FeatureFlagEvaluationsTest.php @@ -235,6 +235,39 @@ public function testGetFlagPayloadDoesNotFireEvent(): void $this->assertSame(1, $this->flagsRequestCount()); } + public function testIsEnabledResolvesMissingFlagsToTheCallerDefault(): void + { + $this->makeClient(); + $snapshot = PostHog::evaluateFlags('user-1'); + + $this->assertTrue($snapshot->isEnabled('does-not-exist', true)); + $this->assertFalse($snapshot->isEnabled('does-not-exist', false)); + $this->assertFalse($snapshot->isEnabled('does-not-exist')); + } + + public function testIsEnabledPrefersTheFlagValueOverTheCallerDefault(): void + { + $this->makeClient(); + $snapshot = PostHog::evaluateFlags('user-1'); + + $this->assertFalse($snapshot->isEnabled('having_fun', true)); + $this->assertTrue($snapshot->isEnabled('multivariate-test', false)); + $this->assertTrue($snapshot->isEnabled('simple-test', false)); + } + + public function testIsEnabledUsesTheCallerDefaultForUnresolvedAndFilteredOutFlags(): void + { + $this->makeLocalClient(self::localDefinitions( + self::localFlag('beta-ui'), + self::localFlag('checkout', continuity: true), + )); + + $snapshot = $this->client->evaluateFlags('user-123', onlyEvaluateLocally: true); + + $this->assertTrue($snapshot->isEnabled('checkout', true)); + $this->assertTrue($snapshot->only(['beta-ui'])->isEnabled('checkout', true)); + } + public function testUnknownKeyAccessRecordsFlagMissingError(): void { $this->makeClient(); From 947c3ccfea9d44f2892cc0eefe22fe5f0922dc20 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Wed, 18 Nov 2026 19:40:38 -0500 Subject: [PATCH 2/2] test(flags): assert caller default never reaches the $feature_flag_called event A missing key read with defaultValue true must still report a null $feature_flag_response and flag_missing, per evaluate-flags spec scenario "Supported caller defaults affect only missing enablement". Co-Authored-By: Claude Opus 5.5 --- test/FeatureFlagEvaluationsTest.php | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/test/FeatureFlagEvaluationsTest.php b/test/FeatureFlagEvaluationsTest.php index f8dc1e5e..5e315303 100644 --- a/test/FeatureFlagEvaluationsTest.php +++ b/test/FeatureFlagEvaluationsTest.php @@ -243,6 +243,14 @@ public function testIsEnabledResolvesMissingFlagsToTheCallerDefault(): void $this->assertTrue($snapshot->isEnabled('does-not-exist', true)); $this->assertFalse($snapshot->isEnabled('does-not-exist', false)); $this->assertFalse($snapshot->isEnabled('does-not-exist')); + PostHog::flush(); + + $batches = $this->batchRequests(); + $this->assertCount(1, $batches); + $this->assertCount(1, $batches[0]['batch']); + $properties = $batches[0]['batch'][0]['properties']; + $this->assertNull($properties['$feature_flag_response']); + $this->assertSame('flag_missing', $properties['$feature_flag_error']); } public function testIsEnabledPrefersTheFlagValueOverTheCallerDefault(): void