Mastering Feature Flags with Laravel Pennant

Prerequisites

To follow this guide, you should be comfortable with PHP and the Laravel framework. Specifically, you need to understand Service Providers, Controllers, and how to interact with Eloquent models. Ensure you have Laravel Pennant installed via Composer and the migrations executed to create the necessary storage tables.

Defining and Checking Features

Features are typically defined within the boot method of a Service Provider using the Feature::define method.

use Laravel\Pennant\Feature;
use App\Models\User;

Feature::define('checkout-new', function (User $user) {
    return $user->is_admin;
});

Once defined, you check the status in your controllers or views. This logic keeps your conditional code clean and centralized.

if (Feature::active('checkout-new')) {
    return view('checkout.new');
}

return view('checkout.old');

Storing Dynamic Values

Pennant isn't limited to booleans. You can store strings, arrays, or integers as feature values. This is perfect for multivariate testing, such as changing a button color for specific user segments.

Feature::define('button-color', function (User $user) {
    return $user->id % 2 === 0 ? 'blue' : 'green';
});

// Retrieve it using the value method
$color = Feature::value('button-color');

Syntax and Persistence

Laravel Pennant uses a persistent database driver by default. When a feature closure runs, the result is saved for that specific user (the scope). This ensures a consistent experience; a user won't see a feature flip-flop between sessions. If you need to reset these values during development, use the pennant:purge Artisan command.

Tips and Best Practices

Use the Lottery helper for canary releases. For example, Lottery::odds(1, 100) allows you to safely roll out a feature to 1% of your traffic. Always clean up your flags once a feature is 100% rolled out to keep your codebase maintainable and prevent "flag debt."