Composer Normalize Laravel Package

Getting Started

1. Install as a dev dependency: composer require --dev ergebnis/composer-normalize
2. Allow the plugin: composer config allow-plugins.ergebnis/composer-normalize true
3. Run composer normalize to normalize your composer.json
4. Check in the normalized result and ensure CI runs composer normalize --dry-run to enforce consistency

Implementation Patterns

• Run composer normalize before committing composer.json changes—ideally via pre-commit hook or in CI (e.g., GitHub Actions, GitLab CI)
• Use --dry-run in CI pipelines to fail builds if composer.json isn’t normalized
• Configure indentation in composer.json under extra.composer-normalize (e.g., {"indent-size": 2, "indent-style": "space"}) to ensure consistent formatting across team and tooling
• Combine with pre-commit or hirak/prestissimo for faster multi-project workflows
• In monorepos, normalize each composer.json at project root level (not globally in root of monorepo)

Gotchas and Tips

• Lock file handling: If composer.lock exists, composer normalize verifies it's up-to-date; use --no-check-lock only when deliberately working with stale lock files
• Override priority: Config in extra.composer-normalize always overrides CLI options—don’t mix both approaches
• Indentation pitfalls: Use --dry-run --diff to confirm spacing behavior before committing; inconsistent --indent-size can cause unnecessary diffs
• Plugin version drift: Ensure all developers use the same version (pin in composer.json dev requirement); updates may change normalization rules (check changelog)
• Pre-commit integration: Add a .git/hooks/pre-commit check:

  if ! composer normalize --dry-run 2>&1 | grep -q "No changes"; then
    echo "❌ composer.json not normalized. Run 'composer normalize'." >&2
    exit 1
  fi
  

• CI tip: Add as a separate job (e.g., normalize-check) to fail fast without blocking install steps
• Troubleshooting: If lock hash doesn’t update, ensure --no-update-lock isn’t enabled and composer normalize has write permissions