laravel-validation

When to use

Use when creating FormRequests, validation rules, or custom rule objects.

Do NOT use when:

• Authorization logic only (use security skill)
• API response format (use api-design skill)

Procedure: Create a FormRequest

Step 0: Inspect

1. Check existing FormRequests — match style, naming, authorization, rule structure.
2. Check existing custom rules — reuse before creating new ones.
3. Check API error response format — match it.

Step 1: Create the class

1. Name: {Action}{Entity}Request — e.g. CreateProjectRequest.
2. Implement authorize() using Policies.
3. Implement rules() with array syntax — never pipe-separated.
4. Use prepareForValidation() only when normalization is truly necessary.

Step 2: Rules

1. Use Laravel's Illuminate\Validation\Rules classes where possible.
2. Keep rules explicit — prefer clarity over cleverness.
3. For nested arrays: validate structure AND leaf values.
4. Extract custom rule objects for complex/reusable logic.

Step 3: Test

• Test required fields, invalid formats, boundary conditions, conditional rules.
• Test authorization where relevant.
• Use focused tests per validation concern.

Conventions

→ See guideline php/validations.md for array syntax, route params, property mapping, custom rules.

Output format

1. FormRequest class with rules, messages, and authorization
2. Custom Rule object if validation logic is complex

Gotcha

• required ≠ not nullable — required means present, nullable means value can be null.
• Custom Rule objects must return $fail callback, not throw exceptions.
• Don't validate data you already trust (e.g., from a verified internal service).

Do NOT

• Do NOT validate in controllers — use FormRequest classes.
• Do NOT use $request->all() — use $request->validated().
• Do NOT put business logic in validation classes.

Verification

Confirm new rules with a concrete probe: a Pest feature test that POSTs with curl-shaped payloads through the browser/HTTP client, or a phpunit/pest run against the FormRequest. Add at least one negative case per rule (missing, wrong type, boundary). Never claim rules work without running them.

Anti-bruteforce — diagnose before retry

When a rule fires unexpectedly, do not blindly toggle required / nullable / sometimes until tests pass. Print $request->all() once, compare against the rule set, identify the root cause, then make a targeted fix.

Clarification guard — ambiguous field → ask

If a field's intent is unclear (is tags a CSV string, an array, or JSON? is email required at create or only at update?), ask the user or check the existing schema / API contract before guessing. Hidden assumptions in validation rules surface as production 422s.

Auto-trigger keywords

• validation
• Form Request
• validation rules
• custom rule