README

A self-contained Laravel 11+ CMS auto-installer package with multi-step web wizard, license validation, and frontend-agnostic UI.

📋 Table of Contents

Features
Requirements
Installation
Configuration
Usage
Installation Wizard Steps
Artisan Commands
Events
Troubleshooting
License

✨ Features

Multi-Step Installation Wizard

8-Step Interactive Process: Guided setup from license validation to final configuration
Real-time Validation: Instant feedback on requirements, permissions, and database connections
Frontend-Agnostic: Automatically detects and adapts to your frontend stack (Blade, Livewire, Vue, React, Next.js, etc.)

Enterprise-Grade Features

License Validation: Remote license verification with API integration
Environment Management: Automatic .env file configuration
Database Setup: Support for MySQL, PostgreSQL, SQLite, and SQL Server
Migration & Seeding: Automated database migrations and seeder execution
Admin Account Creation: Built-in admin user setup with role support (Spatie permission compatible)
Logging System: Dedicated installer logging channel for troubleshooting

Developer-Friendly

Artisan Commands: CLI tools for installation management
Event System: Dispatch events for customization and extensibility
Service Contracts: Clean interfaces for easy testing and mocking
Publishable Assets: Customize views, config, and assets

📦 Requirements

Server Requirements

PHP: >= 8.2
Laravel: 11.x or 12.x
Database: MySQL, PostgreSQL, SQLite, or SQL Server
Extensions: PDO, OpenSSL, JSON, MBstring

Required PHP Extensions

pdo - Database abstraction layer
openssl - Encryption and security
json - Data interchange
mbstring - Multibyte string handling
fileinfo - File type detection
tokenizer - Code tokenization

🔧 Installation

Step 1: Install via Composer

composer require shamimstack/laravel-cms-installer

Step 2: Service Provider Registration (Laravel 10 and below)

For Laravel 11+, package discovery is automatic. For older versions, add to config/app.php:

'providers' => [
    // ...
    shamimstack\Installer\InstallerServiceProvider::class,
],

Step 3: Publish Assets (Optional)

# Publish all assets
php artisan vendor:publish --tag=cms-installer

# Publish only config
php artisan vendor:publish --tag=config

# Publish only views
php artisan vendor:publish --tag=views

# Publish only CSS and JS
php artisan vendor:publish --tag=assets

Step 4: Access the Installer

Once installed, navigate to your application URL. If the application is not installed, you'll be automatically redirected to /install.

Or directly visit: http://your-domain.com/install

⚙️ Configuration

Configuration File

After publishing the config file (cms-installer.php), you can customize the following options:

License Configuration

'license' => [
    'api_url' => env('LICENSE_API_URL', 'https://api.yourservice.com/validate'),
    'api_key' => env('LICENSE_API_KEY', ''),
    'enabled' => env('LICENSE_ENABLED', true),
    'token_path' => storage_path('app/.license'),
],

Database Settings

'database' => [
    'supported_drivers' => ['mysql', 'pgsql', 'sqlite', 'sqlsrv'],
    'default_driver' => 'mysql',
],

Admin User Configuration

'admin' => [
    'model' => App\Models\User::class,
    'role_system' => 'spatie', // or 'column'
    'admin_role_name' => 'admin',
    'role_column' => 'role',
    'admin_email_default' => 'admin@example.com',
],

Permissions

'permissions' => [
    'directories' => [
        'storage' => 'writable',
        'bootstrap/cache' => 'writable',
        'public' => 'writable',
    ],
],

Logging

'logging' => [
    'channel' => 'installer',
    'retention_days' => 7,
],

📖 Usage

Web Interface

The installer provides a beautiful, step-by-step web interface:

Welcome Screen - Accept license terms
Requirements Check - Server and PHP extension verification
Permissions Check - Directory and file permissions
Database Configuration - Connection setup and testing
Migration & Seeding - Database schema and data
Admin Account - Create administrator credentials
Application Settings - Site name, URL, timezone
Completion - Installation summary and access details

Manual Installation Flow

If you prefer manual control:

// In your service provider or bootstrap file
use shamimstack\Installer\Services\DatabaseManager;
use shamimstack\Installer\Services\AdminManager;

$database = app(DatabaseManager::class);
$admin = app(AdminManager::class);

// Configure database
$database->update([
    'DB_CONNECTION' => 'mysql',
    'DB_HOST' => '127.0.0.1',
    'DB_PORT' => '3306',
    'DB_DATABASE' => 'your_db',
    'DB_USERNAME' => 'root',
    'DB_PASSWORD' => 'password',
]);

// Run migrations
$database->runMigrations();

// Create admin
$admin->create([
    'name' => 'Admin User',
    'email' => 'admin@example.com',
    'password' => bcrypt('password'),
]);

🎯 Installation Wizard Steps

Step 1: Welcome / License

Review license terms
Enter license key and API key
Validate credentials remotely

Step 2: Requirements

PHP version check (>= 8.2)
Required extensions verification
Laravel version compatibility

Step 3: Permissions

