Server Check Laravel Package

Technical Evaluation

Architecture Fit

• Pros:
  • Lightweight and focused: Designed specifically for Craft CMS server requirements, which aligns with Laravel projects integrating Craft CMS (e.g., plugins, legacy systems, or hybrid architectures).
  • Modular: Can be used as a standalone CLI tool, web UI, or embedded in Laravel’s bootstrapping process (e.g., bootstrap/app.php or a custom artisan command).
  • Extensible: The underlying RequirementsChecker class can be subclassed to add Laravel-specific checks (e.g., .env validation, Laravel extensions like laravel-debugbar).
  • Non-intrusive: Runs independently of Laravel’s core, reducing risk of conflicts.
• Cons:
  • Craft CMS-centric: Assumes Craft CMS dependencies (e.g., gd, intl, database timezone support), which may not apply to pure Laravel projects.
  • PHP-only: No native support for validating non-PHP components (e.g., Nginx, Redis, or Laravel-specific services like queues).
  • Static checks: Does not validate runtime behavior (e.g., database connectivity under load, file system permissions dynamically).

Integration Feasibility

• Laravel Stack Compatibility:
  • PHP 8.2+: Aligns with Laravel’s minimum PHP version (8.2 as of Laravel 10), but Craft CMS 4 requires PHP 8.2+, so no conflicts.
  • Composer: Can be included as a dev dependency (composer require craftcms/server-check) and integrated via Artisan commands or service providers.
  • CLI Integration: The check.sh script can be wrapped in a custom Artisan command (e.g., php artisan server:check) for seamless Laravel CLI integration.
  • Web Integration: The server/ folder can be deployed to /vendor/bin/server-check or a custom route (e.g., /server-check) for browser-based reports.
• Database Agnosticism:
  • Supports MySQL, MariaDB, and PostgreSQL, which covers Laravel’s primary database options. Custom checks for SQLite or other databases would require extension.
• Environment Variables:
  • Supports CRAFT_STRICT_SERVER_CHECK for CI/CD pipelines, which can be mapped to Laravel’s .env (e.g., STRICT_SERVER_CHECK=true).

Technical Risk

• Low Risk:
  • Mature: Actively maintained by Craft CMS (last release 2026-05-06), with a clear changelog and issue tracker.
  • Isolated: Runs independently of Laravel’s core, reducing risk of breaking changes.
  • Well-Documented: Clear usage instructions for CLI, web UI, and remote execution.
• Moderate Risk:
  • False Positives/Negatives: Database version parsing (e.g., MariaDB) or PHP extension detection (e.g., opcache.save_comments) may require tuning for edge cases.
  • Laravel-Specific Overrides: May need custom logic to handle Laravel’s .env or config/ overrides (e.g., database DSN format).
• High Risk (Mitigable):
  • Performance Overhead: Running checks in CI/CD could slow pipelines if not cached or parallelized (e.g., using Laravel’s parallel: testing).
  • Dependency Bloat: Adding a dev dependency for production-like checks may require justification for teams prioritizing minimalism.

Key Questions

1. Scope:
   • Should this validate only Craft CMS requirements or Laravel + Craft CMS combined (e.g., adding checks for Laravel’s fileinfo, mbstring, or pdo_mysql)?
2. Execution Context:
   • Should checks run pre-deployment (CI/CD), post-deployment (e.g., Laravel’s booted event), or both?
3. Output Handling:
   • Should failures block deployment (e.g., GitHub Actions ::error) or log warnings (e.g., Laravel’s Log::warning)?
4. Customization:
   • Are there Laravel-specific requirements to add (e.g., queue drivers, cache backends, or API integrations)?
5. Performance:
   • How will checks impact CI/CD speed? Should results be cached or run in parallel?
6. Maintenance:
   • Who will update the package if Craft CMS requirements change (e.g., PHP 8.3+ in future versions)?
7. Alternatives:
   • Could Laravel’s php artisan optimize or laravel-debugbar provide overlapping functionality with less overhead?

Integration Approach

Stack Fit

• Laravel Integration Points:
  1. Artisan Command:
     • Create a custom command (e.g., php artisan server:check) that wraps the check.sh script or checkit.php.
     • Example:

       // app/Console/Commands/ServerCheckCommand.php
       namespace App\Console\Commands;
       use Illuminate\Console\Command;
       class ServerCheckCommand extends Command {
           protected $signature = 'server:check {--strict : Fail on warnings}';
           public function handle() {
               $strict = $this->option('strict') ? 'CRAFT_STRICT_SERVER_CHECK=1' : '';
               $exitCode = shell_exec("{$strict} php /path/to/server-check/checkit.php");
               if ($exitCode !== 0) $this->error('Server check failed!');
           }
       }
       

  2. Service Provider:
     • Register a service provider to run checks during Laravel’s booted event (e.g., log warnings to Sentry or Slack).
  3. CI/CD Hook:
     • Add to .github/workflows/ci.yml or gitlab-ci.yml:

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

  4. Web Route:
     • Deploy server/ to /vendor/craftcms/server-check/server and add a route:

       // routes/web.php
       Route::get('/server-check', function () {
           return file_get_contents(__DIR__.'/vendor/craftcms/server-check/server/checkit.php');
       })->name('server.check');
       

• Hybrid Laravel + Craft CMS:
  • Extend RequirementsChecker to include Laravel-specific checks (e.g., laravel-debugbar, telescope, or queue drivers) by subclassing:

    use Craft\ServerCheck\RequirementsChecker;
    class LaravelRequirementsChecker extends RequirementsChecker {
        public function checkLaravelExtensions() {
            return $this->checkExtension('laravel-debugbar', 'Laravel Debugbar');
        }
    }
    

Migration Path

1. Phase 1: CLI Integration
   • Add craftcms/server-check as a dev dependency.
   • Implement a custom Artisan command for manual and CI/CD use.
   • Example:

     composer require craftcms/server-check --dev
     php artisan make:command ServerCheckCommand
     

2. Phase 2: CI/CD Enforcement
   • Add the command to CI pipelines (e.g., GitHub Actions, GitLab CI).
   • Use STRICT_SERVER_CHECK to fail builds on warnings.
3. Phase 3: Web UI (Optional)
   • Deploy the server/ folder to a non-public route for manual validation.
4. Phase 4: Laravel Bootstrapping (Advanced)
   • Integrate checks into Laravel’s booted event to log warnings (e.g., via Sentry or Slack).

Compatibility

• Laravel Versions:
  • Compatible with Laravel 8+ (PHP 8.2+) due to Craft CMS 4’s PHP requirement.
  • For Laravel 7 (PHP 7.4+), use craftcms/server-check:2.x.
• Hosting Environments:
  • Works on shared hosting (e.g., cPanel) if PHP CLI is available.
  • For headless environments (e.g., Laravel Vapor), use the CLI or Docker integration.
• Database Systems:
  • Supports MySQL 8.0.17+, MariaDB 10.4.6+, PostgreSQL 13.0+ (aligns with Laravel’s supported databases).

Sequencing

1. Pre-requisite:
   • Ensure PHP 8.2+ is installed (Laravel 10+ requirement).
2. Installation:
   • Add to composer.json:

     "require-dev": {
         "craftcms/server-check": "^5.0"
     }
     

3. Configuration:
   • Set CRAFT_STRICT_SERVER_CHECK in .env for CI/CD:

     STRICT_SERVER_CHECK=true
     

4. Execution:
   • Run manually: php artisan server:check --strict
   • Run in CI: Add to workflow as a step before deployment.
5. Monitoring:
   • Log failures to error tracking (e.g., Sentry, Datadog).