Composer Normalize Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev ergebnis/composer-normalize
   

   Add to your project's composer.json under "extra":

   "extra": {
       "composer-normalize": {
           "dry-run": false,
           "sort-order": ["require", "require-dev", "config", "autoload"]
       }
   }
   

2. First Run:

   composer normalize
   

   This sorts and formats your composer.json according to predefined rules.

First Use Case

• Onboarding: Automatically format a new project’s composer.json to match team conventions.
• PR Reviews: Run composer normalize before submitting PRs to ensure consistency.
• CI/CD: Integrate into your pipeline to reject malformed composer.json files.

Implementation Patterns

Workflow Integration

1. Pre-Commit Hook: Use with tools like Husky or [Git Hooks] to auto-format composer.json before commits:

   composer normalize --dry-run  # Validate without modifying files
   

2. CI Pipeline: Add to your CI (e.g., GitHub Actions) to enforce normalization:

   - name: Normalize composer.json
     run: composer normalize
   

3. Custom Sort Order: Override defaults in composer.json:

   "extra": {
       "composer-normalize": {
           "sort-order": [
               "config",
               "require",
               "require-dev",
               "autoload",
               "autoload-dev"
           ]
       }
   }
   

Laravel-Specific Use Cases

• Package Development: Normalize composer.json for plugins (e.g., Laravel packages) to ensure consistent dependency ordering.
• Monorepos: Use --path to normalize multiple composer.json files in a single command:

  composer normalize --path ./packages/*
  

Gotchas and Tips

Pitfalls

1. Dry-Run Misuse: Forgetting --dry-run in CI may overwrite files unexpectedly. Always test locally first.

2. Merge Conflicts: Normalization may cause conflicts if multiple developers modify composer.json simultaneously. Use git merge --no-commit to resolve manually.

3. Custom Rules: Overriding sort-order may break tooling (e.g., composer validate). Stick to the Composer schema for compatibility.

Debugging

• Verbose Output: Use -v for detailed logs:

  composer normalize -v
  

• Validation: Combine with composer validate to catch schema issues:

  composer validate && composer normalize
  

Extension Points

1. Custom Normalizers: Extend via Composer Plugin API to add project-specific rules (e.g., alphabetical sorting for require).

2. Git Attributes: Add .gitattributes to ignore normalized files (if using --no-sort):

   composer.json filter=composer-normalize
   

3. Configuration Inheritance: Use composer.json in monorepos to share normalization rules across projects.