Product Installer Laravel Package

Getting Started

First Steps

1. Installation

   composer require oveleon/product-installer
   

   Ensure your project uses Contao 4.x or Contao 5.5+ (Turbo) (verified compatibility) and PHP 8.1+.

2. Basic Setup

   • Register the bundle in config/bundles.php:

     return [
         // ...
         Oveleon\ProductInstallerBundle\ProductInstallerBundle::class => ['all' => true],
     ];
     

   • Publish the default config (if needed):

     php bin/contao-console oveleon:product-installer:install
     

3. First Use Case Create a simple product installer command to deploy a demo product:

   use Oveleon\ProductInstallerBundle\Installer\ProductInstallerInterface;
   
   class DemoProductInstaller implements ProductInstallerInterface
   {
       public function install(array $options): bool
       {
           // Example: Install a product with predefined settings
           $product = new ProductModel();
           $product->name = $options['name'] ?? 'Demo Product';
           $product->save();
   
           return true;
       }
   }
   

   Register it in config/packages/oveleon_product_installer.yaml:

   services:
       App\Installer\DemoProductInstaller:
           tags: ['oveleon.product_installer']
   

Implementation Patterns

Core Workflows

1. Product Installation Use the ProductInstaller service to orchestrate installations:

   $installer = $this->container->get('oveleon.product_installer');
   $installer->install('demo_product', ['name' => 'My Product']);
   

2. Dependency Management Define dependencies between installers (e.g., a theme must be installed before a product):

   # config/packages/oveleon_product_installer.yaml
   oveleon_product_installer:
       installers:
           demo_theme:
               depends_on: ['base_theme']
   

3. Post-Install Hooks Extend functionality with events:

   use Oveleon\ProductInstallerBundle\Event\PostInstallEvent;
   
   $dispatcher->addListener(PostInstallEvent::class, function (PostInstallEvent $event) {
       if ($event->getProductName() === 'demo_product') {
           // Custom logic after installation
       }
   });
   

4. CLI Integration Create custom commands for user-friendly installations:

   use Symfony\Component\Console\Command\Command;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   
   class InstallDemoProductCommand extends Command
   {
       protected function execute(InputInterface $input, OutputInterface $output): int
       {
           $installer = $this->getContainer()->get('oveleon.product_installer');
           $success = $installer->install('demo_product');
   
           $output->writeln($success ? 'Product installed!' : 'Installation failed.');
           return $success ? Command::SUCCESS : Command::FAILURE;
       }
   }
   

5. Configuration Overrides Override default installer options via YAML:

   oveleon_product_installer:
       installers:
           demo_product:
               options:
                   name: 'Custom Product Name'
                   price: 99.99
   

Gotchas and Tips

Common Pitfalls

1. Contao Version Mismatch

   • The package is Contao 4.x/5.5+ (Turbo)-specific. Using it with Contao 3.x or unsupported 5.x versions will fail silently or throw errors.
   • Fix: Verify compatibility in composer.json or README.md. For Contao 5.5+, ensure oveleon/product-installer is explicitly listed in composer.json under require.

2. Missing Database Tables

   • If installers create custom tables, ensure they’re migrated before installation:

     php bin/contao-console doctrine:migrations:migrate
     

   • Tip: Use PreInstallEvent to validate the database schema.

3. Circular Dependencies

   • The package enforces dependency resolution but may fail on circular references (e.g., A depends on B and B depends on A).
   • Fix: Refactor dependencies or use a fallback installer.

4. Permission Issues

   • Installers may require elevated privileges (e.g., file system writes to web/).
   • Tip: Run CLI commands with sudo or adjust file permissions:

     chmod -R 775 web/
     

5. Event Dispatching Order

   • Events like PreInstallEvent and PostInstallEvent fire in a specific order. Misplacing logic (e.g., modifying data in PreInstallEvent but reading it in PostInstallEvent) can cause inconsistencies.
   • Tip: Log event sequences for debugging:

     $dispatcher->addListener(PostInstallEvent::class, function (PostInstallEvent $event) {
         error_log('PostInstallEvent fired for: ' . $event->getProductName());
     });
     

Pro Tips

1. Dry Runs Simulate installations without changes:

   $installer->dryRun('demo_product', ['name' => 'Test']);
   

2. Rollback Support Implement ProductInstallerInterface::rollback() to undo installations:

   public function rollback(array $options): bool
   {
       $product = ProductModel::findByName($options['name']);
       if ($product) {
           $product->delete();
           return true;
       }
       return false;
   }
   

3. Localization Support multilingual products by extending the installer:

   public function install(array $options): bool
   {
       $product = new ProductModel();
       $product->name = $options['name'];
       $product->save();
   
       // Add translations (works for Contao 4.x/5.5+)
       $tlProduct = new TLProduct();
       $tlProduct->pid = $product->id;
       $tlProduct->language = 'en';
       $tlProduct->title = $options['title_en'];
       $tlProduct->save();
   
       return true;
   }
   

4. Logging Enable verbose logging in config/packages/oveleon_product_installer.yaml:

   oveleon_product_installer:
       debug: true
   

5. Testing Use the ProductInstallerTestCase base class for unit tests:

   use Oveleon\ProductInstallerBundle\Test\ProductInstallerTestCase;
   
   class DemoProductInstallerTest extends ProductInstallerTestCase
   {
       public function testInstallation()
       {
           $installer = $this->getInstaller('demo_product');
           $this->assertTrue($installer->install([]));
       }
   }
   

6. Performance Batch database operations for large installations:

   public function install(array $options): bool
   {
       DB::beginTransaction();
       try {
           // Bulk insert products (works for Contao 4.x/5.5+)
           ProductModel::insert($options['products']);
           DB::commit();
           return true;
       } catch (\Exception $e) {
           DB::rollBack();
           return false;
       }
   }
   

7. Contao 5.5+ (Turbo) Specifics

   • Symfony 6+ Compatibility: Ensure your project’s symfony/* packages are compatible with Symfony 6+ if using Contao 5.5+.
   • Dependency Injection: Contao 5.5+ may use autowiring differently. Explicitly type-hint services where needed:

     public function __construct(private ProductInstallerInterface $installer)
     {
     }
     

   • Console Commands: For Contao 5.5+, register commands in src/Command/ and ensure they extend Contao\CoreBundle\Command\ContaoCommand:

     use Contao\CoreBundle\Command\ContaoCommand;
     
     class InstallDemoProductCommand extends ContaoCommand
     {
         // ...
     }
     

   • Configuration: Contao 5.5+ may use config/packages/ or config/bundles.php differently. Verify the correct path for your setup.