Download the PHP package sandermuller/laravel-fluent-validation-rector without Composer

Laravel Fluent Validation Rector

Rector rules for migrating Laravel validation to sandermuller/laravel-fluent-validation. Pipe-delimited strings, array-based rules, Rule:: objects, and Livewire #[Rule] attributes all convert to FluentRule method chains.

Tested on a production codebase: 448 files converted, 3469 tests still passing.

Contents

Getting started

• Installation
• Quick start
• Rules shipped — what gets converted and what stays

Usage

• Sets — mix and match subsets of the migration pipeline
• Individual rules — when you need one specific conversion

Operation

• Formatter integration — what the rector emits and how Pint / PHP-CS-Fixer finish the job
• Diagnostics — skip log + verbosity tiers
• Parity — runtime-equivalence harness for semantics-changing rectors
• #[FluentRules] opt-in — per-method opt-in attribute

Reference

• Public API — frozen surface (symbols, wire keys, behavior)
• Auto-detected — supported shapes you don't need to configure
• Known limitations
• License

Installation

Requirements: PHP 8.3+, Rector 2.4+, sandermuller/laravel-fluent-validation ^1.27.2.

If you're on an older fluent-validation:

Quick start

The ALL set runs the full migration pipeline (converters + grouping + trait insertion) on every file under app/. For most codebases that's enough; the output is ready to commit after Pint runs. If you want finer control, pick subsets via individual rules.

Rules shipped

Grouped by the set that includes them. FluentValidationSetList::ALL runs everything in Converters + Grouping + Traits; SIMPLIFY is a separate post-migration cleanup set you opt into after verifying the initial conversion.

Converters (set CONVERT)

ValidationStringToFluentRuleRector

Converts pipe-delimited rule strings ('required|string|max:255') to fluent chains.

• Where it fires: FormRequest rules(), $request->validate(), Validator::make(), plus RuleSet::from([...]) wrappers anywhere in PHP source (FormRequest rules(): RuleSet returns, action methods, services, controllers, jobs — added 1.1.0). The wrapper itself stays intact; only the inner array converts.

ValidationArrayToFluentRuleRector

Converts array-based rules (['required', 'string', Rule::unique(...)]), including Rule:: objects, Password::min() chains, conditional tuples, closures, and custom rule objects. Same surface as the string converter — FormRequest rules(), $request->validate(), Validator::make(), plus RuleSet::from([...]) wrappers anywhere in PHP source.

InlineResolvableParentRulesRector

Inlines parent::rules() when it appears as a spread at index 0 of a child rules(). Unblocks the converter rectors, which otherwise bail on spread items. Runs first in CONVERT.

ConvertLivewireRuleAttributeRector

Strips Livewire #[Rule('...')] / #[Validate('...')] property attributes and generates a rules(): array method. See config keys for KEY_OVERLAP_BEHAVIOR, MIGRATE_MESSAGES, PRESERVE_REALTIME_VALIDATION.

Grouping (set GROUP)

GroupWildcardRulesToEachRector

Folds flat wildcard and dotted keys into nested each() / children() calls. Applies to FormRequests and Livewire components alike.

Traits (set TRAITS)

AddHasFluentRulesTraitRector

Adds use HasFluentRules; to FormRequests that use FluentRule.

AddHasFluentValidationTraitRector

Adds the fluent-validation trait to Livewire components that use FluentRule. Picks the plain or Filament variant based on direct trait usage.

[!TIP] If your codebase has a shared FormRequest or Livewire base, declare use HasFluentRules; (or HasFluentValidation) on the base once and every subclass inherits it. The trait rectors walk the ancestor chain via ReflectionClass and won't re-add the trait on subclasses, so no base_classes configuration is needed.

Post-migration (set SIMPLIFY)

SIMPLIFY is opt-in, not bundled into ALL. Run it as a separate pass after you've verified the initial conversion.

PromoteFieldFactoryRector

Promotes FluentRule::field() to a typed factory (::string(), ::numeric(), etc.) when every ->rule(...) wrapper in the chain resolves to a v1-scope rule whose target method lives on exactly one typed FluentRule subclass. Unblocks SimplifyRuleWrappersRector's next pass — FluentRule::field()->rule('max:61') becomes FluentRule::string()->max(61) instead of staying on the escape hatch. Runs first in SIMPLIFY.

SimplifyFluentRuleRector

Cleans up FluentRule chains after migration: factory shortcuts (string()->url() → url()), ->label() folded into factory args, min() + max() → between(), redundant type removal.

