Laravel Pennant

https://github.com/laravel/pennant
Admin
A simple, lightweight library for managing feature flags in Laravel applications.
Tokens:42,132
Snippets:334
Trust Score:9.7
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example: create NewFeature

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/console.md

Example command that creates a new feature class at app/Features/NewFeature.php.

```bash
# Creates app/Features/NewFeature.php
php artisan pennant:feature NewFeature
```

--------------------------------

### Example with --except-registered and --store

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/console.md

Example command that purges all features except registered ones from the `database` store. The output is either a message that no features were purged or a list of purged features.

```bash
php artisan pennant:purge --except-registered --store=database
# "No features to purge from storage." or lists purged features
```

--------------------------------

### pennant:feature command usage

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/console.md

Usage examples for the pennant:feature command. The --force option creates the class even if it already exists.

```bash
php artisan pennant:feature NewApi
php artisan pennant:feature NewApi --force
```

--------------------------------

### Usage examples for pennant:purge

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/console.md

Shows common usages of the `pennant:purge` command: purging all features, specific features, excluding features, targeting a store, and using the alias.

```bash
php artisan pennant:purge                          # purge everything from the default store
php artisan pennant:purge new-api legacy-api       # purge two named features
php artisan pennant:purge --except=stable-feature  # purge all except the named ones
php artisan pennant:purge --except-registered      # purge all except defined/registered features
php artisan pennant:purge --store=array            # target a specific store
php artisan pennant:clear                          # alias
```

--------------------------------

### Listening to feature events

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/events.md

Shows how to listen to the FeatureUpdated and UnknownFeatureResolved events. It logs when a flag is updated and when an unknown flag is read. The example also demonstrates that activating a feature fires FeatureUpdated, while checking an unknown feature fires UnknownFeatureResolved and resolves to false.

```php
use Illuminate\Support\Facades\Event;
use Laravel\Pennant\Events\FeatureUpdated;
use Laravel\Pennant\Events\UnknownFeatureResolved;
use Laravel\Pennant\Feature;

// Observe rollouts and typos.
Event::listen(FeatureUpdated::class, function (FeatureUpdated $event) {
    Log::info('flag updated', ['feature' => $event->feature, 'scope' => $event->scope, 'value' => $event->value]);
});

Event::listen(UnknownFeatureResolved::class, function (UnknownFeatureResolved $event) {
    Log::warning('unknown flag read', ['feature' => $event->feature]);
});

Feature::for($user)->activate('new-dashboard'); // fires FeatureUpdated
Feature::for($user)->active('typo-flag');       // fires UnknownFeatureResolved, resolves false
```

--------------------------------

### Using EnsureFeaturesAreActive middleware in routes

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/support.md

Example usage in a route file: applies the middleware with the 'new-api' and 'dark-mode' features, and customizes the inactive response to return a 404 'Coming soon' response.

```php
// routes/web.php
use Laravel\Pennant\Middleware\EnsureFeaturesAreActive;

Route::get('/v2', fn () => 'hello')->middleware(EnsureFeaturesAreActive::using('new-api', 'dark-mode'));

// customize the 400 response for the whole app
EnsureFeaturesAreActive::whenInactive(function ($request, $features) {
    return response('Coming soon', 404);
});
```

--------------------------------

### Scoped and global feature activation examples

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/pending-scoped-feature-interaction.md

Shows scoped and global feature interactions. Activate a feature for multiple users, check with an explicit scope (the default scope is not used in that chain), and use the global scope to activate and check inactivity.

```php
use Laravel\Pennant\Feature;

// Scoped interaction: activate for two users at once.
Feature::for('tim@laravel.com')->for('jess@laravel.com')->activate('new-dashboard');

// Check with explicit scope; the default scope is NOT used in this chain.
if (Feature::for($user)->active('new-dashboard')) {
    // …
}

// Global scope.
Feature::globally()->activate('maintenance-mode');
Feature::globally()->inactive('maintenance-mode'); // false → inactive
```

--------------------------------

### Get all feature values with all()

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/pending-scoped-feature-interaction.md

Returns values() for every feature defined and valid for the first scope. Returns an array of feature-name to value pairs.

```php
public function all()
```

--------------------------------

### Get multiple feature values with values()

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/pending-scoped-feature-interaction.md

Loads missing values and returns a map of feature-name to value for the interaction's single scope. Throws RuntimeException if more than one scope is set.

```php
public function values($features)
```

--------------------------------

### Laravel\Pennant\Contracts\Driver interface

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/types.md

Defines the contract for custom feature drivers. Implement this interface to create a driver that can be used with the FeatureManager. The `define` method registers a resolver for a feature, `defined` returns all defined features, `getAll` retrieves multiple features, `get` and `set` manage a feature value for a scope, `setForAllScopes` sets a value for all scopes, `delete` removes a feature value, and `purge` clears cached features.

```php
// src/Contracts/Driver.php
interface Driver
{
    public function define(string $feature, callable $resolver): void;
    public function defined(): array;
    public function getAll(array $features): array;
    public function get(string $feature, mixed $scope): mixed;
    public function set(string $feature, mixed $scope, mixed $value): void;
    public function setForAllScopes(string $feature, mixed $value): void;
    public function delete(string $feature, mixed $scope): void;
    public function purge(?array $features): void;
}
```

