Installers Laravel Package

Technical Evaluation

Architecture Fit

• Multi-Framework Composer Installer: While primarily designed for Laravel, this package extends Composer’s capabilities to install framework-specific assets (e.g., public, config, routes) during dependency installation. This aligns well with Laravel’s convention-over-configuration philosophy but may introduce indirect coupling if overused in non-Laravel projects.
• Laravel-Specific Optimizations: The package leverages Laravel’s composer.json hooks (e.g., post-install-cmd, post-update-cmd) to automate asset linking, which reduces manual php artisan commands in CI/CD pipelines. However, this assumes Laravel’s directory structure (public/, config/, etc.), limiting flexibility in monorepos or multi-framework setups.
• Composer Integration: Acts as a post-installation layer, not a core framework dependency. This makes it a lightweight addition but requires explicit opt-in via composer.json configuration.

Integration Feasibility

• Low-Coupling Design: The package injects logic into Composer’s lifecycle without modifying Laravel’s core. Integration risk is minimal if:
  • The project already uses Composer for dependency management.
  • Laravel’s default directory structure is preserved (or customizable via installers-definitions).
• Customization: Supports defining custom install paths (e.g., vendor/bin/installers:install --paths=app/Resources). This is useful for non-standard setups but adds complexity.
• Hook Conflicts: Potential clashes with other post-install-cmd scripts (e.g., Laravel Forge, Envoyer, or custom scripts). Mitigation requires sequencing control (e.g., ordering hooks in composer.json).

Technical Risk

Key Questions

1. Directory Structure: Does the project deviate from Laravel’s default (public/, config/)? If so, how will installers-definitions be configured?
2. CI/CD Impact: Will this replace or supplement existing php artisan commands in pipelines? (e.g., optimize, config:cache).
3. Multi-Environment: Are there environment-specific asset paths (e.g., public/staging/)? If so, how will they be handled?
4. Legacy Systems: Does the project use custom Composer scripts that might conflict with the installer’s hooks?
5. Performance: Will the additional Composer step impact build times significantly? (Benchmark with --profile.)

Integration Approach

Stack Fit

• Primary Use Case: Laravel projects using Composer for dependency management. Ideal for:
  • New Laravel projects where asset linking is repetitive.
  • Teams adopting Laravel from scratch (reduces boilerplate).
• Secondary Use Case: Non-Laravel PHP projects with custom installers-definitions (e.g., Symfony, custom frameworks).
• Anti-Patterns:
  • Projects using custom Composer plugins that override asset installation.
  • Monorepos with mixed frameworks (risk of unintended asset linking).

Migration Path

1. Assessment Phase:
   • Audit composer.json for existing post-install-cmd scripts.
   • Verify directory structure compatibility (or plan installers-definitions).
2. Pilot Integration:
   • Add to require-dev (or require) in composer.json:

     "extra": {
       "installer-paths": {
         "public/{$name}": ["type:asset"],
         "config/{$name}": ["type:config"]
       }
     }
     

   • Test locally with composer install --no-dev to validate asset links.
3. CI/CD Adjustment:
   • Replace manual php artisan commands (e.g., link-storage) with Composer’s automated linking.
   • Example: Remove php artisan storage:link if installers handles public/storage.
4. Rollout:
   • Gradual adoption in feature branches, with rollback plan for broken asset paths.

Compatibility

• Composer: Requires Composer 1.10+ (LTS). No breaking changes expected for Laravel 8+.
• Laravel: Works with Laravel 5.5+ (older versions may need composer/installers v1.x).
• Custom Frameworks: Possible with installers-definitions, but requires manual configuration.

Sequencing

• Hook Order: Define explicit ordering in composer.json to avoid conflicts:

  "scripts": {
    "post-install-cmd": [
      "Illuminate\\Foundation\\ComposerScripts::postInstall",
      "@php artisan optimize"
    ],
    "post-update-cmd": [
      "Illuminate\\Foundation\\ComposerScripts::postUpdate",
      "@php artisan optimize"
    ]
  }
  

• Priority: Run installers before Laravel’s default hooks to ensure assets are linked early.

Operational Impact

Maintenance

• Proactive:
  • Monitor Composer updates for installers package (MIT license = low risk, but check changelog).
  • Document installers-definitions in composer.json for future maintainers.
• Reactive:
  • Broken asset links post-update? Check composer.json for misconfigured paths or hook conflicts.
  • Debugging tip: Use composer install --verbose to trace installer execution.

Support

• Common Issues:
  • Permission Errors: Assets may fail to link if public/ is not writable. Mitigate with:

    composer install --no-scripts && composer install
    

  • Missing Assets: Verify installer-paths in composer.json matches actual file locations.
• Troubleshooting:
  • Disable installers temporarily to isolate issues:

    composer install --ignore-platform-reqs --no-scripts
    

Scaling

• Performance:
  • Minimal overhead (asset linking is I/O-bound, not CPU-intensive).
  • Benchmark in CI to ensure build times remain acceptable.
• Large Teams:
  • Reduces "works on my machine" issues by standardizing asset linking.
  • Centralize installers-definitions in a shared composer.json template for consistency.

Failure Modes

Ramp-Up

• Onboarding:
  • For Developers: Highlight that asset linking is now automated (no manual artisan link needed).
  • For Ops: Document CI/CD changes (e.g., removed storage:link from pipelines).
• Training:
  • Workshop: "Composer Installers Deep Dive" covering:
    • installer-paths syntax.
    • Debugging broken links.
    • Custom framework support.
• Documentation:
  • Add to project’s CONTRIBUTING.md:

    ## Asset Linking
    This project uses `composer/installers` to automate asset linking. Custom paths are defined in `composer.json` under `extra/installer-paths`.