El paquete valida el cuerpo de las peticiones de escritura antes de que lleguen a tu controlador. Esta página explica qué valida, cómo leer el documento y cómo escribir las reglas de validación con un FormRequest.
Qué se valida
El paquete valida el cuerpo de todo POST y PATCH JSON antes de que llegue a tu controlador, y de un endpoint de relación también el DELETE (el PUT solo con allow_put). Si el documento no es JSON o no tiene la forma de un documento JSON:API, responde 400 con el source. exacto del miembro que falla; un id mandado por el cliente al crear es un 403 salvo que actives allow_.
Cómo leerlo
Para leerlo, la petición tiene estos métodos (los nombres de atributos y relaciones van en snake_case):
| Método | Devuelve |
|---|---|
$request->isJsonApi() | Si el paquete trata la petición como de JSON:API |
$request->jsonApiType() / jsonApiId() | El type y el id del documento (id es null si no vino) |
$request->jsonApiAttributes() | Los atributos, con los nombres en snake_case |
$request->hasJsonApiRelationship('author') | Si el cliente mandó esa relación (aunque sea data: null) |
$request->jsonApiRelationshipId('author') | El id de una relación a uno, o null |
$request->jsonApiRelationshipIds('tags') | Los id de una relación a muchos, en orden |
Sin el nombre, jsonApiRelationshipId() y jsonApiRelationshipIds() leen el linkage del cuerpo de un endpoint de relación (mira Endpoints de relación).
Validar con un FormRequest
Agrega el trait InteractsWithJsonApi y escribe las reglas sobre los datos planos del documento: los atributos en snake_case y, para cada relación, su objeto. validated() sirve para llenar un modelo y cada error sale con su source.:
use Illuminate\Foundation\Http\FormRequest;
use MundoProgra\JsonApi\Http\Requests\InteractsWithJsonApi;
class StoreArticleRequest extends FormRequest {
use InteractsWithJsonApi;
public function authorize(): bool {
return true;
}
public function rules(): array {
return [
'title' => ['required', 'string', 'max:50'], // /data/attributes/title
'status' => ['sometimes', 'in:draft,published'], // /data/attributes/status
'author.data.id' => ['integer'], // /data/relationships/author/data/id
'tags.data.*.type' => ['in:labels'], // /data/relationships/tags/data/0/type
];
}
// El `type` que acepta este endpoint: otro es un 409. Y en PATCH/PUT, el `id` debe ser el de la URL
// (jsonApiExpectedId(), por defecto el último parámetro de la ruta).
protected function jsonApiExpectedType(): ?string {
return 'articles';
}
}Solo lo que tiene una regla llega a validated(). Un atributo del documento sin regla se ignora: no se asigna al modelo, y la respuesta es la misma que si no lo hubieras mandado. Es una protección útil si tu modelo permite asignación masiva, pero hay que acordarse de escribir una regla para cada atributo que quieras aceptar.
Un error de validación
Un valor repetido en una columna única, por ejemplo, responde así (con el idioma de la aplicación en español):
{
"jsonapi": { "version": "1.1" },
"errors": [
{
"status": "422",
"code": "mundoprogra.json-api.validation.unique",
"title": "Falló la validación",
"detail": "The email has already been taken.",
"source": { "pointer": "/data/attributes/email" }
}
]
}El detail es el mensaje de la regla de Laravel, en el idioma de tu aplicación; mira Límites conocidos. Los demás códigos de error, como el 409 por un type distinto, están en Errores.