Installererag Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require erag/installererag
   

   Ensure PHP 8.0+ is installed (package enforces this via composer.json constraints).

2. Register Provider:

   • Laravel 11+: Add to /bootstrap/providers.php:

     InstallerErag\InstallerServiceProvider::class
     

   • Laravel 10/9: Add to config/app.php under providers.

3. Publish Assets:

   php artisan vendor:publish --tag=InstallerErag --force
   

   This copies:

   • Blade views (resources/views/vendor/installererag/*)
   • Config (config/installererag.php)
   • Migration stubs (if applicable)

4. First Use Case: Trigger the installer via a route (default: /install-app). The package auto-generates a route if none exists in routes/web.php:

   Route::installer(); // Shorthand provided by the package
   

Implementation Patterns

Core Workflow

1. Pre-Installation Checks:

   • Automatically validates PHP version, extensions (e.g., pdo_mysql), and disk permissions.
   • Customize checks in config/installererag.php:

     'php_requirements' => [
         'version' => '8.0.0',
         'extensions' => ['pdo', 'mbstring', 'fileinfo'],
     ],
     

2. Dynamic .env Setup:

   • Use the InstallerErag\Installer::generateEnv() method to create a default .env with placeholders:

     use InstallerErag\Installer;
     $envContent = Installer::generateEnv();
     file_put_contents('.env', $envContent);
     

   • Override defaults via config/installererag.php:

     'env_defaults' => [
         'APP_URL' => 'https://yourdomain.com',
         'DB_DATABASE' => 'laravel_installer',
     ],
     

3. Database Migrations & Seeding:

   • Integrate with Laravel’s migration system:

     use InstallerErag\Installer;
     Installer::runMigrations(); // Runs `php artisan migrate`
     Installer::seedDatabase(); // Runs `php artisan db:seed`
     

   • Customize seeders in config/installererag.php:

     'seeders' => [
         'users' => \Database\Seeders\UserSeeder::class,
     ],
     

4. Custom Account Form:

   • Extend the default admin user creation form by publishing and modifying: resources/views/vendor/installererag/auth/register.blade.php.
   • Hook into form submission via the InstallerErag\Events\AdminCreated event:

     event(new AdminCreated($user));
     

5. Post-Installation Redirects:

   • Configure redirects in config/installererag.php:

     'post_install_redirect' => '/admin/dashboard',
     'post_install_message' => 'Installation complete! Redirecting...',
     

Integration Tips

• Middleware: Protect the installer route with middleware (e.g., web or custom):

  Route::installer()->middleware(['web', 'installer']); // Add to routes/web.php
  

• Localization: Override language files in resources/lang/vendor/installererag.
• Theming: Customize the installer’s CSS by publishing and extending: public/vendor/installererag/css/installer.css.
• API Integration: Use the package’s Installer facade to trigger steps programmatically:

  Installer::checkRequirements(); // Returns array of validation results
  

Gotchas and Tips

Pitfalls

1. Permission Issues:

   • The package defaults to 755 for storage/bootstrap/cache. Override in config/installererag.php:

     'folder_permissions' => [
         'storage' => 0775,
         'bootstrap/cache' => 0775,
     ],
     

   • Debug Tip: Use Installer::checkPermissions() to log missing permissions.

2. Environment File Conflicts:

   • If .env exists, the package skips generation by default. Force overwrite in config:

     'env_force_generate' => true,
     

   • Warning: This erases existing .env files.

3. Route Collisions:

   • The default /install-app route may conflict with existing routes. Rename it in config/installererag.php:

     'route_name' => 'custom-install',
     'route_path' => 'setup-app',
     

4. Database Seeders:

   • Ensure seeders are registered in DatabaseSeeder.php if using custom seeders.
   • Gotcha: The package runs seeders after migrations. Order matters for dependent seeders.

5. PHP Extensions:

   • The package checks for extensions but doesn’t install them. Document missing extensions in your README:

     'php_requirements' => [
         'extensions' => [
             'pdo_mysql' => 'MySQL support',
             'gd' => 'Image processing (optional)',
         ],
     ],
     

Debugging

• Log Output: Enable debug mode in config/installererag.php:

  'debug' => env('APP_DEBUG', false),
  

  Logs appear in storage/logs/laravel.log.

• Manual Validation:

  $requirements = Installer::checkRequirements();
  dd($requirements); // Inspect validation results
  

• Event Listeners: Listen for InstallerErag\Events\InstallationStarted/InstallationCompleted to log custom steps:

  Event::listen(InstallationStarted::class, function () {
      Log::info('Installer started at ' . now());
  });
  

Extension Points

1. Custom Steps:

   • Add pre/post-install hooks via service provider:

     public function boot()
     {
         Installer::addPreInstallStep(function () {
             // Custom logic (e.g., API key setup)
         });
     }
     

2. Dynamic Config:

   • Override config values at runtime:

     config(['installererag.env_defaults.APP_NAME' => 'MyApp']);
     

3. API Mode:

   • Disable the web UI and use the Installer facade for CLI-based installs:

     if (app()->runningInConsole()) {
         Installer::runFullInstall();
     }
     

4. Multi-Tenant Setup:

   • Extend the package to support tenant-specific .env files by overriding generateEnv():

     Installer::extend(function ($installer) {
         $installer->envGenerator = function () {
             return str_replace('DB_DATABASE=laravel', 'DB_DATABASE=tenant_'.request('tenant'), $installer->defaultEnv);
         };
     });
     

Pro Tips

• Docker Integration: Use the package to validate container environments:

  RUN composer require erag/installererag && \
      php artisan installer:check-requirements
  

• CI/CD Pipelines: Automate installs in GitHub Actions:

  - name: Run Installer
    run: php artisan installer:run --env=testing
  

• Local Development: Skip migrations/seeding in local .env:

  INSTALLER_SKIP_MIGRATIONS=true