Composer Require Checker Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Tool: The package is a static analysis CLI tool designed to detect soft dependencies (transitive dependencies not explicitly declared in composer.json). It aligns well with quality assurance (QA) and dependency hygiene in PHP/Laravel projects.
• Laravel Compatibility: While Laravel itself is not a focus, the tool is agnostic to frameworks and works with any Composer-based PHP project. Laravel’s dependency structure (e.g., vendor/, autoloading) is fully compatible.
• Preventative Security: Detects unintended reliance on transitive dependencies, reducing risk of breaking changes during updates (e.g., guzzlehttp/guzzle being pulled in via another package).
• Extension Awareness: Also checks for PHP extensions (e.g., pdo_mysql) not explicitly required, which is critical for Laravel’s database/queue drivers.

Integration Feasibility

• Non-Invasive: Does not modify code or composer.json; runs as a pre-commit hook, CI job, or manual check.
• PHAR/Global Install: Can be run without project installation (via PHAR or global Composer), making it lightweight for CI/CD.
• Configurable: Supports whitelisting symbols (e.g., true, false, core PHP functions) via composer-require-checker.json.
• Custom File Scanning: Can analyze non-autoloaded files (e.g., bin/console, CLI scripts) via glob patterns.

Technical Risk

• False Positives/Negatives:
  • Risk of overly strict checks (e.g., flagging Laravel’s internal usage of Illuminate\Support\Collection if not explicitly required).
  • May miss dynamic class loading (e.g., class_alias() or eval()).
• Performance:
  • Scanning large codebases (e.g., monorepos) could be slow due to PHP’s static analysis overhead.
  • Xdebug conflicts: Tool recommends disabling Xdebug for speed.
• Custom Installer Plugins:
  • Fails to detect files installed via Composer plugins (e.g., post-install-cmd). Workaround: Run with --no-plugins.
• PHP Version Support:
  • Dropped PHP 8.2/8.3 in recent versions (supports 8.1+ as of 4.24.0). Ensure alignment with project’s PHP version.

Key Questions for TPM

1. CI/CD Integration:
   • Should this run in pre-commit (e.g., GitHub Actions) or post-merge (e.g., pre-deploy)?
   • What failure threshold (e.g., block merge if >5 soft dependencies found)?
2. Whitelisting Strategy:
   • How to handle Laravel’s internal dependencies (e.g., illuminate/, symfony/) that are transitive but safe?
   • Should core PHP functions/extensions be fully whitelisted?
3. Performance:
   • For large repos, should it run incrementally (e.g., only changed files)?
   • Can it be parallelized (e.g., via parallel-lint)?
4. Custom Workflows:
   • How to handle plugins like Laravel’s optimize or package:discover?
   • Should it integrate with Laravel’s pint or phpstan for unified QA?
5. Alerting:
   • Should it annotate PRs (e.g., GitHub/GitLab comments) or just fail CI?
   • How to triage false positives (e.g., ignore vendor/ files)?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Composer-Based: Works seamlessly with Laravel’s composer.json.
  • Dependency Hygiene: Complements tools like:
    • phpstan (static analysis)
    • pint (code formatting)
    • laravel-pint (Laravel-specific linting)
  • CI/CD: Ideal for pre-merge checks (e.g., GitHub Actions, GitLab CI).
• Non-Laravel PHP:
  • Useful for any Composer project (e.g., Symfony, custom apps).
• Tooling Stack:
  • PHAR: Preferred for portability (no global install needed).
  • Global Composer: Simpler but requires global PHP access.
  • PHIVE: For teams already using PHIVE for tooling.

Migration Path

1. Pilot Phase:
   • Run locally on a subset of projects to validate false positives/negatives.
   • Start with whitelisting known safe dependencies (e.g., Laravel’s illuminate/*).
2. CI Integration:
   • Add to composer.json scripts (e.g., check:dependencies):

     "scripts": {
       "check:dependencies": "composer-require-checker check --config-file=composer-require-checker.json"
     }
     

   • Or GitHub Actions:

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

3. Gradual Enforcement:
   • Begin as a warning (non-blocking).
   • Transition to blocking after stabilizing whitelists.

Compatibility

• Laravel-Specific:
  • Safe to Whitelist:
    • illuminate/*, symfony/*, laravel/* (if explicitly allowed).
  • Risky Areas:
    • Custom packages in vendor/ (e.g., acme/*).
    • Dynamically loaded classes (e.g., service providers).
• Configuration:
  • Start with default config, then customize:

    {
      "whitelist": {
        "namespaces": ["Illuminate\\", "Symfony\\Component\\"],
        "classes": ["true", "false", "null"]
      },
      "scan-files": ["bin/*", "routes/*"]
    }
    

• Custom Installers:
  • Use --no-plugins flag if plugins alter vendor/ structure.

Sequencing

1. Pre-Analysis:
   • Run composer install --prefer-dist to ensure consistent vendor/.
2. Tool Execution:
   • Run after composer install but before tests/deploy.
3. Post-Analysis:
   • Update composer.json to explicitly require flagged dependencies.
   • Re-run to verify fixes.

Operational Impact

Maintenance

• Configuration Drift:
  • Risk of outdated whitelists as new dependencies are added.
  • Mitigation: Document whitelisting rules in CONTRIBUTING.md.
• Tool Updates:
  • Minor updates (e.g., PHP 8.5 support) are low-risk.
  • Major updates may require re-validation of false positives.
• Dependency Bloat:
  • Explicitly requiring transitive deps (e.g., guzzlehttp/guzzle) may increase composer.json size.
  • Tradeoff: Reduces update risk vs. larger dependency graph.

Support

• Onboarding:
  • Developers must understand soft vs. hard dependencies.
  • Training: Add a README section explaining the tool’s purpose.
• Debugging:
  • False positives may require manual review of:
    • Dynamic class loading.
    • Reflection-based code (e.g., new_class()).
  • Tooling: Integrate with IDE warnings (e.g., PHPStorm annotations).
• Escalation Path:
  • Severity Levels:
    • Critical: Missing PHP extensions (e.g., pdo_mysql).
    • High: External libraries (e.g., guzzlehttp/guzzle).
    • Low: Core PHP functions (e.g., count()).

Scaling

• Performance:
  • Large Repos: Consider parallel scanning (e.g., split by directory).
  • CI Timeouts: May fail on monorepos (>10k files). Optimize with:
    • --exclude-vendor (if safe).
    • Incremental scans (e.g., only changed files).
• Distributed Teams:
  • Centralized Config: Store composer-require-checker.json in repo.
  • Local Overrides: Allow per-developer configs (e.g., ~/.composer-require-checker.json).

Failure Modes