diff --git a/.changeset/every-cases-sleep.md b/.changeset/every-cases-sleep.md new file mode 100644 index 0000000..fa02346 --- /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 689550f..67827cb 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 5ac53e8..1951d98 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 b61b66f..5e31530 100644 --- a/test/FeatureFlagEvaluationsTest.php +++ b/test/FeatureFlagEvaluationsTest.php @@ -235,6 +235,47 @@ 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')); + 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 + { + $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();