--------------------------------

### Swap default store and verify storage semantics

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/drivers.md

Shows how to swap the default store to 'array' at runtime and verify storage semantics using Feature::define(), activate(), value(), stored(), and purge().

```php
use Illuminate\Support\Facades\App;
use Laravel\Pennant\Feature;
use Laravel\Pennant\FeatureManager;

// Swap the default store at runtime (in-memory).
Feature::setDefaultDriver('array');

// Confirm storage semantics.
Feature::define('roller', fn () => true);
Feature::for($user)->activate('roller');       // persists true
Feature::for($user)->value('roller');          // true
Feature::stored();                             // contains 'roller' on DB driver
Feature::purge();                              // clear everything
```

--------------------------------

### Get single feature value with value()

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/pending-scoped-feature-interaction.md

Returns the feature's value for the first scope. Equivalent to head($this->values([$feature])).

```php
public function value($feature)
```

--------------------------------

### DatabaseDriver::__construct

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/drivers.md

Initializes a new DatabaseDriver instance with the database manager, event dispatcher, configuration repository, store name, and initial feature state resolvers.

```APIDOC
## DatabaseDriver::__construct

### Description
Initializes a new DatabaseDriver instance.

### Method
__construct

### Signature
```php
public function __construct(DatabaseManager $db, Dispatcher $events, Repository $config, string $name, $featureStateResolvers)
```

### Parameters
- **$db** (\Illuminate\Database\DatabaseManager) - Required - Database connection manager.
- **$events** (Dispatcher) - Required - Dispatcher for `UnknownFeatureResolved`.
- **$config** (\Illuminate\Config\Repository) - Required - Reads `pennant.stores.<name>.table` and `pennant.stores.<name>.connection`.
- **$name** (string) - Required - Store name.
- **$featureStateResolvers** (array<string, callable(mixed $scope): mixed>) - Required - Initial resolver map.

### Returns
void
```

--------------------------------

### Define and inspect features with Feature facade

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/decorator.md

Shows how to define features and inspect them through the Feature facade. Use Feature::define with a closure or a class name for lazy resolution, then retrieve defined names, stored flags, the name-to-resolver map, or a resolved instance.

```php
use Laravel\Pennant\Feature;

// Define + inspect through the decorator/facade.
Feature::define('new-dashboard', fn (User $user) => $user->is_admin);
Feature::define(TeamDashboard::class);            // lazy class-based resolution

$names = Feature::defined();                      // ['new-dashboard', 'team-dashboard', …]
$all    = Feature::stored();                      // names of persisted flags
$map    = Feature::nameMap();                     // name → resolver/class
$klass  = Feature::instance(TeamDashboard::class);// resolved instance
```

--------------------------------

### using(BackedEnum|UnitEnum|string ...$features): string

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/support.md

Generates a middleware alias string for the given features, usable in route files or the HTTP kernel.

```APIDOC
## using(BackedEnum|UnitEnum|string ...$features): string

### Description
Generates a middleware alias string for the given features, usable in route files or the HTTP kernel.

### Method
Static helper

### Signature
`using(BackedEnum|UnitEnum|string ...$features): string`

### Parameters
- `$features` (BackedEnum|UnitEnum|string) - Required - Variadic list of features.

### Returns
`string` - The middleware alias string in the format `static::class . ':' . implode(',', enum_value(...))`.

### Example
```php
Route::get('/v2', fn () => 'hello')->middleware(EnsureFeaturesAreActive::using('new-api', 'dark-mode'));
```
```

--------------------------------

### Decorator constructor with parameter documentation

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/decorator.md

Constructor for the Decorator class. Parameters include the store name, the underlying driver, a callback returning the default scope, the application container, and the in-memory feature state cache.

```php
// src/Drivers/Decorator.php:102
/**
 * @param  string  $name
 * @param  Driver  $driver
 * @param  (callable(): mixed)  $defaultScopeResolver
 * @param  Container  $container
 * @param  Collection<int, array{ feature: string, scope: mixed, value: mixed }>  $cache
 */
public function __construct($name, $driver, $defaultScopeResolver, $container, $cache)
```

--------------------------------

### Use FeatureManager with custom scope and error handling

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/feature.md

Shows how to obtain the FeatureManager from the container, set a custom scope resolver, switch the default driver to 'array', retrieve a store decorator, flush the cache, and handle the exception thrown when requesting an undefined store. The exception message is "Pennant store [does-not-exist] is not defined."

```php
use Illuminate\Support\Facades\App;
use Laravel\Pennant\FeatureManager;

$manager = App::make(FeatureManager::class);

$manager->resolveScopeUsing(fn ($driver) => session()->get('tenant_id'));
$manager->setDefaultDriver('array');

$decorator = $manager->store('array');   // Decorator over ArrayDriver
$manager->flushCache();

// Exceptions
try {
    $manager->store('does-not-exist');
} catch (InvalidArgumentException $e) {
    // "Pennant store [does-not-exist] is not defined."
}
```

--------------------------------

### Name attribute usage example

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/support.md

