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

.github/workflows/tests.yml

@@ -0,0 +1,56 @@
+name: Tests
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+
+permissions:
+  contents: read
+
+concurrency:
+  # Cancel in-flight runs for the same PR when a new commit lands; let
+  # master pushes always finish so we keep a complete trunk history.
+  group: tests-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  phpunit:
+    name: "PHPUnit (PHP ${{ matrix.php }})"
+    runs-on: ubuntu-latest
+    strategy:
+      # Surface every failing version on every run, not just the first.
+      fail-fast: false
+      matrix:
+        # Floor matches the `>=8.1` declared in composer.json. The
+        # 8.1 entry enforces the promise; later minors cover every
+        # currently-supported PHP release.
+        php: ['8.1', '8.3', '8.4']
+    steps:
+      - name: Checkout
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8  # v7.0.0
+
+      - name: Setup PHP ${{ matrix.php }}
+        uses: shivammathur/setup-php@2282b6a082fc605c8320908a4cca3a5d1ca6c6fe  # 2.37.2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+          tools: composer:v2
+
+      - name: Resolve Composer cache directory
+        id: composer-cache
+        run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
+
+      - name: Cache Composer packages
+        uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7  # v6.0.0
+        with:
+          path: ${{ steps.composer-cache.outputs.dir }}
+          key: php-${{ matrix.php }}-composer-${{ hashFiles('composer.json') }}
+          restore-keys: |
+            php-${{ matrix.php }}-composer-
+
+      - name: Install dependencies
+        run: composer update --no-interaction --no-progress --prefer-dist
+
+      - name: Run PHPUnit
+        run: composer run-script unit-tests

README.md