Storage directory writability
Bootstrap/cache permissions
Public directory access

Step 4: Database

Select database driver
Enter connection details
Test connection in real-time
Save configuration to .env

Step 5: Migration & Seeding

Run database migrations
Execute seeders
View migration output
Error handling and rollback info

Step 6: Admin Account

Choose admin creation method
Enter administrator details
Configure roles (if using Spatie)
Email verification setup

Step 7: Application Settings

Application name
Base URL
Default timezone
Locale settings
Debug mode toggle

Step 8: Complete

Installation summary
Created resources overview
Login credentials reminder
Next steps and recommendations

🛠️ Artisan Commands

installer:status

Display current installation state, frontend stack, and license status.

php artisan installer:status

Output includes:

Installation status (installed/not installed)
Environment information
Frontend stack detection
License validation status
Metadata (installation date, versions, etc.)

installer:reset

Reset the installation process by removing the lock file.

# Safe reset (asks for confirmation in production)
php artisan installer:reset

# Force reset (no confirmation)
php artisan installer:reset --force

Use cases:

Re-running the installer
Development environment resets
Troubleshooting installation issues

📡 Events

The package dispatches events throughout the installation process for extensibility:

Available Events

Event	Description
`InstallerStarted`	Installation wizard begins
`LicenseValidated`	License successfully validated
`DatabaseConfigured`	Database connection configured
`MigrationsCompleted`	All migrations executed
`SeedingCompleted`	Database seeding finished
`AdminCreated`	Admin account created
`InstallationCompleted`	Full installation complete

Listening to Events

use shamimstack\Installer\Events\InstallationCompleted;

protected $listen = [
    InstallationCompleted::class => [
        'App\Listeners\SendInstallationNotification',
    ],
];

Example Listener

namespace App\Listeners;

use shamimstack\Installer\Events\InstallationCompleted;

class SendInstallationNotification
{
    public function handle(InstallationCompleted $event): void
    {
        // Send email notification
        // Log to external monitoring
        // Trigger webhook
        // etc.
    }
}

🔍 Troubleshooting

Common Issues

1. "Directory Not Writable" Error

Solution: Ensure proper permissions:

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

2. Database Connection Failed

Solutions:

Verify database credentials
Check database server is running
Ensure database exists (or has CREATE privileges)
Check firewall rules for remote connections

3. License Validation Fails

Solutions:

Verify API key is correct
Check server can reach license API endpoint
Ensure SSL certificates are up to date
Review storage/logs/installer.log for details

4. Migration Errors

Solutions:

Check database connection
Verify migrations exist and are valid
Increase PHP memory limit if needed
Review database user privileges

5. Frontend Detection Issues

Solutions:

Ensure composer.json and package.json are present
Check that frontend dependencies are installed
Review detected stack in installer:status command

Log Files

The installer maintains detailed logs:

Location: storage/logs/installer.log
Retention: Configurable (default: 7 days)
Level: Debug (captures all operations)

View logs in real-time:

tail -f storage/logs/installer.log

Getting Help

If you encounter issues:

Check the log file: storage/logs/installer.log
Run status command: php artisan installer:status
Review requirements documentation
Contact support with:
- Log file contents
- PHP version (php -v)
- Laravel version (php artisan --version)
- Database type and version
- Error messages and screenshots

📝 License

This package is proprietary software licensed under the terms agreed upon during purchase.

🤝 Contributing

We welcome contributions! Please follow these steps:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

🙏 Acknowledgments

Laravel framework and community
All contributors and testers
Our amazing users providing feedback

📞 Support

For support and questions:

Documentation: https://docs.shamimstack.com/installer
Email: support@shamimstack.com
GitHub Issues: https://github.com/shamimstack/laravel-cms-installer/issues

Made with ❤️ by ShamimStack

shamimstack / laravel-cms-installer

Maintainers

Package info

Statistics

Security

README

📋 Table of Contents

✨ Features

Multi-Step Installation Wizard

Enterprise-Grade Features

Developer-Friendly

📦 Requirements

Server Requirements

Required PHP Extensions

🔧 Installation

Step 1: Install via Composer

Step 2: Service Provider Registration (Laravel 10 and below)

Step 3: Publish Assets (Optional)

Step 4: Access the Installer

⚙️ Configuration

Configuration File

License Configuration

Database Settings

Admin User Configuration

Permissions

Logging

📖 Usage

Web Interface

Manual Installation Flow

🎯 Installation Wizard Steps

Step 1: Welcome / License

Step 2: Requirements

Step 3: Permissions

Step 4: Database

Step 5: Migration & Seeding

Step 6: Admin Account

Step 7: Application Settings

Step 8: Complete

🛠️ Artisan Commands

installer:status

installer:reset

📡 Events

Available Events

Listening to Events

Example Listener

🔍 Troubleshooting

Common Issues

1. "Directory Not Writable" Error

2. Database Connection Failed

3. License Validation Fails

4. Migration Errors

5. Frontend Detection Issues

Log Files

Getting Help

📝 License

🤝 Contributing

🙏 Acknowledgments

📞 Support