Apply the Name attribute to a feature class and define it. The attribute overrides the feature name, so Feature::name returns 'team-dash' instead of the class name.

```php
use Laravel\Pennant\Attributes\Name;

#[Name('team-dash')]
class TeamDashboard
{
    public function resolve(mixed $scope): mixed { return true; }
}

Feature::define(TeamDashboard::class);
Feature::name(TeamDashboard::class); // 'team-dash'
```

--------------------------------

### instance() method signature with docblock

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/decorator.md

Returns the feature's implementation: a container-resolved class instance, a Closure/Lottery, or a closure returning a scalar value.

```php
/**
 * @param  \BackedEnum|\UnitEnum|string  $name
 */
public function instance($name)
```

--------------------------------

### __call

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/feature.md

Dynamically forwards any unknown method to the default store, enabling methods like Feature::active() and Feature::for().

```APIDOC
## __call

### Description
Dynamically forwards any unknown method to the default store: `$this->store()->$method(...$parameters)`. This is what makes `Feature::active()`, `Feature::for()`, `Feature::when()`, etc. work.

### Method
`__call($method, $parameters)`

### Parameters
- **$method** (string) - Required - The method name to call on the default store.
- **$parameters** (array) - Required - The parameters to pass to the method.

### Returns
Mixed - The result of the forwarded method call.

### Example
```php
$result = $manager->active('feature');
```
```

--------------------------------

### Get and set default driver in FeatureManager

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/feature.md

Defines the default driver getter and setter. getDefaultDriver reads the 'pennant.default' config value, falling back to 'database' if absent. setDefaultDriver writes the given name into the config repository.

```php
// src/FeatureManager.php:266
public function getDefaultDriver()
// src/FeatureManager.php:277
public function setDefaultDriver($name)
```

--------------------------------

### handle(Request $request, Closure $next, BackedEnum|UnitEnum|string ...$features)

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/support.md

Processes the incoming request, loading missing features and aborting with a 400 response if any required features are inactive, otherwise passing the request to the next middleware.

```APIDOC
## handle(Request $request, Closure $next, BackedEnum|UnitEnum|string ...$features)

### Description
Processes the incoming request, loading missing features and aborting with a 400 response if any required features are inactive, otherwise passing the request to the next middleware.

### Method
Middleware handle

### Signature
`handle(Request $request, Closure $next, BackedEnum|UnitEnum|string ...$features): mixed`

### Parameters
- `$request` (Request) - Required - The incoming HTTP request.
- `$next` (Closure) - Required - The next middleware closure.
- `$features` (BackedEnum|UnitEnum|string) - Required - Variadic list of features to check.

### Returns
`mixed` - The response from the next middleware or the custom responder/abort response.

### Behavior
Loads missing features, and if `Feature::someAreInactive($features)`, responds with the custom responder or `abort(400, $error)` where `$error = config('app.debug') ? 'Required features [n1, n2] not enabled.' : ''`. Otherwise passes to `$next($request)`.
```

--------------------------------

### Define and check features with Feature::define and Feature::active

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/feature.md

Shows how to define a feature with a resolver closure and check it for the default scope (authenticated user). Also demonstrates reading the raw value for a specific scope using Feature::for($user)->value().

```php
use Laravel\Pennant\Feature;

// Define a feature with a resolver closure.
Feature::define('new-checkout', fn (User $user) => $user->inBeta());

// Check the flag for the default scope (authenticated user).
if (Feature::active('new-checkout')) {
    // …
}

// Read the raw value for a specific scope.
$value = Feature::for($user)->value('new-checkout');
```

--------------------------------

### Publish Pennant config and migrations

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/configuration.md

Publishes the Pennant configuration file and migration for the features table. Run each command separately to publish the respective assets.

```bash
php artisan vendor:publish --tag=pennant-config
php artisan vendor:publish --tag=pennant-migrations
```

--------------------------------

### nameMap() method signature

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/decorator.md

Returns the full map of feature names to their implementations as an array of string to mixed values.

```php
public function nameMap(): array
```

--------------------------------

### DatabaseDriver constructor

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/drivers.md

Constructor for the DatabaseDriver. Accepts the database manager, event dispatcher, config repository, store name, and an initial resolver map. The config repository reads the 'pennant.stores.<name>.table' and 'pennant.stores.<name>.connection' settings.

```php
// src/Drivers/DatabaseDriver.php:92
/**
 * @param  array<string, (callable(mixed $scope): mixed)>  $featureStateResolvers
 * @return void
 */
public function __construct(DatabaseManager $db, Dispatcher $events, Repository $config, string $name, $featureStateResolvers)
```

--------------------------------

### Configure Pennant stores in config/pennant.php

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/configuration.md

Default configuration file for Pennant, defining the default store and available stores. The default store is set to 'database' unless the PENNANT_STORE environment variable is defined. The 'array' store uses the in-memory driver, while the 'database' store uses the persistent database driver with optional connection and table settings.

```php
return [

    'default' => env('PENNANT_STORE', 'database'),

    'stores' => [

        'array' => [
            'driver' => 'array',
        ],

        'database' => [
            'driver' => 'database',
            'connection' => null,
            'table' => 'features',
        ],

    ],
];
```

--------------------------------

