Version Checker Laravel Package

Technical Evaluation

Release Delta (v1.1.0 → v1.4.1)

• Reviewed baseline: v1.1.0 (2026-02-17). Prior release reviewed: v1.4.0 (2026-10-10). New release: v1.4.1 (2026-10-19).
• v1.4.1 headline — version detection source changed: fix: detect the RoadRunner version from roadrunner/roadrunner (db8a121).
  • Semver classifies this as a patch (bug fix), and it is not a breaking change to the package's public API or its Composer coordinate.
  • However, it is a functional change to the detection mechanism: the package now derives the RoadRunner version from the roadrunner/roadrunner package rather than wherever it looked before. Two things follow:
    1. The canonical RR distribution name appears to have moved to roadrunner/roadrunner — consistent with the v1.4.0 vendor consolidation. Our earlier guidance pinning spiral/roadrunner should be re-verified; it may now be the legacy coordinate.
    2. Detection that previously succeeded may now return "not detected" (or a different value) for installs where RR is not present as a Composer dependency — e.g. RR baked into a Docker base image, installed via system package, or a custom/self-built rr binary. This is a behavioral regression risk in our environment, not in the package.
  • Timing signal: shipped 9 days after v1.4.0, strongly suggesting v1.4.0 (or one of the unreviewed v1.2/v1.3 releases) carried a detection defect. Treat v1.4.0 as a weak baseline and target ^1.4.1 as the floor.
