Skip to content

feat(flags): accept a caller default on FeatureFlagEvaluations::isEnabled() - #324

Merged
turnipdabeets merged 2 commits into
mainfrom
posthog/is-feature-enabled-default-value
Nov 19, 2026
Merged

turnipdabeets merged 2 commits into
mainfrom
posthog/is-feature-enabled-default-value

Conversation

@posthog

@posthog posthog Bot commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

💡 Motivation and Context

Brings posthog-php into compliance with the is-feature-enabled contract, which the weekly SDK compliance matrix flags as ❌ Fail for this SDK:

Spec requires: Hard SHALL, both applicability. "The SDK SHALL accept a caller-supplied boolean default (defaultValue) … and SHALL return it whenever the flag has no value … A flag that has a value — including false and variant strings — always wins over the caller-supplied default."

SDK currently: no defaultValue parameter at all; a missing/unloaded/failed flag collapses to a hardcoded result with no way for a caller to override it.

Backwards compatibility: Backward-compatible — adding an optional default parameter is purely additive.

A genuinely disabled flag and a flag with no value at all were indistinguishable, so callers who want a feature on while flags are unavailable had no way to express that.

🔨 What changed

FeatureFlagEvaluations::isEnabled() takes an optional bool $defaultValue = false, returned only when the snapshot holds no record for the key — unknown flag, flags never loaded, a failed /flags request, or a flag local evaluation left unresolved. A flag that has a value, including false, still wins over the default.

The deprecated Client::isFeatureEnabled() / PostHog::isFeatureEnabled() facades are deliberately left alone: they are already marked @deprecated in favour of evaluateFlags(...)->isEnabled(...), which is the surface this change makes compliant.

Backwards compatibility: purely additive. The parameter is optional and its default (false) is the value the method returned for a miss before, so no existing call site changes behaviour. No deprecation path is needed.

💚 How did you test it?

  • Three new cases in test/FeatureFlagEvaluationsTest.php covering the spec's scenarios: missing flags resolve to the caller default (true and false), a flag value wins over the default (false flag with default true, variant flag with default false), and unresolved / filtered-out flags take the default.
  • Full suite green locally: ./vendor/bin/phpunit --bootstrap vendor/autoload.php --configuration phpunit.xml → 2818 tests, 12581 assertions, 0 failures.
  • ./vendor/bin/phpcs --standard=phpcs.xml --extensions=php lib test → no new issues.
  • composer api:update regenerated api/public-api.json (the added optional parameter); composer api:check passes. The Laravel API snapshot is unaffected — it only covers PostHog\Laravel\ symbols.
  • Change intent recorded with pnpm change (minor).

➡️ Follow-ups

  • The same gap exists on the equivalent surfaces in posthog-go, posthog-ruby and posthog-dotnet; this PR covers PHP only.
  • openspec/specs/is-feature-enabled/spec.md's "Surface variants" table still documents the deprecated PHP signature without a default — worth refreshing in sdk-specs, which this PR intentionally does not touch.

📝 Checklist

  • All commits are signed
  • I reviewed the submitted code.
  • I added tests to verify the changes.
  • I updated the docs if needed.
  • No breaking change or entry added to the changelog.

If releasing new changes

  • Ran pnpm change to generate a change intent file

🤖 Agent context

Autonomy: Fully autonomous

Opened by a scheduled agent that reads the SDK compliance matrices in PostHog/sdk-specs and implements one gap per run. This gap was picked over the other open candidates because its backwards-compatibility verdict is "backward-compatible" (additive), the contract is a core, widely used flag read, and the remediation is self-contained to a single method. Runner-up candidates — the identical default-value gap in posthog-go/-ruby/-dotnet, and the Logs and Traces contracts missing on several server SDKs — were left for future runs; Logs/Traces are whole subsystems rather than a scoped fix.

Decision worth a reviewer's eye: the compliance note's remediation named the deprecated Client::isFeatureEnabled(). That method was skipped on purpose, and the non-deprecated snapshot surface was fixed instead. If you want parity on the deprecated facade too, say so and it can be added.

No manual end-to-end testing against a live PostHog project was performed — only the automated checks listed above.


Created with PostHog Desktop

🤖 Generated with Claude Code

…bled()

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 <noreply@anthropic.com>

Generated-By: PostHog Desktop
Task-Id: 8e05f524-d4d3-4802-be50-f997b9c60502
@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

posthog-php-socket Compliance Report

Date: 2026-11-19T00:44:10.994899+00:00
Duration: 118139ms

✅ All Tests Passed!

47/47 tests passed


Capture Tests

✅ 30/30 tests passed

