Composer Require Checker Laravel Package

Technical Evaluation

Architecture Fit

• Dependency Validation Tool: Fits seamlessly into a Laravel/PHP ecosystem where managing transitive dependencies is critical. Laravel’s reliance on Composer and its complex dependency graph makes this tool highly relevant.
• Static Analysis: Complements existing tools like PHPStan, Psalm, or Laravel Pint by focusing on dependency hygiene rather than code correctness.
• Non-Invasive: Operates as a standalone CLI tool, avoiding runtime overhead or integration complexity.

Integration Feasibility

• Composer-Centric: Works directly with composer.json, requiring no Laravel-specific modifications.
• Laravel-Specific Considerations:
  • May flag Laravel Framework core classes (e.g., Illuminate\*) as "soft dependencies" if not explicitly required (though Laravel’s require section typically covers this).
  • Service Providers/Artisan Commands: Custom files outside autoload (e.g., app/Console/Commands) can be scanned via config.
• CI/CD Integration: Can be embedded in pre-commit hooks or CI pipelines (e.g., GitHub Actions) to enforce dependency discipline.

Technical Risk

• False Positives:
  • Risk of flagging Laravel’s Facades (e.g., Auth::*) as soft dependencies if not explicitly required (though Laravel’s require section usually includes illuminate/support).
  • Dynamic Class Loading: Tools like Laravel’s ClassLoader or autoload-dev may obscure dependency tracking.
• Performance:
  • Scanning large codebases (e.g., monorepos) could be slow due to static analysis overhead.
  • Xdebug Compatibility: Requires disabling Xdebug for optimal performance (as noted in docs).
• Configuration Complexity:
  • Custom whitelists (e.g., for internal packages) may need maintenance.
  • Custom Installer Plugins: Workarounds (e.g., --no-plugins) required for non-standard vendor/ structures.

Key Questions

1. Laravel-Specific Dependencies:
   • Should Laravel’s core packages (e.g., illuminate/*) be whitelisted in the config?
   • How to handle package-specific plugins (e.g., Laravel’s laravel/installer) without breaking scans?
2. CI/CD Strategy:
   • Should this run in pre-commit (fast feedback) or CI (gatekeeper)?
   • How to handle false positives in automated pipelines?
3. Performance:
   • Can the tool be parallelized for large codebases?
   • Should it be cached (e.g., store results between runs)?
4. Tooling Integration:
   • Can it be combined with PHPStan/Psalm for unified dependency + correctness checks?
   • Should it generate a report (e.g., JSON/HTML) for devs?

Integration Approach

Stack Fit

• Primary Use Case:
  • Laravel Monorepos: Enforce explicit dependencies in shared libraries.
  • Vendor Package Development: Ensure third-party Laravel packages declare all dependencies.
• Secondary Use Case:
  • Legacy PHP Projects: Audit existing codebases for soft dependencies.
• Compatibility:
  • PHP 8.1–8.5: Officially supported (PHP 8.3 dropped in v4.21.0).
  • Laravel 10/11: No conflicts; operates at Composer level.
  • Custom Autoloading: Supports autoload-dev and glob patterns for non-standard files.

Migration Path

1. Pilot Phase:
   • Run in local development first to identify false positives.
   • Configure composer-require-checker.json to whitelist known safe dependencies (e.g., Laravel core).
2. CI Integration:
   • Add to GitHub Actions/GitLab CI as a required check:

     - name: Check Composer Dependencies
       run: php composer-require-checker.phar check composer.json
     

3. Gradual Enforcement:
   • Start as a warning, then transition to a blocking check.
   • Use --severity=high to filter critical issues.

Compatibility

• Laravel-Specific:
  • No Laravel Dependencies: The tool itself is framework-agnostic.
  • Service Providers/Commands: Extend scan-files in config to include:

    "scan-files": ["app/Console/*", "app/Providers/*"]
    

• Custom Composer Plugins:
  • Use --no-plugins workaround if plugins alter vendor/ structure.
• PHAR vs. Global Install:
  • PHAR preferred for reproducibility (avoids global Composer conflicts).

Sequencing

1. Pre-Requirements:
   • Ensure composer.json is up-to-date (run composer install first).
   • Disable Xdebug if performance is critical (XDEBUG_MODE=off).
2. Execution Order:
   • Run after dependency installation but before testing/deployment.
   • Example workflow:

     composer install
     composer-require-checker check composer.json
     php artisan test
     

3. Post-Processing:
   • Address warnings by adding missing require entries to composer.json.
   • Re-run until no issues remain.

Operational Impact

Maintenance

• Configuration Drift:
  • Whitelists may need updates if new internal packages or Laravel versions are introduced.
  • Solution: Document whitelist rules in CONTRIBUTING.md.
• Tool Updates:
  • Minor updates (e.g., PHP 8.5 support) are low-risk; major versions may require testing.
  • Solution: Pin to a stable version (e.g., 4.24.0) in CI.

Support

• Developer Onboarding:
  • Educate team on soft vs. hard dependencies and why this matters.
  • Provide a template config (composer-require-checker.json) for new projects.
• False Positive Handling:
  • Maintain a centralized list of known false positives (e.g., Laravel Facades).
  • Use --ignore flags for recurring issues:

    composer-require-checker check --ignore="illuminate/support" composer.json
    

Scaling

• Large Codebases:
  • Parallelization: Split scans by directory (e.g., src/, app/).
  • Caching: Store results in .cache/composer-require-checker/ to avoid re-scanning unchanged files.
• Distributed Teams:
  • CI Parallelism: Run in parallel with other checks (e.g., PHPStan).
  • Local vs. CI: Allow local runs to skip slow scans (e.g., --fast flag if supported).

Failure Modes

Ramp-Up

• Phase 1: Local Adoption (2 weeks)
  • Add to local dev workflows; document common whitelist entries.
• Phase 2: CI Integration (1 week)
  • Add as a required check in PR templates.
• Phase 3: Enforcement (1 week)
  • Transition from warning to blocking in CI.
• Phase 4: Optimization (Ongoing)
  • Tune config for false positives; explore caching.

Key Metrics to Track

1. False Positive Rate: % of issues requiring manual whitelisting.
2. CI Execution Time: Ensure scans complete within 5 minutes.
3. Dependency Stability: Track breaking changes post-enforcement (e.g., fewer "soft dependency" issues).