Server Check Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require craftcms/server-check
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       CraftCMS\ServerCheck\ServerCheckServiceProvider::class,
   ],
   

2. First Use Case: Run the server check via Artisan:

   php artisan server-check
   

   This generates a report in storage/logs/server-check.log (or CLI output if run without --log).

3. Where to Look First:

   • Documentation: Craft CMS Server Requirements (official docs).
   • Source: vendor/craftcms/server-check/src/Checks/ for built-in checks (e.g., PhpVersionCheck, MemoryLimitCheck).
   • Config: config/server-check.php (auto-generated; customize thresholds/ignored checks).

Implementation Patterns

Core Workflows

1. Pre-Deployment Checks: Integrate into CI/CD pipelines (e.g., GitHub Actions) to block deployments:

   # .github/workflows/deploy.yml
   - name: Server Check
     run: php artisan server-check --fail-on-warnings
   

2. Custom Checks: Extend the base Check class to validate project-specific requirements:

   namespace App\Checks;
   
   use CraftCMS\ServerCheck\Check;
   
   class CustomExtensionCheck extends Check
   {
       public function check(): bool
       {
           return extension_loaded('redis');
       }
   
       public function getMessage(): string
       {
           return 'Redis extension is required for caching.';
       }
   }
   

   Register in config/server-check.php:

   'checks' => [
       \App\Checks\CustomExtensionCheck::class,
   ],
   

3. Dynamic Reporting: Use the ServerCheck facade to fetch results programmatically:

   use CraftCMS\ServerCheck\Facades\ServerCheck;
   
   $results = ServerCheck::run();
   foreach ($results as $result) {
       if (!$result->isPassing()) {
           // Log or notify (e.g., Slack)
       }
   }
   

4. Ignoring Checks: Temporarily disable checks in config/server-check.php:

   'ignoredChecks' => [
       \CraftCMS\ServerCheck\Checks\OpCacheCheck::class,
   ],
   

Integration Tips

• Laravel Mix: Add a script to webpack.mix.js to run checks during npm run dev:

  mix.scripts(['node_modules/craftcms/server-check/bin/server-check.js'], 'public/js/server-check.js');
  

• Cron Jobs: Schedule periodic checks via Laravel’s scheduler:

  // app/Console/Kernel.php
  $schedule->command('server-check --log --email=admin@example.com')->weekly();
  

• Admin Panel: Display results in a custom Craft CMS control panel module.

Gotchas and Tips

Pitfalls

1. False Positives:

   • OpCache: May fail on shared hosting where OPcache is enabled but misconfigured. Add to ignoredChecks if irrelevant.
   • PHP Extensions: Some checks (e.g., gd, intl) may pass locally but fail on production due to missing extensions. Test in staging first.

2. Performance:

   • Running all checks on low-memory servers (e.g., 512MB) may trigger Allowed memory exhausted. Use --skip=MemoryLimitCheck or increase memory_limit in php.ini.

3. Environment-Specific Configs:

   • Override config/server-check.php per environment (e.g., config/server-check.production.php). Use Laravel’s environment configs:

     'requiredPhpVersion' => env('SERVER_CHECK_PHP_VERSION', '8.1'),
     

Debugging

• Verbose Output: Use --verbose to see raw check logic:

  php artisan server-check --verbose
  

• Log Analysis: Check storage/logs/server-check.log for failed checks. Example entry:

  [2026-04-07 12:00:00] craftcms.server-check.ERROR: PhpVersionCheck failed: PHP 7.4 detected, but 8.1+ is required.
  

• Check Isolation: Test individual checks with --only=PhpVersionCheck.

Extension Points

1. Custom Messages: Override getMessage() in your Check class to provide actionable feedback:

   public function getMessage(): string
   {
       return 'Upgrade PHP: ' . $this->getRequiredVersion() . ' <https://craftcms.com/support/upgrade-guide>';
   }
   

2. Severity Levels: Extend the Severity enum to add custom levels (e.g., DEPRECATION):

   namespace App\Checks;
   
   use CraftCMS\ServerCheck\Severity;
   
   class CustomSeverity extends Severity
   {
       public const DEPRECATION = 'deprecation';
   }
   

3. Third-Party Integrations:

   • Slack Notifications: Hook into the server-check.failed event:

     // EventServiceProvider.php
     protected $listen = [
         \CraftCMS\ServerCheck\Events\CheckFailed::class => [
             \App\Listeners\SlackNotification::class,
         ],
     ];
     

   • Status Pages: Push results to tools like Better Uptime via API.

Config Quirks

• Auto-Generated Config: The package generates config/server-check.php on first run. Commit this file to version control to avoid surprises.
• Dynamic Thresholds: Use environment variables for dynamic values:

  'requiredMemory' => env('SERVER_CHECK_MEMORY_LIMIT', '256M'),
  

• Check Dependencies: Some checks rely on others (e.g., PhpVersionCheck must pass before OpCacheCheck). Order matters in config/server-check.php:

  'checks' => [
      \CraftCMS\ServerCheck\Checks\PhpVersionCheck::class,
      \CraftCMS\ServerCheck\Checks\OpCacheCheck::class,
  ],