Composer Installers Extender Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: This package extends Composer’s native installer plugin (composer/installers) to support arbitrary package types (e.g., custom vendor types like laravel-module, theme, or domain-specific packages). It is ideal for Laravel projects where:
  • You need to install non-standard package types (e.g., plugins, themes, or modular components) into custom directories (e.g., app/Modules/, resources/themes/).
  • You rely on Composer scripts (post-install, post-update) to automate post-installation tasks (e.g., symlinking, configuration generation).
  • You want to decouple package installation logic from Laravel’s core while maintaining Composer’s dependency management.
• Laravel Synergy:
  • Works seamlessly with Laravel’s service provider and package discovery systems if paired with composer/installers (which maps packages to vendor/).
  • Enables modular architectures (e.g., Luminary’s laravel-modules or custom module systems) by allowing packages to install into app/ or other non-vendor paths.
  • Complements Laravel’s package auto-discovery (since 5.5) if packages are structured to register service providers dynamically.

Integration Feasibility

• Low-Coupling Design:
  • The package extends composer/installers without modifying Laravel’s core, making it backward-compatible.
  • Requires minimal configuration: Add the package to composer.json, define custom types in extra.installer-types, and specify target directories in package composer.json.
• Example Workflow:
  1. Install the package:

     composer require oomphinc/composer-installers-extender
     

  2. Configure composer.json to recognize custom types:

     {
       "extra": {
         "installer-types": {
           "laravel-module": "vendor/module",
           "theme": "resources/themes/%package%"
         }
       }
     }
     

  3. Define a custom package’s composer.json:

     {
       "type": "laravel-module",
       "extra": {
         "installer-name": "module"
       }
     }
     

• Laravel-Specific Considerations:
  • If using Laravel’s package auto-discovery, ensure custom packages include a PackageServiceProvider and follow Laravel’s conventions.
  • For modules, integrate with systems like illuminate/modules or custom solutions (e.g., spatie/laravel-module-stub).

Technical Risk

Key Questions

1. What are the primary use cases for custom package types in this project? (e.g., modules, themes, plugins, or domain-specific components?)
2. How will custom-installed packages interact with Laravel’s service container? (e.g., auto-discovery, manual binding, or facade publishing?)
3. Are there existing tools (e.g., spatie/laravel-package-tools) that could replace or complement this?
4. What post-installation tasks are required, and how will they be automated? (e.g., symlinks, database migrations, config publishing?)
5. How will this integrate with CI/CD pipelines? (e.g., testing custom-installed packages, handling rollbacks?)

Integration Approach

Stack Fit

• Core Stack Compatibility:
  • PHP 7.2+: The package supports modern PHP versions; Laravel 8+ is recommended for full feature parity.
  • Composer 1.x/2.x: Works with both, but Composer 2’s performance improvements are beneficial for large projects.
  • Laravel 5.5+: Optimal for package auto-discovery and modular architectures.
• Tooling Synergy:
  • Laravel Mix/Vite: If custom packages include assets, ensure build processes are triggered post-install.
  • Envoy/Deployer: Automate post-install scripts (e.g., symlinks, cache clearing) in deployment workflows.
  • PHPStan/Psalm: Validate custom package types in static analysis if using strict typing.

Migration Path

Compatibility

• With Laravel Ecosystem:
  • Packages: Works with any Composer-managed package; prioritize those with post-install-cmd scripts.
  • Modules: Integrates with illuminate/modules or custom module systems (e.g., nWidart/laravel-modules).
  • Themes: Ideal for projects using spatie/laravel-theme or custom theme systems.
• With Third-Party Tools:
  • Laravel Package Tools: Can coexist but may overlap; evaluate redundancy.
  • Spatie’s Packages: Compatible with laravel-package-tools if using auto-discovery.
  • Custom Scripts: Supports arbitrary post-install-cmd scripts (e.g., php artisan package:discover).

Sequencing

1. Pre-Integration:
   • Document current package types and installation workflows.
   • Identify candidate packages for custom types (e.g., low-maintenance, non-critical).
2. Pilot Phase:
   • Test with 1–2 non-critical packages (e.g., a theme or plugin).
   • Validate post-install scripts and Laravel integration.
3. Full Rollout:
   • Migrate remaining packages; update composer.json and CI/CD.
   • Train developers on new workflows (e.g., installing custom types).
4. Optimization:
   • Automate repetitive tasks (e.g., symlink generation) with Composer scripts.
   • Monitor performance impact (e.g., installation time for large projects).

Operational Impact

Maintenance

• Proactive Tasks:
  • Composer Updates: Monitor composer/installers and composer-installers-extender for breaking changes.
  • Package Updates: Ensure custom packages declare compatible types and post-install scripts.
  • Configuration Drift: Audit composer.json for orphaned or misconfigured installer-types.
• Reactive Tasks:
  • Permission Issues: Resolve Permission denied errors in target directories (e.g., app/Modules/).
  • Broken Scripts: Debug failed post-install-cmd scripts (e.g., missing dependencies, syntax errors).
  • Laravel Cache: Clear caches manually or automate with a Composer script if packages modify Laravel’s config/routes.

Support

• Troubleshooting:
  • Common Issues:
    • No installer found for package → Verify installer-types and package composer.json type.
    • Directory not writable → Adjust permissions or use COMPOSER_HOME to cache files.
    • Class not autoloaded → Ensure packages include autoload rules and use Laravel’s auto-discovery.
  • Debugging Tools:
    • composer diagnose → Check environment issues.
    • composer dump-autoload → Regenerate autoloader if classes are missing.
    • php artisan package:discover → Force-discover packages if auto-discovery fails.
• Documentation:
  • Maintain a PACKAGE_TYPES.md