feat(analytics): add feature flag support (local + remote evaluation)

[tylerjroach]

Summary

Adds Mixpanel feature-flag support to the PHP SDK via a new $mp->flags facade — both local evaluation (one-shot fetch of definitions, then in-process FNV-1a bucketing + JSON Logic runtime rules) and remote evaluation (HTTP /flags on every call). API surface aligns with the Python / Ruby / Go / Java / Node server SDKs so cross-language behavior is consistent.

$mp = Mixpanel::getInstance("TOKEN", ["flags" => ["mode" => FeatureFlags_MixpanelFlags::MODE_REMOTE]]);
if ($mp->flags->isEnabled("new-checkout", ["distinct_id" => "u-123"])) { ... }

PHP-specific design notes:

• No background polling thread. PHP has no native threading and FPM/Apache processes don't survive past a single request. Long-lived CLI workers call loadDefinitions() on whatever cadence they need.
• Exposure events flow through the existing event queue, so they're naturally batched / flushed at end-of-request — evaluation never blocks on a /track HTTP call.
• fallbackReason on the returned SelectedVariant distinguishes the five ways an eval can fall back (FLAG_NOT_FOUND, MISSING_CONTEXT_KEY, NO_ROLLOUT_MATCH, BACKEND_ERROR, NOT_READY) — null on success.

Public API surface (strongly typed, PHP 8.1+)

The whole feature-flag implementation ships with real PHP types — typed properties, typed parameters, typed returns, declare(strict_types=1) in every file. IDE autocomplete and static analyzers get accurate types; latent type-mismatch bugs surface at parse/runtime instead of silently coercing.

// Configuration (in $options to Mixpanel constructor)
[
    "flags" => [
        "mode"                       => FeatureFlags_MixpanelFlags::MODE_REMOTE
                                        | FeatureFlags_MixpanelFlags::MODE_LOCAL,  // default: MODE_REMOTE
        "api_host"                   => string,  // default: inherits "host" then "api.mixpanel.com"
        "request_timeout_in_seconds" => int,     // default: 10 (applied to connect + read)
    ],
]

// On the Mixpanel class
public ?FeatureFlags_MixpanelFlags $flags = null;

// Lifecycle (no-ops/sentinels in remote mode)
public function loadDefinitions(): bool                                            // local: fetch /flags/definitions
public function areFlagsReady(): bool                                              // local: ready check
public function lastSyncedAt(): ?int                                               // local: unix ts of last sync
public function getMode(): string                                                  // 'local' or 'remote'
public function getProvider(): FeatureFlags_MixpanelFlagsBase
public function shutdown(): void

// Evaluation
public function isEnabled(string $flagKey, array $context): bool
public function getVariantValue(string $flagKey, mixed $fallbackValue, array $context): mixed
public function getVariant(
    string $flagKey,
    FeatureFlags_MixpanelSelectedVariant $fallback,
    array $context,
    bool $reportExposure = true
): FeatureFlags_MixpanelSelectedVariant
public function getAllVariants(array $context): array   // array<string, FeatureFlags_MixpanelSelectedVariant>
public function trackExposure(
    string $flagKey,
    FeatureFlags_MixpanelSelectedVariant $variant,
    array $context
): void

// SelectedVariant fields (typed properties)
public ?string $variantKey
public mixed   $variantValue
public ?string $experimentId
public ?bool   $isExperimentActive
public ?bool   $isQaTester
public ?string $variantSource      // SOURCE_LOCAL | SOURCE_REMOTE | SOURCE_FALLBACK
public ?string $fallbackReason     // null on success; REASON_* on fallback

// Fallback reasons (constants on FeatureFlags_MixpanelSelectedVariant)
REASON_FLAG_NOT_FOUND          // flag key doesn't exist
REASON_MISSING_CONTEXT_KEY     // context lacks the flag's bucketing attribute
REASON_NO_ROLLOUT_MATCH        // flag exists, no rollout matched
REASON_BACKEND_ERROR           // remote: HTTP transport / status failure
REASON_NOT_READY               // local: getVariant called before loadDefinitions

Dependency / version changes

• PHP minimum bumped from >=5.0 to >=8.1. PHP 8.1 is already end-of-life at the time of this change, so it's the natural floor. Enables typed properties (7.4+), mixed (8.0), union types (8.0), and declare(strict_types=1) throughout the feature-flag implementation.
• Two new runtime deps (both tiny, pure-PHP packages):
  • jwadhams/json-logic-php ^1.5 — runtime-rule evaluation in local mode.
  • symfony/polyfill-mbstring ^1.27 — Unicode case folding for runtime rules; no-op pass-through when ext-mbstring is present.