View Details
Test Status Duration
Format Validation.Event Has Required Fields ✅ 22ms
Format Validation.Event Has Uuid ✅ 516ms
Format Validation.Event Has Lib Properties ✅ 518ms
Format Validation.Distinct Id Is String ✅ 517ms
Format Validation.Token Is Present ✅ 517ms
Format Validation.Custom Properties Preserved ✅ 517ms
Format Validation.Event Has Timestamp ✅ 516ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc ✅ 517ms
Retry Behavior.Retries On 503 ✅ 5824ms
Retry Behavior.Does Not Retry On 400 ✅ 2520ms
Retry Behavior.Does Not Retry On 401 ✅ 2518ms
Retry Behavior.Respects Retry After Header ✅ 8524ms
Retry Behavior.Implements Backoff ✅ 16238ms
Retry Behavior.Retries On 500 ✅ 5627ms
Retry Behavior.Retries On 502 ✅ 5624ms
Retry Behavior.Retries On 504 ✅ 5625ms
Retry Behavior.Max Retries Respected ✅ 16241ms
Deduplication.Generates Unique Uuids ✅ 525ms
Deduplication.Preserves Uuid On Retry ✅ 5623ms
Deduplication.Preserves Uuid And Timestamp On Retry ✅ 10835ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 5629ms
Deduplication.No Duplicate Events In Batch ✅ 524ms
Deduplication.Different Events Have Different Uuids ✅ 518ms
Compression.Sends Gzip When Enabled ✅ 518ms
Batch Format.Uses Proper Batch Structure ✅ 517ms
Batch Format.Flush With No Events Sends Nothing ✅ 513ms
Batch Format.Multiple Events Batched Together ✅ 510ms
Error Handling.Does Not Retry On 403 ✅ 2518ms
Error Handling.Does Not Retry On 413 ✅ 2520ms
Error Handling.Retries On 408 ✅ 5624ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id ✅ 517ms
Request Payload.Flags Request Uses V2 Query Param ✅ 516ms
Request Payload.Flags Request Hits Flags Path Not Decide ✅ 515ms
Request Payload.Flags Request Omits Authorization Header ✅ 515ms
Request Payload.Token In Flags Body Matches Init ✅ 514ms
Request Payload.Groups Round Trip ✅ 515ms
Request Payload.Groups Default To Empty Object ✅ 515ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False ✅ 514ms
Request Payload.Disable Geoip Omitted Defaults To False ✅ 515ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key ✅ 515ms
Request Lifecycle.No Flags Request On Init Alone ✅ 512ms
Request Lifecycle.No Flags Request On Normal Capture ✅ 506ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests ✅ 518ms
Request Lifecycle.Mock Response Value Is Returned To Caller ✅ 515ms
Retry Behavior.Retries Flags On 502 ✅ 616ms
Retry Behavior.Retries Flags On 504 ✅ 616ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event ✅ 517ms

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

posthog-php-fork_curl Compliance Report

Date: 2026-11-19T00:43:41.292705+00:00
Duration: 119268ms

✅ All Tests Passed!

47/47 tests passed


Capture Tests

✅ 30/30 tests passed

View Details
Test Status Duration
Format Validation.Event Has Required Fields ✅ 39ms
Format Validation.Event Has Uuid ✅ 532ms
Format Validation.Event Has Lib Properties ✅ 534ms
Format Validation.Distinct Id Is String ✅ 533ms
Format Validation.Token Is Present ✅ 532ms
Format Validation.Custom Properties Preserved ✅ 534ms
Format Validation.Event Has Timestamp ✅ 533ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc ✅ 534ms
Retry Behavior.Retries On 503 ✅ 5858ms
Retry Behavior.Does Not Retry On 400 ✅ 2538ms
Retry Behavior.Does Not Retry On 401 ✅ 2537ms
Retry Behavior.Respects Retry After Header ✅ 8548ms
Retry Behavior.Implements Backoff ✅ 16284ms
Retry Behavior.Retries On 500 ✅ 5651ms
Retry Behavior.Retries On 502 ✅ 5649ms
Retry Behavior.Retries On 504 ✅ 5650ms
Retry Behavior.Max Retries Respected ✅ 16281ms
Deduplication.Generates Unique Uuids ✅ 543ms
Deduplication.Preserves Uuid On Retry ✅ 5650ms
Deduplication.Preserves Uuid And Timestamp On Retry ✅ 10866ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 5650ms
Deduplication.No Duplicate Events In Batch ✅ 543ms
Deduplication.Different Events Have Different Uuids ✅ 536ms
Compression.Sends Gzip When Enabled ✅ 536ms
Batch Format.Uses Proper Batch Structure ✅ 534ms
Batch Format.Flush With No Events Sends Nothing ✅ 521ms
Batch Format.Multiple Events Batched Together ✅ 522ms
Error Handling.Does Not Retry On 403 ✅ 2536ms
Error Handling.Does Not Retry On 413 ✅ 2536ms
Error Handling.Retries On 408 ✅ 5651ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id ✅ 525ms
Request Payload.Flags Request Uses V2 Query Param ✅ 524ms
Request Payload.Flags Request Hits Flags Path Not Decide ✅ 525ms
Request Payload.Flags Request Omits Authorization Header ✅ 525ms
Request Payload.Token In Flags Body Matches Init ✅ 525ms
Request Payload.Groups Round Trip ✅ 524ms
Request Payload.Groups Default To Empty Object ✅ 524ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False ✅ 524ms
Request Payload.Disable Geoip Omitted Defaults To False ✅ 525ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key ✅ 524ms
Request Lifecycle.No Flags Request On Init Alone ✅ 519ms
Request Lifecycle.No Flags Request On Normal Capture ✅ 517ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests ✅ 528ms
Request Lifecycle.Mock Response Value Is Returned To Caller ✅ 526ms
Retry Behavior.Retries Flags On 502 ✅ 627ms
Retry Behavior.Retries Flags On 504 ✅ 627ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event ✅ 536ms

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

