Composer Suite Laravel Package

Product Decisions This Supports

• Multi-environment dependency management: Enables teams to maintain distinct dependency configurations (e.g., Symfony 4 vs. 5) in a single codebase, reducing duplication and merge conflicts.
• Local development workflows: Simplifies integration with local or private repositories (e.g., monorepos, internal packages) without polluting the main composer.json.
• Feature flagging for dependencies: Supports A/B testing or phased rollouts of dependency versions by generating isolated configurations.
• Build vs. buy: Avoids reinventing custom scripts or tools for dynamic composer.json generation, leveraging an open-source solution with minimal maintenance overhead.
• CI/CD optimization: Reduces build matrix complexity by generating environment-specific composer.json files on-the-fly (e.g., for testing against multiple PHP/Symfony versions).
• Legacy system migration: Gradually transition between dependency versions by toggling between generated suites (e.g., composer.lock for v4 vs. v5).

When to Consider This Package

• Avoid if:

  • Your team prefers immutable composer.json files (e.g., strict monorepo or package-locked workflows).
  • You need runtime dependency switching (this package requires environment variable toggling; use composer-require or custom scripts instead).
  • Your project has complex nested dependencies where path/URL resolution in generated files may break (test thoroughly).
  • You require atomic updates across all generated files (this is manual; consider a custom tool or composer hooks).
  • Your stakeholders reject environment-specific composer.json files (e.g., security policies or CI/CD constraints).

• Consider if:

  • You manage multiple dependency versions (e.g., PHP 7.4 vs. 8.1, Symfony 4/5/6) in a single repo.
  • Local development requires frequent switching between published and local packages (e.g., monorepos, private Git repos).
  • Your CI/CD pipeline needs lightweight matrix testing without bloating composer.json with conditional logic.
  • You want to reduce merge conflicts by centralizing dependency variations in one file.
  • Your team lacks bandwidth to maintain custom scripts for dynamic composer.json generation.

How to Pitch It (Stakeholders)

For Executives/Business Leaders:

"This package lets us reduce technical debt by consolidating multiple dependency configurations (e.g., Symfony 4 vs. 5) into a single composer.json file. Instead of maintaining duplicate files or complex build scripts, we generate environment-specific versions on demand—cutting merge conflicts and CI/CD overhead. For example, our local dev team can seamlessly switch between published and local packages without manual edits, while our QA pipeline can test against multiple PHP versions without bloating our repo. It’s a low-risk, high-reward tool to simplify our PHP/Laravel stack while keeping flexibility."

For Engineering Teams:

*"Problem: Managing multiple dependency versions (e.g., symfony/console: ^4.0 || ^5.0) or local packages in a single composer.json leads to:

• Merge conflicts in PRs.
• Manual composer.json edits for local dev.
• CI/CD complexity for matrix testing.

Solution: This package lets us define suites (e.g., symfony4, symfony5, local-dev) in composer.json#extra, then generate isolated composer.{suite}.json files with a single command:

composer suite:generate

• Switch between suites via export COMPOSER='composer.symfony5.json' (no code changes).
• Supports advanced actions: Replace dependencies, prepend/append repos, or unset keys—all declaratively.
• Works with paths: Local repos (e.g., ../../my-package) resolve correctly in generated files.
• Zero runtime overhead: Just toggle the COMPOSER env var; no runtime dependency switching.

Trade-offs:

• Requires discipline to keep composer.json DRY.
• Generated files must be committed to VCS (or managed externally).
• Not a silver bullet for runtime flexibility (but solves 80% of our use cases).

Next Steps:

1. Pilot with local dev workflows (replace manual composer.json edits).
2. Test CI matrix builds (e.g., Symfony 4/5 in parallel).
3. Document the composer-suite schema for the team."*

Key Metric to Track: Reduction in composer.json merge conflicts and CI build time for multi-version testing.