Implementing Simple Feature Flags in Laravel with Laravel Toggle

Feature flags, also known as feature toggles, are a powerful technique in modern software development. They allow you to turn features of your application on or off without deploying new code. This provides immense flexibility for A/B testing, gradual rollouts, hiding incomplete features, and quickly disabling problematic features in production. For Laravel developers, the Laravel Toggle package offers a lightweight and elegant solution to manage these flags.

Laravel Toggle empowers you to control your feature flags globally, either through environment variables, the database, or a combination of both. In this tutorial, we'll walk through installing, configuring, and using Laravel Toggle to manage your application's features.

1. Installation #

Getting started with Laravel Toggle is straightforward. First, you need to add the package to your Laravel project using Composer:

composer require protonemedia/laravel-toggle

After installation, you'll need to publish the package's configuration file. This allows you to customize how Laravel Toggle behaves.

php artisan vendor:publish --provider="Protonemedia\LaravelToggle\ToggleServiceProvider" --tag="toggle-config"

If you plan to manage your feature flags via the database (which is often recommended for dynamic control), you'll also need to run the migrations to create the toggle table:

php artisan migrate

2. Configuration (config/toggle.php) #

The published toggle.php configuration file gives you control over how the package operates:

// config/toggle.php
return [
    'environment_variables' => env('TOGGLE_ENVIRONMENT_VARIABLES', true),
    'database_table' => 'toggle',
    'cache_key' => 'laravel-toggle.features',
    'cache_ttl' => env('TOGGLE_CACHE_TTL', 3600),
];

• environment_variables: Set this to true if you want Laravel Toggle to check for flags defined in your .env file. The package will look for variables prefixed with TOGGLE_ (e.g., TOGGLE_NEW_FEATURE).
• database_table: The name of the database table where feature flags will be stored (default is toggle).
• cache_key and cache_ttl: These settings control the caching behavior for database-managed flags. Caching helps improve performance by reducing database queries.

3. Managing Feature Flags #

Laravel Toggle provides flexibility in how you define and manage your flags.

Via Environment Variables #

This is the simplest way to get started. Just add a TOGGLE_ prefixed variable to your .env file:

TOGGLE_NEW_DASHBOARD=true TOGGLE_EXPERIMENTAL_LOGIN=false

• Set to true to enable the feature.
• Set to false to disable the feature.

Flags defined this way are quick to implement but require a change in your .env file (and potentially a deployment) to update in production.

Via Database #

For more dynamic control, especially in production environments where you don't want to redeploy to change a flag, using the database is ideal. Laravel Toggle provides convenient Artisan commands for this.

• List all flags: php artisan toggle:list

• Enable a feature: php artisan toggle:set new-dashboard --on

• Disable a feature: php artisan toggle:set new-dashboard --off

• Remove a feature flag from the database: php artisan toggle:forget new-dashboard

When using the database, Laravel Toggle automatically creates a toggle table with name (string) and active (boolean) columns.

4. Using Feature Flags in Your Application #

Once your flags are defined, you can easily check their status within your Laravel application using the Toggle facade or Blade directives.

Using the Toggle Facade #

You can use the Toggle facade in your controllers, services, or any other PHP code to check the status of a feature flag.

use Protonemedia\LaravelToggle\Facades\Toggle;

class DashboardController extends Controller
{
    public function index()
    {
        if (Toggle::active('new-dashboard')) {
            // Show the new dashboard version
            return view('dashboard.new');
        } else {
            // Show the old dashboard version
            return view('dashboard.old');
        }
    }

    public function analytics()
    {
        if (Toggle::inactive('experimental-login')) {
            // Only show analytics if experimental login is OFF
            return view('dashboard.analytics');
        }
        abort(403, 'Experimental login active, analytics temporarily disabled.');
    }
}

• Toggle::active('feature-name'): Returns true if the feature is active, false otherwise.
• Toggle::inactive('feature-name'): Returns true if the feature is inactive, false otherwise.

Using Blade Directives #

For conditional rendering in your Blade views, Laravel Toggle provides a convenient @toggle directive.

<!-- resources/views/layouts/app.blade.php -->

@toggle('new-search-bar')
    <div class="new-search-bar">
        <!-- New search bar implementation -->
        <input type="text" placeholder="Search the new way...">
    </div>
@else
    <div class="old-search-bar">
        <!-- Old search bar implementation -->
        <input type="text" placeholder="Search the old way...">
    </div>
@endtoggle

@toggle('beta-banner')
    <div class="alert alert-warning">
        This is a beta feature! Proceed with caution.
    </div>
@endtoggle

Conditional Routing or Middleware #

You can also use Toggle::active() within your route definitions or custom middleware to restrict access to certain routes or entire sections of your application based on a feature flag.

// routes/web.php

// Restrict an entire route group based on a feature flag
Route::middleware(function ($request, $next) {
    if (!Toggle::active('admin-v2')) {
        abort(404);
    }
    return $next($request);
})->prefix('admin-v2')->group(function () {
    Route::get('/', [NewAdminController::class, 'index']);
    // ... other admin v2 routes
});

// Or conditionally register routes
if (Toggle::active('api-v2')) {
    Route::prefix('api/v2')->group(function () {
        // ... API v2 routes
    });
}

Conclusion #

Laravel Toggle provides a simple, yet effective, way to implement feature flags in your Laravel applications. By abstracting the logic of turning features on and off, it empowers developers to deploy code more confidently, experiment with new features, and respond quickly to issues. Whether you prefer the simplicity of environment variables or the dynamic control of a database, Laravel Toggle has you covered, helping you build more robust and agile Laravel applications.