feat: add caller-supplied default value to FeatureFlagEvaluations::isEnabled()

.changeset/feature-flag-evaluations-default-value.md

@@ -0,0 +1,5 @@
+---
+"posthog-php": minor
+---
+
+Add an optional `$defaultValue` parameter to `FeatureFlagEvaluations::isEnabled()`. Previously, an unknown/unresolved flag always collapsed to `false` with no way for a caller to distinguish "flag is off" from "flag has no value" — the spec requires the SDK to return a caller-supplied default in that case. `isEnabled($key, defaultValue: true)` now returns `true` when the flag has no resolvable value; a flag with a real value, including `false`, always wins over the default. Existing callers who don't pass it see identical behavior.

api/public-api.json

@@ -2695,6 +2695,16 @@
                             "default": null,
                             "defaultConstant": null,
                             "hasDefault": false
+                        },
+                        {
+                            "name": "defaultValue",
+                            "type": "bool",
+                            "byReference": false,
+                            "variadic": false,
+                            "optional": true,
+                            "default": false,
+                            "defaultConstant": null,
+                            "hasDefault": true
                         }
                     ]
                 },

lib/FeatureFlagEvaluations.php

@@ -52,17 +52,19 @@ public function getKeys(): 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
+     * unknown keys; a flag with a real value (including false) always takes precedence.
      *
      * @param string $key Feature flag key.
+     * @param bool $defaultValue Value to return when the flag has no resolvable value.
      * @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;
     }
 
     /**

test/FeatureFlagEvaluationsTest.php

@@ -181,6 +181,34 @@ public function testUnknownKeyAccessRecordsFlagMissingError(): void
         $this->assertSame('flag_missing', $properties['$feature_flag_error']);
     }
 
+    public function testIsEnabledReturnsCallerSuppliedDefaultForUnknownKey(): void
+    {
+        $host = new FakeFlagEvaluationsHost();
+        $snapshot = new FeatureFlagEvaluations(
+            'user-1',
+            [],
+            [],
+            $host
+        );
+
+        $this->assertTrue($snapshot->isEnabled('does-not-exist', true));
+        $this->assertFalse($snapshot->isEnabled('does-not-exist'));
+        $this->assertFalse($snapshot->isEnabled('does-not-exist', false));
+    }
+
+    public function testIsEnabledDefaultDoesNotOverrideARealFalseValue(): void
+    {
+        $host = new FakeFlagEvaluationsHost();
+        $snapshot = new FeatureFlagEvaluations(
+            'user-1',
+            ['flag-a' => $this->makeRecord('flag-a', false)],
+            [],
+            $host
+        );
+
+        $this->assertFalse($snapshot->isEnabled('flag-a', true));
+    }
+
     public function testOnlyWarnsOnUnknownKeys(): void
     {
         $host = new FakeFlagEvaluationsHost();