Laravel Hyrule Laravel Package

Technical Evaluation

Architecture fit — square/laravel-hyrule is a thin adapter that bridges Square's hyrule JSON Schema validator into Laravel's Illuminate\Contracts\Validation\Rule pipeline. It is a leaf dependency: it does not own persistence, queuing, or request lifecycle, so it slots cleanly into any Laravel app that already uses FormRequests or the Validator facade. The 3.0.0 release expands the adapter's surface by mapping more JSON Schema semantics (prohibited_if/unless, exclude_if/unless/with/without, missing_if/unless/with) onto Laravel-style conditional validation, which brings the bridge closer to parity with native Laravel rule behavior.

Integration feasibility — Low effort. Composer install, package auto-discovery (no manual provider registration in standard Laravel), then use as an inline rule or as a custom rule object inside rules(). The 3.0.0 headline is Laravel 10 support, so adoption on Laravel 10 is the intended happy path; teams on Laravel 8/9 should expect to stay on 2.3.1 unless the composer constraints say otherwise.

Technical risk — The major version bump (2.3.1 → 3.0.0) is the primary risk signal. Per semver, 3.0.0 almost certainly raises the minimum Laravel and PHP floors (Laravel 10 implies PHP 8.1+) and may drop older Laravel branches entirely — that is a breaking change for any app still on Laravel 8/9. Secondary risk is semantic drift: the newly supported rules (prohibited_if, exclude_with, missing_unless, etc.) have precise Laravel semantics, and mapping them to JSON Schema keyword semantics is non-trivial. Divergence between "Laravel rule behavior" and "JSON Schema behavior" in edge cases (empty vs. missing vs. null) is the most likely source of subtle production bugs.

Key questions

• What are the exact composer.json constraints in 3.0.0 (PHP floor, laravel/framework and illuminate/* ranges, square/hyrule version)?
• Does 3.0.0 drop Laravel 8/9 and PHP <8.1, or only add Laravel 10 support? (Determines whether this is a forced upgrade or optional.)
• Are the new conditional rules covered by tests, and do their error messages match native Laravel output?
• Does error reporting map JSON Schema validation failures into Laravel's MessageBag with per-field keys, or a single blob?
• What is Square's stated support/deprecation policy for this package?

Integration Approach

Stack fit — Targets Laravel 10 / PHP 8.1+. Compatible with FormRequests, inline Validator::make, Rule objects, and conditional rule builders. No queue, cache, or filesystem dependencies. Safe to add to an existing validation layer without touching HTTP kernels, middleware, or service providers.

Migration path — Two-step. First, complete the host-app Laravel 10 / PHP 8.1 upgrade (this is the forcing function). Then bump square/laravel-hyrule from 2.3.1 to 3.0.0. Do not attempt to upgrade the package first — 3.0.0 will not install against Laravel 9. If the app is stuck on Laravel 9, pin to ^2.3 and treat 3.0.0 as deferred technical debt. For teams already on Laravel 10, the bump is effectively a no-op unless they opt into the new conditional rules.

Compatibility — Verify sibling validation packages (e.g. custom rule registries, laravel-jsonschema-style wrappers, API-doc generators that introspect rules) still resolve. The new conditional keywords are additive, so existing schemas continue to work unchanged. Watch for square/hyrule core version pinning — a transitive major of the underlying validator would ripple through.

Sequencing

1. Inventory all current usages of the rule (grep for the rule class / alias) and capture their JSON Schemas.
2. Upgrade Laravel to 10 and PHP to 8.1+ on a branch; run the existing test suite green before touching the package.
3. Bump square/laravel-hyrule to ^3.0 and re-run tests; diff any changed validation error strings.
4. Adopt the new conditional rules (prohibited_if, exclude_*, missing_*) incrementally, behind feature tests that assert both pass and fail cases against known-good fixtures.
5. Update developer docs / schema style guide to reflect the newly supported keywords.

Operational Impact

Maintenance — Small, focused package; low ongoing maintenance footprint if version-pinned. However, it is a Square-maintained OSS project with a small contributor base (3.0.0 introduces one first-time contributor). Cadence appears release-driven rather than scheduled — 2.3.1 to 3.0.0 spans a meaningful gap. Pin to ^3.0 and review changelogs at each minor.

Support — GitHub issues only; no commercial SLA. Acceptable for a validation helper (failure is contained to request validation), not acceptable if schemas become a hard contractual boundary with external API consumers. Mitigation: vendor the package or fork if it becomes load-bearing.

Scaling — Per-request overhead is modest but non-zero: JSON Schema validation is heavier than native Laravel rules, and schema compilation may repeat per invocation. For high-throughput endpoints with complex schemas, benchmark before rollout and consider caching compiled schema objects at the app layer. No horizontal scaling concerns — stateless.

Failure modes

• Hard: composer resolution failure after a host-app Laravel/PHP bump (constraint mismatch).
• Hard: upgrade to 3.0.0 breaks 2.x behavior silently if error messages or edge-case semantics changed without a test catching it.
• Soft: divergence between JSON Schema semantics and Laravel conditional-rule semantics for the newly added keywords (empty string vs. missing key vs. null), producing validation verdicts that differ from what a native-rule author expects.
• Soft: single-blob error output making it hard for API clients to map failures to fields.

Ramp-up — Low for Laravel developers — the rule reads like any other validation rule. The real learning curve is JSON Schema authoring (draft version, $ref usage, conditional keywords), which is a skills gap separate from the package. Budget a short internal guide and a set of canonical schema examples before teams self-serve.