When you're building APIs that need to scale or roll out new features to a limited set of users, feature flags come in handy. In this section, we will see how to implement feature flags within a Laravel 11 API, leveraging a first-party package called Laravel Pennant.

If you've worked with JavaScript before, you’re probably familiar with feature flag services like LaunchDarkly or Split. Laravel, though, has its own clean, efficient way to handle feature flags natively, and we’re going to explore that.

Getting Started with Laravel Pennant

First things first, we need to install the Laravel Pennant package, which is Laravel’s lightweight and highly effective solution for feature flags.

composer require laravel/pennant

Once that's done, you'll want to publish the configuration files and the database migrations that come with the package.

php artisan vendor:publish --tag=laravel-pennant-config
php artisan migrate

This step will set up everything you need in the background, including a database table to store your feature flags.

Pro Tip: If you want to explore other feature flagging options for your Laravel application, check out API Insights, which offers great tips on enhancing API functionality.

Defining Your Feature Flags

Now that we’ve got the package installed, let’s define a feature flag. We'll start by creating a new service provider, so we don't clutter up your AppServiceProvider.

php artisan make:provider FeatureServiceProvider

In the FeatureServiceProvider, we’ll define our features inside the boot() method. Here’s an example that flags a group of beta testers:

public function boot()
{
    Feature::define('beta-tester', function (User $user): bool {
        return $user->hasActivePlan();
    });
}

Here, we’re checking if a user has an active plan (using something like Laravel Cashier for subscription management), and allowing them to access beta features based on that condition. It’s easy to customize this logic further depending on your use case.

For more about managing subscriptions, check out the Laravel Cashier’s documentation.

Using Feature Flags in Controllers

Now, how do we use these flags within our API? It’s pretty straightforward. In your controllers, you can check whether a feature is active or not and adjust the API response accordingly.

public function show(User $user)
{
    if (Feature::active('beta-tester', $user)) {
        return new ApiBetaResponse();
    }

    return new ApiResponse();
}

This is where feature flags become truly powerful — you can gate certain parts of your API or change functionality based on user roles, plans, or other conditions.

Middleware for Feature Flags

Laravel Pennant also allows you to use middleware to control access based on feature flags. For example, you might want to restrict access to a specific route for users with the 'beta-tester' flag:

Route::middleware('feature:beta-tester')->group(function () {
    Route::get('/test', function () {
        return view('test');
    });
});

This way, only users with the appropriate flag can access the route.

Want to dig deeper? Check out the Laravel Pennant documentation.

Error Handling and Custom Responses

Handling error states when a feature flag is inactive is crucial for a smooth user experience. Laravel Pendant allows you to define custom error responses, so when users don’t meet the criteria for accessing a feature, they get appropriate feedback.

In the service provider, you can define a custom response like this:

Feature::define('beta-tester', function (User $user): bool {
    return $user->hasActivePlan();
})->onInactive(function ($request, $response) {
    return response()->json(['message' => 'This feature is not available to you.'], 403);
});

This approach ensures that users without the required feature flag get an informative response, rather than a generic error.

Why Version Control for Feature Flags?

One of the biggest benefits of using Laravel Pendant is version control. If a feature flag breaks something in production, you can easily roll back to a previous state. This is incredibly useful when working in environments with high user interaction and frequent updates.

Want to explore more best practices? Take a look at the Laravel SDK for other powerful tools you can integrate with your API.