@@ -1,4 +1,4 @@
-Mixpanel PHP Library [![Build Status](https://travis-ci.org/mixpanel/mixpanel-php.svg)](https://travis-ci.org/mixpanel/mixpanel-php)
+Mixpanel PHP Library
 ============
 
 ##### _May 13, 2026_ - [2.11.0](https://github.com/mixpanel/mixpanel-php/releases/tag/2.11.0)
@@ -82,7 +82,7 @@ Documentation
 * <a href="https://mixpanel.com/help/reference/php" target="_blank">Reference Docs</a>
 * <a href="http://mixpanel.github.io/mixpanel-php" target="_blank">Full API Reference</a>
 
-For further examples and options checkout out the "examples" folder
+For further examples and options check out the "examples" folder.
 
 Changelog
 -------------

composer.json

@@ -17,11 +17,12 @@
         }
     ],
     "require": {
-        "php": ">=5.0"
+        "php": ">=8.1",
+        "jwadhams/json-logic-php": "^1.5",
+        "symfony/polyfill-mbstring": "^1.27"
     },
     "require-dev": {
-        "phpunit/phpunit": "5.6.*",
-        "phpdocumentor/phpdocumentor": "2.9.*"
+        "phpunit/phpunit": "^8.5.52 || ^9.5"
     },
     "autoload": {
         "files": ["lib/Mixpanel.php"]

lib/FeatureFlags/MixpanelFlags.php

@@ -0,0 +1,139 @@
+<?php
+
+declare(strict_types=1);
+
+require_once(dirname(__FILE__) . "/MixpanelLocalFlags.php");
+require_once(dirname(__FILE__) . "/MixpanelRemoteFlags.php");
+
+/**
+ * Public entry point reached via $mp->flags. Decides between the local
+ * and remote provider based on the `mode` option, owns the underlying
+ * provider's lifecycle, and forwards every public method to it.
+ *
+ * Usage:
+ *
+ *   $mp = Mixpanel::getInstance('TOKEN', array(
+ *       'flags' => array('mode' => FeatureFlags_MixpanelFlags::MODE_REMOTE),
+ *   ));
+ *   $enabled = $mp->flags->isEnabled('my-flag', array(
+ *       'distinct_id' => 'user-123',
+ *   ));
+ */
+class FeatureFlags_MixpanelFlags {
+
+    /**
+     * Evaluation mode values for the `mode` config key. These constants
+     * give callers an IDE-checkable, grep-able alternative to bare string
+     * literals. The raw strings remain valid input — these are exact aliases.
+     */
+    const MODE_LOCAL  = 'local';
+    const MODE_REMOTE = 'remote';
+
+    private FeatureFlags_MixpanelFlagsBase $_provider;
+
+    /** One of the MODE_* constants. */
+    private string $_mode;
+
+    public function __construct(string $token, string $version, callable $tracker, array $options) {
+        // No extension checks — FNV-1a hashing uses PHP's built-in
+        // ext-hash (bundled in core), case folding uses
+        // symfony/polyfill-mbstring (composer dep), HTTP uses the
+        // existing CurlConsumer which already runtime-checks ext-curl.
+        $flagsOpts = isset($options['flags']) && is_array($options['flags']) ? $options['flags'] : array();
+        if (isset($flagsOpts['mode'])) {
+            $requested = strtolower((string) $flagsOpts['mode']);
+            if ($requested !== self::MODE_LOCAL && $requested !== self::MODE_REMOTE) {
+                // Fail loudly on typos ('lcoal' -> silently falls through to remote is a debug trap).
+                throw new InvalidArgumentException(
+                    "Invalid flags 'mode' option: " . var_export($flagsOpts['mode'], true) .
+                    ". Expected '" . self::MODE_LOCAL . "' or '" . self::MODE_REMOTE . "'."
+                );
+            }
+            $this->_mode = $requested;
+        } else {
+            $this->_mode = self::MODE_REMOTE;
+        }
+
+        if ($this->_mode === self::MODE_LOCAL) {
+            $this->_provider = new FeatureFlags_MixpanelLocalFlags($token, $version, $tracker, $options);
+        } else {
+            $this->_provider = new FeatureFlags_MixpanelRemoteFlags($token, $version, $tracker, $options);
+        }
+    }
+
+    public function __destruct() {
+        try {
+            $this->shutdown();
+        } catch (\Throwable $t) {
+            // Swallow: destructors run during shutdown/fatal-error paths where
+            // throwing could mask the original error or hit a partially-torn-down
+            // interpreter state.
+        }
+    }
+
+    public function getMode(): string {
+        return $this->_mode;
+    }
+
+    public function getProvider(): FeatureFlags_MixpanelFlagsBase {
+        return $this->_provider;
+    }
+
+    /**
+     * Fetch flag definitions from the server. Local mode only; no-op
+     * (returns true) in remote mode.
+     */
+    public function loadDefinitions(): bool {
+        if ($this->_provider instanceof FeatureFlags_MixpanelLocalFlags) {
+            return $this->_provider->loadDefinitions();
+        }
+        return true;
+    }
+
+    public function areFlagsReady(): bool {
+        if ($this->_provider instanceof FeatureFlags_MixpanelLocalFlags) {
+            return $this->_provider->areFlagsReady();
+        }
+        return true;
+    }
+
+    public function lastSyncedAt(): ?int {
+        if ($this->_provider instanceof FeatureFlags_MixpanelLocalFlags) {
+            return $this->_provider->lastSyncedAt();
+        }
+        return null;
+    }
+
+    public function getVariant(
+        string $flagKey,
+        FeatureFlags_MixpanelSelectedVariant $fallback,
+        array $context,
+        bool $reportExposure = true
+    ): FeatureFlags_MixpanelSelectedVariant {
+        return $this->_provider->getVariant($flagKey, $fallback, $context, $reportExposure);
+    }
+
+    public function getVariantValue(string $flagKey, mixed $fallbackValue, array $context): mixed {
+        return $this->_provider->getVariantValue($flagKey, $fallbackValue, $context);
+    }
+
+    public function isEnabled(string $flagKey, array $context): bool {
+        return $this->_provider->isEnabled($flagKey, $context);
+    }
+
+    public function getAllVariants(array $context): array {
+        return $this->_provider->getAllVariants($context);
+    }
+
+    public function trackExposure(
+        string $flagKey,
+        FeatureFlags_MixpanelSelectedVariant $variant,
+        array $context
+    ): void {
+        $this->_provider->trackExposure($flagKey, $variant, $context);
+    }
+
+    public function shutdown(): void {
+        $this->_provider->shutdown();
+    }
+}