Composer Lint Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev sllh/composer-lint
   

   or globally:

   composer global require sllh/composer-lint
   

2. First Use Case: Run the extended validation command:

   composer validate
   

   This will enforce default rules (php, type, minimum-stability, version-constraints) and fail if any are violated.

3. Configuration: Edit ~/.config/composer/config.json (global) or .composer/config.json (project-specific) to enable/disable rules:

   {
       "config": {
           "sllh-composer-lint": {
               "php": true,
               "type": false,  // Disable if not needed
               "minimum-stability": false,  // Disable for dev environments
               "version-constraints": true
           }
       }
   }
   

Implementation Patterns

Usage Patterns

1. Pre-Commit Hooks: Integrate with tools like Husky or Laravel Git Hooks to run composer validate before commits:

   composer validate --no-check-publish
   

   • Use --no-check-publish to skip publishing packages (irrelevant for validation).

2. CI/CD Pipeline: Add to Laravel’s CI (e.g., GitHub Actions) as a pre-deployment step:

   - name: Validate composer.json
     run: composer validate --strict
   

   • --strict ensures CI fails on violations (recommended for production pipelines).

3. Team Onboarding: Use as a developer checklist in CONTRIBUTING.md:

   "Run composer validate before submitting PRs to ensure composer.json adheres to project standards."

4. Project-Specific Rules: Override global config in .composer/config.json for team-specific needs:

   {
       "config": {
           "sllh-composer-lint": {
               "version-constraints": {
                   "allowed": ["^", "~", "==", ">=", "<="]  // Customize allowed operators
               }
           }
       }
   }
   

Workflows

1. Fixing Violations:

   • PHP Requirement Missing: Add php: ^8.1 to require.
   • Invalid Version Constraint: Replace ~2.0 with ^2.0 (or vice versa if configured).
   • Unset Package Type: Add "type": "library" to composer.json.
   • Unnecessary Stability Flag: Remove minimum-stability or set to dev for local dev.

2. Debugging: Run with --verbose for detailed error messages:

   composer validate --verbose
   

3. Partial Validation: Validate only specific sections (e.g., require):

   composer validate --section=require
   

Integration Tips

1. Laravel-Specific:

   • Combine with laravel-zero-config or laravel-mix projects to ensure PHP version constraints align with Laravel’s requirements.
   • Use with composer normalize for additional formatting (e.g., sorting packages).

2. Monorepos:

   • Disable sort-packages if using tools like Laravel Sail or Bedrock with complex dependency structures.
   • Run validation per-package if performance is an issue.

3. Legacy Projects:

   • Gradually enable rules (e.g., start with version-constraints, then php).
   • Use --no-dev to skip dev-dependency checks during migration.

Gotchas and Tips

Pitfalls

1. Composer Version Mismatch:

   • Issue: The package may fail on Composer 2.5+. Errors like Class not found or Invalid argument often indicate compatibility issues.
   • Fix: Downgrade Composer to 2.4 or fork the package for updates.

2. False Positives:

   • minimum-stability Rule: May flag legitimate uses (e.g., dev dependencies or local projects). Fix: Disable globally or per-project:

     "minimum-stability": false
     

   • type Rule: Might reject custom package types (e.g., metapackage). Fix: Whitelist types in config or disable the rule.

3. Performance:

   • Large composer.json: Validation slows down with >500 dependencies. Fix: Run in CI only or disable non-critical rules (e.g., sort-packages).

4. Config Overrides:

   • Issue: Project-specific config may override global settings unexpectedly. Fix: Use explicit paths (e.g., .composer/config.json) and document overrides.

5. CI Flakiness:

   • Issue: Non-deterministic failures in CI (e.g., network timeouts during validation). Fix: Cache Composer dependencies or retry failed steps.

Debugging

1. Error Messages:

   • Example output:

     [Error] PHP requirement missing in "require" section.
     [Error] Invalid version constraint "~2.0" in "require": use "^2.0" instead.
     

   • Tip: Use --verbose to see full rule details.

2. Rule-Specific Debugging:

   • PHP Check: Verify php: ^8.1 exists in require.
   • Version Constraints: Use Composer’s version constraint guide to validate formats.
   • Type Check: Ensure "type" is set to library, project, etc.

3. Config Validation:

   • Test config changes locally before pushing to CI:

     composer config --list | grep sllh-composer-lint
     

Extension Points

1. Custom Rules:

   • Limitation: The package doesn’t support adding new rules, but you can:
     • Fork and extend the source code.
     • Combine with other tools (e.g., composer-normalize for additional checks).

2. Post-Validation Hooks:

   • Use Composer’s post-validate-cmd script to run custom logic:

     {
         "scripts": {
             "post-validate-cmd": [
                 "@php artisan optimize:clear",
                 "@php scripts/post-validate.php"
             ]
         }
     }
     

3. Integration with PHPStan/Laravel Pint:

   • Add composer validate to your phpstan.neon or pint.json workflows for a unified linting pipeline.

Tips

1. Laravel-Specific:

   • PHP Version: Align composer.json PHP constraints with Laravel’s supported versions.
   • Dev vs. Prod: Disable minimum-stability in CI but enable it locally for dev dependencies.

2. Team Adoption:

   • Document Rules: Add a DEPENDENCIES.md file explaining why each rule exists (e.g., "We use ^ for version constraints to avoid breaking changes").
   • Automate Fixes: Use composer why-not or composer why to debug constraint issues.

3. Performance:

   • Cache Results: Store validation outputs in CI artifacts to avoid redundant checks.
   • Parallelize: Run validation in parallel with other CI steps (e.g., tests).

4. Fallbacks:

   • No Composer 2.5+ Support: Use composer-normalize as a temporary replacement until a fork is available.
   • Rule Conflicts: Disable conflicting rules and file an issue upstream if needed.