al_imran/runtime-feature-toggle

A runtime feature engine for Laravel applications.

v1.0.0 2026-06-07 06:22 UTC

Requires

• php: ^8.2
• illuminate/cache: ^10.0|^11.0|^12.0|^13.0
• illuminate/database: ^10.0|^11.0|^12.0|^13.0
• illuminate/support: ^10.0|^11.0|^12.0|^13.0

MIT

• Al IMRAN

Published on Packagist.org on 2026-06-07 07:24 UTC

README

Runtime Feature Toggle is a high-performance, decoupled feature flag engine for Laravel. It allows you to dynamically control application behavior and configuration at runtime without code deployments or configuration changes.

Instant Control, Zero Deployment

Imagine you need to pause all outgoing emails or SMS notifications during a maintenance window. Normally, you'd have to update an .env key or change your code and redeploy to production.

With Runtime Feature Toggle, you can toggle these features instantly via the database. The best part? Our intelligent caching system ensures that these checks are lightning-fast, giving you the power of dynamic control with the performance of local configuration.

Why Use This Package?

In modern software development, decoupling feature releases from code deployments is critical. This package solves several common problems:

• Safe Releases: Gradually roll out features to specific users or segments.
• Kill Switches: Instantly disable problematic features in production without a rollback.
• Dynamic Configuration: Update logic parameters (like discount rates or API limits) via a dashboard instead of .env files.
• Zero-Dependency Core: Unlike many other packages, it doesn't force a specific User model or Auth structure on you.

Key Features

• 🚀 High Performance: Atomic caching ensures evaluation is lightning fast.
• 💎 Sleek Management UI: Built-in dashboard to manage flags and JSON payloads.
• 🎭 Contextual Awareness: Evaluate flags based on Users, IPs, Request data, or any custom entity.
• 📦 Dynamic Payloads: Return complex JSON configurations, not just simple booleans.
• 🛠 Extensible: Easily add custom condition logic (e.g., "User belongs to Beta Team").
• 🧪 Test-Ready: Robust mocking support for your PHPUnit suites.

Installation

You can install the package via composer:

composer require al_imran/runtime-feature-toggle

Setup

Run the installation command to publish the configuration, migrations, and assets:

php artisan feature:install

This command will:

1. Publish the config/feature.php file.
2. Publish and run the database migrations.
3. Prepare the package for use.

Feature Management

This package comes with a built-in dashboard to add, edit, and maintain your feature flags without touching the database manually.

Accessing the Dashboard

By default, the dashboard is available at: YOUR_APP_URL/features-manager

From here, you can:

• Add New Features: Define keys and initial JSON payloads.
• Toggle States: Instantly enable or disable features globally.
• Manage Rules: Add complex conditions (like User ID or Time Ranges) to control feature availability.
• Edit Payloads: Update dynamic configuration values on the fly.

Customizing & Securing the Dashboard

By default, the management dashboard is accessible at /features-manager. While this is convenient for development, you should secure it in production environments.

Option 1: Using Configuration (Easiest)

The simplest way to protect the dashboard is by updating the config/feature.php file. You can add any middleware (like auth or custom admin middleware) to the routes array:

// config/feature.php
'routes' => [
    'prefix' => 'admin/features', // Change the URL prefix if desired
    'middleware' => ['web', 'auth', 'can:manage-features'], // Add your protection here
],

Option 2: Taking Full Ownership of Routes

If you need even more control (e.g., adding extra routes or changing the route structure), you can publish the routes file to your application:

php artisan vendor:publish --tag=feature-routes

This will create routes/runtimeFeature.php in your project. The package will automatically detect and use this file instead of its internal routes. You can then modify the group directly:

// routes/runtimeFeature.php
Route::middleware(['web', 'auth', 'your-custom-admin-middleware'])
    ->prefix('features-manager')
    ->name('features.')
    ->group(function () {
        // Your customized routes...
    });

Important

Security Reminder: The developer is responsible for ensuring that the dashboard routes are properly protected. By default, only the web middleware is applied, which provides no authentication or authorization.

Basic Usage

1. Simple On/Off Checks (enabled)

Use this to check if a feature is active.

use Imran\RuntimeFeatureToggle\Facades\Feature;

// Via Facade
if (Feature::enabled('new_checkout_flow')) {
    // Show the new checkout
}

// Via Helper
if (feature('new_checkout_flow')->enabled()) {
    // Show the new checkout
}

2. Retrieving Dynamic Values (value)

Fetch dynamic configurations stored with your feature flag.

// Returns the JSON payload from the DB. 
// If the feature is missing, it returns null.
// If the feature exists but its value is empty, it returns the default (50).
$limit = Feature::value('upload_limit', 50);

// Helper syntax
$config = feature('theme_colors')->value(['primary' => '#000']);

Method	Returns	Description
enabled()	bool	Is the feature active?
value()	mixed	Returns the dynamic JSON payload or a default.

Advanced Usage

Contextual Evaluation

Pass a context (e.g., a User model) to evaluate rules specifically for that entity.

$user = auth()->user();

if (Feature::enabled('beta_access', $user)) {
    // This user specifically has access based on rules defined in the dashboard
}

Custom Conditions

Register your own logic for rule evaluation.

// In a ServiceProvider
Feature::extend('user_level', function ($context, $value) {
    return $context->level >= $value;
});

Mocking for Tests

Avoid database hits in your tests by faking feature states.

public function test_new_feature_is_displayed()
{
    Feature::fake([
        'new_feature' => true,
        'api_limit' => 1000
    ]);

    $this->get('/dashboard')->assertSee('New Feature');
}

Real-World Use Cases

1. Feature Rollout: Enable new_sidebar for 10% of users to monitor performance before a full launch.
2. A/B Testing: Store different configuration values (e.g., button colors) in the value field to test user engagement.
3. Emergency Toggles: If a 3rd-party service goes down, instantly disable the integration via the dashboard to keep the rest of the app running.

Comparison: Laravel Pennant

While Laravel Pennant is an excellent tool for user-centric feature flags, Runtime Feature Toggle differs in its focus:

• Management UI: We provide a ready-to-use dashboard for non-technical stakeholders to manage flags.
• Dynamic Payloads: We treat JSON configurations as first-class citizens, making it easier to use flags for remote config.
• Decoupled Context: Our engine doesn't assume an Eloquent User model, making it easier to use in non-standard or multi-tenant applications.

Testing

composer test

Security

If you discover any security-related issues, please email [e-mail] instead of using the issue tracker.

Contributing

Please see CONTRIBUTING for details.

License

The MIT License (MIT). Please see License File for more information.

Packagist Description: A high-performance, decoupled feature flag engine with a management UI and dynamic JSON configuration support for Laravel.

Keywords: laravel, feature-flags, remote-config, feature-toggle, runtime-configuration