README

A simple, flexible feature toggle system for Laravel — control the visibility of features across environments, users, and conditions.

📋 Table of Contents

Introduction
Features
Requirements
Quick Start
Installation
Usage
API Reference
Feature Conditions
Artisan Commands
Configuration
Database Schema
Security
Testing
Roadmap
Support
Examples

🚀 Introduction

Laravel FeatureBox is a lightweight Laravel package that helps you manage feature flags in your application.

Whether you're rolling out features gradually, testing beta features for specific users, or disabling features in production — FeatureBox gives you full control.

Inspired by tools like LaunchDarkly, but made for Laravel.

✨ Features

🚀 Simple & Lightweight - Easy to install and use
🔧 Flexible Conditions - Support for environments, user roles, dates, and custom conditions
⚡ High Performance - Built-in caching support
🛠️ Artisan Commands - Manage features from the command line
🔒 Secure - No external API calls, all logic is local
📊 Database Storage - Features stored in your database
🧪 Testable - Comprehensive test suite included
🌍 Multi-language - Documentation in English and Arabic

📋 Requirements

PHP >= 8.1
Laravel >= 10.0
MySQL/PostgreSQL/SQLite

🚀 Quick Start

# Install the package
composer require mohamedhekal/laravel-featurebox

# Publish configuration and migrations
php artisan vendor:publish --tag=featurebox-config
php artisan vendor:publish --tag=featurebox-migrations

# Run migrations
php artisan migrate

# Enable a feature
php artisan featurebox:enable new_checkout

# Use in your code
if (FeatureBox::isEnabled('new_checkout')) {
    // New checkout flow
}

📦 Installation

Install via Composer:

composer require mohamedhekal/laravel-featurebox

Then publish the config and migration files:

php artisan vendor:publish --tag=featurebox-config
php artisan vendor:publish --tag=featurebox-migrations
php artisan migrate

⚙️ Usage

Enable or disable features from the database or using Artisan commands.

Basic Usage

use FeatureBox\Facades\FeatureBox;

if (FeatureBox::isEnabled('new_checkout')) {
    // Show new checkout flow
} else {
    // Show classic checkout
}

With Context

You can pass context to evaluate conditions:

FeatureBox::isEnabled('new_checkout', [
    'user_id' => auth()->id(),
    'role'    => auth()->user()->role,
]);

In Blade Templates

@if(FeatureBox::isEnabled('dark_mode'))
    <link rel="stylesheet" href="/css/dark-mode.css">
@endif

In Controllers

public function checkout()
{
    if (FeatureBox::isEnabled('new_checkout')) {
        return view('checkout.new');
    }
    
    return view('checkout.classic');
}

📚 API Reference

Core Methods

`FeatureBox::isEnabled(string $feature, array $context = []): bool`

Check if a feature is enabled for the given context.

// Basic check
$enabled = FeatureBox::isEnabled('new_feature');

// With context
$enabled = FeatureBox::isEnabled('premium_feature', [
    'user_id' => 123,
    'plan' => 'premium'
]);

`FeatureBox::isDisabled(string $feature, array $context = []): bool`

Check if a feature is disabled (opposite of isEnabled).

if (FeatureBox::isDisabled('old_feature')) {
    // Show alternative
}

`FeatureBox::enable(string $feature, array $conditions = []): bool`

Enable a feature with optional conditions.

// Enable without conditions
FeatureBox::enable('simple_feature');

// Enable with conditions
FeatureBox::enable('conditional_feature', [
    'environments' => ['production'],
    'user_roles' => ['admin']
]);

`FeatureBox::disable(string $feature): bool`

Disable a feature.

FeatureBox::disable('deprecated_feature');

`FeatureBox::get(string $feature): ?array`

Get detailed information about a feature.

$feature = FeatureBox::get('my_feature');
// Returns: [
//     'name' => 'my_feature',
//     'is_enabled' => true,
//     'conditions' => [...],
//     'created_at' => '2024-01-01 00:00:00',
//     'updated_at' => '2024-01-01 00:00:00'
// ]

`FeatureBox::all(): array`

Get all features with their status.

$features = FeatureBox::all();
// Returns array of all features

🧠 Feature Conditions

