README

This package provides an opinionated API for implementing feature flags in your Laravel applications. It supports application-wide features as well as model specific feature flags.

Installation

You can install the package via Composer:

composer require ryangjchandler/laravel-feature-flags

You should then publish and run the migrations with:

php artisan vendor:publish --tag="feature-flags-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="feature-flags-config"

Usage

Global flags

To enable or disable a global feature flag, you can use the Features::enable() and Features::disable() methods respectively.

use RyanChandler\LaravelFeatureFlags\Facades\Features;

Features::enable(name: 'registration');
Features::disable(name: 'registration');

To check if a flag is enabled or disabled, use the Features::enabled() and Features::disabled() methods respectively.

use RyanChandler\LaravelFeatureFlags\Facades\Features;

if (Features::enabled(name: 'registration')) {
    // `registration` is enabled.
}

if (Features::disabled(name: 'registration')) {
    // `registration` is disabled.
}

If you wish to just create a new flag without updating existing ones, i.e. inside of a seeder, you can use Features::add().

use RyanChandler\LaravelFeatureFlags\Facades\Features;

Features::add('registration');

This will create a new flag that is disabled by default. To enable the flag by default, provide a boolean value to the enabled argument.

use RyanChandler\LaravelFeatureFlags\Facades\Features;

Features::add('registration', enabled: true);

If you simply want to toggle a flag, you can use the Features::toggle() method.

use RyanChandler\LaravelFeatureFlags\Facades\Features;

Features::toggle(name: 'registration');

If the flag is enabled, it will be disabled. If it's disabled, it will be enabled.

To get an array of all flags, use the Features::all() method. This will return an array where the flag names are used for the keys and a boolean representing the current state of the flag is the value.

use RyanChandler\LaravelFeatureFlags\Facades\Features;

$flags = Features::all();

foreach ($flags as $name => $enabled) {
    // ...
}

Model flags

If you would like to feature flag specific models, begin by implementing the RyanChandler\LaravelFeatureFlags\Models\Contracts\HasFeatures interface and using the RyanChandler\LaravelFeatureFlags\Models\Concerns\WithFeatures trait. Here's an example on a User model.

use RyanChandler\LaravelFeatureFlags\Models\Contracts\HasFeatures;
use RyanChandler\LaravelFeatureFlags\Models\Concerns\WithFeatures;

class User extends Authenticatable implements HasFeatures
{
    use WithFeatures;
}

The trait provides a default implementation that adheres to the interface. It's recommended that you always use this implementation instead of writing your own.

To enable, disable or toggle a flag, use the same Features::enable(), Features::disable() and Features::toggle() methods by providing a named argument for.

use RyanChandler\LaravelFeatureFlags\Facades\Features;

$user = User::first();

Features::enable('registration', for: $user);
Features::disable('registration', for: $user);
Features::toggle('registration', for: $user);

The WithFeatures trait also provides a few helper methods on the model: enableFeature(), disableFeature() and toggleFeature().

Blade directive

This package also provides a set of conditional Blade directives for protecting your views with feature flags.

@feature('registration')
    <a href="/register">Register now!</a>
@endfeature

You can use @elsefeature and @unlessfeature directives too.

If you would like to check a feature flag for a model, you can provide a named argument to the directive.

return view('my-view', [
    'user' => User::first(),
]);

@feature('registration', for: $user)
    <a href="/register">Register now!</a>
@endfeature

Middleware

This package provides a piece of middleware to protect your routes with feature flags.

You need to add the following code to your app/Http/Kernel.php file.

protected $routeMiddleware = [
    'feature' => \RyanChandler\LaravelFeatureFlags\Middleware\HasFeature::class,
];

You can then register middleware on your route like so:

Route::get('/register', fn () => ...)->middleware('feature:registration');

The default behaviour of the middleware is to abort with a 403 Forbidden status code.

This can be configured in the configuration file by changing the value of middleware.behaviour. The package uses the MiddlewareBehaviour enumeration as the configuration value.

You can change the status code using the middleware.code configuration option.

Redirecting instead of aborting

If you would prefer to redirect instead of aborting, set middleware.behaviour to MiddlewareBehaviour::Redirect and middleware.redirect to your preferred redirect location.

Multiple features

If you wish, you may protect your routes behind multiple feature flags. You can do this by comma-separating the flags passed when defining the middleware on your route definition:

Route::get('/feature', fn () => ...)->middleware('feature:verified,two-factor');

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

ryangjchandler / laravel-feature-flags

Maintainers

Details