README

Laravel Feature Flags allows instant, zero-deployment toggling of application features.

The state of each feature flag can be checked from anywhere in the application code (including via a @feature('name') blade directive) to determine whether the conditions you set have been met to enable the feature.

Each feature can be in one of three states:

On: enabled for everyone
Off: disabled for everyone
Dynamic: evaluated according to a feature-specific closure (with a fallback option)

Installation

Install With Composer

composer require codinglabsau/laravel-feature-flags

Database Migrations

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

Publish Configuration

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

Set Your Cache Store

This package caches the state of features to reduce redundant database queries. The cache is expired whenever the feature state changes.

By default, this package will use the default cache configured in your application.

If you wish to change to a different cache driver, update your .env:

FEATURES_CACHE_STORE=file

Upgrading

See the upgrade guide for instructions on upgrading between major versions.

Usage

Create a new feature in the database and set the initial state:

use Codinglabs\FeatureFlags\Models\Feature;
use Codinglabs\FeatureFlags\Enums\FeatureState;

Feature::create([
    'name' => 'search-v2',
    'state' => FeatureState::on()
]);

Its recommended that you seed the features to your database before a new deployment or as soon as possible after a deployment.

Check If A Feature Is Enabled

Blade View

Use the @feature blade directive anywhere in your view files.

@feature('search-v2')
    // new search goes here
@else
    // legacy search here
@endfeature

In Your Code

Use the FeatureFlag facade to conveniently check the state of a feature in your app code.

use Codinglabs\FeatureFlags\Facades\FeatureFlag;

if (FeatureFlag::isOn('search-v2')) {
    // new feature code
} else {
    // old code
}

Middleware

Register feature as a route middleware in your HTTP Kernel to protect routes. A 404 response will be returned if the feature does not resolve to the on state.

// app/Http/Kernel.php
protected $routeMiddleware = [
    // ... 
    'feature' => \Codinglabs\FeatureFlags\Middleware\VerifyFeatureIsOn::class,
];

// routes/web.php
Route::get('search-v2', \App\Http\Controllers\SearchV2Controller::class)->middleware('feature:search-v2');

Check If A Feature Is Disabled

Blade View

@unlessfeature('search-v2')
    // no new features for you
@endfeature

In Your Code

use Codinglabs\FeatureFlags\Facades\FeatureFlag;

if (FeatureFlag::isOff('search-v2')) {
    // no new features for you
}

Get The Underlying Current State

If you want to know what the underlying FeatureState value is:

use Codinglabs\FeatureFlags\Facades\FeatureFlag;

// value from Codinglabs\FeatureFlags\Enums\FeatureState
$featureState = FeatureFlag::getState('search-v2');

Updating Feature State

To change the state of a feature you can call the following methods:

use Codinglabs\FeatureFlags\Facades\FeatureFlag;

FeatureFlag::turnOn('search-v2');
FeatureFlag::turnOff('search-v2');
FeatureFlag::makeDynamic('search-v2');

Alternatively you can set the state directly by passing a feature state enum:

FeatureFlag::updateFeatureState('search-v2', FeatureState::on())

It is recommended that you only update a features state using the above methods as it will take care of flushing the cache and dispatching the feature updated event:

\Codinglabs\FeatureFlags\Events\FeatureUpdatedEvent::class

You should listen for the FeatureUpdatedEvent event if you have any downstream implications when a feature state is updated, such as invalidating any cached items that are referenced in dynamic handlers.

Artisan Commands

Manage feature flags directly from the command line — useful when SSHed into a server.

Interactive Management

php artisan feature:manage

Displays a table of all features and their states, then lets you select a feature, choose a new state, and confirm before saving. Loops so you can make multiple changes in one session.

Scriptable Commands

# Turn a feature on
php artisan feature:on search-v2

# Turn a feature off
php artisan feature:off search-v2

# Set a specific state (on, off, dynamic)
php artisan feature:state search-v2 dynamic

These commands handle cache invalidation automatically and return appropriate exit codes for use in scripts.

Advanced Usage

Dynamic Features

A dynamic handler can be defined in the boot() method of your AppServiceProvider:

use Codinglabs\FeatureFlags\Facades\FeatureFlag;

FeatureFlag::registerDynamicHandler('search-v2', function ($feature, $request) {
    return $request->user() && $request->user()->hasRole('Tester');
});

