Composer Installers Extender Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package to your project via Composer:

   composer require --dev oomphinc/composer-installers-extender
   

   Ensure composer/installers is also installed (required dependency).

2. Basic Configuration Create/update composer.json to define custom installers for arbitrary package types (e.g., type: "laravel-module"):

   {
     "extra": {
       "installer-paths": {
         "modules/{$name}/": ["type:laravel-module"]
       }
     }
   }
   

   Define the installer in composer/installers-extender.json (auto-generated or manual):

   {
     "installers": {
       "laravel-module": {
         "type": "laravel-module",
         "target": "modules/{$name}/",
         "stub": "stubs/module.stub"
       }
     }
   }
   

3. First Use Case Install a custom package type (e.g., a "module") via Composer:

   composer require vendor/module-package:dev-main --dev
   

   Verify the files are installed in modules/module-package/.

Implementation Patterns

Workflow Integration

1. Custom Package Types

   • Define reusable types (e.g., type: "laravel-theme", type: "config-package") in installers-extender.json.
   • Use stubs (e.g., stubs/theme.stub) to generate boilerplate files (e.g., composer.json, README.md) during installation.

2. Dynamic Paths Leverage placeholders ({$name}, {$version}) in installer-paths for flexible directory structures:

   "extra": {
     "installer-paths": {
       "resources/lang/{$locale}/{$name}/": ["type:translation-package"]
     }
   }
   

3. Post-Install Hooks Combine with post-install-cmd in composer.json to run scripts after installation:

   "scripts": {
     "post-install-cmd": [
       "php artisan vendor:publish --tag=module-config --force"
     ]
   }
   

4. Multi-Package Projects Use wildcards to group related packages (e.g., type: "laravel-*"):

   "installer-paths": {
     "packages/{$name}/": ["type:laravel-*"]
   }
   

Laravel-Specific Patterns

• Service Providers Auto-register providers by parsing installed packages and publishing config files:

  // In a custom Composer script
  $packages = json_decode(file_get_contents('composer.lock'), true);
  foreach ($packages['packages'] as $package) {
      if (str_contains($package['type'], 'laravel')) {
          $this->publishes([...], 'config');
      }
  }
  

• Namespace Resolution Use the installer to generate config/app.php entries dynamically:

  // stubs/module.stub
  <?php
  return [
      'providers' => [
          // Auto-generated
      ],
  ];
  

Gotchas and Tips

Common Pitfalls

1. Missing composer/installers

   • Error: Class 'Composer\Installers\Installer' not found.
   • Fix: Install composer/installers as a dev dependency:

     composer require --dev composer/installers
     

2. Stub File Paths

   • Error: Stubs not found during installation.
   • Fix: Ensure stubs are in the correct directory (e.g., stubs/module.stub) and referenced absolutely in installers-extender.json:

     "stub": "stubs/module.stub"
     

3. Case Sensitivity

   • Gotcha: installer-paths keys are case-sensitive on some OSes (e.g., Modules/ vs modules/).
   • Fix: Standardize paths (e.g., lowercase) and test cross-platform.

4. Caching Issues

   • Gotcha: Composer cache may retain old installer configurations.
   • Fix: Clear cache or run:

     composer clear-cache
     

5. Conflicting Installers

   • Gotcha: Multiple installers targeting the same path.
   • Fix: Use specific types or prioritize with installer-priority (if supported).

Debugging Tips

• Dry Run: Test installations without modifying files:

  composer require vendor/package --dry-run
  

• Verbose Mode: Enable Composer debug logs:

  COMPOSER_DEBUG=1 composer require vendor/package
  

• Check Generated Files: Inspect vendor/composer/installed.json for installation details.

Extension Points

1. Custom Installer Classes Extend Composer\Installers\Installer for complex logic:

   namespace App\Composer;
   
   use Composer\Installers\Installer;
   
   class ModuleInstaller extends Installer {
       protected $stub = __DIR__ . '/../../stubs/module.stub';
       // Custom logic here
   }
   

   Register in installers-extender.json:

   "installers": {
     "laravel-module": {
       "class": "App\\Composer\\ModuleInstaller"
     }
   }
   

2. Dynamic Stubs Use Twig templates for dynamic stubs (requires twig/twig):

   "stub": "stubs/module.twig"
   

   Example stub (stubs/module.twig):

   {# module.stub #}
   <?php
   return [
       'name' => '{{ name }}',
       'version' => '{{ version }}',
   ];
   

3. Pre/Post Install Scripts Hook into Composer lifecycle events via scripts:

   "scripts": {
     "post-install-cmd": [
       "@php artisan module:discover"
     ]
   }
   

Configuration Quirks

• Priority Handling: Installers with the same type may conflict. Use explicit installer-priority (if available) or namespace types (e.g., type: "myvendor-module").
• Symlinks: Avoid symlinks in installer-paths unless explicitly handled (Composer may not resolve them correctly).
• Windows Paths: Use forward slashes (/) in paths for cross-platform compatibility.