Installer Plugin Laravel Package

Operational Impact

Maintenance

• Plugin Updates:
  • Monitor for Composer plugin API changes (e.g., v3 deprecations) and fork if needed.
  • Dependency updates: Track composer-plugin-api and react/promise for breaking changes.
  • Rollback plan: Maintain a backup of replicate/ files in a vendor/ subdirectory for recovery.
• Handler Maintenance:
  • Document handler logic in a HANDLERS.md file to onboard new developers.
  • Test handlers in isolation using PHPUnit’s Composer\Test\MockIO to catch regressions.
  • Deprecation warnings: Use handlers to log warnings for obsolete files (e.g., "This file will be removed in v2").
• Laravel-Specific Overheads:
  • Cache invalidation: Ensure config:clear runs post-install via composer.json scripts.
  • Published configs: Avoid replicating files that Laravel’s vendor:publish already manages.

Support

• Debugging Workflow:
  • Composer debug mode: Use composer install --verbose to trace replication failures.
  • Handler logging: Extend HandlerInterface to log actions (e.g., postFileCreationCallback calls) to storage/logs/composer-plugin.log.
  • Common issues:
    • Permission denied: Fix with umask in handlers or CI chmod steps.
    • Handler not found: Verify extra.class in composer.json matches the namespace.
    • File not copied: Check replicate/ directory exists in the metapackage root.
• Support Matrix:

  Issue Type	Owner	Resolution Path
  Handler logic errors	Backend Engineer	Debug with MockIO, update handler tests
  File overwrite conflicts	TPM/Product	Document in CONTRIBUTING.md, use handlers to merge
  Composer plugin failures	DevOps	Check Composer version, fork if needed
  Laravel integration	Laravel Lead	Add to post-install-cmd scripts

Scaling

• Performance:
  • Large replicate/ directories: Test with 1000+ files to validate Composer’s file system performance.
  • Handler overhead: Avoid blocking I/O in postFileCreationCallback (e.g., sync HTTP calls).
  • Parallelism: Composer replicates files sequentially—consider custom scripts for parallel tasks if needed.
• Multi-Environment Scaling:
  • Environment-specific metapackages: Use eckinox-metapackage types like:
    • company/metapackage-dev (with docker-compose.yml)
    • company/metapackage-prod (with supervisor.conf)
  • Version pinning: Lock metapackage versions in composer.json to avoid unintended updates.
• Team Adoption:
  • Onboarding: Create a 5-minute tutorial showing how to:
    1. Create a metapackage with replicate/.
    2. Add a handler for custom logic.
    3. Install it in a Laravel project.
  • Governance: Designate a Composer plugin owner to review new metapackages for security/risk.

Failure Modes

• Critical Failures:
  • Corrupted replicate/: If a metapackage’s replicate/ is missing, Composer falls back to partial install (v1.2.2). Mitigation: Validate replicate/ exists in CI.
  • Handler exceptions: Uncaught exceptions in handleExistingFile may silently skip files. Mitigation: Wrap handler logic in try-catch and log errors.
  • Laravel cache staleness: Replicating config/ without config:clear causes runtime errors. Mitigation: Enforce post-install-cmd scripts.
• Non-Critical Failures:
  • File permission issues: Fixed in v1.2.3 but may persist in restricted environments (e.g., Docker containers). Mitigation: Use chmod -R 755 in CI.
  • Path conflicts: Replicating app/Http/Controllers/ may overwrite user code. Mitigation: Exclude directories in handlers.
  • Handler autoloading: If the handler class isn’t PSR-4 autoloaded, Composer skips it (v1.2.1). Mitigation: Add autoload-dev in metapackage’s composer.json.

Ramp-Up

• Developer Onboarding:
  • Prerequisites:
    • Familiarity with Composer plugins (e.g., how post-install-cmd works).
    • Basic PHP OOP (for handlers) and Composer JSON (for extra.class).
  • Training Materials:
    • Cheat sheet: Commands like composer require --dev eckinox/installer-plugin and composer dump-autoload.
    • Example metapackage: A GitHub repo with a replicate/ directory and handler template.
  • Hands-on Lab:
    1. Create a metapackage with replicate/sample.env.
    2. Add a handler to rename sample.env to .env.
    3. Install it in a Laravel project and verify .env appears.
• Product Owner Buy-In:
  • ROI Justification:
    • Time saved: Reduce onboarding time by X hours per project.
    • Consistency: Eliminate "works on my machine" issues from manual file copies.
  • Risk Mitigation:
    • Start with non-production projects (e.g., internal tools).
    • Phase 1: Replicate static files (e.g., README.md).
    • Phase 2: Add handlers for dynamic logic (e.g., versioned configs).
• Tooling Integration:
  • IDE Support: Add PHPStorm/VSCode snippets for HandlerInterface stubs.
  • CI Templates: Pre-configure GitHub Actions to:

    - name: Install metapackages
      run: composer require company/metapackage-dev --dev
    

  • Documentation:
    • Architecture Decision Record (ADR): Explain why this was chosen over alternatives (e.g., vendor:publish).
    • Runbook: Steps to debug replication failures (e.g., "Check composer.json for eckinox-metapackage type").