### PennantMigration base class with getConnection()

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/support.md

Base class for Pennant migrations. Overrides getConnection() to return the configured database connection from 'pennant.stores.database.connection', falling back to 'database.default' when the config is null or the string 'null'.

```php
// src/Migrations/PennantMigration.php
abstract class PennantMigration extends Migration
{
    /**
     * Get the migration connection name.
     *
     * @return string
     */
    public function getConnection()
    {
        $connection = config('pennant.stores.database.connection');

        return ($connection === null || $connection === 'null') ? config('database.default') : $connection;
    }
}
```

--------------------------------

### FeatureManager::createDatabaseDriver

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/feature.md

Creates a database driver instance.

```APIDOC
## FeatureManager::createDatabaseDriver

### Description
Creates a database driver instance.

### Method
`createDatabaseDriver(array $config, string $name)`

### Parameters
- `$config` (array) - Required - Store config.
- `$name` (string) - Required - Store name.

### Returns
`DatabaseDriver` - Constructed with `container['db']`, `container['events']`, `container['config']`, `$name`, `[]`.
```

--------------------------------

### FeatureManager::__construct

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/feature.md

Creates a new Pennant manager instance.

```APIDOC
## FeatureManager::__construct

### Description
Creates a new Pennant manager instance.

### Method
`__construct(Container $container)`

### Parameters
- `$container` (\Illuminate\Contracts\Container\Container) - Required - The application container; used to read config, events, auth, and resolve feature classes.

### Returns
`void`

### Notes
Registered as a container singleton by `PennantServiceProvider::register()`.
```

--------------------------------

### Load all features with loadAll()

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/pending-scoped-feature-interaction.md

Loads every defined feature that is valid for the interaction's first scope. Returns an array keyed by feature name with (index, value) pairs.

```php
public function loadAll()
```

--------------------------------

### Register custom driver with FeatureManager::extend()

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/drivers.md

Registers a custom 'redis' driver using FeatureManager::extend() and then uses it with Feature::store('redis')->active(). The closure receives the container and config and must return an object implementing Driver.

```php
use Laravel\Pennant\FeatureManager;

// Custom driver via extend().
$manager = App::make(FeatureManager::class);
$manager->extend('redis', function ($container, $config) {
    return new RedisDriver($container->make('redis')->connection($config['connection']));
});

// Then in config: 'stores' => ['redis' => ['driver' => 'redis', 'connection' => 'default']]
Feature::store('redis')->active('my-flag');
```

--------------------------------

### Discover features in a directory

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/decorator.md

Scans a directory for PHP feature files and registers them lazily. The namespace defaults to 'App\Features' and the path defaults to base_path('app/Features').

```php
public function discover($namespace = 'App\Features', $path = null)
```

--------------------------------

### extend

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/feature.md

Registers a custom driver creator. The closure is bound to the manager and called with the container and config.

```APIDOC
## extend

### Description
Registers a custom driver creator. The closure is bound to the manager and called as `($container, $config)`.

### Method
`extend(string $driver, Closure $callback)`

### Parameters
- **$driver** (string) - Required - The driver name.
- **$callback** (Closure) - Required - The callback that creates the driver instance.

### Returns
- **$this** - The manager instance for chaining.

### Example
```php
$manager->extend('custom', function ($container, $config) {
    return new CustomDriver($config);
});
```
```

--------------------------------

### Persist and purge a feature value with Feature facade

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/decorator.md

Demonstrates persisting a feature value with Feature::for($user)->activate and then purging it with Feature::purge. The purge may throw a RuntimeException for drivers that cannot purge, but the built-in drivers can.

```php
use Laravel\Pennant\Feature;
use Laravel\Pennant\Events\FeatureUpdated;

Feature::define('beta', fn () => false);

// Persist and later purge, observing events.
Feature::for($user)->activate('beta', 'gradual');     // value 'gradual'

try {
    Feature::purge('beta');                          // deletes the stored value
} catch (RuntimeException $e) {
    // Only reachable for drivers that cannot purge; the built-in drivers can.
}
```

--------------------------------

### Activate a feature with Feature::activate

Source: https://github.com/laravel/pennant/blob/1.x/resources/boost/skills/pennant-development/SKILL.md

Use these snippets to activate a feature flag. The first activates globally, the second activates for a specific user using Feature::for().

```php
Feature::activate('new-dashboard');
Feature::for($user)->activate('new-dashboard');
```

--------------------------------

### FeatureManager driver factory method signatures

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/feature.md

Shows the signatures for createArrayDriver and createDatabaseDriver factory methods. These are matched by convention during driver resolution.

```php
// src/FeatureManager.php:157
public function createArrayDriver()
// src/FeatureManager.php:167
public function createDatabaseDriver(array $config, string $name)
```

--------------------------------

### Use the feature() helper with different argument counts

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/feature.md

Shows the three usage patterns of the feature() helper: retrieving the FeatureManager instance, checking a feature's scalar value for the default scope, and using the when/unless-style with active and inactive closures.

```php
$manager = feature();                       // FeatureManager
if (feature('new-checkout')) { … }          // scalar value for default scope
feature('new-checkout', fn () => 'new', fn () => 'old'); // when/unless-style
```

