Laravel Installer Laravel Package

Getting Started

Minimal Steps to First Use

1. Install the Package

   composer require relayercore/laravel-installer
   

   Ensure your project uses Laravel 10–12 and PHP 8.2+.

2. Publish Configuration

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

   Edit config/installer.php to set:

   • App name/logo
   • PHP/extension requirements (e.g., pdo, mbstring)
   • Writable directories (e.g., storage/app)
   • Admin model (e.g., \App\Models\User)
   • Post-install hook (e.g., php artisan key:generate).

3. Publish Views (Optional)

   php artisan vendor:publish --tag=installer-views
   

   Customize Blade templates in resources/views/vendor/installer/.

4. Test the Installer

   • Run php artisan serve and visit /install.
   • Verify the 5-step wizard (Requirements → Permissions → Database → Admin → Complete).
   • Check storage/installed is created post-install.

5. Block App Access Until Installed The package includes middleware to redirect all routes to /install until storage/installed exists. No additional setup is needed.

Implementation Patterns

Core Workflow

1. Middleware-Driven Access Control

   • The InstallerMiddleware checks for storage/installed and redirects unauthenticated users to /install.
   • Pattern: Use app()->hasBeenInstalled() in routes to conditionally block access:

     Route::middleware(['web', 'installer'])->group(function () {
         // Protected routes
     });
     

2. Step-Based Installation

   • Each step (e.g., Requirements, Database) is a Livewire component in app/Http/Livewire/Installer/.
   • Pattern: Extend the wizard by creating a custom step:

     // app/Providers/InstallerStepsServiceProvider.php
     public function registerSteps()
     {
         $this->app->make(\RelayerCore\Installer\Contracts\InstallerStep::class)
             ->addStep(new \App\Livewire\Installer\CustomStep());
     }
     

3. Configuration-Driven Customization

   • Override defaults in config/installer.php:

     'requirements' => [
         'php' => '8.2',
         'extensions' => ['pdo', 'mbstring', 'gd'], // Add custom extensions
     ],
     'writable_directories' => [
         'storage/app/public', // Add custom directories
     ],
     

   • Pattern: Use environment-specific configs (e.g., .env-based overrides):

     'admin_model' => env('INSTALLER_ADMIN_MODEL', \App\Models\User::class),
     

4. Database Integration

   • The installer auto-creates the database if it doesn’t exist and tests the connection.
   • Pattern: Customize database validation:

     // app/Providers/InstallerServiceProvider.php
     public function boot()
     {
         Installer::extend('database', function ($installer) {
             return new \App\Services\CustomDatabaseValidator($installer);
         });
     }
     

5. Post-Install Hooks

   • Run custom logic after installation (e.g., seeders, migrations):

     'after_install' => function () {
         \Artisan::call('migrate:fresh --seed');
         \Artisan::call('storage:link');
     },
     

Integration Tips

• For Commercial Apps (CodeCanyon):
  • Include a .env with a generic APP_KEY (as per security best practices).
  • Use the after_install hook to regenerate the key:

    'after_install' => function () {
        \Artisan::call('key:generate');
    },
    

• For Multi-Tenant Apps:
  • Extend the admin creation step to support tenant-specific roles:

    // app/Livewire/Installer/AdminStep.php
    public function createAdmin()
    {
        $user = \App\Models\User::create([
            'name' => $this->adminName,
            'email' => $this->adminEmail,
            'password' => bcrypt($this->adminPassword),
            'tenant_id' => $this->tenantId, // Custom field
        ]);
    }
    

• For Custom Validation:
  • Add step-specific validation in Livewire components:

    // app/Livewire/Installer/CustomStep.php
    protected $rules = [
        'custom_field' => 'required|string|max:255',
    ];
    

Gotchas and Tips

Pitfalls

1. Middleware Conflicts

   • If you use web middleware elsewhere, ensure installer middleware is applied last to avoid redirect loops.
   • Fix: Reorder middleware in app/Http/Kernel.php:

     'web' => [
         \App\Http\Middleware\EncryptCookies::class,
         \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
         \App\Http\Middleware\InstallerMiddleware::class, // Move to end
         \Illuminate\Session\Middleware\StartSession::class,
     ],
     

2. Database Connection Testing

   • The installer may fail silently if the database schema doesn’t match expectations (e.g., missing tables).
   • Tip: Add a pre-install check in after_install:

     'after_install' => function () {
         if (!Schema::hasTable('users')) {
             throw new \Exception("Database schema mismatch. Run migrations first.");
         }
     },
     

3. Livewire Script Paths

   • Livewire 3+ uses hashed script paths (e.g., /livewire/livewire.js?ver=...), which can break the installer’s Alpine.js integration.
   • Fix: Whitelist dynamic paths in InstallerMiddleware:

     protected function shouldRedirectToInstaller($request)
     {
         return ! $request->is('livewire/*[hash]*') && ! file_exists(storage_path('installed'));
     }
     

4. Admin Model Assumptions

   • The package assumes your admin model has name, email, and password fields. Custom models may require overrides.
   • Tip: Extend the AdminCreator service:

     // app/Providers/InstallerServiceProvider.php
     public function boot()
     {
         Installer::extend('admin', function ($installer) {
             return new \App\Services\CustomAdminCreator($installer);
         });
     }
     

5. Environment-Specific Requirements

   • Requirements like php: 8.2 are hardcoded in config. For multi-environment setups, use:

     'requirements' => [
         'php' => env('INSTALLER_PHP_VERSION', '8.2'),
     ],
     

Debugging

• Installer Stuck on a Step:

  • Check Livewire logs (storage/logs/laravel.log) for validation errors.
  • Tip: Add debug output in Livewire components:

    protected function mount()
    {
        \Log::debug('CustomStep mounted', ['data' => $this->data]);
    }
    

• Database Connection Errors:

  • Verify .env has correct credentials before running the installer.
  • Tip: Test connections manually:

    php artisan db:show
    

• Middleware Redirect Loops:

  • Ensure storage/installed is not accidentally deleted during development.
  • Fix: Add a debug check:

    // app/Http/Middleware/InstallerMiddleware.php
    public function handle($request, Closure $next)
    {
        if (app()->environment('local') && file_exists(storage_path('installed'))) {
            return $next($request); // Bypass in local
        }
        // ... rest of middleware
    }
    

Extension Points

1. Custom Steps

   • Create a Livewire component and register it in InstallerStepsServiceProvider:

     // app/Livewire/Installer/CustomStep.php
     public function mount()
     {
         $this->step = 'custom';
     }
     
     public function render()
     {
         return view('installer.steps.custom');
     }
     

2. Override Views

   • Publish views and modify templates in resources/views/vendor/installer/:

     php artisan vendor:publish --tag=installer-views
     

   • Tip: Use @extends('installer::layouts.app') to inherit base layouts.

3. Modify Validation Logic

   • Extend the Installer facade to add custom validation:

     // app/Providers/InstallerServiceProvider.php
     public function boot()
     {
         Installer::extend('validation', function ($installer) {
             return new \App\Services\CustomValidator($installer);
         });
     }
     

4. **Post