Dynamic handlers will only be called when a feature is in the dynamic state. This will allow you to define custom rules around whether that feature is enabled like in the example above where the user can only access the feature if they have a tester role.

Each handler is provided with the features name and current request as arguments and must return a boolean value.

Default Handler For Dynamic Features

You may also define a default handler which will be the catch-all handler for features that don't have an explicit handler defined for them:

FeatureFlag::registerDefaultDynamicHandler(function ($feature, $request) {
    return $request->user() && $request->user()->hasRole('Tester');
});

An explicit handler defined using registerDynamicHandler() will take precedence over the default handler. If neither a default nor explicit handler has been defined then the feature will resolve to off by default.

Feature Scopes

Features can be assigned a scope to categorise them. A feature's scope has no effect on its state — isOn(), isOff(), middleware, and Blade directives all behave the same regardless of scope. Scope becomes useful when you build a UI around your feature flags (an admin panel, a tenant dashboard, a feature group system) and need to control which flags appear where.

Use the rich config format to assign a scope and description:

// config/feature-flags.php
'features' => [
    // No scope — standard flags
    'search-v2' => FeatureState::on(),
    'dark-mode' => FeatureState::off(),

    // Scoped — categorised for filtering in your UI
    'new-checkout-flow' => [
        'state' => FeatureState::off(),
        'scope' => 'dev',
        'description' => 'Redesigned single-page checkout flow',
    ],
],

Scope values are free-form strings — use whatever makes sense for your workflow (dev, beta, ticket-124, etc.). Both scope and description sync from config on every deploy, so changing a feature's scope is just a config change.

If you've built a UI around your feature toggles, use scope to filter which flags are shown:

// Only unscoped features — e.g. a production admin panel
Feature::whereNull('scope')->get();

// Unscoped + beta — e.g. a beta testers dashboard
Feature::where(function ($query) {
    $query->whereNull('scope')->orWhere('scope', 'beta');
})->get();

In a multi-tenant setup, scope lets you control which flags appear on each tenant's dashboard — for example, keeping dev-scoped flags out of tenant-facing UIs entirely while still having them active in code.

Handle Missing Features

Features must exist in the database otherwise a MissingFeatureException will be thrown. This behaviour can be turned off by explicitly handling cases where a feature doesn't exist:

FeatureFlag::handleMissingFeaturesWith(function ($feature) {
    // log or report this somewhere...
})

If a handler for missing features has been defined then an exception will not be thrown and the feature will resolve to off.

Using Your Own Model

To use your own model, update the config and replace the existing reference with your own model:

// app/config/feature-flags.php

'feature_model' => \App\Models\Feature::class,

Make sure to also cast the state column to a feature state enum using the FeatureStateCast:

// app/Models/Feature.php

use Codinglabs\FeatureFlags\Casts\FeatureStateCast;

protected $casts = [
    'state' => FeatureStateCast::class
];

Sharing features with UI (Inertiajs example)

// app/Middleware/HandleInertiaRequest.php

use Codinglabs\FeatureFlags\FeatureFlags;
use Codinglabs\FeatureFlags\Models\Feature;

Inertia::share([
    'features' => function () {
        return Feature::all()
            ->filter(fn ($feature) => FeatureFlags::isOn($feature['name']))
            ->pluck('name');
    }
]);

// app.js

Vue.mixin({
  methods: {
    hasFeature: function(feature) {
      return this.$page.features.includes(feature)
    }
  }
})

<!-- SomeComponent.vue -->

<div v-if="hasFeature('search-v2')">Some cool new feature</div>

Testing

composer test

codinglabsau / laravel-feature-flags

Maintainers

Package info

Statistics

Security

README

Installation

Install With Composer

Database Migrations

Publish Configuration

Set Your Cache Store

Upgrading

Usage

Check If A Feature Is Enabled

Blade View

In Your Code

Middleware

Check If A Feature Is Disabled

Blade View

In Your Code

Get The Underlying Current State

Updating Feature State

Artisan Commands

Interactive Management

Scriptable Commands

Advanced Usage

Dynamic Features

Default Handler For Dynamic Features

Feature Scopes

Handle Missing Features

Using Your Own Model

Sharing features with UI (Inertiajs example)

Testing

Security Vulnerabilities

Credits

License