Installers Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require composer/installers --dev
   

   • Add to composer.json under require-dev (recommended for most use cases).

2. Configure composer.json: Add a extra key with installer-paths to define where packages should be installed:

   {
       "extra": {
           "installer-paths": {
               "public/{$name}": ["type:asset-package"],
               "vendor/package/{$name}": ["type:package"],
               "app/Providers/{$name}/...": ["type:laravel-provider"]
           }
       }
   }
   

   • Use placeholders like {$name} (package name) or {$version} (version).

3. First Use Case: Install a package with a custom path (e.g., spatie/laravel-permission):

   composer require spatie/laravel-permission
   

   • The package will auto-install to app/Providers/LaravelPermission/... (if configured).

Implementation Patterns

Common Workflows

1. Framework-Specific Installations:

   • Use type: keys to target Laravel-specific paths (e.g., type:laravel-provider, type:laravel-model).
   • Example for a model:

     "extra": {
         "installer-paths": {
             "app/Models/{$name}/...": ["type:laravel-model"]
         }
     }
     

2. Asset Packages:

   • Install frontend assets (e.g., laravel-mix, vite) to public/:

     "public/js/{$name}": ["type:asset-package"]
     

3. Vendor-Specific Directories:

   • Group packages under vendor/package-name/:

     "vendor/{$name}": ["type:package"]
     

4. Conditional Install Paths:

   • Use environment variables or custom logic via post-install-cmd in composer.json:

     "scripts": {
         "post-install-cmd": [
             "@php -r \"file_exists('.env') && putenv('APP_ENV='.getenv('APP_ENV'))\""
         ]
     },
     "extra": {
         "installer-paths": {
             "storage/framework/{$name}": ["type:cache", "APP_ENV=local"]
         }
     }
     

Integration Tips

• Laravel Packages: Combine with laravel/package-development for local package testing. Example:

  composer require laravel/package-development --dev
  

  Then configure package.json to link to your local package path.

• CI/CD Pipelines: Use composer install --prefer-dist --no-dev in production to avoid dev dependencies, but ensure installers is excluded:

  composer install --prefer-dist --no-dev --ignore-platform-reqs
  

• Custom Types: Extend the installer by defining new type: keys in a custom script or plugin.

Gotchas and Tips

Pitfalls

1. Path Conflicts:

   • Overlapping paths (e.g., public/js/{$name} and public/{$name}) may cause silent failures.
   • Fix: Use specific prefixes (e.g., public/js/{$name}/dist) or debug with composer dump-autoload --verbose.

2. Case Sensitivity:

   • Paths are case-sensitive on Linux/macOS but not on Windows. Test cross-platform.

3. Caching Issues:

   • Composer caches installer paths. Clear cache if paths don’t update:

     composer clear-cache
     

4. Dev vs. Prod:

   • installer-paths in require-dev won’t apply to --no-dev installs. Use conditional paths or scripts to handle this.

5. Plugin Conflicts:

   • If using other Composer plugins (e.g., composer/semver), ensure they don’t override installer behavior.

Debugging

• Verbose Mode: Run composer install --verbose to see where packages are installed.
• Dry Run: Use composer install --dry-run to preview changes without installing.
• Check Installed Paths: Run composer show --path to list installed packages and their paths.

Tips

1. Laravel-Specific Types: Leverage built-in types like:

   • type:laravel-provider → app/Providers/{$name}/...
   • type:laravel-model → app/Models/{$name}/...
   • type:laravel-migration → database/migrations/{$name}_...

2. Dynamic Paths: Use placeholders like {$version} or {$name} to avoid hardcoding:

   "storage/logs/{$name}-{$version}": ["type:log-package"]
   

3. Post-Install Scripts: Automate post-install tasks (e.g., publishing config) with:

   "scripts": {
       "post-install-cmd": [
           "php artisan vendor:publish --tag=config --provider=\"Vendor\\Package\\PackageServiceProvider\""
       ]
   }
   

4. Exclude from Git: Add generated paths to .gitignore (e.g., vendor/package-name/).

5. Custom Installer Logic: Extend the installer by creating a custom plugin or using post-install-cmd to move files post-installation. Example:

   composer require monolog/monolog
   

   Then in post-install-cmd:

   "post-install-cmd": [
       "@php -r \"if (file_exists('vendor/monolog/monolog')) { copy('vendor/monolog/monolog/CHANGELOG.md', 'docs/monolog-changelog.md'); }\""
   ]