Install Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ekyna/install-bundle
   

   Add to config/app.php under providers:

   Ekyna\InstallBundle\InstallBundle::class,
   

2. First Use Case: Create a basic installer by implementing InstallerInterface in a bundle service:

   namespace App\Installers;
   
   use Ekyna\InstallBundle\Installer\InstallerInterface;
   
   class ExampleInstaller implements InstallerInterface
   {
       public function install()
       {
           // Your installation logic (e.g., migrations, config generation)
           return true;
       }
   }
   

   Register it as a service in your bundle’s Resources/config/services.yml:

   services:
       app.example_installer:
           class: App\Installers\ExampleInstaller
           tags:
               - { name: ekyna.installer }
   

3. Run Installers:

   php artisan ekyna:install
   

Implementation Patterns

Workflow Integration

1. Pre-Install Hooks: Extend InstallerInterface to support preInstall() for setup tasks:

   public function preInstall()
   {
       // Validate environment or dependencies
   }
   

2. Post-Install Actions: Use postInstall() for cleanup or notifications:

   public function postInstall()
   {
       // Log completion or trigger events
   }
   

3. Conditional Execution: Implement shouldInstall() to skip installers when unnecessary:

   public function shouldInstall()
   {
       return !file_exists($this->configPath);
   }
   

4. Dependency Management: Chain installers via depends tag in services.yml:

   tags:
       - { name: ekyna.installer, depends: { "app.migration_installer" } }
   

Common Use Cases

• Database Setup: Run migrations or seeders.
• Configuration: Generate or update config files.
• Asset Installation: Copy vendor assets or themes.
• Environment Checks: Validate PHP/OS requirements.

Gotchas and Tips

Pitfalls

1. Order Dependency: Installers run in arbitrary order unless explicitly tagged with depends. Use postInstall() for post-dependency tasks.

2. State Management: Avoid side effects in install()—use shouldInstall() to check for prior runs (e.g., via config files or DB flags).

3. Error Handling: Installers must return true on success. Silent failures may go unnoticed. Log errors explicitly:

   try {
       // Risky operations
   } catch (\Exception $e) {
       \Log::error("Installer failed: " . $e->getMessage());
       return false;
   }
   

4. Bundle Activation: Installers only run for active bundles. Verify bundle is enabled in config/bundles.php:

   Ekyna\InstallBundle\InstallBundle::class => ['all' => true],
   

Debugging Tips

• Dry Run: Override the command to log actions without executing:

  protected function execute(InputInterface $input, OutputInterface $output)
  {
      $installers = $this->getInstallers();
      foreach ($installers as $installer) {
          $output->writeln("<comment>Would run:</comment> " . get_class($installer));
      }
  }
  

• Verbose Output: Extend the command to show installer names:

  $output->writeln("<info>Running:</info> " . $installer::class);
  

Extension Points

1. Custom Commands: Extend the base command to add flags (e.g., --force, --dry-run):

   protected function getOptions()
   {
       return [
           new \Symfony\Component\Console\Input\InputOption('force', 'f', InputOption::VALUE_NONE, 'Force installation'),
       ];
   }
   

2. Event Dispatching: Trigger events (e.g., installer.run) before/after execution using Symfony’s EventDispatcher:

   $dispatcher->dispatch(new InstallerEvent($installer), 'installer.run');
   

3. Configuration: Load installer-specific configs via config/installers.php:

   $config = $this->container->getParameter('installer.example_config');