SimplifyRuleWrappersRector

Rewrites escape-hatch ->rule(...) calls into native typed-rule methods. Runs after SimplifyFluentRuleRector so factory shortcuts apply first.

InlineMessageParamRector

Collapses ->message('...') / ->messageFor('key', '...') chain calls into the inline message: named parameter on FluentRule factories and rule methods. Requires sandermuller/laravel-fluent-validation ^1.20 (earlier floors get zero rewrites via the reflection-time surface probe).

Docblock polish (set POLISH)

POLISH is opt-in, not bundled into ALL. Run it as a separate pass after CONVERT stabilizes (multi-pass convergence requires the final shape).

UpdateRulesReturnTypeDocblockRector

Narrows the @return PHPDoc annotation on rules() methods from the wide array<string, ValidationRule|string|array<mixed>> union down to array<string, \SanderMuller\FluentValidation\Contracts\FluentRuleContract> when every value in the returned array is a FluentRule::*() call chain. Cosmetic (runtime behavior untouched), but gives PHPStan and editors a narrower type to reason about. Run as a separate pass after CONVERT stabilizes.

Opting in: #[FluentRules] attribute

#[FluentRules] is a per-method opt-in attribute (defined in sandermuller/laravel-fluent-validation) that signals "convert this method's rule array, even though my class doesn't fall under one of the auto-qualifying shapes (FormRequest / fluent-validation trait / Livewire)." It also lifts the abstract-class safety guard when applied to rules() itself, treating the attribute as the user's audit assertion that subclasses don't manipulate parent::rules() as a plain array.

Use #[FluentRules] when:

• You have a method on a non-FormRequest / non-Livewire / non-trait class that holds rules under a name other than rules() — e.g. a custom Validator subclass's rulesWithoutPrefix(). The attribute qualifies the class for processing and tells the converter to walk that specific method's body.
• You have an abstract class with rules() whose subclasses you have audited to confirm none manipulate parent::rules() with array merges. The attribute is your assertion of audit-safety; the package's safety guard for abstract classes is bypassed for the attributed rules() method.

Do NOT use #[FluentRules] on:

• Methods named after Eloquent / Laravel framework hooks (casts(), messages(), attributes(), toArray(), jsonSerialize(), etc.) — the denylist guard catches misapplied attributes, drops them silently for class-qualification AND conversion purposes, and emits a skip-log warning so you notice the mistake.
• Abstract methods whose subclasses you have NOT audited. Converting the parent silently breaks subclasses that do array_merge(parent::rules(), [...]). The attribute is per-method: applying it to a sibling helper does NOT lift the abstract-with-rules() guard for the unattributed rules() itself.

Sets

[!NOTE] Don't bundle ALL + SIMPLIFY + POLISH into a single config call. SIMPLIFY runs after manual diff review of the initial conversion; POLISH needs CONVERT's multi-pass output to stabilize. Each is a separate vendor/bin/rector process invocation against its own withSets([...]) block.

Individual rules

When you need a single conversion (a one-off migration of a specific codebase path, or running just the array-based converter on a subset of files), import and register the rule class directly:

The full rule list (any of these can be registered individually without pulling the whole set):

Configurable rules

Four rules accept configuration via withConfiguredRule().

ConvertLivewireRuleAttributeRector config

SimplifyRuleWrappersRector config

UpdateRulesReturnTypeDocblockRector config

Same two keys as SimplifyRuleWrappersRector (TREAT_AS_FLUENT_COMPATIBLE, ALLOW_CHAIN_TAIL_ON_ALLOWLISTED). Allowlisted items count as FluentRule for the narrow-@return-tag decision. Mixed arrays (allowlisted items + string/array entries) with an existing narrow FluentRuleContract tag emit a stale-narrow skip-log warning.

