Composer Require Checker Laravel Package

Getting Started

Minimal Steps

1. Installation:

   wget https://github.com/maglnet/ComposerRequireChecker/releases/latest/download/composer-require-checker.phar
   chmod +x composer-require-checker.phar
   

   or globally via Composer:

   composer global require maglnet/composer-require-checker
   

2. First Run: Navigate to your Laravel project root and execute:

   ./composer-require-checker.phar check composer.json
   

   or if globally installed:

   composer-require-checker check composer.json
   

3. Interpret Output:

   • Errors: Symbols (classes, functions, constants) used in your code but not explicitly required in composer.json.
   • Warnings: PHP extensions (e.g., curl, pdo_mysql) used but not declared in require or require-dev.

First Use Case

Prevent "Soft Dependency" Breaks:

• After updating vendor dependencies, run the checker to catch unintended reliance on transitive packages (e.g., using Guzzle indirectly via laravel/http-client).
• Example: If spatie/laravel-activitylog updates and drops support for monolog/monolog@1.x, the checker flags your code’s use of Monolog\Logger if not explicitly required.

Implementation Patterns

Workflows

1. CI/CD Integration: Add to composer.json scripts or .github/workflows/laravel.yml:

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

   Trigger on pull_request to block soft dependencies early.

2. Pre-Release Check:

   composer install --prefer-dist --no-dev
   ./composer-require-checker.phar check composer.json --format=json > checker-report.json
   

   Use --format=json to parse results programmatically (e.g., fail builds if issues exist).

3. Custom Config for Laravel: Create composer-require-checker.json to whitelist Laravel’s core symbols:

   {
     "config": {
       "whitelist": {
         "classes": ["Illuminate\\*"],
         "functions": ["app\\("],
         "constants": ["LARAVEL_START"]
       }
     }
   }
   

   Run with:

   ./composer-require-checker.phar check composer.json --config-file=composer-require-checker.json
   

Integration Tips

• Laravel Packages: Use --scan-files to include package-specific files (e.g., src/, tests/):

  ./composer-require-checker.phar check composer.json --scan-files="src/*,tests/*"
  

• Monorepos: Specify project roots explicitly:

  ./composer-require-checker.phar check packages/package-a/composer.json
  

• Custom Installers: Temporarily disable plugins for accurate scans (as noted in the docs):

  composer install --no-plugins
  ./composer-require-checker.phar check composer.json
  composer install  # Restore plugins
  

Gotchas and Tips

Pitfalls

1. False Positives:

   • Laravel Facades: Whitelist Illuminate\Support\Facades\* to avoid flags on Auth::user().
   • PHP Built-ins: The tool may warn about true, false, or null—add these to whitelist.constants.
   • Dynamic Imports: Avoid scanning files with require_once or include unless paths are static.

2. Performance:

   • Xdebug: Disable it (XDEBUG_MODE=off) to avoid timeouts or "max nesting level" errors.
   • Large Codebases: Exclude node_modules/ or vendor/ from scans (use scan-files to limit scope).

3. Custom Installers:

   • If your package uses post-install-cmd or custom installers, run composer install --no-plugins first to ensure files land in vendor/.

4. PHP Extensions:

   • The tool checks for extension usage (e.g., curl_init()). If you rely on ext-curl but it’s not in require, add:

     "config": {
       "extensions": ["curl"]
     }
     

Debugging

• Verbose Output: Use --verbose to see parsed files and symbols:

  ./composer-require-checker.phar check composer.json --verbose
  

• Dry Run: Test config changes without modifying composer.json:

  ./composer-require-checker.phar check composer.json --dry-run
  

• JSON Format: Parse results programmatically to automate fixes:

  ./composer-require-checker.phar check composer.json --format=json | jq '.violations[] | .file, .symbol'
  

Extension Points

1. Custom Rules: Extend the tool by forking and modifying src/ComposerRequireChecker/Checker/Checker.php to add project-specific logic (e.g., allow DB::* but not PDO::*).

2. CI Integration: Fail builds on warnings (not just errors) by piping output to a script:

   - name: Enforce Hard Dependencies
     run: |
       ./composer-require-checker.phar check composer.json --format=json | jq '.violations | length' > /dev/null
       if [ $(jq '.violations | length' checker-report.json) -gt 0 ]; then
         exit 1
       fi
   

3. Whitelist Management: Use a shared config file (e.g., config/composer-require-checker.json) for team-wide rules, versioned in Git.

Laravel-Specific Quirks

• Service Providers: The tool may flag App\Providers\* if not whitelisted. Add to whitelist.classes:

  "classes": ["App\\Providers\\*"]
  

• Artisan Commands: Include bin/console in scan-files if using CLI-specific logic:

  "scan-files": ["bin/console"]
  

• Package Development: For packages, ensure composer.json autoload includes all entry points (e.g., src/, config/). Example:

  "autoload": {
    "psr-4": {
      "Acme\\": "src/"
    },
    "files": ["config/acme.php"]
  }