Laravel Fluent Validation Laravel Package

Product Decisions This Supports

Build vs. Buy: Replace Manual Validation Logic

• Replace Laravel’s native string-based validation ('name|required|string|min:2') with a type-safe, IDE-autocomplete-driven alternative.
• Eliminate validation-related bugs from misplaced rules (e.g., min:5 on a string vs. integer) via static typing and method chaining.
• Centralize validation logic in Form Requests or services, reducing duplication in controllers.

Roadmap: Developer Experience (DX) Improvements

• Phase 1: Migrate critical validation logic (e.g., bulk imports, complex forms) to FluentRule for 160x faster wildcard validation (e.g., items.*.id).
• Phase 2: Enforce type safety in validation rules via PHPStan integration, catching errors early.
• Phase 3: Standardize error messages and field labels across the codebase by embedding them in rules (no separate attributes()/messages() arrays).

Use Cases

1. Bulk Operations
   • CSV/JSON imports with nested arrays (e.g., orders.*.line_items.*.price).
   • Performance gain: 62x–160x faster than Laravel’s native wildcard validation.
2. Complex Forms
   • Dynamic conditional validation (e.g., role requires permissions only if isAdmin).
   • DX gain: IDE autocompletion for when(), requiredIf(), etc.
3. API Contracts
   • Standardize validation across microservices using shared rule sets (e.g., FluentRule::email()->required()->unique('users')).
4. Legacy Migration
   • Automated refactoring via Rector to convert string rules to fluent syntax in bulk.

When to Consider This Package

Adopt If:

✅ Validation logic is complex (nested arrays, dynamic conditions, bulk operations). ✅ Team struggles with string-based validation syntax (e.g., min:5 ambiguity, unique:table,column,id order). ✅ Performance is critical for large payloads (e.g., >100 items in items.*.*). ✅ IDE support is a priority (autocompletion for ->required()->min(5)->max(255)). ✅ Type safety is desired (PHPStan integration flags unbounded each() chains).

Look Elsewhere If:

❌ Project uses Laravel <11 or PHP <8.2 (package requires these). ❌ Validation is trivial (e.g., simple forms with 3–5 fields). ❌ Team prefers string syntax for brevity (though fluent syntax is often more readable). ❌ No budget for migration (Rector automates ~80% of refactoring, but manual tweaks may be needed). ❌ Using Filament/Livewire without HasFluentValidation trait (requires workaround).

How to Pitch It (Stakeholders)

For Executives:

"Reduce validation bugs and speed up bulk operations by 160x."

• Problem: String-based validation ('name|required|string') leads to errors (e.g., wrong min: units, misplaced unique clauses) and slows down imports/bulk edits.
• Solution: FluentRule replaces strings with type-safe, IDE-autocomplete chains (e.g., FluentRule::string()->min(5)->max(255)).
• Impact:
  • Dev productivity: No more Googling min: rules or debugging unique syntax.
  • Performance: 62x–160x faster for large arrays (critical for CSV imports, admin panels).
  • Maintenance: Embed error messages/labels in rules (no separate attributes()/messages() arrays).
• Risk: Low—Rector automates 80% of migration; team can pilot on 1–2 high-impact endpoints first.

For Engineers:

"Validation that’s faster, safer, and easier to write."

• Key Benefits:
  • No more string parsing: FluentRule::email()->required()->unique('users') vs. 'email|required|email|unique:users'.
  • IDE autocompletion: See available methods (e.g., ->min() only for strings, ->afterToday() only for dates).
  • Performance: Optimized for wildcards (items.*.*)—160x faster than Laravel’s native validation.
  • Type safety: PHPStan flags unbounded each() chains; Rector migrates legacy code automatically.
  • Cleaner code: Labels/messages attached to rules (no drift between rules()/messages() arrays).
• Migration Path:
  1. Pilot: Replace 1–2 complex validation blocks (e.g., bulk import logic).
  2. Automate: Use Rector to convert string rules to fluent syntax in bulk.
  3. Enforce: Add HasFluentRules trait to new Form Requests.
• Trade-offs:
  • Slight learning curve (but no memorization—IDE guides you).
  • Requires Laravel 11+ and PHP 8.2+.

For QA/Testers:

"Fewer validation bugs in production."

• How it helps:
  • Static analysis: PHPStan catches invalid rule combinations (e.g., ->digits() on a string).
  • Clearer errors: Labels like FluentRule::string('Full Name') ensure messages use correct field names.
  • Consistency: Rules are co-located with their fields (no scattered items.*.id definitions).
• Example: Before:

  'items.*.id' => 'required|integer|exists:items,id',
  'items.*.name' => 'required|string|max:255',
  

  After:

  'items' => FluentRule::array()->each([
      'id' => FluentRule::integer()->required()->exists('items', 'id'),
      'name' => FluentRule::string()->required()->max(255),
  ]),
  

  Result: Easier to audit, less chance of missing a rule.