posthog-php-lib_curl Compliance Report

Date: 2026-11-19T00:44:02.586042+00:00
Duration: 118956ms

✅ All Tests Passed!

47/47 tests passed


Capture Tests

✅ 30/30 tests passed

View Details
Test Status Duration
Format Validation.Event Has Required Fields ✅ 28ms
Format Validation.Event Has Uuid ✅ 524ms
Format Validation.Event Has Lib Properties ✅ 523ms
Format Validation.Distinct Id Is String ✅ 523ms
Format Validation.Token Is Present ✅ 524ms
Format Validation.Custom Properties Preserved ✅ 523ms
Format Validation.Event Has Timestamp ✅ 522ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc ✅ 523ms
Retry Behavior.Retries On 503 ✅ 5831ms
Retry Behavior.Does Not Retry On 400 ✅ 2525ms
Retry Behavior.Does Not Retry On 401 ✅ 2524ms
Retry Behavior.Respects Retry After Header ✅ 8530ms
Retry Behavior.Implements Backoff ✅ 16245ms
Retry Behavior.Retries On 500 ✅ 5631ms
Retry Behavior.Retries On 502 ✅ 5629ms
Retry Behavior.Retries On 504 ✅ 5631ms
Retry Behavior.Max Retries Respected ✅ 17045ms
Deduplication.Generates Unique Uuids ✅ 227ms
Deduplication.Preserves Uuid On Retry ✅ 5629ms
Deduplication.Preserves Uuid And Timestamp On Retry ✅ 10835ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 5636ms
Deduplication.No Duplicate Events In Batch ✅ 527ms
Deduplication.Different Events Have Different Uuids ✅ 523ms
Compression.Sends Gzip When Enabled ✅ 523ms
Batch Format.Uses Proper Batch Structure ✅ 522ms
Batch Format.Flush With No Events Sends Nothing ✅ 519ms
Batch Format.Multiple Events Batched Together ✅ 510ms
Error Handling.Does Not Retry On 403 ✅ 2524ms
Error Handling.Does Not Retry On 413 ✅ 2524ms
Error Handling.Retries On 408 ✅ 5630ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id ✅ 521ms
Request Payload.Flags Request Uses V2 Query Param ✅ 521ms
Request Payload.Flags Request Hits Flags Path Not Decide ✅ 520ms
Request Payload.Flags Request Omits Authorization Header ✅ 520ms
Request Payload.Token In Flags Body Matches Init ✅ 521ms
Request Payload.Groups Round Trip ✅ 520ms
Request Payload.Groups Default To Empty Object ✅ 520ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False ✅ 521ms
Request Payload.Disable Geoip Omitted Defaults To False ✅ 520ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key ✅ 520ms
Request Lifecycle.No Flags Request On Init Alone ✅ 517ms
Request Lifecycle.No Flags Request On Normal Capture ✅ 507ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests ✅ 524ms
Request Lifecycle.Mock Response Value Is Returned To Caller ✅ 522ms
Retry Behavior.Retries Flags On 502 ✅ 625ms
Retry Behavior.Retries Flags On 504 ✅ 622ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event ✅ 522ms

…lled 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 <noreply@anthropic.com>
@turnipdabeets
turnipdabeets marked this pull request as ready for review November 19, 2026 00:40
@turnipdabeets
turnipdabeets requested a review from a team as a code owner November 19, 2026 00:40
@turnipdabeets
turnipdabeets enabled auto-merge (squash) November 19, 2026 00:41
@turnipdabeets
turnipdabeets merged commit 966f0f5 into main Nov 19, 2026
30 checks passed
@turnipdabeets
turnipdabeets deleted the posthog/is-feature-enabled-default-value branch November 19, 2026 00:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant