Composer Normalize Laravel Package

Getting Started

Minimal Steps

1. Installation Add the plugin to your project via Composer:

   composer require --dev localheinz/composer-normalize
   

   Ensure composer.json includes the plugin under "config":

   {
       "config": {
           "allow-plugins": {
               "localheinz/composer-normalize": true
           }
       }
   }
   

2. First Run Normalize your composer.json with:

   composer normalize
   

   Review the changes in the diff output. Commit the normalized file.

3. Where to Look First

   • Default Rules: Check vendor/localheinz/composer-normalize/config/default.json for built-in sorting/validation rules.
   • Custom Rules: Override defaults via .composer-normalize.json (see Implementation Patterns).
   • CI Integration: Add to pre-commit hooks (e.g., Husky) or CI pipelines (e.g., GitHub Actions) to enforce consistency.

Implementation Patterns

Core Workflows

1. Project Onboarding

   • Run composer normalize once to baseline existing composer.json.
   • Add to composer.json scripts:

     {
         "scripts": {
             "post-install-cmd": [
                 "@normalize"
             ],
             "post-update-cmd": [
                 "@normalize"
             ]
         }
     }
     

   • Note: Use post-install-cmd/post-update-cmd cautiously—only for projects where normalization is non-negotiable.

2. Team Enforcement

   • Pre-Commit Hook:

     composer normalize --dry-run || exit 1
     

     (Fail if changes would occur without applying them.)
   • CI Check:

     # GitHub Actions example
     - name: Check composer.json normalization
       run: composer normalize --dry-run
     

3. Custom Rule Sets

   • Create .composer-normalize.json in your project root:

     {
         "sort": [
             "require",
             "require-dev",
             "config",
             "extra.laravel"
         ],
         "rules": {
             "extra.laravel.auth": "required",
             "scripts.*": "alphabetical"
         }
     }
     

   • Laravel-Specific: Extend rules to enforce Laravel conventions (e.g., grouping extra.laravel keys).

4. Partial Normalization

   • Use --only to target specific sections:

     composer normalize --only="scripts"
     

Integration Tips

• IDE Support: Configure your IDE (e.g., PHPStorm) to ignore composer.json formatting—let the tool handle it.
• Monorepos: Run in subdirectories with --working-dir:

  composer normalize --working-dir=packages/api
  

• Merge Conflicts: Normalize before merging branches to avoid composer.json merge hell.

Gotchas and Tips

Pitfalls

1. Overzealous Autoloading

   • Normalization may reorder autoload/autoload-dev sections, breaking IDE indexing temporarily. Run composer dump-autoload afterward if issues arise.

2. Dry-Run False Positives

   • --dry-run may show changes even for trivial whitespace fixes. Use --no-diff to suppress output if only validation matters:

     composer normalize --dry-run --no-diff
     

3. Plugin Conflicts

   • If using other Composer plugins (e.g., dealerdirect/phpcodesniffer-composer-installer), ensure normalization runs after them in post-install-cmd.

4. Git Ignore

   • Accidentally committing normalized files to version control is harmless, but avoid adding vendor/ to .gitignore if you rely on the plugin’s cached rules.

Debugging

• Verbose Mode: Use -v to debug rule application:

  composer normalize -v
  

• Rule Validation: Test rules in isolation:

  composer normalize --only="rules"
  

• Reset to Defaults: Override .composer-normalize.json with an empty file to revert to defaults.

Extension Points

1. Custom Rules

   • Extend rules via .composer-normalize.json or environment variables:

     COMPOSER_NORMALIZE_RULES='{"scripts.*": "reverse-alphabetical"}' composer normalize
     

   • Advanced: Subclass Localheinz\ComposerNormalize\Rule\RuleInterface for project-specific logic.

2. Excluding Files

   • Skip normalization for specific files (e.g., composer.lock) via:

     {
         "exclude": [
             "composer.lock",
             "vendor/**"
         ]
     }
     

3. Laravel-Specific Quirks

   • Package Development: Normalize extra.laravel keys to match Laravel’s expected structure:

     {
         "rules": {
             "extra.laravel": {
                 "publishes": "required",
                 "providers": "alphabetical"
             }
         }
     }
     

   • Breeze/Scaffolded Projects: Run normalization after scaffolding to clean up default composer.json chaos.

4. Performance

   • Cache rules in CI by pre-downloading the plugin:

     - name: Cache Composer Normalize
       uses: actions/cache@v3
       with:
         path: ~/.cache/composer/files
         key: ${{ runner.os }}-composer-normalize