Composer Require Checker Laravel Package

Product Decisions This Supports

• Dependency Hygiene & Risk Mitigation:

  • Enables proactive detection of "soft" (transitive) dependencies, reducing hidden risks from undocumented library updates.
  • Aligns with shift-left security by catching dependency issues early in the CI/CD pipeline (e.g., pre-merge or pre-release).

• Build vs. Buy:

  • Buy: Avoids reinventing static analysis for dependency validation. The tool is battle-tested (1K+ stars, MIT license) and maintained.
  • Build: Justify custom solutions only if the package lacks critical features (e.g., support for monorepos or specific PHP extensions). Currently, the tool covers 90%+ of use cases out-of-the-box.

• Roadmap Priorities:

  • Phase 1: Integrate into pre-commit hooks (e.g., Husky) or CI gates (GitHub Actions/GitLab CI) to block soft dependencies.
  • Phase 2: Extend to vendor-specific policies (e.g., "block all non-PSR-compliant transitive deps").
  • Phase 3: Pair with dependency update tools (e.g., composer outdated) to auto-fix issues.

• Use Cases:

  • Open-Source Projects: Enforce explicit dependencies for maintainability (e.g., Laravel, Symfony).
  • Enterprise PHP: Audit legacy codebases with opaque dependency trees (e.g., Magento, custom CMS).
  • Security Teams: Identify unintended exposure to vulnerable transitive deps (e.g., guzzlehttp/guzzle via thatvendor/api-lib).

When to Consider This Package

Adopt If:

• Your project uses Composer and has >50 dependencies (higher risk of transitive issues).
• You need to audit PHP codebases for hidden dependencies (e.g., during acquisitions or migrations).
• Your team lacks static analysis expertise but wants to enforce dependency hygiene.
• You’re upgrading PHP versions or major Composer packages (e.g., Laravel 10 → 11) and fear breakage.
• CI/CD budget allows for a lightweight static analysis step (~1–5 mins per run).

Look Elsewhere If:

• Your project uses non-PHP languages (e.g., Node.js, Python).
• You need runtime dependency validation (use composer validate or phpstan instead).
• Your build environment lacks PHP CLI (e.g., serverless functions).
• You require fine-grained control over false positives (consider custom static analyzers like Psalm or PHPStan).
• Your dependency graph is trivial (<20 packages with no transitive complexity).

Alternatives to Evaluate:

How to Pitch It (Stakeholders)

For Executives/Non-Technical Stakeholders:

*"This tool is like a dependency X-ray for our PHP projects. Right now, we might unknowingly rely on libraries that aren’t explicitly listed in our codebase—like using a tool from your car because it’s already in the garage, but not paying for it. If the garage owner (Composer) changes the tool’s location or version, our code breaks unexpectedly.

ComposerRequireChecker scans our code to flag these ‘hidden’ dependencies, forcing us to explicitly declare what we use. This:

• Reduces risk from undocumented library updates (e.g., API failures after a Composer upgrade).
• Saves time by catching issues early (e.g., during PR reviews or CI checks).
• Improves security by eliminating ‘accidental’ exposure to vulnerable transitive deps.

Cost: Free (MIT license), runs in CI (~1–5 mins), and pays for itself by preventing post-release fires. Ask: Should we pilot this in [High-Risk Project X] to audit dependencies before the next major release?"*

For Engineers/Architects:

*"Problem: Transitive dependencies (e.g., guzzlehttp/guzzle pulled in by thatvendor/api-lib) are a ticking time bomb. When upstream packages update, your code may break silently—only discovered in QA or production.

Solution: ComposerRequireChecker is a CLI tool that:

• Static analyzes your PHP code to detect symbols (classes/functions) used from non-explicit dependencies.
• Flags ‘soft’ dependencies (e.g., use GuzzleHttp\Psr7\Stream; when guzzlehttp/psr7 isn’t in require).
• Checks PHP extensions (e.g., openssl functions without ext-openssl in require).

Why Now?

• Prevents ‘works on my machine’ issues from transitive updates.
• Integrates with CI (e.g., GitHub Actions) to block bad PRs early.
• Lightweight: No runtime overhead; runs in ~1–5 mins for large codebases.

Implementation:

1. Add to CI (e.g., php composer-require-checker.phar check composer.json).
2. Configure whitelists for false positives (e.g., vendor/bin/ scripts).
3. Treat warnings as blocking until resolved.

Trade-offs:

• False positives: Rare, but configurable (see config.dist.json).
• No runtime checks: Pairs well with composer validate and phpstan.

Next Steps:

• Run against [Project Y] to validate ROI.
• Propose adding to pre-commit hooks for developer feedback.
• Explore auto-fixing via composer require (future work)."*