From baa1215311f5cc83ef61e6f99ff3fced0f8793fa Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Fri, 6 Nov 2026 13:21:32 +0100 Subject: [PATCH 1/4] fix(flags): skip client-only definition warnings --- .changeset/kind-waves-sip.md | 5 + lib/Client.php | 35 ++++- test/FlagDefinitionCacheProviderTest.php | 176 ++++++++++++++++++++++- 3 files changed, 203 insertions(+), 13 deletions(-) create mode 100644 .changeset/kind-waves-sip.md diff --git a/.changeset/kind-waves-sip.md b/.changeset/kind-waves-sip.md new file mode 100644 index 00000000..490168f0 --- /dev/null +++ b/.changeset/kind-waves-sip.md @@ -0,0 +1,5 @@ +--- +"posthog-php": patch +--- + +Suppress definition-load warnings for client-only flags and reconcile warnings on shared-cache loads without repeating unchanged definitions. diff --git a/lib/Client.php b/lib/Client.php index d5c82969..b7ba0836 100644 --- a/lib/Client.php +++ b/lib/Client.php @@ -1879,9 +1879,6 @@ private function fetchAndApplyFlagDefinitionsFromApi(): void $data = $this->normalizeFlagDefinitionData($payload); $this->applyFlagDefinitions($data); - // Only a fresh response warns: PHP builds a client per request, and a 304 or a shared-cache - // load carries definitions that a fresh response already warned about. - $this->warnAboutUnresolvableFlags(); $this->storeFlagDefinitionsInCacheProvider($data); } @@ -1897,12 +1894,15 @@ private function warnAboutUnresolvableFlags(): void UnresolvedFlagReason::EXPERIENCE_CONTINUITY => [], UnresolvedFlagReason::UNSUPPORTED_DEFINITION => [], ]; - // Rebuilt from the current definitions, so a flag that is deleted or becomes resolvable is - // forgotten and warns again if it later returns to an unresolvable definition. + // Rebuilt from the current definitions, so deleted, resolvable or client-only flags are + // forgotten and warn again if they later return to an eligible unresolvable definition. $warnedFlags = []; $uncheckedFlags = []; foreach ($this->featureFlags as $flag) { - if (!is_array($flag) || !is_string($flag['key'] ?? null)) { + if ( + !is_array($flag) || !is_string($flag['key'] ?? null) + || ($flag['evaluation_runtime'] ?? null) === 'client' + ) { continue; } try { @@ -1920,7 +1920,8 @@ private function warnAboutUnresolvableFlags(): void if ($reason === null) { continue; } - $fingerprint = ($flag['version'] ?? '') . ':' . sha1(serialize($flag)) . ':' . $reason; + $fingerprint = ($flag['version'] ?? '') . ':' + . sha1(serialize($this->sortFlagDefinitionKeys($flag))) . ':' . $reason; $warnedFlags[$flag['key']] = $fingerprint; if (($this->warnedUnresolvableFlags[$flag['key']] ?? null) !== $fingerprint) { $flagKeysByReason[$reason][] = $flag['key']; @@ -1966,6 +1967,25 @@ private function warnAboutUnresolvableFlags(): void } } + /** + * Sort object keys recursively for warning deduplication without changing condition list order. + * + * @param array $definition + * @return array + */ + private function sortFlagDefinitionKeys(array $definition): array + { + if (!array_is_list($definition)) { + ksort($definition, SORT_STRING); + } + foreach ($definition as $key => $value) { + if (is_array($value)) { + $definition[$key] = $this->sortFlagDefinitionKeys($value); + } + } + return $definition; + } + /** * Normalize API flag definition data using SDK defaults for optional fields. * @@ -2046,6 +2066,7 @@ private function applyFlagDefinitions(array $data): void } $this->flagDefinitionsLoaded = true; + $this->warnAboutUnresolvableFlags(); } /** diff --git a/test/FlagDefinitionCacheProviderTest.php b/test/FlagDefinitionCacheProviderTest.php index a6d57282..b6186a8e 100644 --- a/test/FlagDefinitionCacheProviderTest.php +++ b/test/FlagDefinitionCacheProviderTest.php @@ -5,11 +5,13 @@ require_once 'test/error_log_mock.php'; use InvalidArgumentException; +use PHPUnit\Framework\Attributes\DataProvider; use PHPUnit\Framework\Attributes\IgnoreDeprecations; use PHPUnit\Framework\TestCase; use PostHog\Client; use PostHog\FlagDefinitionCacheProvider; use PostHog\Test\Assets\MockedResponses; +use PostHog\UnresolvedFlagReason; class MockFlagDefinitionCacheProvider implements FlagDefinitionCacheProvider { @@ -812,31 +814,193 @@ private function sampleFlagDefinitionData(): array ]; } - public function testUnresolvableFlagWarningIsLoggedForApiLoadsOnly(): void + public function testUnresolvableFlagWarningIsLoggedOncePerClientForApiAndCacheLoads(): void { $definitions = $this->sampleFlagDefinitionData(); $definitions['flags'][0]['ensure_experience_continuity'] = true; $warning = '(reason: experience_continuity): beta-ui.'; - // A client that only reads the shared cache does not warn: the request that fetched the - // definitions already did. $provider = new MockFlagDefinitionCacheProvider(); $provider->shouldFetch = false; $provider->cachedData = $definitions; - $this->createClient($provider, new MockedHttpClient(host: 'app.posthog.com')); - $this->assertWarningCount($warning, 0); + $cacheHttpClient = new MockedHttpClient(host: 'app.posthog.com'); + $cacheClient = $this->createClient($provider, $cacheHttpClient); + $this->assertWarningCount($warning, 1); + $cacheClient->loadFlags(); + $this->assertWarningCount($warning, 1); + $this->assertSame([], $cacheHttpClient->calls ?? []); $provider = new MockFlagDefinitionCacheProvider(); $httpClient = new MockedHttpClient(host: 'app.posthog.com', flagEndpointResponse: $definitions); $client = $this->createClient($provider, $httpClient); - $this->assertWarningCount($warning, 1); + $this->assertWarningCount($warning, 2); $provider->shouldFetch = false; $provider->cachedData = $provider->storedData; $client->loadFlags(); $this->assertSame(1, $provider->getCallCount); $this->assertCount(1, $httpClient->calls); + $this->assertWarningCount($warning, 2); + } + + public static function definitionLoadSourceProvider(): iterable + { + yield 'API' => [true]; + yield 'shared cache' => [false]; + } + + private static function warningDefinition(string $key, string $reason, array $runtime): array + { + return [ + 'key' => $key, + 'version' => 1, + 'active' => true, + 'ensure_experience_continuity' => $reason === UnresolvedFlagReason::EXPERIENCE_CONTINUITY, + 'filters' => ['groups' => [[ + 'properties' => $reason === UnresolvedFlagReason::UNSUPPORTED_DEFINITION + ? [['key' => 'id', 'type' => 'cohort', 'value' => 999]] + : [], + 'rollout_percentage' => 100, + ]]], + ] + $runtime; + } + + #[DataProvider('definitionLoadSourceProvider')] + public function testDefinitionLoadWarningsExcludeOnlyClientRuntime(bool $fromApi): void + { + global $errorMessages; + $definitions = ['flags' => [], 'group_type_mapping' => [], 'cohorts' => []]; + $expectedUnresolved = []; + $expectedNames = []; + foreach ([UnresolvedFlagReason::EXPERIENCE_CONTINUITY, UnresolvedFlagReason::UNSUPPORTED_DEFINITION] as $reason) { + foreach ([ + 'client' => ['evaluation_runtime' => 'client'], + 'server' => ['evaluation_runtime' => 'server'], + 'all' => ['evaluation_runtime' => 'all'], + 'null' => ['evaluation_runtime' => null], + 'absent' => [], + 'uppercase' => ['evaluation_runtime' => 'CLIENT'], + ] as $runtimeName => $runtime) { + $key = $reason . '-' . $runtimeName; + $definitions['flags'][] = self::warningDefinition($key, $reason, $runtime); + $expectedUnresolved[$key] = $reason; + if ($runtimeName !== 'client') { + $expectedNames[$reason][] = $key; + } + } + } + $definitions['flags'][] = self::warningDefinition('client-value', '', ['evaluation_runtime' => 'client']); + $provider = new MockFlagDefinitionCacheProvider(); + $provider->shouldFetch = $fromApi; + $provider->cachedData = $definitions; + $httpClient = new MockedHttpClient(host: 'app.posthog.com', flagEndpointResponse: $definitions); + $client = $this->createClient($provider, $httpClient); + + $this->assertCount(2, $errorMessages); + foreach ($expectedNames as $reason => $names) { + $this->assertWarningCount('(reason: ' . $reason . '): ' . implode(', ', $names) . '.', 1); + } + $this->assertStringContainsString('5 flag(s)', $errorMessages[0]); + $this->assertStringContainsString('5 flag(s)', $errorMessages[1]); + $this->assertSame($definitions['flags'], $client->featureFlags); + $snapshot = $client->evaluateFlags('user', onlyEvaluateLocally: true); + $this->assertSame(['client-value'], $snapshot->getKeys()); + $this->assertTrue($snapshot->getFlag('client-value', false)); + $this->assertSame($expectedUnresolved, $snapshot->getUnresolvedFlags()); + + $client->loadFlags(); + $this->assertCount(2, $errorMessages); + if ($fromApi) { + $httpClient->setFlagEndpointResponseQueue([['responseCode' => 304]]); + $client->loadFlags(); + $this->assertSame(array_fill(0, 3, '/flags/definitions?send_cohorts&token=random_key'), array_column($httpClient->calls, 'path')); + } else { + $this->assertSame([], $httpClient->calls ?? []); + } + $this->assertCount(2, $errorMessages); + } + + public static function warningRuntimeTransitionProvider(): iterable + { + foreach ([UnresolvedFlagReason::EXPERIENCE_CONTINUITY, UnresolvedFlagReason::UNSUPPORTED_DEFINITION] as $reason) { + foreach (['server' => ['evaluation_runtime' => 'server'], 'all' => ['evaluation_runtime' => 'all'], + 'null' => ['evaluation_runtime' => null], 'absent' => []] as $runtimeName => $runtime) { + foreach (['API', 'cache', 'API via client cache'] as $source) { + yield "$reason / $runtimeName / $source" => [$reason, $runtime, $source]; + } + } + } + } + + #[DataProvider('warningRuntimeTransitionProvider')] + public function testClientRuntimeClearsWarningHistory(string $reason, array $runtime, string $source): void + { + $original = self::warningDefinition('checkout', $reason, $runtime); + $definitions = ['flags' => [$original], 'group_type_mapping' => [], 'cohorts' => []]; + $provider = new MockFlagDefinitionCacheProvider(); + $provider->shouldFetch = $source !== 'cache'; + $provider->cachedData = $definitions; + $httpClient = new MockedHttpClient(host: 'app.posthog.com', flagEndpointResponse: $definitions); + $client = $this->createClient($provider, $httpClient); + $warning = "(reason: $reason): checkout."; + $this->assertWarningCount($warning, 1); + + $clientOnly = $original; + $clientOnly['evaluation_runtime'] = 'client'; + $provider->shouldFetch = $source === 'API'; + $provider->cachedData['flags'] = [$clientOnly]; + $httpClient->setFlagEndpointResponseQueue([['response' => $provider->cachedData]]); + $client->loadFlags(); $this->assertWarningCount($warning, 1); + $this->assertSame($clientOnly, $client->featureFlagsByKey['checkout']); + + $provider->shouldFetch = $source !== 'cache'; + $provider->cachedData = $definitions; + $httpClient->setFlagEndpointResponseQueue([['response' => $definitions], ['response' => $definitions]]); + $client->loadFlags(); + $this->assertWarningCount($warning, 2); + $client->loadFlags(); + $this->assertWarningCount($warning, 2); + + $definitions['flags'][0]['version'] = 2; + $provider->cachedData = $definitions; + $httpClient->setFlagEndpointResponseQueue([['response' => $definitions]]); + $client->loadFlags(); + $this->assertWarningCount($warning, 3); + $paths = array_column($httpClient->calls ?? [], 'path'); + $this->assertSame(array_fill(0, $source === 'cache' ? 0 : ($source === 'API' ? 5 : 4), '/flags/definitions?send_cohorts&token=random_key'), $paths); + } + + public function testReserializedCacheDefinitionsDoNotRepeatWarnings(): void + { + global $errorMessages; + $definitions = ['flags' => [ + self::warningDefinition('continuity', UnresolvedFlagReason::EXPERIENCE_CONTINUITY, []), + self::warningDefinition('unsupported', UnresolvedFlagReason::UNSUPPORTED_DEFINITION, []), + ], 'group_type_mapping' => [], 'cohorts' => []]; + $definitions['flags'][0]['filters']['groups'][] = ['properties' => [], 'rollout_percentage' => 50]; + $provider = new MockFlagDefinitionCacheProvider(); + $httpClient = new MockedHttpClient(host: 'app.posthog.com', flagEndpointResponse: $definitions); + $client = $this->createClient($provider, $httpClient); + $this->assertCount(2, $errorMessages); + + $reverseObjectKeys = static function (array $value) use (&$reverseObjectKeys): array { + $value = array_map(static fn($item) => is_array($item) ? $reverseObjectKeys($item) : $item, $value); + return array_is_list($value) ? $value : array_reverse($value, true); + }; + $provider->shouldFetch = false; + $provider->cachedData = json_decode(json_encode($reverseObjectKeys($definitions)), true); + $client->loadFlags(); + $client->loadFlags(); + $this->assertCount(2, $errorMessages); + $this->assertSame($provider->cachedData['flags'], $client->featureFlags); + + // Object key order is immaterial, but evaluation condition order is part of a definition. + $provider->cachedData['flags'][0]['filters']['groups'] = array_reverse($provider->cachedData['flags'][0]['filters']['groups']); + $client->loadFlags(); + $this->assertWarningCount('(reason: experience_continuity): continuity.', 2); + $this->assertWarningCount('(reason: unsupported_definition): unsupported.', 1); + $this->assertSame(['/flags/definitions?send_cohorts&token=random_key'], array_column($httpClient->calls, 'path')); } private function assertWarningCount(string $expected, int $count): void From 55413e5c0cf2c8a5ddc7e81266436b6f2333ee18 Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Fri, 6 Nov 2026 13:33:28 +0100 Subject: [PATCH 2/4] chore: include Laravel in flag fix release --- .changeset/kind-waves-sip.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.changeset/kind-waves-sip.md b/.changeset/kind-waves-sip.md index 490168f0..25be6e54 100644 --- a/.changeset/kind-waves-sip.md +++ b/.changeset/kind-waves-sip.md @@ -1,5 +1,6 @@ --- "posthog-php": patch +"posthog-laravel": patch --- Suppress definition-load warnings for client-only flags and reconcile warnings on shared-cache loads without repeating unchanged definitions. From b21328286e5970848c794af127e0e500a733f505 Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Fri, 6 Nov 2026 14:46:12 +0100 Subject: [PATCH 3/4] fix(flags): keep shared-cache warning loads silent --- .changeset/kind-waves-sip.md | 2 +- lib/Client.php | 25 ++++--- test/FlagDefinitionCacheProviderTest.php | 92 ++++++++++++++++++------ 3 files changed, 88 insertions(+), 31 deletions(-) diff --git a/.changeset/kind-waves-sip.md b/.changeset/kind-waves-sip.md index 25be6e54..355063f2 100644 --- a/.changeset/kind-waves-sip.md +++ b/.changeset/kind-waves-sip.md @@ -3,4 +3,4 @@ "posthog-laravel": patch --- -Suppress definition-load warnings for client-only flags and reconcile warnings on shared-cache loads without repeating unchanged definitions. +Suppress definition-load warnings for client-only flags. Preserve PHP's fresh-response-only warning policy to avoid per-request log spam from shared-cache readers, while reconciling warning history on cache loads so flags warn again after returning from client-only runtime. diff --git a/lib/Client.php b/lib/Client.php index b7ba0836..5fee8bf4 100644 --- a/lib/Client.php +++ b/lib/Client.php @@ -1772,7 +1772,7 @@ public function loadFlags() if ($cachedData !== null) { $normalizedData = $this->normalizeFlagDefinitionCacheData($cachedData); if ($normalizedData !== null) { - $this->applyFlagDefinitions($normalizedData); + $this->applyFlagDefinitions($normalizedData, false); if ($this->debug) { error_log("[PostHog][Client] Using cached flag definitions from external cache"); } @@ -1878,17 +1878,19 @@ private function fetchAndApplyFlagDefinitionsFromApi(): void $this->flagsEtag = $response->getEtag(); $data = $this->normalizeFlagDefinitionData($payload); - $this->applyFlagDefinitions($data); + $this->applyFlagDefinitions($data, true); $this->storeFlagDefinitionsInCacheProvider($data); } /** * Warn about flags whose definition local evaluation cannot resolve. Each flag is warned about - * once per client until its definition changes. + * once per client until its definition changes. Cache loads reconcile history without emitting + * warnings on every PHP-FPM request. * + * @param bool $emitWarnings Whether this load fetched a fresh API response. * @return void */ - private function warnAboutUnresolvableFlags(): void + private function warnAboutUnresolvableFlags(bool $emitWarnings): void { $flagKeysByReason = [ UnresolvedFlagReason::EXPERIENCE_CONTINUITY => [], @@ -1922,12 +1924,18 @@ private function warnAboutUnresolvableFlags(): void } $fingerprint = ($flag['version'] ?? '') . ':' . sha1(serialize($this->sortFlagDefinitionKeys($flag))) . ':' . $reason; - $warnedFlags[$flag['key']] = $fingerprint; - if (($this->warnedUnresolvableFlags[$flag['key']] ?? null) !== $fingerprint) { + $alreadyWarned = ($this->warnedUnresolvableFlags[$flag['key']] ?? null) === $fingerprint; + if ($emitWarnings || $alreadyWarned) { + $warnedFlags[$flag['key']] = $fingerprint; + } + if ($emitWarnings && !$alreadyWarned) { $flagKeysByReason[$reason][] = $flag['key']; } } $this->warnedUnresolvableFlags = $warnedFlags; + if (!$emitWarnings) { + return; + } $experienceContinuityFlags = $flagKeysByReason[UnresolvedFlagReason::EXPERIENCE_CONTINUITY]; if (count($experienceContinuityFlags) > 0) { @@ -2047,9 +2055,10 @@ private function normalizeFlagDefinitionCacheData(array $data): ?array * Apply flag definitions to in-memory state. * * @param array $data + * @param bool $emitWarnings Whether this load fetched a fresh API response. * @return void */ - private function applyFlagDefinitions(array $data): void + private function applyFlagDefinitions(array $data, bool $emitWarnings): void { $this->featureFlags = $data['flags']; $this->groupTypeMapping = $data['group_type_mapping']; @@ -2066,7 +2075,7 @@ private function applyFlagDefinitions(array $data): void } $this->flagDefinitionsLoaded = true; - $this->warnAboutUnresolvableFlags(); + $this->warnAboutUnresolvableFlags($emitWarnings); } /** diff --git a/test/FlagDefinitionCacheProviderTest.php b/test/FlagDefinitionCacheProviderTest.php index b6186a8e..2efcacd2 100644 --- a/test/FlagDefinitionCacheProviderTest.php +++ b/test/FlagDefinitionCacheProviderTest.php @@ -814,7 +814,7 @@ private function sampleFlagDefinitionData(): array ]; } - public function testUnresolvableFlagWarningIsLoggedOncePerClientForApiAndCacheLoads(): void + public function testUnresolvableFlagWarningsAreOnlyLoggedForFreshApiResponses(): void { $definitions = $this->sampleFlagDefinitionData(); $definitions['flags'][0]['ensure_experience_continuity'] = true; @@ -823,24 +823,58 @@ public function testUnresolvableFlagWarningIsLoggedOncePerClientForApiAndCacheLo $provider = new MockFlagDefinitionCacheProvider(); $provider->shouldFetch = false; $provider->cachedData = $definitions; - $cacheHttpClient = new MockedHttpClient(host: 'app.posthog.com'); - $cacheClient = $this->createClient($provider, $cacheHttpClient); + $httpClient = new MockedHttpClient(host: 'app.posthog.com', flagEndpointResponse: $definitions); + $client = $this->createClient($provider, $httpClient); + $this->assertWarningCount($warning, 0); + $client->loadFlags(); + $this->assertWarningCount($warning, 0); + $this->assertSame([], $httpClient->calls ?? []); + + $provider->shouldFetch = true; + $client->loadFlags(); $this->assertWarningCount($warning, 1); - $cacheClient->loadFlags(); + + $provider->shouldFetch = false; + $provider->cachedData = $provider->storedData; + $client->loadFlags(); $this->assertWarningCount($warning, 1); - $this->assertSame([], $cacheHttpClient->calls ?? []); + $provider->shouldFetch = true; + $client->loadFlags(); + $this->assertSame(3, $provider->getCallCount); + $this->assertCount(2, $httpClient->calls); + $this->assertWarningCount($warning, 1); + } + public function testCachedDefinitionsDoNotRepeatWarningsAcrossClients(): void + { + global $errorMessages; + $definitions = ['flags' => [ + self::warningDefinition('continuity', UnresolvedFlagReason::EXPERIENCE_CONTINUITY, []), + self::warningDefinition('unsupported', UnresolvedFlagReason::UNSUPPORTED_DEFINITION, []), + ], 'group_type_mapping' => [], 'cohorts' => []]; $provider = new MockFlagDefinitionCacheProvider(); $httpClient = new MockedHttpClient(host: 'app.posthog.com', flagEndpointResponse: $definitions); $client = $this->createClient($provider, $httpClient); - $this->assertWarningCount($warning, 2); + $this->assertWarningCount('(reason: experience_continuity): continuity.', 1); + $this->assertWarningCount('(reason: unsupported_definition): unsupported.', 1); $provider->shouldFetch = false; $provider->cachedData = $provider->storedData; - $client->loadFlags(); - $this->assertSame(1, $provider->getCallCount); + for ($request = 0; $request < 3; $request++) { + $cacheHttpClient = new MockedHttpClient(host: 'app.posthog.com'); + $cacheClient = $this->createClient($provider, $cacheHttpClient); + $snapshot = $cacheClient->evaluateFlags('user', onlyEvaluateLocally: true); + + $this->assertCount(2, $errorMessages); + $this->assertSame([ + 'continuity' => UnresolvedFlagReason::EXPERIENCE_CONTINUITY, + 'unsupported' => UnresolvedFlagReason::UNSUPPORTED_DEFINITION, + ], $snapshot->getUnresolvedFlags()); + $this->assertSame([], $cacheHttpClient->calls ?? []); + } $this->assertCount(1, $httpClient->calls); - $this->assertWarningCount($warning, 2); + $this->assertSame(1, $provider->onReceivedCallCount); + $this->assertSame(3, $provider->getCallCount); } public static function definitionLoadSourceProvider(): iterable @@ -896,12 +930,15 @@ public function testDefinitionLoadWarningsExcludeOnlyClientRuntime(bool $fromApi $httpClient = new MockedHttpClient(host: 'app.posthog.com', flagEndpointResponse: $definitions); $client = $this->createClient($provider, $httpClient); - $this->assertCount(2, $errorMessages); - foreach ($expectedNames as $reason => $names) { - $this->assertWarningCount('(reason: ' . $reason . '): ' . implode(', ', $names) . '.', 1); + $expectedWarningCount = $fromApi ? 2 : 0; + $this->assertCount($expectedWarningCount, $errorMessages); + if ($fromApi) { + foreach ($expectedNames as $reason => $names) { + $this->assertWarningCount('(reason: ' . $reason . '): ' . implode(', ', $names) . '.', 1); + } + $this->assertStringContainsString('5 flag(s)', $errorMessages[0]); + $this->assertStringContainsString('5 flag(s)', $errorMessages[1]); } - $this->assertStringContainsString('5 flag(s)', $errorMessages[0]); - $this->assertStringContainsString('5 flag(s)', $errorMessages[1]); $this->assertSame($definitions['flags'], $client->featureFlags); $snapshot = $client->evaluateFlags('user', onlyEvaluateLocally: true); $this->assertSame(['client-value'], $snapshot->getKeys()); @@ -909,7 +946,7 @@ public function testDefinitionLoadWarningsExcludeOnlyClientRuntime(bool $fromApi $this->assertSame($expectedUnresolved, $snapshot->getUnresolvedFlags()); $client->loadFlags(); - $this->assertCount(2, $errorMessages); + $this->assertCount($expectedWarningCount, $errorMessages); if ($fromApi) { $httpClient->setFlagEndpointResponseQueue([['responseCode' => 304]]); $client->loadFlags(); @@ -917,7 +954,7 @@ public function testDefinitionLoadWarningsExcludeOnlyClientRuntime(bool $fromApi } else { $this->assertSame([], $httpClient->calls ?? []); } - $this->assertCount(2, $errorMessages); + $this->assertCount($expectedWarningCount, $errorMessages); } public static function warningRuntimeTransitionProvider(): iterable @@ -943,7 +980,8 @@ public function testClientRuntimeClearsWarningHistory(string $reason, array $run $httpClient = new MockedHttpClient(host: 'app.posthog.com', flagEndpointResponse: $definitions); $client = $this->createClient($provider, $httpClient); $warning = "(reason: $reason): checkout."; - $this->assertWarningCount($warning, 1); + $warningsPerVersion = $source === 'cache' ? 0 : 1; + $this->assertWarningCount($warning, $warningsPerVersion); $clientOnly = $original; $clientOnly['evaluation_runtime'] = 'client'; @@ -951,22 +989,22 @@ public function testClientRuntimeClearsWarningHistory(string $reason, array $run $provider->cachedData['flags'] = [$clientOnly]; $httpClient->setFlagEndpointResponseQueue([['response' => $provider->cachedData]]); $client->loadFlags(); - $this->assertWarningCount($warning, 1); + $this->assertWarningCount($warning, $warningsPerVersion); $this->assertSame($clientOnly, $client->featureFlagsByKey['checkout']); $provider->shouldFetch = $source !== 'cache'; $provider->cachedData = $definitions; $httpClient->setFlagEndpointResponseQueue([['response' => $definitions], ['response' => $definitions]]); $client->loadFlags(); - $this->assertWarningCount($warning, 2); + $this->assertWarningCount($warning, 2 * $warningsPerVersion); $client->loadFlags(); - $this->assertWarningCount($warning, 2); + $this->assertWarningCount($warning, 2 * $warningsPerVersion); $definitions['flags'][0]['version'] = 2; $provider->cachedData = $definitions; $httpClient->setFlagEndpointResponseQueue([['response' => $definitions]]); $client->loadFlags(); - $this->assertWarningCount($warning, 3); + $this->assertWarningCount($warning, 3 * $warningsPerVersion); $paths = array_column($httpClient->calls ?? [], 'path'); $this->assertSame(array_fill(0, $source === 'cache' ? 0 : ($source === 'API' ? 5 : 4), '/flags/definitions?send_cohorts&token=random_key'), $paths); } @@ -995,12 +1033,22 @@ public function testReserializedCacheDefinitionsDoNotRepeatWarnings(): void $this->assertCount(2, $errorMessages); $this->assertSame($provider->cachedData['flags'], $client->featureFlags); + $provider->shouldFetch = true; + $httpClient->setFlagEndpointResponseQueue([['response' => $provider->cachedData]]); + $client->loadFlags(); + $this->assertCount(2, $errorMessages); + // Object key order is immaterial, but evaluation condition order is part of a definition. + $provider->shouldFetch = false; $provider->cachedData['flags'][0]['filters']['groups'] = array_reverse($provider->cachedData['flags'][0]['filters']['groups']); $client->loadFlags(); + $this->assertCount(2, $errorMessages); + $provider->shouldFetch = true; + $httpClient->setFlagEndpointResponseQueue([['response' => $provider->cachedData]]); + $client->loadFlags(); $this->assertWarningCount('(reason: experience_continuity): continuity.', 2); $this->assertWarningCount('(reason: unsupported_definition): unsupported.', 1); - $this->assertSame(['/flags/definitions?send_cohorts&token=random_key'], array_column($httpClient->calls, 'path')); + $this->assertSame(array_fill(0, 3, '/flags/definitions?send_cohorts&token=random_key'), array_column($httpClient->calls, 'path')); } private function assertWarningCount(string $expected, int $count): void From 84fc62732888cc88aab2118aca04efee73995dfe Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Sat, 7 Nov 2026 08:51:34 +0100 Subject: [PATCH 4/4] fix(flags): skip cache warning scans without history --- lib/Client.php | 4 +++ test/FlagDefinitionCacheProviderTest.php | 44 ++++++++++++++++++++++++ 2 files changed, 48 insertions(+) diff --git a/lib/Client.php b/lib/Client.php index 5fee8bf4..3edf2c90 100644 --- a/lib/Client.php +++ b/lib/Client.php @@ -1892,6 +1892,10 @@ private function fetchAndApplyFlagDefinitionsFromApi(): void */ private function warnAboutUnresolvableFlags(bool $emitWarnings): void { + if (!$emitWarnings && $this->warnedUnresolvableFlags === []) { + return; + } + $flagKeysByReason = [ UnresolvedFlagReason::EXPERIENCE_CONTINUITY => [], UnresolvedFlagReason::UNSUPPORTED_DEFINITION => [], diff --git a/test/FlagDefinitionCacheProviderTest.php b/test/FlagDefinitionCacheProviderTest.php index 2efcacd2..436aa54e 100644 --- a/test/FlagDefinitionCacheProviderTest.php +++ b/test/FlagDefinitionCacheProviderTest.php @@ -9,6 +9,7 @@ use PHPUnit\Framework\Attributes\IgnoreDeprecations; use PHPUnit\Framework\TestCase; use PostHog\Client; +use PostHog\FeatureFlag; use PostHog\FlagDefinitionCacheProvider; use PostHog\Test\Assets\MockedResponses; use PostHog\UnresolvedFlagReason; @@ -845,6 +846,49 @@ public function testUnresolvableFlagWarningsAreOnlyLoggedForFreshApiResponses(): $this->assertWarningCount($warning, 1); } + public function testCacheLoadsWithoutWarningHistoryDoNotInspectCohortProperties(): void + { + global $errorMessages; + $cohort = new class (['type' => 'AND', 'values' => [ + ['key' => 'plan', 'type' => 'person', 'operator' => 'exact', 'value' => 'paid'], + ]]) extends \ArrayObject { + public int $readCount = 0; + + public function offsetGet(mixed $key): mixed + { + $this->readCount++; + return parent::offsetGet($key); + } + }; + $definitions = $this->sampleFlagDefinitionData(); + $definitions['flags'][0]['filters']['groups'][0]['properties'] = [ + ['key' => 'id', 'type' => 'cohort', 'value' => 1], + ]; + $definitions['flags'][] = array_replace($definitions['flags'][0], ['key' => 'other-flag']); + $definitions['cohorts']['1'] = $cohort; + + // Confirm the probe detects the definition-warning traversal without relying on timings. + $this->assertNull(FeatureFlag::getDefinitionUnresolvedReason( + $definitions['flags'][0], [], $definitions['cohorts'], $definitions['group_type_mapping'] + )); + $this->assertGreaterThan(0, $cohort->readCount); + $cohort->readCount = 0; + + $provider = new MockFlagDefinitionCacheProvider(); + $provider->shouldFetch = false; + $provider->cachedData = $definitions; + $httpClient = new MockedHttpClient(host: 'app.posthog.com'); + $client = $this->createClient($provider, $httpClient); + $client->loadFlags(); + + $this->assertSame(0, $cohort->readCount); + $this->assertSame($definitions['flags'], $client->featureFlags); + $this->assertSame(2, $provider->getCallCount); + $this->assertSame(0, $provider->onReceivedCallCount); + $this->assertSame([], $httpClient->calls ?? []); + $this->assertSame([], $errorMessages); + } + public function testCachedDefinitionsDoNotRepeatWarningsAcrossClients(): void { global $errorMessages;