Getting Started

Minimal Steps

Installation:

composer require jmrashed/laravel-installer

Publish the installer assets and configuration:

php artisan vendor:publish --provider="Jmrashed\Installer\InstallerServiceProvider"

Enable the Installer: Add the middleware to your app/Http/Kernel.php:

protected $middlewareGroups = [
    'web' => [
        // ...
        \Jmrashed\Installer\Http\Middleware\CheckIfInstalled::class,
    ],
];

First Use Case: Access /install in your browser. The installer will guide you through the 9-step process, starting with the Welcome Screen and proceeding to Server Requirements, File Permissions, etc. Ensure your Laravel app is in a non-production environment (e.g., APP_ENV=local) before running the installer.

Implementation Patterns

Usage Patterns

Customizing Steps: Override or extend the default installation steps by publishing the installer views and modifying them:
```
php artisan vendor:publish --tag=installer-views
```
Edit the views in resources/views/vendor/installer/. For example, customize the Server Requirements step (server-requirements.blade.php) to add or remove checks.

Conditional Logic: Use the InstallerStep trait in custom steps. Example:

namespace App\Installer\Steps;

use Jmrashed\Installer\Contracts\InstallerStep as StepContract;

class CustomStep implements StepContract {
    use \Jmrashed\Installer\Traits\InstallerStep;

    public function run() {
        // Custom logic here
        return $this->nextStep('step_name');
    }
}

Database Configuration: The installer handles database setup automatically. Customize the database connection in config/installer.php:

'database' => [
    'default' => 'mysql',
    'connections' => [
        'mysql' => [
            'driver' => 'mysql',
            'host' => env('DB_HOST', '127.0.0.1'),
            'port' => env('DB_PORT', '3306'),
            'database' => env('DB_DATABASE', 'laravel'),
            'username' => env('DB_USERNAME', 'root'),
            'password' => env('DB_PASSWORD', ''),
        ],
    ],
],

Environment Configuration: The installer generates .env files. Customize the template by publishing and modifying:
```
php artisan vendor:publish --tag=installer-env
```
Edit resources/views/vendor/installer/env.blade.php.
Post-Installation Hooks: Trigger actions after installation by defining a postInstall method in a service provider or using Laravel's registered hook:
```
public function boot() {
    if ($this->app->installed()) {
        // Run post-installation tasks
    }
}
```

Workflows

Local Development: Use the installer to quickly spin up a Laravel project with preconfigured settings (e.g., database, caching, queues). Ideal for onboarding new team members or resetting local environments.
Production Deployment: Disable the installer in production by setting INSTALLER_ENABLED=false in .env. Use the installer only in staging or development environments.
Multi-Tenant Setups: Extend the installer to support multi-tenancy by adding tenant-specific configuration steps. Override the tenants table migration or add a step to configure tenant-related settings.

Integration Tips

Laravel Forge/Vapor: Integrate the installer with deployment scripts to automate the setup process. Example:
```
# In your deployment script
cd /path/to/app && php artisan install:run --force
```

Custom Validation: Add custom validation rules to steps by extending the validate method in a step class:

public function validate() {
    $validator = Validator::make(request()->all(), [
        'custom_field' => 'required|string|max:255',
    ]);
    return $validator;
}

Localization: Localize the installer by publishing and translating the language files:
```
php artisan vendor:publish --tag=installer-lang
```
Edit resources/lang/en/installer.php and add translations for other locales.

Gotchas and Tips

Pitfalls

Environment Mismatch: The installer may fail if APP_ENV is set to production. Always run it in local or staging environments. Add a check in your middleware:

public function handle($request, Closure $next) {
    if (app()->environment('production') && $request->is('install*')) {
        abort(403, 'Installer disabled in production.');
    }
    return $next($request);
}

File Permissions: The installer checks for correct permissions (e.g., storage/, bootstrap/cache/). If permissions are misconfigured, the installer may fail silently. Manually verify permissions before running:
```
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache
```
Database Conflicts: If the database already exists, the installer may skip migration steps or fail. Handle this gracefully by extending the database step:
```
public function run() {
    if (Schema::hasTable('migrations')) {
        return $this->nextStep('app_config');
    }
    // Proceed with migrations
}
```
Composer Autoloader: Ensure the vendor directory is writable. The installer may fail if Composer cannot regenerate the autoloader. Run:
```
composer dump-autoload
```
if issues arise.
Caching: Clear cached views and config before running the installer:
```
php artisan view:clear
php artisan config:clear
```

Debugging

Log Output: Enable debug mode in config/installer.php:
```
'debug' => true,
```
Logs will appear in storage/logs/installer.log.
Step-Specific Errors: Use Laravel's debugbar or dd() to inspect request data in custom steps. Example:
```
public function run() {
    dd(request()->all()); // Debug input
}
```
Middleware Conflicts: If the installer route is blocked, temporarily disable middleware in app/Http/Kernel.php for testing:
```
protected $middleware = [
    // \App\Http\Middleware\CheckForMaintenanceMode::class, // Disable temporarily
];
```

Config Quirks

Step Order: The installer steps are executed in the order defined in config/installer.php. Reorder steps by modifying the steps array:

'steps' => [
    'welcome',
    'server_requirements',
    'file_permissions',
    'custom_step', // Add your custom step here
    // ...
],

Hidden Steps: Hide steps from the UI by adding 'hidden' => true to the step configuration:
```
'steps' => [
    'database' => [
        'hidden' => true,
    ],
],
```

Conditional Steps: Skip steps dynamically by returning false in the shouldRun method:

public function shouldRun() {
    return !Schema::hasTable('users'); // Skip if table exists
}

Extension Points

Custom Steps: Create modular steps by following the InstallerStep contract. Example:

namespace App\Installer\Steps;

use Jmrashed\Installer\Contracts\InstallerStep;

class SmsConfigStep implements InstallerStep {
    public function run() {
        // Configure SMS settings (e.g., Twilio, AWS SNS)
        return $this->nextStep('finalize');
    }
}

'steps' => [
    'sms_config' => \App\Installer\Steps\SmsConfigStep::class,
],

API Integration: Extend the installer to support API-based configurations (e.g., OAuth, payment gateways). Example:

public function run() {
    $apiKey = request('api_key');
    config(['services.stripe.key' => $apiKey]);
    return $this->nextStep('app_config');
}

Theming: Override the installer's Blade templates to match your app's theme. Publish and modify:
```
php artisan vendor:publish --tag=installer-views
```
Edit resources/views/vendor/installer/layouts/app.blade.php for global styling.
Multi-Language Support: Add language packs by extending

Laravel Installer Laravel Package