Skip to content

Installation Guide

Jump to bottom
Mohamed Hamad edited this page Jul 26, 2025 · 1 revision

Installation Guide

This guide will walk you through the complete installation process for Laravel FeatureBox.

📋 Requirements

Before installing Laravel FeatureBox, ensure your system meets these requirements:

System Requirements

  • PHP: >= 8.1
  • Laravel: >= 10.0
  • Database: MySQL, PostgreSQL, or SQLite
  • Composer: Latest version

PHP Extensions

The following PHP extensions are required:

  • dom
  • curl
  • libxml
  • mbstring
  • zip
  • pcntl
  • pdo
  • sqlite (if using SQLite)
  • pdo_sqlite (if using SQLite)
  • bcmath
  • soap
  • intl
  • gd
  • exif
  • iconv
  • fileinfo

🚀 Quick Installation

Step 1: Install via Composer

composer require mohamedhekal/laravel-featurebox

Step 2: Publish Configuration and Migrations

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

Step 3: Run Migrations

php artisan migrate

Step 4: Verify Installation

php artisan featurebox:list

📖 Detailed Installation

Step 1: Install the Package

The package is available on Packagist and can be installed using Composer:

composer require mohamedhekal/laravel-featurebox

This command will:

  • Download the package from Packagist
  • Install all dependencies
  • Register the service provider automatically (Laravel auto-discovery)
  • Register the Facade alias

Step 2: Publish Configuration

Publish the configuration file to customize the package settings:

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

This creates config/featurebox.php with the following default configuration:

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'),
];

Step 3: Publish Migrations

Publish the database migrations to create the required tables:

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

This creates a migration file in database/migrations/ that will create the features table.

Step 4: Run Migrations

Execute the migrations to create the database table:

php artisan migrate

The migration 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
);

Step 5: Verify Installation

Test that the package is working correctly:

# List all features (should be empty initially)
php artisan featurebox:list

# Enable a test feature
php artisan featurebox:enable test_feature

# Check if the feature is enabled
php artisan featurebox:list

⚙️ Configuration

Environment Variables

Add these variables to your .env file to customize the package behavior:

# Cache settings
FEATUREBOX_CACHE_ENABLED=true
FEATUREBOX_CACHE_TTL=300

# Database table name
FEATUREBOX_TABLE=features

Cache Configuration

The package uses Laravel's cache system for performance. You can configure caching in config/featurebox.php:

'cache' => [
    'enabled' => env('FEATUREBOX_CACHE_ENABLED', true),
    'ttl' => env('FEATUREBOX_CACHE_TTL', 300), // 5 minutes
],

Database Configuration

The package uses your Laravel database configuration. Make sure your database connection is properly configured in config/database.php.

🔧 Manual Installation (Advanced)

If you prefer to install the package manually or need to customize the installation:

1. Download the Package

git clone https://github.com/mohamedhekal/laravel-featurebox.git
cd laravel-featurebox
composer install

2. Add to Composer Autoload

Add the package to your composer.json:

{
    "require": {
        "mohamedhekal/laravel-featurebox": "dev-main"
    },
    "repositories": [
        {
            "type": "path",
            "url": "./laravel-featurebox"
        }
    ]
}

3. Register Service Provider

Add the service provider to config/app.php:

'providers' => [
    // ...
    MohamedHekal\LaravelFeatureBox\FeatureBoxServiceProvider::class,
],

'aliases' => [
    // ...
    'FeatureBox' => MohamedHekal\LaravelFeatureBox\Facades\FeatureBox::class,
],

4. Copy Configuration and Migrations

Copy the configuration and migration files manually:

cp laravel-featurebox/config/featurebox.php config/
cp laravel-featurebox/database/migrations/* database/migrations/

🔄 Upgrading

From Previous Versions

When upgrading the package:

  1. Update the package:

    composer update mohamedhekal/laravel-featurebox

  2. Publish new configuration (if any):

    php artisan vendor:publish --tag=featurebox-config --force

  3. Run new migrations:

    php artisan migrate

  4. Clear cache:

    php artisan cache:clear

🧪 Testing Installation

Basic Test

Create a simple test to verify the installation:

// In a controller or route
use FeatureBox\Facades\FeatureBox;

// Enable a test feature
FeatureBox::enable('test_feature');

// Check if it's enabled
if (FeatureBox::isEnabled('test_feature')) {
    echo "Feature is enabled!";
} else {
    echo "Feature is disabled!";
}

Artisan Command Test

Test the Artisan commands:

# List features
php artisan featurebox:list

# Enable a feature
php artisan featurebox:enable my_feature

# Disable a feature
php artisan featurebox:disable my_feature

🚨 Troubleshooting

Common Installation Issues

1. Composer Memory Limit

If you encounter memory issues during installation:

COMPOSER_MEMORY_LIMIT=-1 composer require mohamedhekal/laravel-featurebox

2. Permission Issues

If you get permission errors:

sudo chown -R $USER:$USER .
chmod -R 755 storage bootstrap/cache

3. Migration Errors

If migrations fail:

# Check migration status
php artisan migrate:status

# Rollback and re-run
php artisan migrate:rollback
php artisan migrate

4. Service Provider Not Found

If the service provider is not auto-discovered:

  1. Check if Laravel auto-discovery is enabled
  2. Manually register the service provider in config/app.php
  3. Clear configuration cache: php artisan config:clear

5. Facade Not Found

If the Facade is not working:

  1. Check if the alias is registered in config/app.php
  2. Clear application cache: php artisan cache:clear
  3. Clear configuration cache: php artisan config:clear

Verification Commands

Use these commands to verify the installation:

# Check if package is installed
composer show mohamedhekal/laravel-featurebox

# Check if service provider is registered
php artisan config:show app.providers | grep FeatureBox

# Check if facade is working
php artisan tinker
>>> FeatureBox::all()
>>> exit

# Check if commands are available
php artisan list | grep featurebox

📚 Next Steps

After successful installation:

  1. Read the API Reference to learn how to use the package
  2. Check the Examples for usage patterns
  3. Configure caching for better performance
  4. Set up your first features using Artisan commands

🆘 Support

If you encounter any issues during installation:

Clone this wiki locally