[!NOTE] Per-rector configuration. Each rector receives its own configuration array via withConfiguredRule(...); the values are not pooled across rectors. When the same wire key appears on both SimplifyRuleWrappersRector and UpdateRulesReturnTypeDocblockRector, pass the key on each rector that consumes it — configuring only one will leave the other running with a default-empty allowlist (silent partial config; docblocks won't narrow on your custom factories). The DTO builder section below shows the recommended shared-instance pattern.

AddHasFluentRulesTraitRector config

Typed configuration (DTO builders)

Each configurable rector has an opt-in DTO builder under SanderMuller\FluentValidationRector\Config\ that produces the same wire-key array via a ->toArray() terminal step. The builders give you compile-time type safety, IDE autocomplete, and immutable composition without changing anything on the rector side — the rector's configure(array) signature is unchanged and the array shape is identical. The constant-array form keeps working alongside the DTO form; pick whichever fits your rector.php style.

Cross-rector shared DTOs are the canonical multi-rector form. The example above shows the lockstep pattern: a single $allowlist instance feeds both SimplifyRuleWrappersRector::with(...) and UpdateRulesReturnTypeDocblockRector's DocblockNarrowOptions::with(...). Adding a class to the allowlist updates both surfaces atomically. Configuring only one of the two rectors leaves the other running with an empty allowlist — the kind of silent-partial-config that produces no error but quietly skips your custom factories on the un-configured rector's surface.

The ::with(...) named constructor is shorthand for ::default()->withAllowlistedFactories(...) — both produce identical output. Use whichever reads better at the call site; mixed-style is fine.

Same pattern for the trait-add rector's base-class allowlist:

Formatter integration

The rector emit is not formatter-clean by design. Run a formatter (Pint, PHP-CS-Fixer, or equivalent) after vendor/bin/rector process to normalize output. The recommended pipeline:

Three cosmetic seams a formatter resolves automatically. The fixer names below are from PHP-CS-Fixer; Pint ships the same set under the same names as part of its default Laravel preset.

1. Imports are inserted at prepend position (not alphabetical). The ordered_imports fixer resolves.
2. Unused imports may be left in place (e.g. a Livewire\Attributes\Rule import after the attribute is stripped). The no_unused_imports fixer resolves.
3. Generated @return docblocks emit Illuminate\Contracts\Validation\ValidationRule as a fully-qualified reference. The fully_qualified_strict_types fixer hoists it to a use statement + short-name reference.

All three are in Pint's default Laravel preset, so most Laravel consumers have them without explicit configuration. PHP-CS-Fixer users on a custom ruleset should verify the three fixers are enabled. Without any formatter you'll see rougher-than-example output, but the code is still valid PHP.

[!TIP] For the cleanest pre-formatter output, enable ->withImportNames()->withRemovingUnusedImports() in your rector.php:

[!NOTE] The rector doesn't insert line breaks between method calls. FluentRule::string()->required()->max(255) is valid PHP on a single line and keeps diffs minimal. If you prefer multi-line chains, the method_chaining_indentation fixer (Pint / PHP-CS-Fixer) reflows them after Rector runs.

Diagnostics

The skip log is opt-in. In default runs, bail-capable rules still count skips and the end-of-run summary reports the total, but no file is written to your project root:

FLUENT_VALIDATION_RECTOR_VERBOSE accepts three values (case-insensitive):

[!TIP] Rector caches per-file results. Files that hit a bail produce no transformation, so the skip entry is written once and the rule is not re-invoked on cached runs. To force every file to be revisited and every bail to be re-logged, run vendor/bin/rector process --clear-cache (or delete .cache/rector*).

[!NOTE] ConvertLivewireRuleAttributeRector verifies the generated rules(): array is syntactically correct, but it can't prove the converted rule is behaviorally equivalent to the source attribute. If a converted Livewire component has no feature test covering validation, review the diff by hand and watch for dropped message: (use MIGRATE_MESSAGES to opt in), explicit onUpdate:, or translate: false args (logged to the skip file) that need manual migration to Livewire's messages(): array hook or project config. messages: (plural, not a Livewire-documented arg) surfaces its own "unrecognized, likely typo for message:?" log entry.

Parity

A small subset of rectors changes which Laravel rule object handles validation at runtime. The functional test suite proves source→source AST shape; the parity harness under tests/Parity/ proves the resulting rule sets produce equivalent error bags when Laravel runs them. Together they cover both structural and behavioral correctness.

In-scope rectors (semantics may change):

• SimplifyRuleWrappersRector — promotes field()->rule('accepted') to typed factory chains.
• GroupWildcardRulesToEachRector — folds wildcard sibling keys into each(...).
• PromoteFieldFactoryRector — rewrites field()->required()->rule('string') to string()->required().

Pure-refactor rectors (Validation*ToFluentRule, AddHasFluent*Trait, ConvertLivewireRuleAttribute, Inline*, UpdateRulesReturnTypeDocblock, SimplifyFluentRule) ship with structural coverage only — their transformations don't change which rule class handles validation.

Authoring a fixture. Each fixture lives at tests/Parity/Fixture/<RectorName>/<case>.php and returns:

The harness runs Validator::make($payload, $rules_before) and Validator::make($payload, $rules_after), then diffs the resulting error bags. Outcomes: MATCH, BEFORE_REJECTS_AFTER_PASSES, AFTER_REJECTS_BEFORE_PASSES, BOTH_REJECT_DIFFERENT_MESSAGES, BOTH_REJECT_DIFFERENT_ORDER, or SKIPPED (DB / closure denylist).

Allowed divergences. Some transformations legitimately change behavior — e.g. boolean()->accepted() rejects 'yes' / 'on' strings that bare accepted accepts because of boolean()'s implicit type pre-check. Categorize via DivergenceCategory enum:

• ImplicitTypeConstraint — typed rule attaches an implicit constraint absent from the pre-rector form.
• MessageKeyDrift — same fail outcome, different underlying message-key path.
• AttributeLabelDrift — same fail, :attribute substitution renders differently.
• OrderDependentPipeline — same messages, different per-field order.

The category constrains the allowed runtime outcome; mismatched category fails the test. The free-text rationale lives next to the divergence so future readers see why it's acceptable.

Coverage gate. tests/Parity/CoverageTest.php asserts every in-scope rector has ≥1 fixture. New semantics-changing rectors must extend the in-scope list AND ship at least one fixture before merging.

Auto-detected (no config needed)

The converters detect rules-shaped methods by content signature — a string-keyed return [...]; whose values include a recognized rule string, Rule::*() call, FluentRule chain, or constructor-form rule object. No consumer config needed for any of these:

• Validator::validate(...) and the global validator(...) helper (when prefixed with \ or in the global namespace).
• Custom-named rules methods (editorRules(), rulesWithoutPrefix(), etc.) on classes that qualify as rules-bearing — FormRequest descendants, fluent-validation-trait users, Livewire components, #[FluentRules]-marked methods.
• Dynamic args inside non-conditional tuples — ['max', $cond ? 15 : 20], ['between', config('a'), config('b')], ['max', $this->limit ?? 10] — convert via the permissive emittable-arg path (see ValidationArrayToFluentRuleRector).
• #[Validate] attribute args: rule string, as: / attribute: label (→ ->label()), and onUpdate: false (consumed as a real-time-validation opt-out marker).

Known limitations

• Namespace-less files. Classes at the file root without a namespace are silently skipped by the grouping and trait rectors. Laravel projects always use namespaces, so this rarely comes up in practice.
• Rules built inside withValidator() callbacks. withValidator() is a post-validation hook for adding custom errors via $validator->after(...), not a rules definition. No FluentRule equivalent — imperative code stays.
• Rules built via Collection::put()->merge()->all() chains. Runtime-resolved collection pipelines aren't statically determinable. Out of scope unless a narrow shape (pure literal put() chain ending in ->all()) gathers consumer demand.
• Multi-statement helper bodies. Auto-detection requires a single-statement return [...]; shape. Helpers like private function buildRules() { $rules = [...]; return $rules; } stay untouched. Inline the return or convert by hand.
• Ternary picking the rule NAME. ['nullable', $flag ? 'email' : 'url'] (where the ternary chooses a different rule) is left alone. A ->when(cond, thenFn, elseFn) conversion is tractable in principle but wasn't worth it: three separate codebase audits turned up near-zero usage (single digits across a 100+ FormRequest corpus), and the closure-based fluent form loses the terseness users reach for ternaries to preserve. Use Rule::when(...) or branch the rules array outside the ternary instead. (Ternaries / function calls / match / nullsafe fetches as a rule's argument convert fine — see Auto-detected.)
• #[Validate(..., onUpdate: true)] / translate: false. These attribute args have no FluentRule builder equivalent and no migration path. They land in the skip log so you can move them to Livewire's hooks or project config manually. message: is opt-in: enable MIGRATE_MESSAGES to migrate string and array message: args into a generated messages(): array method alongside rules(). With MIGRATE_MESSAGES off (default), message: args also land in the skip log for manual migration.

Testing

The suite runs against Orchestra Testbench — no host Laravel app required.

Changelog

Release notes live in GitHub releases page.

Contributing

See CONTRIBUTING.md for the dev setup, test workflow, and PR conventions.

Security

Disclose vulnerabilities privately — see SECURITY.md for the GitHub Security Advisories link or PGP-accepting email.

Credits

• Sander Muller
• All contributors

License

MIT — see LICENSE.md.