--------------------------------

### setAll method signature

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/decorator.md

Resolves every entry's feature/scope, then calls driver->setAll() if the driver implements CanSetManyFeaturesForScopes, otherwise loops driver->set(). Caches each value and dispatches FeatureUpdated per entry.

```php
/**
 * @internal
 *
 * @param  list<array{ feature: string, scope: mixed, value: mixed }>  $features
 */
public function setAll(array $features): void
```

--------------------------------

### loadAll()

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/pending-scoped-feature-interaction.md

Loads every defined feature that is valid for the interaction's first scope. Returns a map of feature name to (index, value) pairs.

```APIDOC
## Method: loadAll()

### Description
Loads all defined features valid for the first scope into cache, returning a map of feature name to (index, value) pairs.

### Method
loadAll

### Returns
array<string, array<int, mixed>> - Keyed by feature name, each value is an array of (index, value) pairs.

### Example
```php
$loaded = $interaction->loadAll();
```
```

--------------------------------

### set method signature

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/decorator.md

Resolves feature/scope, calls driver->set(), updates the cache, and dispatches FeatureUpdated.

```php
/** @internal */
public function set($feature, $scope, $value): void
```

--------------------------------

### Feature (facade) static methods

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/feature.md

The Feature facade exposes static methods for configuring stores, defining features, checking feature states, and interacting with feature values. It is the primary API for feature flag operations.

```APIDOC
## Feature Facade (Laravel\Pennant\Feature)

### Description
The Feature facade statically proxies all public methods on the FeatureManager. It provides a global access point for managing and evaluating feature flags.

### Methods

| Static method | Description |
|---|---|
| `store(string|null $store = null)` | Get a driver instance by name, or default if null. |
| `driver(string|null $name = null)` | Alias for `store`; returns a Decorator. |
| `createArrayDriver()` | Create an array driver instance. |
| `createDatabaseDriver(array $config, string $name)` | Create a database driver instance. |
| `serializeScope(mixed $scope)` | Serialize a scope value. |
| `useMorphMap(bool $value = true)` | Enable or disable morph map usage. |
| `flushCache()` | Flush the feature cache. |
| `resolveScopeUsing(callable $resolver)` | Set a custom scope resolver. |
| `getDefaultDriver()` | Get the default driver name. |
| `setDefaultDriver(string $name)` | Set the default driver name. |
| `forgetDriver(array|string|null $name = null)` | Forget a driver instance. |
| `forgetDrivers()` | Forget all driver instances. |
| `extend(string $driver, \Closure $callback)` | Register a custom driver. |
| `setContainer(\Illuminate\Container\Container $container)` | Set the container instance. |
| `discover(string $namespace = 'App\\Features', string|null $path = null)` | Discover feature classes. |
| `define(\BackedEnum|\UnitEnum|string $feature, mixed $resolver = null)` | Define a feature with an optional resolver. |
| `isResolverValidForScope(callable|string $resolver, mixed $scope)` | Check if a resolver is valid for a scope. |
| `defined()` | Get defined features. |
| `stored()` | Get stored features. |
| `globally()` | Begin a global feature interaction. |
| `activateForEveryone(\BackedEnum|\UnitEnum|string|array $feature, mixed $value = true)` | Activate a feature for everyone. |
| `deactivateForEveryone(\BackedEnum|\UnitEnum|string|array $feature)` | Deactivate a feature for everyone. |
| `purge(\BackedEnum|\UnitEnum|string|array|null $features = null)` | Purge stored features. |
| `name(\BackedEnum|\UnitEnum|string $feature)` | Get the name of a feature. |
| `nameMap()` | Get the name map. |
| `instance(\BackedEnum|\UnitEnum|string $name)` | Get a feature instance. |
| `getDriver()` | Get the underlying driver instance. |
| `macro(string $name, object|callable $macro)` | Register a macro. |
| `mixin(object $mixin, bool $replace = true)` | Mixin methods. |
| `hasMacro(string $name)` | Check if a macro exists. |
| `flushMacros()` | Flush macros. |
| `macroCall(string $method, array $parameters)` | Call a macro. |
| `for(mixed $scope)` | Start a scoped feature interaction. |
| `load(\BackedEnum|\UnitEnum|string|array $features)` | Load feature values. |
| `loadMissing(\BackedEnum|\UnitEnum|string|array $features)` | Load missing feature values. |
| `loadAll()` | Load all feature values. |
| `value(\BackedEnum|\UnitEnum|string $feature)` | Get the value of a feature. |
| `values(array $features)` | Get values for multiple features. |
| `all()` | Get all feature values. |
| `active(\BackedEnum|\UnitEnum|string $feature)` | Check if a feature is active. |
| `allAreActive(array $features)` | Check if all features are active. |
| `someAreActive(array $features)` | Check if some features are active. |
| `inactive(\BackedEnum|\UnitEnum|string $feature)` | Check if a feature is inactive. |
| `allAreInactive(array $features)` | Check if all features are inactive. |
| `someAreInactive(array $features)` | Check if some features are inactive. |
| `when(\BackedEnum|\UnitEnum|string $feature, \Closure $whenActive, \Closure|null $whenInactive = null)` | Execute a callback when a feature is active. |
| `unless(\BackedEnum|\UnitEnum|string $feature, \Closure $whenInactive, \Closure|null $whenActive = null)` | Execute a callback when a feature is inactive. |
| `activate(\BackedEnum|\UnitEnum|string|array $feature, mixed $value = true)` | Activate a feature. |
| `deactivate(\BackedEnum|\UnitEnum|string|array $feature)` | Deactivate a feature. |
| `forget(\BackedEnum|\UnitEnum|string|array $features)` | Forget feature values. |

### Usage
Calls to these static methods are proxied to the FeatureManager instance. Methods marked as not defined on FeatureManager are forwarded to the default store's Decorator via `__call`.

```

