feat: integrate PostHog feature flags with Laravel Pennant

.gitignore

@@ -15,3 +15,4 @@ xdebug.log
 .DS_Store
 .env
 node_modules/
+/.laravel-changes/

packages/laravel/PENNANT.md

@@ -0,0 +1,75 @@
+# Laravel Pennant
+
+The optional, read-only driver uses the PHP SDK's feature flag snapshots. Install
+Pennant in your application, then select the store:
+
+```sh
+composer require laravel/pennant:^1.26
+```
+
+```dotenv
+PENNANT_STORE=posthog
+```
+
+Package discovery registers a `posthog` store if the application has not already
+configured one. No Pennant migration or database-backed flag store is needed.
+
+```php
+use Laravel\Pennant\Feature;
+
+Feature::for('account-123')->active('new-checkout');
+$variant = Feature::for('account-123')->value('checkout-layout');
+```
+
+Values retain their boolean or variant-string type. Unknown or unresolved flags
+return `false`, not an accidentally active `null`. Reads use the SDK's normal
+exposure events; repeated cached reads do not generate duplicate exposures.
+
+String and integer scopes are distinct IDs. Authenticated user/model scopes use
+their auth identifier or model key, without a class-name prefix, to match ordinary
+SDK capture. Models are not serialized and their properties are not sent.
+Pennant normally uses the authenticated user as its default scope. When that
+scope is null, the driver uses the runtime's current analytics context. Tracing
+headers remain untrusted analytics input, never authorization evidence.
+
+For custom scope types, use Pennant's scope-identifier contract to resolve an
+explicit string/integer identifier. Configure runtime group resolvers for group
+flag targeting. Use the native `evaluateFlags()` API for person/group properties,
+local-only evaluation, payloads, key subsets and unresolved reasons:
+
+```php
+$payload = \PostHog\Laravel\Facades\PostHog::evaluateFlags()->getFlagPayload('checkout-layout');
+```
+
+## Read-only behavior
+
+Define and manage flags in PostHog. `define`, `activate`, `deactivate`, `delete`,
+`purge` and other write operations throw `LogicException`; the driver never pretends
+to modify remote flag definitions. Use remote flag key strings, not locally defined
+PHP feature classes.
+
+`Feature::defined()` intentionally returns an empty array: this read-only external
+store has no local definitions. Pennant calls it during feature-name resolution,
+before resolving the requested scope, so it never evaluates flags or performs I/O.
+Use `Feature::for($scope)->all()` or `Feature::for($scope)->loadAll()` to discover
+PostHog flags for a scope through Pennant's external-definition contract. Discovery
+uses that scope's native snapshot without recording exposure; reading the discovered
+values uses normal deduplicated exposures. Bulk and subsequent individual reads
+reuse the same snapshot, preserving variants and disabled values. Unknown or
+unresolved flags remain inactive.
+
+## Cache lifetime
+
+The SDK reuses snapshots for identical complete evaluation inputs. Pennant also
+has its own feature/scope cache. The integration clears PostHog stores around HTTP,
+queue and command boundaries, including failed jobs. Pennant's own Octane lifecycle
+integration remains active, and the driver resolves the current application rather
+than retaining a request manager in a singleton. Calling commands that opt into
+`IsolatesCommandContext` also clear Pennant's cache on direct child-call entry and
+after restoring the caller, including failures. Uninstrumented direct calls are
+not intercepted; explicit context scopes alone do not clear Pennant's cache.
+
+If targeting properties/groups change for the **same scope within one request**,
+call `Feature::flushCache()` before another Pennant read. Alternatively use native
+`evaluateFlags()` directly, which keys its snapshot cache by all evaluation inputs.
+Do not retain a scoped PostHog manager in an application singleton.

packages/laravel/README.md

@@ -266,6 +266,11 @@ No cache is enabled implicitly, and there is no background timer. The PHP client
 `loadFlags()` remains available for an explicit refresh. You can instead supply a
 custom provider class in `sdk.flag_definition_cache_provider`.
 
+## Laravel Pennant
+
+An optional read-only PostHog store supports Pennant boolean and variant reads.
+See [Pennant setup, scope mapping and cache behavior](PENNANT.md).
+
 ## Configuration callbacks and full PHP access
 
 `posthog.sdk` passes PHP SDK options through. `before_send`, `error_handler`, and

packages/laravel/composer.json

