Getting Started

Minimal Steps

Installation:

composer require craftcms/server-check

Add the service provider to config/app.php:

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

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).
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

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

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.';
    }
}

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

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)
    }
}

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

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.
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.
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

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>';
}

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';
}

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,
],
```

Server Check Laravel Package