--------------------------------

### Constructor for PendingScopedFeatureInteraction

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/pending-scoped-feature-interaction.md

Constructor for PendingScopedFeatureInteraction. Accepts a Decorator instance as the driver, which is the decorated store the interaction operates on.

```php
public function __construct($driver)
```

--------------------------------

### __call($name, $parameters)

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/decorator.md

Magic method that handles dynamic feature interaction calls. It first checks for registered macros, then creates a PendingScopedFeatureInteraction and applies the default scope before invoking the requested method.

```APIDOC
## `__call($name, $parameters)`

### Description
Dispatches feature interaction methods like `active`, `value`, and `when` on the decorator. If a macro is registered for the method name, it is called; otherwise, a `PendingScopedFeatureInteraction` is created and the method is invoked with the given parameters.

### Method
`__call`

### Parameters
- **$name** (string) - Required - The name of the method being called.
- **$parameters** (array) - Required - The parameters to pass to the method.

### Behavior
1. If a macro with `$name` is registered, calls `macroCall($name, $parameters)`.
2. Otherwise, creates a `PendingScopedFeatureInteraction($this)`, and unless `$name === 'for'`, pre-applies the default scope (via `defaultScope()`, only when it is not `null`), then calls `$interaction->{$name}(...$parameters)`.

### Examples
```php
use Laravel\Pennant\Feature;

// Define + inspect through the decorator/facade.
Feature::define('new-dashboard', fn (User $user) => $user->is_admin);
Feature::define(TeamDashboard::class);            // lazy class-based resolution

$names = Feature::defined();                      // ['new-dashboard', 'team-dashboard', …]
$all    = Feature::stored();                      // names of persisted flags
$map    = Feature::nameMap();                     // name → resolver/class
$klass  = Feature::instance(TeamDashboard::class);// resolved instance
```

```php
use Laravel\Pennant\Feature;
use Laravel\Pennant\Events\FeatureUpdated;

Feature::define('beta', fn () => false);

// Persist and later purge, observing events.
Feature::for($user)->activate('beta', 'gradual');     // value 'gradual'

try {
    Feature::purge('beta');                          // deletes the stored value
} catch (RuntimeException $e) {
    // Only reachable for drivers that cannot purge; the built-in drivers can.
}
```
```

--------------------------------

### ArrayDriver

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/drivers.md

Documentation for the ArrayDriver class, including its constructor, methods, and behavior notes.

```APIDOC
## ArrayDriver

### Description
In-memory driver implementing `CanListStoredFeatures`, `Driver`, and `HasFlushableCache`. All state lives in process memory — used for testing and short-lived scopes.

### Constructor

```php
public function __construct(Dispatcher $events, $featureStateResolvers)
```

#### Parameters
- `$events` (`\Illuminate\Contracts\Events\Dispatcher`) - Required - Event dispatcher for `UnknownFeatureResolved`.
- `$featureStateResolvers` (`array<string, callable(mixed $scope): mixed>`) - Required - Initial resolver map (empty `[]` when created by the manager).

### Methods

#### define($feature, $resolver)
- Signature: `(string, callable): void`
- Returns: `void`
- Description: Defines a feature resolver.

#### defined()
- Signature: `(): array`
- Returns: `array<string>` — keys of the resolver map
- Description: Returns all defined features.

#### stored()
- Signature: `(): array`
- Returns: `array<string>` — keys of `$resolvedFeatureStates`
- Description: Returns all stored features.

#### getAll($features)
- Signature: `(array): array`
- Returns: `array<string, array<int, mixed>>`
- Description: Retrieves all feature states for the given features.

#### get($feature, $scope)
- Signature: `(string, mixed): mixed`
- Returns: cached value; else resolves, persists, returns; `false` for unknown features
- Description: Retrieves the value of a feature for a given scope.

#### set($feature, $scope, $value)
- Signature: `(string, mixed, mixed): void`
- Returns: `void`
- Description: Sets the value of a feature for a given scope.

#### setAll(array $features)
- Signature: `(list<array{feature,scope,value}>): void`
- Returns: `void`
- Description: Sets multiple feature values at once.

#### setForAllScopes($feature, $value)
- Signature: `(string, mixed): void`
- Returns: `void`
- Description: Overwrites every stored scope value for the feature.

#### delete($feature, $scope)
- Signature: `(string, mixed): void`
- Returns: `void`
- Description: Deletes the value of a feature for a given scope.

#### purge($features)
- Signature: `(?array): void`
- Returns: `void`
- Description: `null` → clear everything; else unset named features.

#### flushCache()
- Signature: `(): void`
- Returns: `void`
- Description: Resets `$resolvedFeatureStates = []`.

### Behavior Notes
- `get()` uses an `stdClass` sentinel (`$unknownFeatureValue`) returned by `resolveValue()` when no resolver exists for the feature; the sentinel is converted to `false` and the dispatcher fires `UnknownFeatureResolved`.
- Scopes are always normalized through `Feature::serializeScope()` before becoming array keys.
```

