Composer Installers Extender Laravel Package

Getting Started

Minimal Setup

1. Installation Update Composer to require the new version (PHP 7.1+ and Composer 2+ required):

   composer require --dev oomphinc/composer-installers-extender:^2.0
   

   Ensure composer/installers is installed (required dependency):

   composer require --dev composer/installers
   

2. Basic Configuration Define custom installers in composer/installers-extender.json (auto-generated or manual):

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

   Update composer.json to include new dev dependencies:

   {
     "require-dev": {
       "phpunit/phpunit": "^9.0",
       "squizlabs/php_codesniffer": "^3.6",
       "oomphinc/composer-installers-extender": "^2.0"
     }
   }
   

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

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

   Verify files are installed in modules/module-package/ and include generated LICENSE/CHANGELOG.md.

Implementation Patterns

Workflow Integration

1. Custom Package Types Define reusable types (e.g., type: "laravel-theme") in installers-extender.json:

   {
     "installers": {
       "laravel-theme": {
         "type": "laravel-theme",
         "target": "resources/themes/{$name}/",
         "stub": "stubs/theme.stub"
       }
     }
   }
   

   Use stubs to generate boilerplate (e.g., LICENSE, CHANGELOG.md):

   {# stubs/theme.stub #}
   # LICENSE
   Copyright © {{ year }}. All rights reserved.
   

2. Dynamic Paths with Placeholders Leverage {$name}, {$version} in installer-paths:

   "extra": {
     "installer-paths": {
       "packages/{$name}/src/{$name}/": ["type:laravel-package"],
       "packages/{$name}/tests/": ["type:laravel-package"]
     }
   }
   

3. Post-Install Hooks Combine with post-install-cmd to run scripts (e.g., PHPUnit tests):

   "scripts": {
     "post-install-cmd": [
       "@php artisan vendor:publish --tag=config",
       "@phpunit --testdox-html report.xml"
     ]
   }
   

4. Multi-Package Projects Use wildcards for grouped packages (e.g., type: "myvendor-*"):

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

Laravel-Specific Patterns

• Auto-Generated Documentation Use stubs to include CHANGELOG.md/LICENSE in installed packages:

  {# stubs/package.stub #}
  ## CHANGELOG
  
  All notable changes to this project will be documented in this file.
  

• PSR-2 Compliance Leverage php_codesniffer in CI/CD pipelines:

  "scripts": {
    "cs-check": "phpcs --standard=PSR2 src/"
  }
  

• Namespace Resolution Dynamically update config/app.php via stubs:

  {# stubs/module.stub #}
  'providers' => [
      {{ namespace }}\\Providers\\{{ name }}ServiceProvider::class,
  ],
  

Gotchas and Tips

Common Pitfalls

1. PHP/Composer Version Mismatch

   • Error: Your Composer version (1.x) does not satisfy requirement (2.x).
   • Fix: Update Composer globally:

     composer self-update
     

2. Namespace Changes

   • Gotcha: OomphInc\ComposerInstallersExtender\Installer moved to OomphInc\ComposerInstallersExtender\Installers\Installer.
   • Fix: Update custom installers:

     use OomphInc\ComposerInstallersExtender\Installers\Installer;
     

3. Missing Dev Dependencies

   • Error: Class 'PHPUnit\Framework\TestCase' not found.
   • Fix: Install new dev dependencies:

     composer require --dev phpunit/phpunit squizlabs/php_codesniffer
     

4. Stub File Changes

   • Gotcha: New stubs may require {{ year }} or other Twig variables.
   • Fix: Update stubs to include:

     {{ year }} = {{ "now"|date("Y") }}
     

5. Composer 2 Quirks

   • Gotcha: Composer 2 may cache installer configurations aggressively.
   • Fix: Clear cache or use:

     composer clear-cache
     

Debugging Tips

• Dry Run: Test installations without changes:

  composer require vendor/package --dry-run --no-install
  

• Verbose Mode: Enable debug logs:

  COMPOSER_DEBUG=1 composer require vendor/package
  

• Check Installed.json: Inspect vendor/composer/installed.json for details.

Extension Points

1. Custom Installer Classes Extend OomphInc\ComposerInstallersExtender\Installers\Installer:

   namespace App\Composer;
   
   use OomphInc\ComposerInstallersExtender\Installers\Installer;
   
   class ModuleInstaller extends Installer {
       protected $stub = __DIR__ . '/../../stubs/module.stub';
       public function getInstallPath($package) {
           return 'custom/' . $package->getName();
       }
   }
   

   Register in installers-extender.json:

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

2. Dynamic Stubs with Twig Use Twig for dynamic content (e.g., {{ year }}):

   {# stubs/license.stub #}
   Copyright © {{ year }} Your Name. All rights reserved.
   

3. PSR-2 Enforcement Add php_codesniffer to CI:

   # .github/workflows/ci.yml
   - name: PHP_CodeSniffer
     run: phpcs --standard=PSR2 src/ tests/
   

Configuration Quirks

• Composer 2 Path Handling: Use forward slashes (/) for cross-platform paths.
• Symlinks: Avoid in installer-paths unless explicitly supported.
• Priority Conflicts: Explicitly namespace types (e.g., type: "myvendor-module") to avoid clashes.
• New Default Files: Ensure stubs include LICENSE/CHANGELOG.md if required by your project.