Weave Code
Laravel Hyrule Laravel Package
square/laravel-hyrule
Laravel package from Square for defining expressive, reusable rules that determine whether a user can perform an action on a model. Rules live in their own classes with a fluent API, keeping authorization logic out of controllers and policies while integrating cleanly with Laravel.
Object-oriented, composable, fluent API for writing validations in Laravel
Frequently asked questions about Laravel Hyrule
- What is square/laravel-hyrule used for in a Laravel application?
- It provides an object-oriented, composable, fluent API for writing validations in Laravel. Rules live in their own classes and bridge Square's hyrule JSON Schema validator into Laravel's Illuminate\Contracts\Validation\Rule pipeline, so you can keep authorization and validation logic out of controllers and policies. It is a thin adapter and leaf dependency, meaning it does not own persistence, queuing, or the request lifecycle.
- How do I install square/laravel-hyrule with Composer?
- Run composer require square/laravel-hyrule. The package supports Laravel auto-discovery, so no manual service provider registration is needed in a standard Laravel app. After installing, use it as an inline rule or as a custom rule object inside your rules() array.
- Which Laravel and PHP versions does laravel-hyrule 3.0 support?
- Version 3.0.0 targets Laravel 10 and PHP 8.1 or higher, which is the intended happy path. Teams still on Laravel 8 or 9 should expect to stay on 2.3.1 unless the package composer constraints say otherwise. Always check the exact laravel/framework, illuminate/*, and square/hyrule ranges in composer.json before upgrading.
- Can I use laravel-hyrule inside a FormRequest rules() method?
- Yes. The package is designed to slot into any Laravel app that already uses FormRequests or the Validator facade. You can use it as an inline rule or as a custom rule object returned from rules(). It is safe to add to an existing validation layer without touching HTTP kernels, middleware, or service providers.
- What new conditional rules does laravel-hyrule 3.0.0 add?
- The 3.0.0 release maps more JSON Schema semantics onto Laravel-style conditional validation. That includes prohibited_if and prohibited_unless, exclude_if, exclude_unless, exclude_with, and exclude_without, plus missing_if, missing_unless, and missing_with. These additions bring the adapter closer to parity with native Laravel rule behavior.
- Is upgrading laravel-hyrule from 2.3.1 to 3.0.0 a breaking change?
- Treat it as a major version bump and expect breaking changes. Per semver, 3.0.0 almost certainly raises the minimum Laravel and PHP floors, and it may drop Laravel 8 and 9 branches entirely. Upgrade the host app to Laravel 10 and PHP 8.1 first, then bump the package; if you are stuck on Laravel 9, pin to ^2.3 and defer 3.0.0.
- How do validation errors from laravel-hyrule appear in Laravel's MessageBag?
- Because the package integrates through Laravel's Rule contract, failures surface as validation messages against the attribute being validated. What is not spelled out in the package overview is whether nested JSON Schema failures are mapped to per-field keys or returned as a single blob. Write a feature test that asserts your MessageBag keys and message strings before relying on this output in API responses.
- How do I test custom hyrule rules in Laravel?
- Use feature tests that assert both pass and fail cases against known-good fixtures. Run your existing validation test suite green before bumping the package, then diff any changed validation error strings afterward. Adopt the new conditional rules incrementally, behind tests, so semantic differences between Laravel and JSON Schema behavior show up early.
- When should I use laravel-hyrule instead of native Laravel validation rules?
- Use it when you already have JSON Schemas or want reusable, composable rule classes shared across models and form requests. For simple field checks, native Laravel rules are usually enough. Compared with ad hoc custom rule registries or other JSON Schema wrappers, laravel-hyrule is a thin adapter, so it is low effort to add but you should verify it composes with sibling validation packages and API-doc generators.
- What are the maintenance and production risks of square/laravel-hyrule?
- The biggest risk is semantic drift: newly supported rules like prohibited_if, exclude_with, and missing_unless have precise Laravel semantics, and mapping them to JSON Schema keywords is non-trivial. Edge cases around empty versus missing versus null are the most likely source of subtle production bugs. Also watch square/hyrule core version pinning, since a transitive major bump would ripple through, and confirm Square's stated support and deprecation policy before standardizing on it.
Weaver
How can I help you explore Laravel packages today?