--------------------------------

### all()

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/pending-scoped-feature-interaction.md

Returns values for every feature defined and valid for the first scope.

```APIDOC
## Method: all()

### Description
Returns an associative array of feature name to value for all features defined and valid for the first scope.

### Method
all

### Returns
array<string, mixed> - Map of feature name to value for all features.

### Example
```php
$all = $interaction->all();
```
```

--------------------------------

### AllFeaturesPurged event class

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/events.md

Event class with no properties. Dispatched from Decorator::purge(null) (src/Drivers/Decorator.php:628) after driver->purge(null) and cache reset.

```php
// src/Events/AllFeaturesPurged.php
class AllFeaturesPurged
{
    //
}
```

--------------------------------

### Forward dynamic calls with __call in FeatureManager

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/feature.md

Magic method that forwards unknown method calls to the default store via $this->store()->$method(...$parameters). This enables static-like calls such as Feature::active(), Feature::for(), and Feature::when().

```php
// src/FeatureManager.php:350
public function __call($method, $parameters)
```

--------------------------------

### Laravel\Pennant\Contracts\Driver

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/types.md

Documentation for the Laravel\Pennant\Contracts\Driver interface, which must be implemented by custom feature flag drivers.

```APIDOC
## Laravel\Pennant\Contracts\Driver

### Description
Interface that must be implemented by custom feature flag drivers. It defines the contract for defining, retrieving, setting, and deleting feature flag values.

### Methods

#### define
- **Signature**: `public function define(string $feature, callable $resolver): void`
- **Parameters**:
  - `$feature` (string) - Required - The feature name.
  - `$resolver` (callable) - Required - A callable that resolves the feature value for a given scope.
- **Returns**: `void`

#### defined
- **Signature**: `public function defined(): array`
- **Parameters**: None
- **Returns**: `array<string>` - List of defined feature names.

#### getAll
- **Signature**: `public function getAll(array $features): array`
- **Parameters**:
  - `$features` (array) - Required - Array of features keyed by feature name with values as arrays of scopes.
- **Returns**: `array<string, array<int, mixed>>` - Array of features with their values for each scope.

#### get
- **Signature**: `public function get(string $feature, mixed $scope): mixed`
- **Parameters**:
  - `$feature` (string) - Required - The feature name.
  - `$scope` (mixed) - Required - The scope for which to retrieve the value.
- **Returns**: `mixed` - The feature value for the given scope.

#### set
- **Signature**: `public function set(string $feature, mixed $scope, mixed $value): void`
- **Parameters**:
  - `$feature` (string) - Required - The feature name.
  - `$scope` (mixed) - Required - The scope for which to set the value.
  - `$value` (mixed) - Required - The value to set.
- **Returns**: `void`

#### setForAllScopes
- **Signature**: `public function setForAllScopes(string $feature, mixed $value): void`
- **Parameters**:
  - `$feature` (string) - Required - The feature name.
  - `$value` (mixed) - Required - The value to set for all scopes.
- **Returns**: `void`

#### delete
- **Signature**: `public function delete(string $feature, mixed $scope): void`
- **Parameters**:
  - `$feature` (string) - Required - The feature name.
  - `$scope` (mixed) - Required - The scope for which to delete the value.
- **Returns**: `void`

#### purge
- **Signature**: `public function purge(?array $features): void`
- **Parameters**:
  - `$features` (?array) - Required - Array of feature names to purge, or null to purge all.
- **Returns**: `void`
```

--------------------------------

### flushCache() method signature

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/decorator.md

Resets the in-memory cache to a new empty Collection and calls driver->flushCache() if the driver implements HasFlushableCache.

```php
public function flushCache()
```

--------------------------------

### DatabaseDriver::defined

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/drivers.md

Returns an array of all defined feature names.

```APIDOC
## DatabaseDriver::defined

### Description
Returns an array of all defined feature names.

### Method
defined

### Signature
```php
public function defined(): array
```

### Returns
array<string> - List of defined feature names.
```

--------------------------------

### DatabaseDriver::getAll

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/drivers.md

Retrieves the values for multiple features for a given scope.

```APIDOC
## DatabaseDriver::getAll

### Description
Retrieves the values for multiple features for a given scope.

### Method
getAll

### Signature
```php
public function getAll($features): array
```

### Parameters
- **$features** (array) - Required - List of feature names.

### Returns
array<string, array<int, mixed>> - Map of feature name to list of values.
```

--------------------------------

### FeatureManager::store

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/feature.md

Retrieves a store decorator for the given store name.