• No new PHP extension requirements. FNV-1a bucketing uses PHP's built-in hash('fnv1a64', …) from core ext-hash (bundled in every PHP install). Tracking-only customers on PHP 8.1+ upgrading from 2.11.0 see zero install-time impact — no RUN docker-php-ext-install layers required on minimal Docker images.
• lib_version query param on flag HTTP requests resolves dynamically via \Composer\InstalledVersions — no hardcoded version constant to bump at release time. Matches prepare-release.yml's philosophy ("composer.json intentionally has NO version field — Packagist reads from the git tag").
• PHPUnit dev dep is ^8.5.52 || ^9.5; dropped abandoned phpdocumentor/phpdocumentor 2.9.* (security advisories on its symfony/validator transitive dep).
• Updated existing tests for the PHPUnit baseline (PHPUnit\Framework\TestCase, : void setUp/tearDown, assertString*ContainsString).
• Fixed one pre-existing test bug surfaced by the PHPUnit upgrade: MixpanelGroupsProducerTest::testRemove was asserting $unset when the SDK correctly emits $remove.
• CI matrix (.github/workflows/tests.yml) runs PHPUnit against 8.1, 8.3, 8.4 — the supported PHP versions above the new floor.

Test plan

• composer install && composer run-script unit-tests — 83 unit tests pass, 279 assertions. Coverage includes FNV-1a canonical RFC vectors (cross-language bucketing parity), runtime-rule eval (case-folding semantics), every fallback-reason path, exposure event shape, ISO start/complete timestamps in remote-mode exposure, nested numeric preservation, custom-bucketing-key warning behavior, api_host inheritance from top-level host, MODE_* constant equivalence.
• php -l clean on every modified file after the typing pass.
• End-to-end against the live integration test project via the sdk-testing harness — 42 integration tests pass (19 runtime-rule cases × local + remote modes, plus 4 custom-context exposure tests).
• Security review — no HIGH/MEDIUM findings.

What's not in this PR

• README, CHANGELOG, examples/ — feature-flag docs live on the official docs site; CHANGELOG is generated at release time by prepare-release.yml.
• OpenFeature provider package — the fallbackReason discriminator, the variant-metadata fields on SelectedVariant, and the per-call $reportExposure parameter are hooks intentionally exposed so a mixpanel-openfeature-php provider package can bind directly without redesigning the core. Tracked as follow-up.

Trying the PR before release

Customers can install directly from this branch by adding to their composer.json:

```json
{
"repositories": [
{"type": "vcs", "url": "https://github.com/mixpanel/mixpanel-php"}
],
"require": {
"mixpanel/mixpanel-php": "dev-feature-flags-support"
},
"minimum-stability": "dev",
"prefer-stable": true
}
```

