Version Checker Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The roadrunner-php/version-checker package is a lightweight utility for verifying RoadRunner (RR) server versions. It aligns well with infrastructure monitoring, CI/CD pipelines, or pre-deployment checks in Laravel/PHP applications using RoadRunner as a process manager.
• Non-Core Functionality: Since version checks are not part of Laravel’s core, this package is complementary rather than foundational. It could integrate into:
  • Deployment scripts (e.g., Laravel Forge, Envoyer, or custom scripts).
  • Health checks (e.g., custom middleware or console commands).
  • CI/CD hooks (e.g., GitHub Actions, GitLab CI) to fail builds if RR version mismatches.
• RoadRunner Dependency: The package assumes RoadRunner is already in use. If the application isn’t using RoadRunner, this package provides no direct value and should be deprioritized.

Integration Feasibility

• Minimal Overhead: The package is ~100 LOC (likely) and focuses solely on version comparison (e.g., RR_VERSION >= "2.0.0"). Integration would require:
  • A single composer dependency (roadrunner-php/version-checker).
  • One or two lines of code to trigger checks (e.g., in a bootstrap/app.php hook or a custom Artisan command).
• RoadRunner API Compatibility: The package likely uses RoadRunner’s CLI or HTTP API to fetch version info. If RoadRunner’s API changes (e.g., breaking version endpoints), this could introduce technical debt.
• No Laravel-Specific Features: The package is agnostic to Laravel, meaning it won’t interact with Laravel’s service container, queues, or other frameworks. This simplifies integration but limits use cases.

Technical Risk

Key Questions

1. Why check RR versions?
   • Is this for compatibility (e.g., new Laravel features require RR 2.0+)?
   • Security (e.g., patching RR vulnerabilities)?
   • Feature gating (e.g., enabling RR-specific optimizations)?
2. Where should checks run?
   • Pre-deployment (e.g., in a deploy.php script)?
   • Runtime (e.g., middleware to block requests if RR is outdated)?
   • CI/CD (e.g., fail pipeline if RR version is unsupported)?
3. What’s the acceptable version range?
   • Should it enforce exact versions, minimum versions, or compatibility ranges?
4. How to handle failures?
   • Log and continue? Throw an exception? Trigger alerts?
5. Does this replace or supplement existing checks?
   • Are there other tools (e.g., rr get-version CLI) already handling this?

Integration Approach

Stack Fit

• Best Fit Scenarios:
  • RoadRunner-powered Laravel apps (e.g., using RR for HTTP, queues, or workers).
  • Multi-service architectures where RR version consistency is critical.
  • Self-hosted deployments (e.g., not using managed services like Laravel Vapor).
• Poor Fit Scenarios:
  • Applications not using RoadRunner (e.g., traditional PHP-FPM).
  • Projects using managed hosting where RR version is controlled externally.
• Laravel-Specific Integration Points:
  • Artisan Command: Create a php artisan rr:check-version command.
  • Service Provider: Register a VersionChecker facade for global access.
  • Middleware: Block requests if RR version is incompatible (e.g., RRVersionMiddleware).
  • Deploy Hook: Integrate with Envoyer/Forge for pre-deploy validation.

Migration Path

1. Assessment Phase:
   • Audit current RR usage (version, features in use).
   • Define version constraints (e.g., "RR 2.0+ required for Laravel 10").
2. Proof of Concept:
   • Install the package: composer require roadrunner-php/version-checker.
   • Write a minimal check in bootstrap/app.php:

     use RoadRunnerPHP\VersionChecker\VersionChecker;
     if (!VersionChecker::check('>=2.0.0')) {
         throw new \RuntimeException('RoadRunner version not supported');
     }
     

3. Pilot Integration:
   • Test in staging with CI/CD hooks (e.g., fail GitHub Actions if RR is outdated).
   • Log results but don’t block yet.
4. Full Rollout:
   • Add to production deployments (e.g., Envoyer task).
   • Integrate with monitoring (e.g., Slack alerts for version drifts).

Compatibility

• RoadRunner Versions:
  • Test against RR 1.x, 2.x, and edge cases (e.g., alpha/beta).
  • Verify if the package supports custom RR builds or forks.
• PHP Versions:
  • Ensure compatibility with Laravel’s PHP version (e.g., 8.1+).
  • Check if the package enforces PHP version constraints.
• Laravel Versions:
  • No direct Laravel dependency, but indirect risks if RR version ties to Laravel features (e.g., RR 2.0+ for Laravel 10’s new queue workers).

Sequencing

1. Prerequisite: Ensure RoadRunner is installed and accessible (e.g., rr CLI available).
2. Dependency Order:
   • Install roadrunner-php/version-checker after RoadRunner.
   • Run checks before application boot (e.g., in bootstrap/app.php) or early in the request lifecycle (middleware).
3. Phased Rollout:
   • Phase 1: Add checks to CI/CD (low risk).
   • Phase 2: Add runtime checks (higher risk; test in staging).
   • Phase 3: Integrate with monitoring/alerting.

Operational Impact

Maintenance

• Low Ongoing Effort:
  • Package is MIT-licensed and actively maintained (last release: 2026-02-17).
  • Updates likely low-frequency (e.g., annual RR version bumps).
• Dependency Management:
  • Pin exact RR version in composer.json to avoid surprises:

    "roadrunner-php/version-checker": "^1.0.0",
    "spiral/roadrunner": "^2.0.0"
    

• Documentation:
  • Add a README section explaining RR version requirements.
  • Document failure modes (e.g., "If RR is outdated, deployments will fail").

Support

• Troubleshooting:
  • Common issues:
    • RR not installed: Check which rr or rr --version.
    • Permission errors: Ensure the PHP process can access RR’s socket/CLI.
    • False negatives: Verify RR’s version endpoint isn’t cached.
  • Debugging steps:
    • Log raw RR version output: VersionChecker::getVersion().
    • Test locally with php artisan rr:check-version.
• Escalation Path:
  • For package bugs: Open an issue on GitHub.
  • For RR compatibility: Check RoadRunner’s docs.

Scaling

• Performance Impact:
  • Negligible: Version checks are synchronous but fast (HTTP/CLI call to local RR).
  • No database or external API calls; no scaling concerns.
• Distributed Systems:
  • If using multiple RR workers, checks should run once per worker (not per request).
  • Consider caching results (e.g., Redis) if checks are expensive in high-throughput environments.

Failure Modes