@@ -12,8 +12,10 @@
     "require-dev": {
         "orchestra/testbench": "^10.0 || ^11.0",
         "phpunit/phpunit": "^11.0 || ^12.0",
-        "laravel/octane": "^2.0"
+        "laravel/octane": "^2.0",
+        "laravel/pennant": "^1.0"
     },
+    "suggest": {"laravel/pennant": "Use PostHog flags through Laravel Pennant (^1.0)."},
     "autoload": {"psr-4": {"PostHog\\Laravel\\": "src/"}},
     "autoload-dev": {"psr-4": {"PostHog\\Laravel\\Tests\\": "tests/"}},
     "extra": {"laravel": {"providers": ["PostHog\\Laravel\\PostHogServiceProvider"], "aliases": {"PostHog": "PostHog\\Laravel\\Facades\\PostHog"}}},

packages/laravel/src/ConsoleLifecycle.php

@@ -67,6 +67,7 @@ private function enter(): void
         $data = $context->snapshot();
         $context->enter();
         $context->begin($data);
+        Features\PennantCache::flush();
     }
 
     private function remember(Throwable $exception): void
@@ -86,6 +87,7 @@ private function leave(bool $flush = true): void
         } catch (Throwable) {
         } finally {
             $this->app->make(Context::class)->leave();
+            Features\PennantCache::flush();
         }
     }
 }

packages/laravel/src/Features/PennantCache.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace PostHog\Laravel\Features;
+
+use Illuminate\Container\Container;
+use Laravel\Pennant\FeatureManager;
+
+/** @internal Pennant caches values independently of the SDK's scoped snapshots. */
+final class PennantCache
+{
+    public static function flush(): void
+    {
+        $app = Container::getInstance();
+        if (!$app->resolved(FeatureManager::class)) {
+            return;
+        }
+        $manager = $app->make(FeatureManager::class);
+        $manager->setContainer($app);
+        foreach ($app['config']->get('pennant.stores', []) as $name => $store) {
+            if (($store['driver'] ?? null) === 'posthog') {
+                $manager->store($name)->flushCache();
+            }
+        }
+    }
+}

packages/laravel/src/Features/PennantMiddleware.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace PostHog\Laravel\Features;
+
+use Closure;
+
+/** @internal */
+final class PennantMiddleware
+{
+    public function handle($request, Closure $next): mixed
+    {
+        PennantCache::flush();
+        try {
+            return $next($request);
+        } finally {
+            PennantCache::flush();
+        }
+    }
+}

packages/laravel/src/Features/PennantServiceProvider.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace PostHog\Laravel\Features;
+
+use Illuminate\Contracts\Http\Kernel;
+use Illuminate\Support\ServiceProvider;
+use Laravel\Pennant\FeatureManager;
+
+/** @internal */
+final class PennantServiceProvider extends ServiceProvider
+{
+    public function boot(): void
+    {
+        if ($this->app['config']->get('pennant.stores.posthog') === null) {
+            $this->app['config']->set('pennant.stores.posthog', ['driver' => 'posthog']);
+        }
+        $this->callAfterResolving(FeatureManager::class, function ($manager) {
+            $manager->extend('posthog', function () {
+                return new PostHogDriver();
+            });
+        });
+        $this->callAfterResolving(Kernel::class, fn ($kernel) => $kernel->prependMiddleware(PennantMiddleware::class));
+        $this->app['events']->listen([
+            \Illuminate\Queue\Events\JobProcessing::class,
+            \Illuminate\Queue\Events\JobProcessed::class,
+            \Illuminate\Queue\Events\JobExceptionOccurred::class,
+            \Illuminate\Console\Events\CommandStarting::class,
+            \Illuminate\Console\Events\CommandFinished::class,
+        ], fn () => PennantCache::flush());
+    }
+}

packages/laravel/src/Features/PostHogDriver.php

