Requirements Checker Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require symfony/requirements-checker
   

   No additional configuration is needed—it’s a standalone utility.

2. First Use Case Check PHP and system requirements for Symfony in a CLI script:

   use Symfony\Component\Requirements\Checker\RequirementChecker;
   
   $checker = new RequirementChecker();
   $errors = $checker->check();
   $warnings = $checker->checkWarnings();
   
   if ($errors) {
       echo "Critical errors found:\n";
       foreach ($errors as $error) {
           echo "- $error\n";
       }
       exit(1);
   }
   
   if ($warnings) {
       echo "Warnings (non-critical):\n";
       foreach ($warnings as $warning) {
           echo "- $warning\n";
       }
   }
   

3. Where to Look First

   • RequirementChecker: Core class for checking requirements.
   • Requirement: Define custom requirements (e.g., PHP extensions, disk space).
   • RequirementInterface: Extend for custom logic.
   • Symfony Docs (if available).

Implementation Patterns

Common Workflows

1. Pre-Deployment Checks Integrate into Laravel’s artisan commands (e.g., deploy or migrate) to fail fast:

   use Symfony\Component\Requirements\Checker\RequirementChecker;
   
   class DeployCommand extends Command
   {
       protected function handle()
       {
           $checker = new RequirementChecker();
           $errors = $checker->check();
   
           if (!empty($errors)) {
               $this->error('Deployment aborted: ' . implode("\n", $errors));
               return 1;
           }
           // Proceed with deployment...
       }
   }
   

2. Custom Requirements Extend Requirement to validate Laravel-specific needs (e.g., database drivers, queue workers):

   use Symfony\Component\Requirements\Requirement\RequirementInterface;
   
   class RedisRequirement implements RequirementInterface
   {
       public function check(): bool
       {
           return extension_loaded('redis');
       }
   
       public function getMessage(): string
       {
           return 'The Redis extension is required for caching.';
       }
   }
   

   Register it with the checker:

   $checker = new RequirementChecker();
   $checker->addRequirement(new RedisRequirement());
   

3. Environment-Specific Checks Useful for CI/CD pipelines or local development:

   if (app()->environment('production')) {
       $checker->addRequirement(new DiskSpaceRequirement(1024)); // 1GB free
   }
   

4. Integration with Laravel’s Bootstrapping Add checks in bootstrap/app.php or a service provider:

   $app->booting(function () {
       $checker = new RequirementChecker();
       $errors = $checker->check();
   
       if ($errors) {
           throw new \RuntimeException('Server requirements not met: ' . implode("\n", $errors));
       }
   });
   

Gotchas and Tips

Pitfalls

1. False Positives in Shared Hosting Some hosts restrict functions like sys_getloadavg() or disk_free_space(). Handle exceptions gracefully:

   try {
       return disk_free_space('/') > 1024 * 1024 * 1024; // 1GB
   } catch (\RuntimeException $e) {
       return false; // Assume failure if unreadable
   }
   

2. Overhead in Development Avoid running checks on every request. Use middleware only for critical paths (e.g., /up health checks):

   $router->get('/up', function () {
       $checker = new RequirementChecker();
       return response()->json(['status' => empty($checker->check())]);
   });
   

3. PHP Version Mismatches The checker uses PHP_VERSION_ID. For Laravel, ensure your phpversion() in composer.json matches:

   "require": {
       "php": ">=8.1.0"
   }
   

Debugging Tips

• Log Requirements: Dump all requirements for debugging:

  $requirements = $checker->getRequirements();
  \Log::debug('All requirements:', $requirements);
  

• Skip Non-Critical Checks: Use checkWarnings() separately to avoid blocking deployments:

  $warnings = $checker->checkWarnings();
  if ($warnings) {
      \Log::warning('Non-critical issues:', $warnings);
  }
  

Extension Points

1. Custom Requirement Classes Implement RequirementInterface for:

   • Database connectivity (e.g., MySQL socket vs tcp).
   • Laravel-specific extensions (e.g., pdo_pgsql for PostgreSQL).
   • Environment variables (e.g., APP_ENV=production).

2. Composite Requirements Combine multiple checks into a single requirement:

   class LaravelRequirements implements RequirementInterface
   {
       public function check(): bool
       {
           return extension_loaded('pdo_mysql')
               && extension_loaded('mbstring')
               && !empty(getenv('APP_KEY'));
       }
   
       public function getMessage(): string
       {
           return 'Laravel requires PDO MySQL, mbstring, and APP_KEY.';
       }
   }
   

3. Local Overrides For local development, mock requirements to bypass checks:

   if (app()->environment('local')) {
       $checker->addRequirement(new MockRequirement());
   }
   

4. Performance Optimization Cache requirement checks if running in a non-development environment:

   $cacheKey = 'requirements_check_' . PHP_VERSION_ID;
   $errors = cache()->remember($cacheKey, now()->addHours(1), function () use ($checker) {
       return $checker->check();
   });