friendsofcat / laravel-feature-flag
Feature Flags for Laravel
Requires
- php: ^7.3|^8.0
Requires (Dev)
- doctrine/dbal: ^2.6|^3.0
- illuminate/support: ^8.50.0
- laravel/legacy-factories: ^1.1
- mockery/mockery: ^1.4.2
- orchestra/testbench: ^6.19.0
- permafrost-dev/coverage-check: ^1.1
- phpunit/phpunit: ^7.0|^9.3.3
- ramsey/uuid: ^3.0|^4.0
- squizlabs/php_codesniffer: ^3.6
- 4.2.2
- 4.2.1
- v4.2.0
- v4.1.2
- v4.1.1
- v4.1.0
- v4.0.0
- v3.x-dev
- 3.2.0
- v3.1.10
- v3.1.9
- v3.1.8
- v3.1.7
- v3.1.6
- v3.1.5
- v3.1.4
- v3.1.3
- v3.1.2
- v3.1.1
- v3.1.0
- dev-master / 3.0.x-dev
- v3.0.0
- v2.1.1
- v2.1.0
- v2.0.2
- v2.0.1
- v2.0.0
- v1.0.1
- v1.0.0
- dev-fix-variants
- dev-invalid-json-handling
- dev-use-team-name
- dev-add-variant-to-form
- dev-team-based-flags
- dev-php_8
- dev-feature/dry-out-queries
- dev-feature_meta_data
- dev-fix_format_issue
This package is auto-updated.
Last update: 2024-10-29 23:40:45 UTC
README
Overview
You can find a comprehensive blog post about this library here. This project is a work in progress.
We are working on using FeatureFlags or Toggles in our applications. For one we are aiming to do all our work on mainline branch at all times so this would be a key coding discipline to use FeatureFlags so we can hide a feature in progress knowing it will not interfere with the application. For example if a hotfix or another feature is ready to go to production we can push that with no worries of the in progress feature.
At the core we use this library Atriedes/feature as it has the logic needed to consider common feature flag states eg user, users, on, off, groups, admin, internal, random etc. However, we are also mixing in some nice Laravel Authorization features so you can do things like:
In a blade template:
@can('feature-flag', 'add-twitter-field') <!-- code here --> @endcan
Or in PHP:
if (Gate::allows('feature-flag', 'awesome-feature')) { <!-- code here --> }
if (Gate::denies('feature-flag', 'awesome-feature')) { <!-- code here --> }
If you need to pass your feature flags to a front-end JS framework like Angular or Vue.js, you can do so by using the FeatureFlagsForJavascript::get() static method.
This uses this library https://github.com/laracasts/PHP-Vars-To-Js-Transformer to put this info into the windows
object, and for Angular the $window
now you can access it:
JavaScript::Put(
[
'pusher_public_key' => env('PUSHER_PUBLIC'),
'feature_flags' => FeatureFlagsForJavascript::get()
]
);
Installing
Require the package using composer:
composer require "friendsofcat/laravel-feature-flag"
Add the following to your config/app.php providers array:
FriendsOfCat\LaravelFeatureFlags\FeatureFlagsProvider::class,
Publish the package migrations:
php artisan vendor:publish --provider="FriendsOfCat\LaravelFeatureFlags\FeatureFlagsProvider" --tag='migrations'
Then run migration to setup the base table:
php artisan migrate
This package creates a number of routes. They can be overridden by publishing the views:
php artisan vendor:publish --provider="FriendsOfCat\LaravelFeatureFlags\FeatureFlagsProvider" --tag='views'
This will then place the files in resources/vendors/laravel-feature-flags
. Just note that the views @extends('layouts.default')
so if yours differs you will need to make an adjustment to the published views files.
Next, publish the configuration:
php artisan vendor:publish --provider="FriendsOfCat\LaravelFeatureFlags\FeatureFlagsProvider" --tag='config'
Important: The routes detault to being projected by the 'auth' middleware but you should check your installation to make sure permissions are acceptable. Middleware settings are configurable in 'config/laravel-feature-flag.php' file.
Make sure to set the default_view
as well for the layout.
config/laravel-feature-flag.php
Your .env
LARAVEL_FEATURE_FLAG_VIEW="layouts.default"
Usage
Visit /admin/feature_flags
to manage features via the UI.
Checking if a feature flag exists
For this you can use the exists() method
if(\FriendsOfCat\LaravelFeatureFlags\Feature::exists('see-twitter-field'))
{
//do something
}
Enable for User Roles
You can enable a feature flag for specific user roles, by using the roles variant in the configuration form
i.e.
{ "roles": ["admin", "dev"]}
If you don't have a roles property in your User model, you just need to implement the FeatureFlagsEnabler Interface and use FeatureFlagUserRoleTrait
use FriendsOfCat\LaravelFeatureFlags\FeatureFlagsEnabler;
use FriendsOfCat\LaravelFeatureFlags\FeatureFlagUserRoleTrait;
class User extends Authenticatable implements FeatureFlagsUserRoles
{
use AuthenticableTrait, FeatureFlagUserRoleTrait;
}
Enable for User Teams
You can enable a feature flag for specific user teams, by using the teams variant in the configuration form
i.e.
{ "teams": ["Team 1", "Team 2"]}
If you don't have a teams property in your User model, you just need to implement the FeatureFlagsEnabler Interface and use FeatureFlagUserRoleTrait
use FriendsOfCat\LaravelFeatureFlags\FeatureFlagsEnabler;
use FriendsOfCat\LaravelFeatureFlags\FeatureFlagUserRoleTrait;
class User extends Authenticatable implements FeatureFlagsUserRoles
{
use AuthenticableTrait, FeatureFlagUserRoleTrait;
}
Usage Non Auth
Sometimes you are not using this at the Auth user level, it is rare for most of our use cases but for non authenticated situations you can just use this
if(\FriendsOfCat\LaravelFeatureFlags\Feature::isEnabled('see-twitter-field'))
{
//do something
}
Remember you needed to put this into the database, so it is on or off. You might not have a UI, maybe this is a microservice for example, so just migrate the state into the database for example
$feature = new FeatureFlag();
$feature->key = "see-twitter-field";
$feature->variants = "on"; //or "off"
$feature->save();
Now when the FeatureFlag Provider instantiates it will set this as the "World" state and you can access it via the isEnabled "on" being true and "off" being false.
Syncing Flags
Feature flags can be synchronised using the provided feature-flag:sync
command. This will sync flags defined in the sync_flags
configuration in the laravel-feature-flag.php
config file. The format for this flag configuration is "key => default value". By default, any flags that are removed will be removed from storage. There is a --skip-cleanup
flag available to skip this step.
Demo / Example
If you want to try the demo/example also include the following in your config/app.php providers array:
FriendsOfCat\LaravelFeatureFlags\ExampleFeatureProvider::class
and then run:
php artisan vendor:publish --provider="FriendsOfCat\LaravelFeatureFlags\ExampleFeatureProvider" --tag='migrations'
php artisan migrate
It has a rollback to help clean up after.
There is a dummy route called /admin/feature_flags/example
that you can visit and it will show that it is not on. But if you then go to the admin UI /admin/feature_flags
you can toggle it on and off.
Testing
There is the settings page which I do have some Laravel tests for that you can run once the package is installed.
Also if you are trying to test the use of it in your work you can use the helper trait in your test class
use DatabaseTransactions, \FriendsOfCat\LaravelFeatureFlags\FeatureFlagHelper;
Then from there factory out your additions and state then reregister the world
/** * @test */ public function should_fail_validation_since_twitter_missing() { //Make a form request //Set validation on that related to twitter field //make sure the feature flag is on $user_id = Rhumsaa\Uuid\Uuid::uuid4()->toString(); $user = factory(\App\User::class)->create([ 'id' => $user_id, 'is_admin' => 1 ]); $this->actingAs($user); factory(\FriendsOfCat\LaravelFeatureFlags\FeatureFlag::class)->create( [ 'key' => 'add-twitter-field', 'variants' => 'on' ] ); $this->registerFeatureFlags(); //// }
TODO
- Use Model Events to do that level of work
- Cache of the FeatureFlag Settings and update Cache on Change
- Show how it works in the menu and other areas eg include and Provider