• Carried forward — package rename (v1.4.0): roadrunner-php/version-checker → roadrunner/version-checker (#29). Still a breaking change for dependency declaration (composer.json, lockfiles, CI caches, allowlists, SBOM).
  • The PHP namespace (RoadRunnerPHP\VersionChecker\...) remains unconfirmed — release notes for both v1.4.0 and v1.4.1 are silent. Still the highest-impact unknown.
  • Whether the old Packagist name is abandoned, aliased, or mirrored is still unstated. Assume frozen.
  • Note the repo URL is still roadrunner-php/version-checker while the package is roadrunner/version-checker — a persistent source of confusion in tickets and code search.
• Carried forward — documentation refresh (v1.4.0, #25): README/badges/examples updated. Use upstream README as source of truth.
• Still unreviewed: v1.2.0 and v1.3.0. The v1.4.1 fix increases the prior that a detection/API change originated there. Review before treating this assessment as authoritative.
• Net verdict: Rename-driven integration work is unchanged by v1.4.1, but the detection source change is a real operational behavior change that must be validated against our RR install topology (Composer-installed vs. image-provided) before rollout, and it raises a new dependency-hygiene question about spiral/roadrunner vs roadrunner/roadrunner.

Architecture Fit

• Purpose Alignment: Still a lightweight utility for verifying RoadRunner (RR) server versions — fits infrastructure monitoring, CI/CD pipelines, and pre-deployment checks for Laravel/PHP apps on RR. Neither release alters architectural fit.
• Non-Core Functionality: Complementary, not foundational. Fit points remain:
  • Deployment scripts (Forge, Envoyer, custom deploy.php).
  • Health checks (middleware or console command).
  • CI/CD gates (fail builds on RR version mismatch).
• RoadRunner Dependency: No RR → no value. Deprioritize otherwise.
• New consideration — detection is now Composer-graph-aware: Because v1.4.1 reads the version from roadrunner/roadrunner, the package's correctness is now coupled to how RR is installed, not merely whether it is running.
  • Composer-installed RR: clean fit; detection is deterministic and offline.
  • Image/system-installed RR: detection may fail or report unknown → the tool becomes unreliable in exactly the containerized deployments where version drift is most likely. If this describes our estate, the CLI-probe fallback (rr --version) is no longer a nice-to-have but a required wrapper.
• Naming coherence: Still a mild positive — roadrunner/* vendor alignment now looks deliberate across both the checker and RR itself.

Integration Feasibility

• Minimal Overhead (functionally near-unchanged): One composer dependency, one or two lines of code. v1.4.1 adds no configuration surface.
• Rename integration cost (unchanged from v1.4.0):
  • composer require roadrunner-php/version-checker → composer require roadrunner/version-checker in every runbook, Dockerfile, CI job, and internal template.
  • If the namespace changed, wrapper use statements break — small but build-breaking.
  • This is a lockfile swap / package migration, not a version bump. Do not run both names side by side.
• New — validate the detection path: Before trusting the checker, confirm in a throwaway branch that it resolves a version in our install shape. If RR lives in the base image rather than composer.json, expect an empty/unknown result and plan the fallback.
• New — RR dependency coordinate: Our reference config pinned spiral/roadrunner: ^2.0.0. If the ecosystem has moved to roadrunner/roadrunner, that pin is stale and could produce a mismatch where the checker inspects a package we don't actually depend on. Confirm the canonical name before finalizing composer.json.
• RoadRunner API Compatibility: Unchanged risk. Re-confirm against current RR releases given the ~8-month gap from the reviewed baseline.
• No Laravel-Specific Features: Still framework-agnostic; wrap it ourselves if we want Artisan/facade ergonomics.

Technical Risk

Key Questions

1. How is RoadRunner installed in each of our services? Composer (roadrunner/roadrunner), base image, or system package? This now determines whether v1.4.1's detection works at all.
2. Which RR Composer coordinate is canonical — roadrunner/roadrunner or spiral/roadrunner — and is our pinned spiral/roadrunner: ^2.0.0 stale?
3. Scope of the rename: Did the PHP namespace change alongside the Composer name? Is the old name abandoned, aliased, or mirrored?
4. Did v1.4.0 ship a detection regression? What exactly did v1.4.1 fix, and what did v1.2.0/v1.3.0 change?
5. Why check RR versions? Compatibility, security patching, or feature gating?
6. Where should checks run? Pre-deploy, runtime middleware, or CI?
7. What's the acceptable version range — exact, minimum, or compatibility range?
8. How to handle failures? Log and continue, throw, or alert?
9. Does this replace or supplement existing rr --version checks?

Integration Approach

Stack Fit

• Best Fit:
  • RoadRunner-powered Laravel apps where RR is a declared Composer dependency — v1.4.1's detection model is a clean fit here.
  • Multi-service architectures needing RR version consistency.
  • Self-hosted deployments (not Vapor-style managed hosting).
• Poor / conditional fit:
  • Apps not using RoadRunner (PHP-FPM).
  • Managed hosting where RR version is externally controlled.
  • Image-provided RR without a Composer entry — usable only with a CLI fallback wrapper.
• Laravel Integration Points (unchanged): Artisan command rr:check-version, service provider + facade, RRVersionMiddleware, Forge/Envoyer deploy hook.
• Wrapper design implication: Given v1.4.1, the wrapper should attempt Composer-metadata detection first, then fall back to rr --version, and expose which path was used for observability.

Migration Path

1. Assessment Phase:
   • Audit RR usage: version, install method per service, features in use; define constraints.
   • Inventory the old package name across composer.json, composer.lock, Dockerfiles, CI workflows, deploy scripts, docs, SBOM/security allowlists.
   • Confirm the namespace via the new package's autoload config and a sample class.
   • Confirm the RR coordinate (roadrunner/roadrunner vs spiral/roadrunner) and reconcile pins.
2. Proof of Concept:
   • Swap the dependency atomically: composer remove roadrunner-php/version-checker then composer require roadrunner/version-checker:^1.4.1.
   • Explicitly pin ^1.4.1 — do not land on 1.4.0.
   • Verify the wrapper compiles and returns a real version:

     use RoadRunnerPHP\VersionChecker\VersionChecker; // confirm namespace after rename
     
     $version = VersionChecker::getVersion();          // verify non-empty in our install shape
     if ($version === null && !$cliFallbackOk) {
         throw new \RuntimeException('RoadRunner version could not be detected');
     }
     if (!VersionChecker::check('>=2.0.0')) {
         throw new \RuntimeException('RoadRunner version not supported');
     }
     

   • Run this test twice: once with RR as a Composer dep, once with RR only in the image. Both must produce a defined outcome.
   • Confirm the old name is fully gone from composer.lock to avoid dual-install (duplicate classes → autoload conflicts).
3. Pilot Integration:
   • Staging with CI/CD hooks; log results without blocking while the detection source is still new.
   • Compare the checker's reported version against rr --version for a week to validate agreement.
4. Full Rollout:
   • Add to production deploy tasks; wire Slack alerting on drift.
   • Purge CI Composer caches and Docker layers — cache keys often derive from package names.
   • Add a policy/lint rule rejecting roadrunner-php/version-checker and pinning roadrunner/version-checker:^1.4.1.

Compatibility

• Package identity: Only roadrunner/version-checker in resolved dependencies; verify with composer show | grep version-checker. Assert version >= 1.4.1.
• RoadRunner dependency coordinate: Verify roadrunner/roadrunner is the package the checker inspects and that we actually depend on it; otherwise detection silently degrades.
• RR versions: Test against RR 1.x, 2.x, and prereleases. Confirm custom RR builds/forks are handled — these are the most likely v1.4.1 casualties.
• PHP versions: Confirm fit with our Laravel PHP floor (8.1+); check whether v1.2/v1.3 tightened constraints.
• Laravel versions: No direct Laravel dependency, but indirect risk where RR version gates Laravel features (e.g. newer queue workers).
• Ecosystem siblings: Ensure no collision or duplicate-version conflict between roadrunner/* and spiral/roadrunner pins in the same project.

Sequencing

1. Prerequisite: RR installed and reachable; v1.2.0/v1.3.0 changelogs reviewed; install method documented per service.
2. Dependency Order:
   • Install roadrunner/version-checker:^1.4.1 with (or after) the RR package it inspects.
   • Run checks before application boot or early in the request lifecycle.
   • Complete the name migration in a single PR per service; never run both names in one service.
3. Phased Rollout:
   • Phase 1 (rename + pin to ^1.4.1): Coordinate change only; unblocks everything else. Lowest risk.
   • Phase 1.5 (new for v1.4.1): Validate detection across install shapes and add the CLI fallback; this gates Phase 2.
   • Phase 2: Add to CI/CD (non-blocking → blocking).
   • Phase 3: Runtime checks (staging first).
   • Phase 4: Monitoring/alerting integration + lint rule blocking the old name and 1.4.0.

Operational Impact

Maintenance

• Ongoing Effort: Still low, but release cadence is clearly faster than originally assumed — v1.1 → v1.4.1 in ~8 months, and a patch 9 days after the prior minor. Expect meaningful point releases several times a year, including detection-affecting fixes. Budget for a recurring quarterly review rather than an annual one.
• Dependency Management:

  "roadrunner/version-checker": "^1.4.1",
  "roadrunner/roadrunner": "^2.0.0"   // verify canonical coordinate; replace spiral/roadrunner if confirmed
  

  • Never re-add the old name; add a Composer conflict and/or CI grep to fail builds that do.
  • Actively block 1.4.0 in lockfile audits.
• Documentation:
  • Update READMEs/runbooks to the new package name and refreshed examples (#25).
  • Document the detection semantics: "Version is read from the roadrunner/roadrunner Composer package; if RR is provided by the image, the checker returns unknown and the CLI fallback is used."
  • Record the migration date, the last release of the old name, and the reason for the ^1.4.1 floor so future audits distinguish stale-intentional from forgotten.
• Supply chain: Rename creates new SBOM entries and fresh "new dependency" scanner alerts — expect a burst of false positives at migration.

Support

• Troubleshooting:
  • Common issues:
    • RR not installed: which rr / rr --version.
    • Detection returns unknown after v1.4.1 — most likely cause on this release: RR is not a Composer dependency (image-provided or system-installed). Confirm with composer show roadrunner/roadrunner; use the CLI fallback.
    • Version reported doesn't match rr --version: the Composer package and the running binary are out of sync (image built from a different RR version than composer.json pins) — a genuine drift signal, not necessarily a bug.
    • Dual install after rename: remove old name, composer update, verify.
    • Stale class reference: clear bootstrap/cache and opcache.
    • Permission/socket errors; cached version endpoints causing false negatives.
  • Debugging: log VersionChecker::getVersion() raw output; reproduce locally with php artisan rr:check-version.
• Escalation Path:
  • Package bugs: GitHub issues at the unchanged repo URL (roadrunner-php/version-checker) despite the package rename — call this out in tickets so responders don't assume they're on the wrong project.
  • RR compatibility: roadrunner.dev.
• Support-note for v1.4.1 specifically: If detection breaks in a service, the first triage question is "how is RR installed here?" — not "did the upgrade break?" Add this to the runbook's top-level triage script.

Scaling

• Performance Impact: Negligible — and marginally better if detection is now metadata-based (no process/HTTP probe in the common case).
• Distributed Systems: Run checks once per worker, not per request; cache results if needed at high throughput.
• Fleet-wide rollout: A breadth problem — cost scales with number of repositories, CI templates, and distinct install shapes, not traffic. The v1.4.1 detection change adds a new axis to that breadth: services with image-provided RR need a fallback path even after the rename is complete.

Failure Modes