bradietilley / laravel-rules
Fluent rules for form requests in Laravel
Requires
- illuminate/container: ^11.0
- illuminate/support: ^11.0
Requires (Dev)
- laravel/pint: ^1.0
- orchestra/testbench: ^9.0
- pestphp/pest: ^2.0
- phpstan/phpstan: ^1.8
This package is auto-updated.
Last update: 2024-10-25 07:27:27 UTC
README
Rules provides an elegant chainable object-oriented approach to defining rules for Laravel Validation.
'email' => Rule::make() ->bail() ->when( $this->method() === 'POST', Rule::make()->required(), Rule::make()->sometimes(), ) ->string() ->email() ->unique( table: User::class, column: 'email', ignore: $this->route('user')?->id, ), 'password' => rule() ->bail() ->when( $this->method() === 'POST', rule()->required(), rule()->sometimes(), ) ->string() ->password( min: 8, letters: true, numbers: true, ),
Installation
Grab it via composer
composer require bradietilley/laravel-rules
Versions
- PHP 8.1 and 8.2 @ Laravel 10 → v1.2.0
- PHP 8.2 and 8.3 @ Laravel 11 → v1.3.0
Documentation
Rules → A quick overview
use BradieTilley\Rules\Rule; return [ 'my_field' => Rule::make()->required()->string(), ];
This produces a ruleset of the following (when passed to a Validator
instance or returned from a your \Illuminate\Foundation\Http\FormRequest->rules()
method):
[ 'my_field' => [ 'required', 'string', ], ]
Rules → Available rules
Every rule you're familiar with in Laravel will work with this package. Each core rule, such as required
, string
, min
, etc, are also available using their respective methods of the same name in camelCase. Parameters for each rule (such as min 3
and max 4
) in digitsBetween:3,4
are made available as method arguments, such as: ->digitsBetween(min: 3, max: 4)
.
The ->rule()
method acts as a catch-all to support any rule you need to chuck in there, such as in the short interim after new rules are added and support is added to this package.
For example:
Rule::make() /** * You can use the methods provided */ ->required() /** * You can pass in any raw string rule as per default in Laravel */ ->rule('min:2') /** * You can pass in another Rule object which will be merged in */ ->rule(Rule::make()->max(255)) /** * You can pass in a `\Illuminate\Contracts\Validation\Rule` object * * Note: This Laravel interface is deprecated and will be dropped in future versions of Laravel. It is recommended to not use this interface. */ ->rule(new RuleThatImplementsRule()) /** * You can pass in a `\Illuminate\Contracts\Validation\InvokableRule` object * * Note: This Laravel interface is deprecated and will be dropped in future versions of Laravel. It is recommended to not use this interface. */ ->rule(new RuleThatImplementsInvokableRule()) /** * You can pass in a `\Illuminate\Contracts\Validation\ValidationRule` object */ ->rule(new RuleThatImplementsValidationRule()) /** * You can pass in any array of rules. The array values can be any of the * above rule types: strings, Rule objects, ValidationRule instances, etc */ ->rule([ Rule::make()->rule([ 'min:1', ]), 'max:25', new Unique('table', 'column'), ]);
Rules → Conditional rules
You may specify rules that are conditionally defined. For example, you may wish to make a field required
on create, and sometimes
on update. In this case you may define something like:
public function rules(): array { $create = $this->method() === 'POST'; return [ 'name' => Rule::make() ->when($create, Rule::make()->required(), Rule::make()->sometimes()) ->string(), ]; } // or just chuck in the rules as string literals if you feel that's cleaner public function rules(): array { $create = $this->method() === 'POST'; return [ 'name' => Rule::make() ->when($create, 'required', 'sometimes') ->string(), ]; }
The conditional rules that you provide (in the example above: required
and sometimes
) may be of any variable type that is supported by the ->rule()
method (as documented here).
Rules → Reusable rules
The ->with(...)
method in a rule offers you the flexibility you need to specify rule logic that can be re-used wherever you need it.
Here is an example:
/** * Example using a closure */ public function rules(): array { $integerRule = function (Rule $rule) { $rule->integer()->max(100); } return [ 'percent' => Rule::make() ->with($integerRule), ]; } /** * Example using a first class callable */ function integerRule(Rule $rule) { $rule->integer()->max(100); } public function rules(): array { return [ 'percent' => Rule::make() ->with(integerRule(...)), ]; } /** * Example using a callable invokable class */ class IntegerRule { public function __invoke(Rule $rule) { $rule->integer()->max(100); } } public function rules(): array { return [ 'percent' => Rule::make() ->with(new IntegerRule()), ]; } /** * The above examples would all return: */ [ 'percent' => [ 'integer', 'max:100', ], ]
The ->with(...)
method accepts any form of callable
, such as
- Closures (e.g.
function () { }
) - Traditional callable notations (e.g.
[$this, 'methodName']
) - First-class callables (e.g.
$this->methodName(...)
) - Invokable classes (e.g. a class with the
__invoke
magic method) - Whatever else PHP defines as
callable
.
Customisation → Macros
This package allows you to define "macros" which can serve as a fluent way to configure common rules.
For example, the following code adds an australianPhoneNumber
method to the Rule
class:
Rule::macro('australianPhoneNumber', function () { /** @var Rule $this */ return $this->rule('regex:/^\+614\d{8}$/'); }); return [ 'phone' => Rule::make() ->required() ->string() ->australianPhoneNumber(), ]; /** * The above would return: */ [ 'phone' => [ 'required', 'string', 'regex:/^\+614\d{8}$/', ], ]
The downside to using Macros is the lack of auto-completion and intellisense. Macros are not for everyone.
Customisation → Custom Rule
class
You may wish to use your own Rule
class to provide your own customisation. This can be achieved by registering your Rule class via your AppServiceProvider
or a similar place.
\BradieTilley\Rules\Rule::using(\App\Rules\CustomRule::class); // via ::make() \BradieTilley\Rules\Rule::make(); // instanceof App\Rules\CustomRule // via the helper function rule(); // instanceof App\Rules\CustomRule
This allows you to customise any aspect you wish:
public function email(string ...$flags): static { return parent::email(...$flags)->min(5)->max(255); }
CustomRule::make()->required()->email(); // result: [ 'required', 'email', 'min:5', 'max:255', ],
About → Benefits
Better syntax
Similar to chaining DB column schema definitions in migrations, this package aims to provide a clean, elegant chaining syntax.
Parameter Insights
When dealing with string-based validation rules such as decimal
, remembering what the available parameters can become a nuisance. As methods, you can get autocompletion and greater insights into the parameters available, along with a quick @link
to the validation rule documentation, to better understand how the validation rule works.
Variable Injection
Instead of concatenating variables in an awkward manner like 'min:'.getMinValue()
you can clearnly inject variables as method arguments like ->min(getMinValue())
Conditional Logic
Easily add validation rules based on conditions, using the ->when()
and ->unless()
methods, as well as by passing in conditional states into methods such as ->requiredIf($this->method() === 'POST')
.
Wide Support of Rules
Not only does it support all core-Laravel rules, but it also supports any custom rule classes that you define.
Fully Customisable
Full customisation using macros, conditional rules, reusable rules and custom rule classes
About → Performance
The performance of this packages varies as does natural PHP execution time. A single validator test that tests a string and integer with varying validity (based on min/max rules) results in a range of -20 microseconds to 20 microseconds difference, with an average of a 14 microsecond delay.
The more the package is utilised in a single request, the less relative overhead is seen. For example, running the same validation rules with 20 varying strings and integers can result in an average of 9 microseconds or even less.
The overhead here is considered negligible.
Side Feature → The ValidationRule
class
An optional, different approach to a typical implementation of the ValidationRule
interface is the BradieTilley\Rules\Validation\ValidationRule
class which hanldes the horrible signature of the Closure $fail
argument and forced void
return type inside the abstract class, allowing your rule classes to ship with cleaner syntax.
To get started, simply extend the BradieTilley\Rules\Validation\ValidationRule
class in your custom rule class. And instead of defining a validate
method, define the run
method.
So instead of this:
public function validate(string $attribute, mixed $value, Closure $fail): void { if ($this->someCondition) { return; // pass } if ($this->otherCondition) { $fail('Some error message'); return; // you can't return anything so you can't join the $fail and return lines together } }
You would have this:
public function run(string $attribute, mixed $value): static { if ($this->someCondition) { return $this->pass(); } if ($this->otherCondition) { return $this->fail('Some error message'); } return $this->pass(); }
Why
Single line failures
Because of the void
return type of the validate
method, you cannot return $fail('Some error message');
in a single line, and if you adhere to any of the common code styles out there you also have to have an empty line before a return;
statement (unless it's the first line in a body). This cleans things up a bit by allowing that clean single line return:
-$fail('Some error message') - -return; +return $this->fail('Some error message');
Readability
By enforcing a return type (static
in this case), this forces you to specify at least some form of a response rather than ambiguous empty return;
statements that get used for pass and failure results. Although you could return $this;
, it obviously encourages you to do the right thing and return a result. This improves readability by forcing you to explain the exit result:
-if ($this->someCondition) { - return; -} +if ($this->someCondition) { + return $this->pass(); +}
Failure syntax
Invoking a method is always visually cleaner than invoking a Closure
variable. This provides a cleaner syntax:
-$fail('Some error message') +$this->fail('Some error message');
Method signature
The $fail
parameter of the validate
method is messy. It's a Closure
that requires importing at the top, and if you enforce generics in your project, the $fail
parameter requires a type hint that explains any arguments and return types. Removing this type hint means the docblock is purely to say "Run the validation rule." which is superfluous and can be removed too.
-use Closure; // ... - /** - * Run the validation rule. - * - * @param \Closure(string): \Illuminate\Translation\PotentiallyTranslatedString $fail - */ - public function validate(string $attribute, mixed $value, Closure $fail): void + public function run(string $attribute, mixed $value): static { // ... }
Issues
If you spot any issues please feel free to open an Issue and/or PR and I'll address the issues.