@@ -0,0 +1,86 @@
+<?php
+
+namespace PostHog\Laravel\Features;
+
+use Illuminate\Container\Container;
+use Illuminate\Contracts\Auth\Authenticatable;
+use Illuminate\Database\Eloquent\Model;
+use InvalidArgumentException;
+use Laravel\Pennant\Contracts\DefinesFeaturesExternally;
+use Laravel\Pennant\Contracts\Driver;
+use LogicException;
+use PostHog\Laravel\PostHog;
+
+/** @internal */
+final class PostHogDriver implements Driver, DefinesFeaturesExternally
+{
+    public function get(string $feature, mixed $scope): mixed
+    {
+        $id = $this->identity($scope);
+        return Container::getInstance()->make(PostHog::class)->evaluateFlags($id)->getFlag($feature) ?? false;
+    }
+
+    public function getAll(array $features): array
+    {
+        $values = [];
+        foreach ($features as $feature => $scopes) {
+            $values[$feature] = [];
+            foreach ($scopes as $key => $scope) {
+                $values[$feature][$key] = $this->get($feature, $scope);
+            }
+        }
+        return $values;
+    }
+
+    public function defined(): array
+    {
+        // Pennant calls this before resolving the scope; there are no local definitions.
+        return [];
+    }
+
+    public function definedFeaturesForScope(mixed $scope): array
+    {
+        return Container::getInstance()->make(PostHog::class)->evaluateFlags($this->identity($scope))->getKeys();
+    }
+
+    private function identity(mixed $scope): ?string
+    {
+        if ($scope === null) {
+            return null;
+        }
+        if ($scope instanceof Authenticatable) {
+            $scope = $scope->getAuthIdentifier();
+        } elseif ($scope instanceof Model) {
+            $scope = $scope->getKey();
+        }
+        if (is_string($scope) || is_int($scope)) {
+            return (string) $scope;
+        }
+        throw new InvalidArgumentException('PostHog Pennant scopes must have a string or integer identifier.');
+    }
+
+    public function define(string $feature, callable $resolver): void
+    {
+        throw new LogicException('PostHog flags are read-only. Define them in PostHog.');
+    }
+
+    public function set(string $feature, mixed $scope, mixed $value): void
+    {
+        throw new LogicException('PostHog flags are read-only. Update them in PostHog.');
+    }
+
+    public function setForAllScopes(string $feature, mixed $value): void
+    {
+        throw new LogicException('PostHog flags are read-only. Update them in PostHog.');
+    }
+
+    public function delete(string $feature, mixed $scope): void
+    {
+        throw new LogicException('PostHog flags are read-only. Remove them in PostHog.');
+    }
+
+    public function purge(?array $features): void
+    {
+        throw new LogicException('PostHog flags are read-only. Remove them in PostHog.');
+    }
+}

packages/laravel/src/PostHogServiceProvider.php

@@ -39,6 +39,9 @@ public function register(): void
                 $config['flag_cache']['refresh_interval'],
             );
         });
+        if (class_exists(\Laravel\Pennant\FeatureManager::class)) {
+            $this->app->register(Features\PennantServiceProvider::class);
+        }
         if (class_exists(AutocaptureServiceProvider::class)) {
             $this->app->register(AutocaptureServiceProvider::class);
         }
@@ -151,6 +154,7 @@ private function finish(Container $app, bool $restore = false): void
         } finally {
             $context = $app->make(Context::class);
             $restore ? $context->leave() : $context->end();
+            Features\PennantCache::flush();
         }
     }
 }

packages/laravel/tests/ApiSurfaceTest.php

@@ -193,6 +193,10 @@ public function testPublicApiMatchesItsSnapshot(): void
                 \PostHog\Laravel\Autocapture\ModelEvents::class,
                 \PostHog\Laravel\Autocapture\Outcomes::class,
                 \PostHog\Laravel\Autocapture\RequestSummary::class,
+                \PostHog\Laravel\Features\PennantCache::class,
+                \PostHog\Laravel\Features\PennantMiddleware::class,
+                \PostHog\Laravel\Features\PennantServiceProvider::class,
+                \PostHog\Laravel\Features\PostHogDriver::class,
             ] as $internal
         ) {
             $this->assertArrayNotHasKey($internal, $api['symbols']);

packages/laravel/tests/Fixtures/PennantEndEventProvider.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace PostHog\Laravel\Tests\Fixtures;
+
+use Illuminate\Queue\Events\JobExceptionOccurred;
+use Illuminate\Queue\Events\JobProcessed;
+use Illuminate\Support\ServiceProvider;
+use Laravel\Pennant\Feature;
+
+class PennantEndEventProvider extends ServiceProvider
+{
+    public function boot(): void
+    {
+        $this->app['events']->listen([JobProcessed::class, JobExceptionOccurred::class], function (): void {
+            if ($this->app['config']->get('pennant-test.read-on-job-end', false)) {
+                $this->app['config']->set('pennant-test.job-value', Feature::value('layout'));
+            }
+        });
+    }
+}