Requirements Checker Laravel Package

Technical Evaluation

Architecture Fit

• Symfony-Specific Dependency: The package is tightly coupled with Symfony’s runtime requirements (PHP version, extensions, OS-level dependencies). If the product is Symfony-based, this is a direct fit for pre-deployment validation. For non-Symfony Laravel projects, the utility is indirect—useful for enforcing PHP/extension standards but requiring customization (e.g., mapping Symfony’s requirements to Laravel’s).
• Modularity: The package’s design (standalone CLI tool + library) allows integration as either:
  • A pre-commit hook (via symfony/requirements-checker:check).
  • A custom Laravel command (wrapping the library’s logic).
• Extensibility: Supports custom requirement definitions (via YAML/JSON), enabling adaptation for Laravel-specific needs (e.g., pdo_mysql, gd, or laravel-specific extensions).

Integration Feasibility

• Low-Coupling Risk: The package is dependency-agnostic (no Symfony framework required at runtime). Integration via:
  • Composer: require symfony/requirements-checker (no Laravel-specific hooks needed).
  • Artisan Command: ~50 LoC to wrap the checker in a Laravel command (e.g., php artisan check:requirements).
• CI/CD Plugins: Can be embedded in GitHub Actions/GitLab CI via symfony/requirements-checker:check (e.g., fail builds on missing intl or mbstring).
• Legacy Systems: Works with PHP 7.4+; Laravel 8+ projects will have no issues. Older Laravel versions (e.g., 5.x) may need PHP version polyfills.

Technical Risk

• False Positives/Negatives:
  • Symfony’s default requirements (e.g., apcu) may not apply to Laravel. Risk mitigated by custom requirement files.
  • OS-level checks (e.g., systemd) are Symfony-specific; irrelevant for Laravel but harmless if ignored.
• Performance Overhead:
  • Minimal at runtime (checks are idempotent). CLI mode adds ~100ms–1s for full scans.
• Maintenance Burden:
  • Symfony updates may introduce breaking changes (e.g., new PHP version requirements). Monitor via Symfony’s deprecations.

Key Questions

1. Scope of Requirements:
   • Should this enforce only PHP/extensions (lightweight) or full Symfony-like checks (heavier, less relevant)?
2. Customization Needs:
   • Are there Laravel-specific dependencies (e.g., redis, pgsql) to add to the requirement set?
3. CI/CD vs. Local Dev:
   • Should this run in pre-commit (fast feedback) or CI (gatekeeping)?
4. Output Format:
   • CLI-only or integrate with Laravel’s logging (e.g., Log::error() for failures)?
5. Long-Term Sync:
   • Will Symfony’s requirements evolve to conflict with Laravel’s? (E.g., dropping PHP 8.0 support.)

Integration Approach

Stack Fit

• PHP/Laravel Native: Zero framework conflicts; works with any Composer-based PHP project.
• Tooling Synergy:
  • Composer Scripts: Add to composer.json:

    "scripts": {
      "check-requirements": "symfony/requirements-checker:check"
    }
    

  • Artisan Integration: Create a custom command (see below).
  • CI/CD: Native support in GitHub Actions:

    - name: Check PHP requirements
      run: vendor/bin/requirements-checker check
    

• Alternative Stacks:
  • Symfony Projects: Use out-of-the-box.
  • Non-PHP: Irrelevant.

Migration Path

1. Phase 1: Lightweight Adoption

   • Install via Composer:

     composer require symfony/requirements-checker --dev
     

   • Add to composer.json scripts (run manually or via CI).
   • Output: Terminal-based (colorized, exit codes for CI).

2. Phase 2: Laravel Integration

   • Create a custom Artisan command (app/Console/Commands/CheckRequirements.php):

     use Symfony\Component\Process\Exception\ProcessFailedException;
     use Symfony\Component\Process\Process;
     
     class CheckRequirements extends Command {
         protected $signature = 'check:requirements';
         protected $description = 'Check PHP/Laravel requirements';
     
         public function handle() {
             $process = new Process(['vendor/bin/requirements-checker', 'check']);
             $process->run();
             if (!$process->isSuccessful()) {
                 throw new ProcessFailedException($process);
             }
             $this->info('All requirements satisfied!');
         }
     }
     

   • Register in app/Console/Kernel.php:

     protected $commands = [
         Commands\CheckRequirements::class,
     ];
     

   • Output: Leverages Laravel’s logging/console styling.

3. Phase 3: Customization

   • Define a custom requirements file (config/requirements.yml):

     php:
         version: ">=8.1"
     extensions:
         - pdo_mysql
         - gd
         - intl
     laravel:
         - "pdo_mysql extension must be enabled for database"
     

   • Pass to the checker via CLI flag:

     vendor/bin/requirements-checker check --config=config/requirements.yml
     

Compatibility

• Laravel Versions:
  • LTS (8.x, 9.x, 10.x): Full compatibility.
  • Legacy (5.x, 6.x): May need PHP 7.4+ polyfills or custom requirement tweaks.
• PHP Versions:
  • Symfony’s checker supports PHP 7.4–8.3. Laravel 10+ requires PHP 8.1+; align requirements accordingly.
• Hosting Constraints:
  • Shared hosting (e.g., cPanel) may lack systemd or apcu; filter irrelevant checks.

Sequencing

1. Pre-Development:
   • Run during project setup to catch environment misconfigurations early.
2. CI Pipeline:
   • Execute in build phase (before tests) to fail fast.
   • Example GitHub Actions workflow:

     jobs:
       check-requirements:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v4
           - uses: shivammathur/setup-php@v2
             with:
               php-version: '8.2'
           - run: composer install
           - run: vendor/bin/requirements-checker check --config=config/requirements.yml
     

3. Local Development:
   • Add to composer.json scripts for manual invocation:

     "scripts": {
       "dev:check": "check-requirements"
     }
     

   • Run with: composer dev:check.

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor symfony/requirements-checker for breaking changes (e.g., PHP version drops).
  • Mitigation: Pin version in composer.json (e.g., ^v1.0).
• Custom Requirement Drift:
  • If Laravel-specific rules are added, maintain them in config/requirements.yml.
• Tooling Updates:
  • Laravel’s Artisan or Composer may evolve; ensure custom commands remain compatible.

Support

• Debugging:
  • Failures provide actionable output (missing extensions, PHP version).
  • Example error:

    [ERROR] The intl extension is missing. Install it or check your PHP installation.
    

  • Laravel Integration: Log failures to storage/logs/laravel.log for centralized monitoring.
• User Onboarding:
  • Document requirements in README.md or CONTRIBUTING.md (e.g., "Run composer check-requirements before contributing").

Scaling

• Performance:
  • Checks are O(1); negligible impact even in large monorepos.
  • Parallelize in CI by running alongside other checks (e.g., composer validate).
• Distributed Systems:
  • Irrelevant for runtime; only affects development environments or deployment pipelines.
• Resource Usage:
  • Memory: <10MB (minimal).
  • CPU: <5% during checks.

Failure Modes