Composer Lint Laravel Package

Product Decisions This Supports

• Dependency Hygiene: Enforce standardized composer.json formats (e.g., ^2.0 over ~2.0) to reduce runtime dependency conflicts in Laravel applications, aligning with SemVer best practices.
• Developer Velocity: Automate 80% of manual composer.json reviews, freeing engineers to focus on feature development. Integrates with Laravel’s CI/CD (e.g., GitHub Actions) to fail builds early on misconfigurations.
• Risk Mitigation: Catch critical issues like:
  • Missing PHP version constraints (e.g., php:^8.1).
  • Invalid package types (e.g., library vs. project).
  • Unnecessary minimum-stability flags in production.
• Roadmap Priorities:
  • Phase 1: Standardize dependency formats across all Laravel projects (use this package + composer-normalize).
  • Phase 2: Extend to multi-repo validation (e.g., monorepos with shared composer.json).
  • Phase 3: Replace custom scripts with this tool to reduce tech debt.
• Build vs. Buy:
  • Buy: Prefer this over building custom validation scripts for basic-to-moderate needs. Avoid paid tools (e.g., Snyk) for this use case.
  • Custom: Only consider if rules need Laravel-specific extensions (e.g., validating config/app.php against composer.json PHP versions).

When to Consider This Package

• Adopt if:

  • Your team manually reviews composer.json for consistency (e.g., version formats, PHP requirements).
  • You want to reduce dependency-related bugs in Laravel apps by enforcing strict composer.json rules.
  • Your CI/CD pipeline lacks automated composer.json validation (e.g., no composer validate in pre-merge checks).
  • You’re using Composer 1.x or 2.x (up to 2.4) and need lightweight, rule-based validation.
  • You prioritize open-source, zero-cost solutions over proprietary tools.

• Look elsewhere if:

  • You need advanced schema validation (e.g., custom JSON structures, nested dependencies) → Use composer-normalize.
  • Your team requires interactive dependency resolution (e.g., conflict detection) → Use Composer’s built-in validate or composer-require-checker.
  • You’re not using Composer (e.g., Packagist-only workflows) → Irrelevant.
  • You need active maintenance → Last release was 2021; evaluate risk for long-term projects (consider forking).
  • Your composer.json is highly customized (e.g., dynamic dependencies, non-standard types) → May require rule exclusions.

How to Pitch It (Stakeholders)

For Executives:

*"This tool automates 90% of composer.json validation—catching errors like missing PHP version constraints or invalid version formats before they reach production. For a team of 10 developers, it could save 2–5 hours/week in manual reviews and reduce dependency-related bugs by 30%.

• Cost: Free, open-source, zero ongoing maintenance.
• Impact: Aligns with our 2024 Tech Debt Reduction initiative by standardizing dependency management.
• Risk: Low—lightweight, Composer-native, and tested in CI pipelines. Proposal: Pilot in [Project Y]’s CI/CD next sprint and measure false-positive rates. If successful, roll out to all Laravel repos."*

For Engineering (Laravel Teams):

*"Problem: Composer’s default validate misses critical misconfigurations (e.g., ~2.0 syntax, unstated PHP requirements), leading to runtime errors in Laravel apps. Solution: composer-lint adds 5 key checks with zero setup:

1. PHP Version Enforcement: Ensures composer.json PHP requirements match Laravel’s config/app.php.
2. Version Format Validation: Converts ~2.0 → ^2.0 (SemVer compliance).
3. Package Type Checks: Validates library/project types for multi-repo setups.
4. Stability Flag Control: Blocks minimum-stability in production (except for projects).
5. CI/CD Integration: Fails builds on violations via composer validate --strict.

How to Start:

1. Install:

   composer require sllh/composer-lint --dev
   

2. Configure in ~/.config/composer/config.json:

   {
     "config": {
       "sllh-composer-lint": {
         "php": true,
         "version-constraints": true,
         "minimum-stability": false  // Disable for dev deps
       }
     }
   }
   

3. Add to CI (GitHub Actions example):

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

Tradeoffs:

• Last updated in 2021: No support for Composer 2.5+. Test in staging or fork if needed.
• Lightweight: Focuses on basic rules; use composer-normalize for advanced cases.
• False Positives: Tune config to avoid blocking legitimate setups (e.g., dev dependencies).

Next Steps: Let’s test it on [Laravel E-Commerce] and compare to our current manual checks. If it catches >50% of past composer.json issues, we’ll expand to all repos."*

For Security/Compliance Teams:

*"This tool reduces supply-chain risk by:

• Enforcing PHP version pinning (mitigates CVEs from outdated PHP).
• Validating version constraints (prevents ~1.0 → 2.0 surprises).
• Blocking unstable dependencies in production (aligns with our SBOM requirements). Integration: Add to your pre-deployment security scans alongside composer audit and roave/security-advisories."*