ryangjchandler / laravel-feature-flags
An opinionated feature flags package for Laravel.
Requires
- php: ^8.1
- illuminate/contracts: ^9.0
- illuminate/database: ^9.0
- spatie/laravel-package-tools: ^1.9.2
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.8
- nunomaduro/collision: ^6.0
- nunomaduro/larastan: ^2.0.1
- orchestra/testbench: ^7.0
- pestphp/pest: ^1.21
- pestphp/pest-plugin-laravel: ^1.1
- phpstan/extension-installer: ^1.1
- phpstan/phpstan-deprecation-rules: ^1.0
- phpstan/phpstan-phpunit: ^1.0
- phpunit/phpunit: ^9.5
- spatie/laravel-ray: ^1.26
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.