Then composer update mixpanel/mixpanel-php. Pin to a SHA (dev-feature-flags-support#<sha>) for stability while testing.

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 5/5

The new feature-flag implementation is well-structured with no blocking defects; all previously flagged issues have been addressed.

The json_encode failure path is now properly detected before the HTTP call, the curl_init guard is in place, and the strict isEnabled semantics are intentional and documented. The one remaining gap — _trackExposure catching Exception but not Error — is low-risk given the tracker is always the internally-defined closure.

lib/FeatureFlags/MixpanelFlagsBase.php — catch block in _trackExposure could be widened to match the Error-aware pattern used in MixpanelLocalFlags.

Important Files Changed

Filename	Overview
lib/FeatureFlags/MixpanelFlagsBase.php	Shared HTTP + exposure-tracking base; curl_init guard and json_encode failure handling both addressed; Exception-only catch in _trackExposure is inconsistent with the Error-aware pattern used in MixpanelLocalFlags.
lib/FeatureFlags/MixpanelLocalFlags.php	FNV-1a bucketing + JSON Logic runtime evaluation; dead pre-loop $selected assignment at line 235 is cosmetic; core evaluation logic is correct.
lib/FeatureFlags/MixpanelRemoteFlags.php	Previously flagged json_encode failure is now detected and surfaced as REASON_BACKEND_ERROR before the HTTP call; clean implementation.
lib/FeatureFlags/MixpanelFlags.php	Clean facade delegating to local/remote providers; mode validation throws early on invalid input.
lib/FeatureFlags/MixpanelFlagsUtils.php	FNV-1a 64 normalizedHash, traceparent generator, and case-folding helpers; byte-walk mod-100 is correct for 32-bit PHP compatibility.
lib/FeatureFlags/MixpanelSelectedVariant.php	Well-typed value object with immutable withSource/withFallbackReason wither methods; all REASON_* constants are present.
lib/Mixpanel.php	Flags facade wired lazily only when flags key is present; tracker closure routes exposure events through the existing event queue.
composer.json	PHP floor bumped to 8.1; two new runtime deps (json-logic-php, polyfill-mbstring); PHPUnit upgraded; phpdocumentor dropped.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant App
    participant MixpanelFlags
    participant LocalProvider as MixpanelLocalFlags
    participant RemoteProvider as MixpanelRemoteFlags
    participant FlagsAPI as Mixpanel /flags API
    participant EventQueue as Event Queue

    App->>MixpanelFlags: isEnabled("flag", context)
    MixpanelFlags->>LocalProvider: getVariant() [local mode]
    LocalProvider->>LocalProvider: FNV-1a hash + JSON Logic eval
    LocalProvider->>EventQueue: _trackExposure (async, batched)
    LocalProvider-->>App: SelectedVariant (SOURCE_LOCAL)

    App->>MixpanelFlags: isEnabled("flag", context)
    MixpanelFlags->>RemoteProvider: getVariant() [remote mode]
    RemoteProvider->>FlagsAPI: "GET /flags?context=JSON&flag_key=flag"
    FlagsAPI-->>RemoteProvider: "{flags: {...}}"
    RemoteProvider->>EventQueue: _trackExposure (async, batched)
    RemoteProvider-->>App: SelectedVariant (SOURCE_REMOTE)

    App->>MixpanelFlags: getAllVariants(context)
    MixpanelFlags->>RemoteProvider: getAllVariants()
    RemoteProvider->>FlagsAPI: "GET /flags?context=JSON"
    FlagsAPI-->>RemoteProvider: "{flags: {...}}"
    RemoteProvider-->>App: map of SelectedVariants (no auto-exposure)
    App->>MixpanelFlags: trackExposure("flag", variant, context)
    MixpanelFlags->>RemoteProvider: trackExposure()
    RemoteProvider->>EventQueue: _trackExposure

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant App
    participant MixpanelFlags
    participant LocalProvider as MixpanelLocalFlags
    participant RemoteProvider as MixpanelRemoteFlags
    participant FlagsAPI as Mixpanel /flags API
    participant EventQueue as Event Queue

    App->>MixpanelFlags: isEnabled("flag", context)
    MixpanelFlags->>LocalProvider: getVariant() [local mode]
    LocalProvider->>LocalProvider: FNV-1a hash + JSON Logic eval
    LocalProvider->>EventQueue: _trackExposure (async, batched)
    LocalProvider-->>App: SelectedVariant (SOURCE_LOCAL)

    App->>MixpanelFlags: isEnabled("flag", context)
    MixpanelFlags->>RemoteProvider: getVariant() [remote mode]
    RemoteProvider->>FlagsAPI: "GET /flags?context=JSON&flag_key=flag"
    FlagsAPI-->>RemoteProvider: "{flags: {...}}"
    RemoteProvider->>EventQueue: _trackExposure (async, batched)
    RemoteProvider-->>App: SelectedVariant (SOURCE_REMOTE)

    App->>MixpanelFlags: getAllVariants(context)
    MixpanelFlags->>RemoteProvider: getAllVariants()
    RemoteProvider->>FlagsAPI: "GET /flags?context=JSON"
    FlagsAPI-->>RemoteProvider: "{flags: {...}}"
    RemoteProvider-->>App: map of SelectedVariants (no auto-exposure)
    App->>MixpanelFlags: trackExposure("flag", variant, context)
    MixpanelFlags->>RemoteProvider: trackExposure()
    RemoteProvider->>EventQueue: _trackExposure

Loading

_{Reviews (3): Last reviewed commit: "fix(flags): detect json_encode failure +..." | Re-trigger Greptile}

[tylerjroach]

Pushed 8d58a16 addressing all three Greptile threads.

P1 — json_encode failure not detected (MixpanelRemoteFlags.php:87): now checks the return value and throws Exception('...could not be JSON-encoded: ' . json_last_error_msg()) before touching http_build_query. getVariant / getAllVariants already catch and route through _handleError + return REASON_BACKEND_ERROR, so the failure surfaces via the user's error_callback and via the fallback reason. New test testJsonEncodeFailureSurfacesAsBackendError uses invalid UTF-8 ("\xB1\x31") to trigger the path — asserts no HTTP call was attempted, fallback reason is REASON_BACKEND_ERROR, and error_callback got a message mentioning JSON encoding.

P2 — curl_init extension guard (MixpanelFlagsBase.php:102): added if (!function_exists('curl_init')) throw new RuntimeException(...) at the top of _httpGet, mirroring the guard AbstractConsumer uses.

P2 — isEnabled strict === true: kept the strict check and added a doc comment. The behavior is intentional and matches Node, Ruby, Python, and Go — non-boolean truthy values (1, "true", "on", ...) indicate a type mismatch on a flag that should be a Feature Gate, and we fail closed rather than accept an ambiguous "on" signal.

All 39 flag tests pass locally.