Server Check Laravel Package

Getting Started

Minimal Steps

1. Quick CLI Check: Run in a Unix-like terminal (Linux, macOS, WSL):

   curl -Lsf https://raw.githubusercontent.com/craftcms/server-check/HEAD/check.sh | bash
   

   • Exit Code: 0 (pass), 1 (fail/warning).
   • Strict Mode: Add CRAFT_STRICT_SERVER_CHECK=1 to fail on warnings:

     CRAFT_STRICT_SERVER_CHECK=1 php server/checkit.php
     

2. Web UI Report:

   • Upload the server/ folder to your web root.
   • Access checkit.php via browser for an HTML report.

3. Remote CLI:

   • Upload server/ to any server path.
   • Run:

     php /path/to/server/checkit.php
     

First Use Case

Pre-deployment validation for a Laravel + Craft CMS hybrid project:

# Add to your CI/CD pipeline (e.g., GitHub Actions)
- name: Validate Server Requirements
  run: curl -Lsf https://raw.githubusercontent.com/craftcms/server-check/HEAD/check.sh | bash
  # Fail if warnings exist (strict mode)
  env:
    CRAFT_STRICT_SERVER_CHECK: "1"

Where to Look First

• Script Logic: check.sh (for CLI).
• PHP Version: Requirements (e.g., PHP 8.2+, GD extension).
• Changelog: 5.1.0 (GD extension now required).

Implementation Patterns

Workflows

1. CI/CD Integration:

   • GitHub Actions Example:

     jobs:
       server-check:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v4
           - name: Run Server Check
             run: |
               curl -Lsf https://raw.githubusercontent.com/craftcms/server-check/HEAD/check.sh | bash
               if [ $? -ne 0 ]; exit 1; fi
     

   • Strict Mode: Use CRAFT_STRICT_SERVER_CHECK=1 to fail on warnings.

2. Docker Build Validation:

   • Add to Dockerfile:

     RUN curl -Lsf https://raw.githubusercontent.com/craftcms/server-check/HEAD/check.sh | bash
     

   • Example: Craft CMS Docker.

3. Local Development:

   • Alias in ~/.bashrc:

     alias craft-check='curl -Lsf https://raw.githubusercontent.com/craftcms/server-check/HEAD/check.sh | bash'
     

   • Run before composer install or php artisan serve.

4. Webhook-Based Validation:

   • Deploy server/ to a subdomain (e.g., check.yourdomain.com).
   • Trigger checkit.php via API or cron for remote servers.

Laravel Integration Tips

1. Custom Artisan Command:

   • Extend the check into Laravel’s CLI:

     // app/Console/Commands/CheckServer.php
     namespace App\Console\Commands;
     use Illuminate\Console\Command;
     class CheckServer extends Command {
         protected $signature = 'craft:server-check';
         public function handle() {
             $output = shell_exec('php artisan vendor:publish --provider="craftcms/server-check"');
             $this->info($output);
         }
     }
     

   • Register in app/Console/Kernel.php:

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

2. Service Provider Hook:

   • Run checks during boot():

     // app/Providers/AppServiceProvider.php
     public function boot() {
         if (app()->environment('production')) {
             $this->validateServer();
         }
     }
     protected function validateServer() {
         $exitCode = shell_exec('php server/checkit.php');
         if ($exitCode !== 0) {
             throw new \RuntimeException('Server requirements not met!');
         }
     }
     

3. Laravel Mix/Webpack:

   • Add a pre-build script to fail if checks fail:

     // webpack.mix.js
     mix.webpackConfig({
         devServer: {
             before: (app) => {
                 return require('child_process').execSync('php server/checkit.php');
             }
         }
     });
     

4. Event Listener:

   • Trigger checks on Illuminate\Foundation\Bootstrap\LoadConfiguration:

     // app/Providers/EventServiceProvider.php
     protected $listen = [
         'Illuminate\Foundation\Bootstrap\LoadConfiguration' => [
             App\Listeners\ValidateServer::class,
         ],
     ];
     

Extension Points

1. Custom Requirements:

   • Extend RequirementsChecker (in server/RequirementsChecker.php):

     // Add to server/RequirementsChecker.php
     public function checkCustomRequirement() {
         return new RequirementResult(
             'Custom Requirement',
             'Your custom check description',
             function() {
                 return extension_loaded('your_extension');
             }
         );
     }
     

2. Database-Specific Checks:

   • Override checkDatabase() to add Laravel-specific DB validations:

     public function checkDatabase($dsn) {
         $results = parent::checkDatabase($dsn);
         // Add Laravel-specific checks (e.g., MySQL strict mode)
         $results[] = new RequirementResult(
             'MySQL Strict Mode',
             'MySQL must be in strict mode for Laravel compatibility.',
             function() use ($dsn) {
                 // Implement check logic
             }
         );
         return $results;
     }
     

3. Output Formatting:

   • Modify server/RequirementsChecker.php to integrate with Laravel’s logging:

     public function getReport() {
         $report = parent::getReport();
         \Log::info('Server Check Report', ['report' => $report]);
         return $report;
     }
     

Gotchas and Tips

Pitfalls

1. Exit Code Misinterpretation:

   • Gotcha: Exit code 1 can mean either a failure or a warning (if CRAFT_STRICT_SERVER_CHECK=1 is set).
   • Fix: Always run in strict mode for CI/CD:

     CRAFT_STRICT_SERVER_CHECK=1 php server/checkit.php
     

2. Database Connection Issues:

   • Gotcha: The check may fail if the dsn (Data Source Name) is malformed or the database is unreachable.
   • Fix: Provide a valid DSN or mock the check for local environments:

     // Mock DSN for local testing
     putenv('CRAFT_SERVER_CHECK_DSN=mysql:host=localhost;dbname=test');
     

3. PHP Configuration Overrides:

   • Gotcha: The script temporarily modifies memory_limit during checks, which might affect other processes.
   • Fix: Run checks in an isolated environment or restore settings manually:

     php -d memory_limit=-1 server/checkit.php
     

4. False Positives for opcache.save_comments:

   • Gotcha: Some PHP builds may report opcache.save_comments as disabled even if it’s enabled.
   • Fix: Verify with:

     php -i | grep opcache.save_comments
     

5. Web Root Assumptions:

   • Gotcha: The script assumes the server/ folder is in the web root. If not, database checks may fail.
   • Fix: Set the CRAFT_SERVER_CHECK_WEB_ROOT environment variable:

     CRAFT_SERVER_CHECK_WEB_ROOT=/custom/path php server/checkit.php
     

Debugging Tips

1. Verbose Output:

   • Enable debug mode by setting:

     CRAFT_SERVER_CHECK_DEBUG=1 php server/checkit.php
     

2. Dry Run:

   • Test without modifying PHP settings:

     php -d memory_limit=-1 -d opcache.enable=0 server/checkit.php
     

3. Log File:

   • Redirect output to a log file for CI/CD:

     php server/checkit.php > server-check.log 2>&1
     

4. Manual Extension Check:

   • Pre-check extensions manually:

     php -m | grep -E 'gd|intl|opcache|bcmath|json|fileinfo'
     

Configuration Quirks

1. Environment Variables:
   • Override defaults:

     Variable	Purpose	Example
     CRAFT_SERVER_CHECK_DSN	Database DSN for