Composer Require Checker Laravel Package

Technical Evaluation

Architecture Fit

• Dependency Validation: Aligns perfectly with Laravel’s dependency management philosophy, ensuring explicit dependency declarations to avoid "soft" dependencies.
• Static Analysis: Complements Laravel’s existing tooling (e.g., PHPStan, Psalm) by focusing on Composer dependency hygiene, reducing runtime surprises.
• Non-Invasive: Operates as a standalone CLI tool, avoiding integration conflicts with Laravel’s core or ecosystem.

Integration Feasibility

• Laravel Compatibility: Works with any PHP project (including Laravel) since it analyzes composer.json and source files, not Laravel-specific artifacts.
• CI/CD Integration: Can be embedded in Laravel’s CI pipeline (e.g., GitHub Actions) to enforce dependency discipline pre-merge.
• No Laravel-Specific Logic: No risk of breaking Laravel internals; operates at the Composer layer.

Technical Risk

• False Positives/Negatives: May flag legitimate transitive dependencies (e.g., Laravel’s illuminate/support used by laravel/framework). Requires configuration tuning (e.g., whitelisting).
• Performance: Scanning large codebases (e.g., Laravel + plugins) could be slow; mitigate by running in CI or parallelizing.
• Custom Installers: Laravel’s post-install-cmd or custom installers may mislead the tool (workaround: --no-plugins flag).

Key Questions

1. Whitelisting Strategy: How to balance strictness (e.g., flagging Laravel’s core dependencies) vs. pragmatism?
2. CI/CD Placement: Should it run on every push (slow) or gated (e.g., PRs targeting composer.json)?
3. Configuration Management: Centralize config (e.g., in composer-require-checker.json) or per-team?
4. Extension Handling: Should PHP extensions (e.g., pdo_mysql) be explicitly required in composer.json?
5. Laravel-Specific Dependencies: Should Laravel’s core packages (e.g., illuminate/) be whitelisted globally?

Integration Approach

Stack Fit

• PHP/Laravel Ecosystem: Native support for Composer-based projects; no Laravel-specific dependencies.
• Toolchain Compatibility:
  • CI/CD: Integrates with GitHub Actions, GitLab CI, etc., via CLI.
  • Dev Environments: Works with Docker, Vagrant, or local PHP setups.
  • IDE: Can be triggered via IDE scripts (e.g., PHPStorm run configurations).

Migration Path

1. Pilot Phase:
   • Run in a non-production Laravel repo to test false positives/negatives.
   • Configure composer-require-checker.json to whitelist known safe dependencies (e.g., Laravel’s core).
2. CI Integration:
   • Add to Laravel’s CI pipeline (e.g., GitHub Actions) with a fail-fast rule for critical paths.
   • Example workflow:

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

3. Gradual Enforcement:
   • Start as a warning, then promote to blocking failures post-validation.

Compatibility

• Laravel Versions: Works with all Laravel 5.8+ (PHP 8.1+) due to PHP 8.5 support in v4.17.0+.
• Custom Autoloading: May require adjustments if Laravel uses non-standard autoload paths (e.g., autoload-dev).
• Monorepos: Supports scanning subdirectories via glob patterns (e.g., packages/*/composer.json).

Sequencing

1. Pre-Commit Hooks (Optional): Local validation for fast feedback (e.g., via husky).
2. CI Pipeline: Run after composer install but before tests.
3. Release Process: Mandatory for major/minor dependency updates to catch breaking changes early.

Operational Impact

Maintenance

• Configuration Drift: Requires periodic updates to composer-require-checker.json as new dependencies are added.
• Tool Updates: Minor version bumps (e.g., PHP 8.5 support) may need testing but are low-risk.
• Dependency Graph Changes: Updates to Laravel or major dependencies may trigger new warnings.

Support

• Onboarding: Developers must understand "soft" vs. "hard" dependencies; provide clear docs/rules.
• False Positive Handling: Establish a process for whitelisting legitimate transitive dependencies (e.g., via PR approval).
• Extension Gaps: Ensure PHP extensions (e.g., intl) are explicitly required in composer.json.

Scaling

• Large Codebases: Performance may degrade; mitigate by:
  • Running in CI (not locally).
  • Excluding test files or vendor code via config.
  • Parallelizing scans (if supported in future versions).
• Distributed Teams: Centralize config in a shared template (e.g., Laravel’s package.json equivalent).

Failure Modes

Ramp-Up

1. Training:
   • Add a section to Laravel’s internal docs explaining the tool’s purpose and workflow.
   • Example: "Why we require all dependencies explicitly" with examples.
2. Pilot:
   • Run in a non-critical repo (e.g., a plugin) to refine whitelists.
3. Phased Rollout:
   • Start with backend services, then frontend (if applicable), and finally core Laravel repos.
4. Metrics:
   • Track:
     • % of PRs blocked by new warnings.
     • Time to resolve false positives.
     • Reduction in runtime dependency surprises.