Composer Normalize Laravel Package

Product Decisions This Supports

• Developer-experience investment: Decide whether to standardize composer.json formatting and key/package ordering across Laravel/PHP repositories as part of engineering hygiene, rather than treating it as ad hoc contributor preference.
• Platform and roadmap planning: Add ergebnis/composer-normalize to Laravel app/package scaffolding, shared CI templates, and engineering standards so new repositories start consistent and existing repositories can be normalized incrementally.
• Build vs. buy/adopt: Prefer a mature, MIT-licensed Composer plugin over maintaining a custom formatter or relying on code-review comments. The package is dev-only, has a narrow scope, and can run as a Composer plugin, PHAR, or PHIVE install.
• CI quality gates: Use composer normalize --dry-run in CI to fail builds when composer.json is not normalized or when the lock file is stale, reducing review noise and merge conflicts around dependency changes.
• Use cases to prioritize: Multi-repo Laravel teams, open-source PHP packages, repositories with frequent dependency updates from Dependabot/Renovate, onboarding-heavy teams, and codebases where contributors frequently reorder or reformat composer.json.
• Release and maintenance decisions: Treat this as internal tooling rather than a customer-facing feature. Success should be measured by reduced review churn, fewer formatting-only diffs, faster onboarding, and fewer lock-file consistency issues—not by product analytics.

When to Consider This Package

• Consider it when your team maintains multiple PHP/Laravel repositories or packages and composer.json changes frequently enough to create formatting noise, merge conflicts, or inconsistent package ordering.
• Consider it when you want a low-cost, deterministic convention for dependency files and are prepared to enforce it in CI with composer normalize --dry-run.
• Consider it when contributors regularly add/remove dependencies and you want fewer review comments about ordering, indentation, key placement, or lock-file hash consistency.
• Consider the PHAR/PHIVE path if your security policy restricts Composer plugins or you need normalization in constrained CI environments.
• Look elsewhere or defer adoption when you have a single small repository with little Composer churn, no shared CI standards, or no owner for tooling governance.
• Look elsewhere if your primary need is dependency security auditing, license compliance, unused-dependency detection, or require-checker analysis; this package normalizes formatting and ordering, not dependency policy.
• Pilot first if your organization has strict allow-plugins controls, custom composer.json ordering requirements, or concerns about tooling writing lock-file hashes. The plugin is dev-only and low-risk, but it should still be approved and pinned deliberately.

How to Pitch It (Stakeholders)

Executive summary: ergebnis/composer-normalize is a small, MIT-licensed developer-productivity tool that standardizes composer.json across Laravel/PHP repositories. It is not customer-facing and does not affect runtime behavior, but it reduces code-review friction, merge conflicts, onboarding time, and formatting-only diffs. Adoption cost is low: add it as a dev dependency, allow the Composer plugin where required, and enforce it in CI with a dry-run check.

For engineering: Add ergebnis/composer-normalize as a dev dependency, document the allow-plugins setting, run composer normalize locally, and gate CI with composer normalize --dry-run. Use the PHAR/PHIVE option where plugin installation is restricted. Pin the version, pilot it in one or two representative repositories, then roll it into the base Laravel template and shared CI pipeline.

Decision requested: Approve a time-boxed pilot in a small set of active Laravel/PHP repositories. Evaluate success by reduced composer.json review churn, fewer formatting-related comments, successful CI enforcement, and smoother onboarding. If the pilot is clean, standardize it across repositories through the scaffolding and CI templates.