Composer Normalize Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev ergebnis/composer-normalize
   composer config allow-plugins.ergebnis/composer-normalize true
   

   • Add the package as a dev dependency and enable the plugin.

2. First Use Case: Run in your Laravel project root:

   composer normalize
   

   • This normalizes composer.json in-place, ensuring consistent formatting and sorting of keys/values.

3. Where to Look First:

   • Documentation: README for CLI options and examples.
   • Examples: Review the examples section to see real-world diffs (e.g., PestPHP, PHPUnit).
   • Config: Check composer.json for existing extra.composer-normalize settings (if any).

Implementation Patterns

Daily Workflows

1. Pre-Commit Hook: Integrate with Laravel’s Git hooks (e.g., via laravel/git-hooks) to auto-normalize composer.json before commits:

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

   • Use --dry-run in CI/CD pipelines to enforce consistency without side effects.

2. Team Onboarding:

   • Add composer normalize to your contributing.md as a required step for PRs.
   • Example CI step (GitHub Actions):

     - name: Normalize composer.json
       run: composer normalize --dry-run
     

3. Custom Formatting: Configure indentation in composer.json:

   {
     "extra": {
       "composer-normalize": {
         "indent-size": 4,
         "indent-style": "space"
       }
     }
   }
   

   • Overrides CLI defaults globally.

4. Multi-Package Projects: Normalize specific files in monorepos:

   composer normalize packages/package-a/composer.json
   

Integration Tips

• Laravel Mix/Webpack: Add a script to package.json to normalize during build:

  {
    "scripts": {
      "build": "npm run dev && composer normalize"
    }
  }
  

• PHPStan/PSR-12: Combine with tools like php-cs-fixer for a full formatting pipeline:

  composer normalize && php-cs-fixer fix
  

• Custom Rules: Extend the normalizer by subclassing ComposerJsonNormalizer (advanced use case).

Gotchas and Tips

Pitfalls

1. Lock File Conflicts:

   • Running composer normalize without --no-update-lock may trigger unnecessary composer.lock updates.
   • Fix: Use --no-update-lock in CI to avoid flaky builds.

2. Merge Conflicts:

   • Normalization reorders keys (e.g., "require" → "require-dev"). Conflicts may arise if multiple contributors modify composer.json simultaneously.
   • Fix: Normalize locally before merging or use --diff to preview changes.

3. Custom Config Overrides:

   • CLI options (e.g., --indent-size) are ignored if extra.composer-normalize is set.
   • Fix: Remove or update the extra config if CLI behavior is desired.

4. Performance:

   • Normalization is fast, but large composer.json files (e.g., with hundreds of dependencies) may take a few seconds.
   • Tip: Cache results in CI with composer normalize --dry-run and fail fast.

Debugging

• Unexpected Changes: Use --diff to compare before/after:

  composer normalize --diff
  

  • Helps identify why keys/values were reordered.

• Plugin Not Running: Verify the plugin is enabled:

  composer config --list | grep allow-plugins
  

  • Ensure allow-plugins.ergebnis/composer-normalize is true.

• Phar Issues: If using the .phar version, ensure it’s executable (chmod +x) and PHP’s open_basedir restrictions aren’t blocking it.

Extension Points

1. Custom Normalization: Override the default normalizer by creating a custom plugin:

   use Ergebnis\Json\Normalizer\Vendor\Composer\ComposerJsonNormalizer;
   
   class CustomNormalizer extends ComposerJsonNormalizer {
       protected function normalizeExtra(array $extra): array {
           // Custom logic for the "extra" section
           return parent::normalizeExtra($extra);
       }
   }
   

   • Requires deeper integration with the plugin’s internals.

2. Post-Normalization Hooks: Use Laravel’s composer.post-autoload-dump script to run additional tasks after normalization:

   {
     "scripts": {
       "post-autoload-dump": [
         "@composer normalize",
         "php artisan optimize:clear"
       ]
     }
   }
   

3. Git Attributes: Add .gitattributes to ignore whitespace changes (if using custom indentation):

   composer.json diff=composer-normalize
   

   • Requires custom Git diff drivers (advanced).

Pro Tips

• Atomic Commits: Normalize composer.json in a separate commit from functional changes to avoid noise in PRs.

• Monorepo Projects: Use find to normalize all composer.json files recursively:

  find . -name composer.json -exec composer normalize {} \;
  

• Backup First: Always commit or stash changes before running composer normalize in production-like environments.

• CI Caching: Cache composer.lock and composer.json in CI to avoid redundant normalization:

  - uses: actions/cache@v3
    with:
      path: |
        composer.lock
        composer.json
      key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}