Ressources d’API et réponses JSON

Que sont les ressources API ?

Génération d’une ressource

$ php artisan make:resource UserResource
# For collections:
$ php artisan make:resource UserCollection

Ressource de base

<?php
namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            "id"         => $this->id,
            "name"       => $this->name,
            "email"      => $this->email,
            "created_at" => $this->created_at->toISOString(),
        ];
    }
}

Retour d’une ressource

<?php
public function show(User $user): UserResource
{
    return new UserResource($user);
}
// Response: {"data": {"id": 1, "name": "Alice", ...}}

Collections de ressources

<?php
public function index(): AnonymousResourceCollection
{
    return UserResource::collection(User::paginate(15));
}

Champs conditionnels

<?php
return [
    "id"    => $this->id,
    "email" => $this->when($request->user()?->isAdmin(), $this->email),
    "token" => $this->whenLoaded("tokens", $this->tokens->first()->plainTextToken),
];

whenLoaded()

<?php
return [
    "id"      => $this->id,
    "posts"   => PostResource::collection($this->whenLoaded("posts")),
    "profile" => new ProfileResource($this->whenLoaded("profile")),
];

Ressources imbriquées

<?php
return [
    "id"     => $this->id,
    "author" => new UserResource($this->author),
    "tags"   => TagResource::collection($this->tags),
];

Métadonnées supplémentaires

<?php
public function with($request): array
{
    return [
        "meta" => ["version" => "1.0"],
    ];
}

Encapsulation

<?php
// In AppServiceProvider::boot():
JsonResource::withoutWrapping();

Pagination des ressources

<?php
return UserResource::collection(User::paginate(15));
// Response includes: data[], links{}, meta{}

Vérification des ressources

<?php
$response->assertJsonStructure([
    "data" => ["id", "name", "email"]
]);

Résumé

Vérification rapide