Composer Normalize Laravel Package

Product Decisions This Supports

• Standardization of composer.json files across a Laravel/PHP codebase to reduce merge conflicts, improve readability, and enforce consistency in dependency management.
• Automated CI/CD integration to enforce formatting rules, ensuring all PRs meet project standards before merging (e.g., fail builds if composer.json is not normalized).
• Developer experience (DX) improvements by eliminating manual formatting debates and reducing cognitive load for contributors.
• Scalability for open-source or multi-team projects where contributors may have varying composer.json formatting preferences.
• Roadmap alignment with Laravel’s emphasis on maintainability (e.g., aligning with Laravel’s own normalization practices).
• Build vs. buy decision: Opt for this package over custom scripts or manual processes to avoid reinventing the wheel and leverage a battle-tested solution.
• Use cases:
  • Enforcing consistent composer.json formatting in monorepos or large codebases.
  • Integrating with pre-commit hooks (e.g., Husky) or CI pipelines (GitHub Actions, GitLab CI) to auto-format files.
  • Reducing technical debt by standardizing legacy composer.json files across a codebase.

When to Consider This Package

• Adopt if:

  • Your team struggles with inconsistent composer.json formatting (e.g., misordered keys, mixed indentation, or unstructured sections).
  • You maintain a Laravel/PHP project with multiple contributors or open-source repositories where formatting varies.
  • You want to automate CI checks to reject PRs with non-compliant composer.json files (e.g., using --dry-run in CI).
  • Your project uses Composer heavily (e.g., monorepos, plugins, or complex dependency trees) where standardization is critical.
  • You prioritize developer productivity by reducing manual formatting discussions.

• Look elsewhere if:

  • Your composer.json files are already standardized and minimal changes are needed (overhead of tooling may not justify benefits).
  • Your team prefers manual control over formatting (e.g., using IDE plugins like PHPStorm’s built-in formatter).
  • You’re using a custom Composer setup that conflicts with the package’s normalization rules (e.g., highly customized composer.json structures).
  • Your project has strict performance requirements in CI, and the package adds negligible value (though its impact is typically minimal).
  • You’re already using a similar tool (e.g., composer-normalizer by mlocati, though this package offers more Laravel-aligned defaults).

How to Pitch It (Stakeholders)

For Executives/Stakeholders:

*"This package solves a hidden productivity drain in our PHP/Laravel projects: inconsistent composer.json formatting. Currently, contributors spend time debating or manually fixing formatting issues in PRs, slowing down development. By adopting ergebnis/composer-normalize, we can:

• Automate standardization of composer.json files, reducing merge conflicts and manual work.
• Enforce consistency across the codebase, improving onboarding and maintainability.
• Integrate seamlessly with CI/CD, ensuring all contributions meet our standards before merging (e.g., fail builds for non-compliant files).
• Leverage a lightweight, open-source solution (MIT-licensed) used by projects like PestPHP and PHPUnit, with minimal maintenance overhead. The cost is negligible—a one-time setup and a CI pipeline update—while the benefits are immediate: faster PR reviews, fewer formatting debates, and a more professional codebase. This aligns with our goals for [scalability/maintainability/team efficiency]."*

For Engineering Teams:

*"This tool normalizes composer.json files to a consistent, Laravel-friendly format, addressing pain points like:

• Merge conflicts: Keys are ordered alphabetically, and sections are structured uniformly (e.g., require, require-dev, autoload).
• CI integration: Add composer normalize --dry-run to your CI pipeline to block non-compliant PRs (e.g., GitHub Actions/GitLab CI).
• Developer experience: No more arguments about indentation or key ordering—just run composer normalize locally or via pre-commit hooks.
• Laravel alignment: Follows Laravel’s own normalization practices, ensuring compatibility with ecosystem tools.

How to adopt:

1. Install as a dev dependency: composer require --dev ergebnis/composer-normalize.
2. Enable plugins: composer config allow-plugins.ergebnis/composer-normalize true.
3. Run locally: composer normalize (or integrate with Husky for pre-commit checks).
4. Add to CI: composer normalize --dry-run to fail builds on formatting issues.

Example impact: Projects like PestPHP use this to keep composer.json clean—we can too. Let’s prototype this in [Project X] and measure PR cycle time improvements."*