```APIDOC
## FeatureManager::store

### Description
Retrieves a store decorator for the given store name.

### Method
`store($store = null)`

### Parameters
- `$store` (string|null) - Optional - Named store from `pennant.stores.*`. Defaults to `null` (uses default driver).

### Returns
`Laravel\Pennant\Drivers\Decorator` - A cached, per-name `Decorator` wrapping the resolved driver.

### Throws
- `InvalidArgumentException` - `Pennant store [{$name}] is not defined.` when no config exists for the store.
- `InvalidArgumentException` - `Driver [{$config['driver']}] is not supported.` when the configured driver has no factory method and no custom creator.
```

--------------------------------

### Purge and deactivate features with error handling

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/feature.md

Demonstrates purging all stored feature values and deactivating a specific feature for all scopes, with a try-catch block to handle RuntimeException from the driver.

```php
use Laravel\Pennant\Feature;

// Purge everything, catching manager-level failures along the way.
try {
    Feature::purge();                                   // delete all stored values
    Feature::deactivateForEveryone(['legacy-flag']);    // force false for all scopes
} catch (RuntimeException $e) {
    report($e); // e.g. driver does not support some operation
}
```

--------------------------------

### Catch Pennant store and scope failures with try/catch

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/errors.md

Shows how to catch the non-throwing failure modes in consumer code. The first try block catches an InvalidArgumentException when selecting an undefined store, the second catches a RuntimeException when passing an unserializable scope, and the third catches a RuntimeException when reading values for multiple scopes. All error sites throw RuntimeException or InvalidArgumentException, so callers can report them centrally via Laravel's exception handler.

```php
use Illuminate\Contracts\Container\Container;
use InvalidArgumentException;
use RuntimeException;
use Laravel\Pennant\Feature;

// 1 & 2: manager/store selection failures.
try {
    $store = Feature::store('typo-store');
} catch (InvalidArgumentException $e) {
    // "Pennant store [typo-store] is not defined."
}

// 3: incompatible scope type.
try {
    Feature::for(new \stdClass)->value('foo'); // stdClass is not serializable
} catch (RuntimeException $e) {
    // "Unable to serialize the feature scope to a string. …"
}

// 6: multi-scope value reads.
try {
    Feature::for('a@b.c')->for('d@e.f')->values(['foo']);
} catch (RuntimeException $e) {
    // "It is not possible to retrieve the values for multiple scopes."
}
```

--------------------------------

### DynamicallyRegisteringFeatureClass event class

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/events.md

Event class with a public $feature property of type class-string. Dispatched from Decorator::ensureDynamicFeatureIsDefined() (src/Drivers/Decorator.php:752) before $this->define($feature) runs, providing a hook for observing first-use registration of feature classes.

```php
// src/Events/DynamicallyRegisteringFeatureClass.php
class DynamicallyRegisteringFeatureClass
{
    /**
     * Create a new event instance.
     *
     * @param  class-string  $feature  The feature class.
     */
    public function __construct(
        public $feature,
    ) {}
}
```

--------------------------------

### FeatureManager cache and scope resolver method signatures

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/feature.md

Shows the signatures for flushCache and resolveScopeUsing methods. flushCache clears in-memory caches on all resolved stores, while resolveScopeUsing sets a custom default scope resolver.

```php
// src/FeatureManager.php:215
public function flushCache()
// src/FeatureManager.php:245
public function resolveScopeUsing($resolver)
```

--------------------------------

### __construct($driver)

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/pending-scoped-feature-interaction.md

Constructs a new PendingScopedFeatureInteraction instance with a Decorator driver.

```APIDOC
## Constructor: __construct($driver)

### Description
Initializes a PendingScopedFeatureInteraction with the given Decorator driver.

### Method
__construct

### Parameters
- **$driver** (Decorator) - Required - The decorated store the interaction operates on.

### Example
```php
$interaction = new PendingScopedFeatureInteraction($driver);
```
```

--------------------------------

### delete method signature

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/decorator.md

Calls driver->delete(), removes the cache entry, and dispatches FeatureDeleted.

```php
/** @internal */
public function delete($feature, $scope): void
```

--------------------------------

### FeatureManager::createArrayDriver

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/feature.md

Creates an array driver instance.

```APIDOC
## FeatureManager::createArrayDriver

### Description
Creates an array driver instance.

### Method
`createArrayDriver()`

### Parameters
None.

### Returns
`ArrayDriver` - Constructed with `container['events']` and `[]` resolvers.
```

--------------------------------

### FeatureManager store method signature

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/feature.md

Shows the store method signature that returns a Decorator for a named store. Throws InvalidArgumentException if the store is not defined or the driver is not supported.

```php
// src/FeatureManager.php:74
public function store($store = null)
```

--------------------------------

### when() method signature

Source: https://github.com/laravel/pennant/blob/1.x/_autodocs/api-reference/pending-scoped-feature-interaction.md

Conditionally executes a closure based on whether a feature is active. If active, calls $whenActive with the feature value and the interaction instance; otherwise calls $whenInactive if provided, returning null when not.

```php
/**
 * @param  \BackedEnum|\UnitEnum|string  $feature
 * @param  \Closure  $whenActive
 * @param  \Closure|null  $whenInactive
 * @return mixed
 */
public function when($feature, $whenActive, $whenInactive = null)
```
Tokens:
Raw