Each feature can include optional conditions like:

✅ Environments (local, staging, production)
👤 User roles or specific user IDs
📅 Start/end dates
🔧 Custom JSON conditions

Example Conditions

{
  "environments": ["staging", "production"],
  "user_roles": ["admin", "beta"],
  "user_ids": [1, 2, 3],
  "start_date": "2025-01-01",
  "end_date": "2025-12-31",
  "custom": {
    "plan": "premium",
    "region": "US"
  }
}

Conditions will be evaluated dynamically before enabling any feature.

🧪 Artisan Commands

Enable a Feature

# Enable without conditions
php artisan featurebox:enable new_checkout

# Enable with conditions
php artisan featurebox:enable new_checkout --conditions='{"environments":["production"],"user_roles":["admin"]}'

Disable a Feature

php artisan featurebox:disable new_checkout

List All Features

php artisan featurebox:list

🔧 Configuration

The package configuration is located at config/featurebox.php:

return [
    'cache' => [
        'enabled' => env('FEATUREBOX_CACHE_ENABLED', true),
        'ttl' => env('FEATUREBOX_CACHE_TTL', 300), // 5 minutes
    ],
    
    'default_conditions' => [
        // Default conditions for all features
    ],
    
    'table' => env('FEATUREBOX_TABLE', 'features'),
];

Environment Variables

FEATUREBOX_CACHE_ENABLED=true
FEATUREBOX_CACHE_TTL=300
FEATUREBOX_TABLE=features

📊 Database Schema

The package creates a features table with the following structure:

CREATE TABLE features (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(255) UNIQUE NOT NULL,
    is_enabled BOOLEAN DEFAULT FALSE,
    conditions JSON NULL,
    created_at TIMESTAMP NULL,
    updated_at TIMESTAMP NULL
);

🔐 Security

All logic is scoped locally; no external API calls or tracking. You can optionally cache the features for performance using Laravel's cache system.

🧪 Testing

composer test

Example Test

use FeatureBox\Facades\FeatureBox;

public function test_feature_can_be_enabled()
{
    FeatureBox::enable('test_feature');
    
    $this->assertTrue(FeatureBox::isEnabled('test_feature'));
}

✅ Roadmap

Feature toggle logic
JSON-based conditions
Artisan commands
Caching support
Web UI dashboard
A/B testing support
Redis driver
Feature analytics

🆘 Support

Documentation: GitHub Wiki
Issues: GitHub Issues
Discussions: GitHub Discussions
Email: mohamedhekal@gmail.com

🧑‍💻 Developed by Mohamed Hekal

Feel free to submit issues, ideas, or pull requests.

🤝 Contributing

Please see CONTRIBUTING.md for details.

📄 License

This package is open-sourced under the MIT license.

📚 Examples

E-commerce Example

// Enable new checkout for premium users only
FeatureBox::enable('new_checkout', [
    'user_roles' => ['premium'],
    'environments' => ['production']
]);

// In your checkout controller
public function checkout()
{
    $user = auth()->user();
    
    if (FeatureBox::isEnabled('new_checkout', [
        'user_id' => $user->id,
        'role' => $user->role
    ])) {
        return $this->newCheckout();
    }
    
    return $this->classicCheckout();
}

Beta Testing Example

// Enable beta features for specific users
FeatureBox::enable('beta_dashboard', [
    'user_ids' => [1, 5, 10, 15],
    'start_date' => '2025-01-01',
    'end_date' => '2025-03-31'
]);

Environment-Specific Features

// Enable debug features only in local environment
FeatureBox::enable('debug_panel', [
    'environments' => ['local']
]);

Gradual Rollout

// Roll out to 10% of users
FeatureBox::enable('gradual_rollout', [
    'custom' => [
        'rollout_percentage' => 10
    ]
]);

// In your code
$user = auth()->user();
$rolloutHash = crc32($user->id . 'gradual_rollout');
$inRollout = ($rolloutHash % 100) < 10;

if (FeatureBox::isEnabled('gradual_rollout', [
    'rollout_percentage' => $inRollout ? 10 : 0
])) {
    // New feature
}

mohamedhekal / laravel-featurebox

Maintainers

Details