Form Requests: validación estructurada en APIs

Por qué Form Requests

En APIs REST, los datos de entrada (JSON, formularios) deben validarse antes de usarlos. Hacerlo directamente en el controlador lleva a métodos largos y reglas repetidas. Los Form Requests permiten extraer la validación a clases dedicadas, reutilizables y fáciles de testear.

flowchart TD
  P[Petición HTTP]
  FR[Form Request reglas authorize mensajes]
  C[Método del controlador]
  E[Respuesta 422 con errores de validación]
  P --> FR
  FR -->|pasa las reglas| C
  FR -->|no pasa las reglas| E

php artisan make:request StorePostRequest
php artisan make:request UpdatePostRequest

Estructura básica

Un Form Request típico incluye rules() y opcionalmente authorize() y messages():

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StorePostRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true; // o lógica de autorización
    }

    public function rules(): array
    {
        return [
            'title' => 'required|string|max:255|unique:posts,title',
            'body' => 'required|string',
            'published_at' => 'nullable|date',
        ];
    }

    public function messages(): array
    {
        return [
            'title.required' => 'El título es obligatorio.',
            'title.unique' => 'Ya existe un post con ese título.',
        ];
    }
}

Uso en el controlador

Inyecta el Form Request en el método del controlador. Laravel ejecuta la validación automáticamente antes de invocar el método; si falla, devuelve errores (por defecto en JSON para peticiones API):

public function store(StorePostRequest $request): JsonResponse
{
    $validated = $request->validated();
    $post = Post::create($validated);
    return response()->json(new PostResource($post), 201);
}

$request->validated() devuelve solo los campos que pasaron las reglas. Los errores de validación se envían con código 422 Unprocessable Entity y estructura estándar de Laravel.

En una petición API, el cuerpo de respuesta incluye el objeto errors con los mensajes por campo, por ejemplo:

Reglas útiles para APIs

Algunas reglas frecuentes en APIs:

| Regla | Uso | |-------|-----| | required | Campo obligatorio | | string, integer, boolean | Tipo de dato | | email | Formato de correo | | unique:table,column | Valor único en tabla | | exists:table,column | Referencia a registro existente | | array | Espera un array | | array:* | Reglas para elementos del array |

Ejemplo con relación:

'title' => 'required|string|max:255',
'category_id' => 'required|exists:categories,id',
'tags' => 'array',
'tags.*' => 'exists:tags,id',