From 5003272e5cba7955d8039f7e326f5593651007ef Mon Sep 17 00:00:00 2001
From: Manoel Aranda Neto <marandaneto@gmail.com>
Date: Tue, 25 Aug 2026 12:57:20 +0200
Subject: [PATCH 1/2] fix(flags): handle empty evaluation key scopes

---
 .changeset/empty-scopes-stop.md     |  5 +++++
 lib/Client.php                      |  9 +++++++++
 test/FeatureFlagEvaluationsTest.php | 13 +++++++++++++
 3 files changed, 27 insertions(+)
 create mode 100644 .changeset/empty-scopes-stop.md

diff --git a/.changeset/empty-scopes-stop.md b/.changeset/empty-scopes-stop.md
new file mode 100644
index 0000000..092b412
--- /dev/null
+++ b/.changeset/empty-scopes-stop.md
@@ -0,0 +1,5 @@
+---
+'posthog-php': patch
+---
+
+Return an empty feature flag snapshot without evaluation requests when the requested flag key list is empty.
diff --git a/lib/Client.php b/lib/Client.php
index 6fd0e85..fc57574 100644
--- a/lib/Client.php
+++ b/lib/Client.php
@@ -1069,6 +1069,15 @@ public function evaluateFlags(
             );
         }
 
+        if ($flagKeys === []) {
+            return new FeatureFlagEvaluations(
+                $distinctId,
+                [],
+                $groups,
+                $this,
+            );
+        }
+
         [$personProperties, $groupProperties] = $this->addLocalPersonAndGroupProperties(
             $groups,
             $personProperties,
diff --git a/test/FeatureFlagEvaluationsTest.php b/test/FeatureFlagEvaluationsTest.php
index 3c59364..0c8fa12 100644
--- a/test/FeatureFlagEvaluationsTest.php
+++ b/test/FeatureFlagEvaluationsTest.php
@@ -289,6 +289,19 @@ public function testCaptureFlagsAttachesFeaturePropertiesWithoutHttpRequest(): v
         }
     }
 
+    public function testEmptyFlagKeysReturnsEmptySnapshotWithoutEvaluationRequests(): void
+    {
+        $this->makeClient();
+        $callsBefore = count($this->http_client->calls ?? []);
+
+        $snapshot = PostHog::evaluateFlags('user-1', flagKeys: []);
+
+        $this->assertInstanceOf(FeatureFlagEvaluations::class, $snapshot);
+        $this->assertSame([], $snapshot->getKeys());
+        $this->assertCount($callsBefore, $this->http_client->calls ?? []);
+        $this->assertSame(0, $this->flagsRequestCount());
+    }
+
     public function testFlagKeysIsForwardedInRequestBody(): void
     {
         $this->makeClient();

From 43b5a0fa62c5cf5d1570c788cc7ffaf2df20b3f0 Mon Sep 17 00:00:00 2001
From: Manoel Aranda Neto <marandaneto@gmail.com>
Date: Tue, 25 Aug 2026 14:45:51 +0200
Subject: [PATCH 2/2] docs(flags): document empty evaluation scopes

---
 lib/Client.php | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/lib/Client.php b/lib/Client.php
index fc57574..8f496b4 100644
--- a/lib/Client.php
+++ b/lib/Client.php
@@ -1044,9 +1044,10 @@ public function getAllFlags(
      * @param bool $disableGeoip Whether to disable GeoIP enrichment during remote evaluation.
      * @param list<string>|null $flagKeys Optional list of flag keys. When provided, only these
      *     flags are evaluated — the underlying /flags request asks the server for just this
-     *     subset, which makes the response smaller and the request cheaper. Use this when you
-     *     only need a handful of flags out of many. Distinct from FeatureFlagEvaluations::only(),
-     *     which scopes which already-evaluated flags get attached to a captured event.
+     *     subset, which makes the response smaller and the request cheaper. An empty list returns
+     *     an empty snapshot without local or remote evaluation. Use this when you only need a
+     *     handful of flags out of many. Distinct from FeatureFlagEvaluations::only(), which scopes
+     *     which already-evaluated flags get attached to a captured event.
      * @return FeatureFlagEvaluations
      */
     public function evaluateFlags(