Eloquent API Resource

Cosa sono le API Resource

Quando costruisci un’API, restituire direttamente i modelli Eloquent come JSON può esporre colonne che vorresti nascondere o inviare al client molti dati che non gli servono. Le Eloquent API Resource sono un livello di trasformazione tra il modello e la risposta JSON. Con il metodo toArray() definisci esplicitamente “cosa e in che formato” includere nella risposta. Vantaggi principali:

Controllo totale sui campi inclusi nella risposta
Un unico posto per rinominare campi e trasformare valori
Puoi mostrare o nascondere campi in base a condizioni
Puoi annidare le relazioni mantenendo una struttura coerente

Creazione di una resource

Con il comando Artisan make:resource generi una classe resource.

php artisan make:resource UserResource

La classe generata si trova nella directory app/Http/Resources.

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

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

Con $this accedi direttamente alle proprietà del modello. La classe resource fa da proxy verso il modello.

Uso nel controller

Puoi restituire la resource da controller o route.

use App\Http\Resources\UserResource;
use App\Models\User;

Route::get('/users/{user}', function (User $user) {
    return new UserResource($user);
});

In alternativa, usa il metodo toResource() del modello.

Route::get('/users/{user}', function (User $user) {
    return $user->toResource();
});

toResource() cerca automaticamente la classe resource corrispondente (UserResource) in base al nome del modello. Di default la risposta è wrappata nella chiave data.

{
  "data": {
    "id": 1,
    "name": "Mario Rossi",
    "email": "[email protected]",
    "created_at": "2024-01-15T10:00:00.000000Z",
    "updated_at": "2024-01-15T10:00:00.000000Z"
  }
}

Resource collection

Per restituire più modelli usa il metodo collection().

use App\Http\Resources\UserResource;
use App\Models\User;

Route::get('/users', function () {
    return UserResource::collection(User::all());
});

Oppure toResourceCollection() su una collection Eloquent.

return User::all()->toResourceCollection();

Resource collection personalizzata

Per aggiungere metadati all’intera collection crea una resource collection dedicata.

php artisan make:resource UserCollection

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    public function toArray(Request $request): array
    {
        return [
            'data' => $this->collection,
            'links' => [
                'self' => route('users.index'),
            ],
        ];
    }
}

Route::get('/users', function () {
    return new UserCollection(User::all());
});

Trasformazione dei campi

In toArray() puoi rinominare i campi e trasformare i valori.

public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'full_name' => $this->name,                         // Rinomina il campo
        'email_address' => $this->email,                    // Rinomina il campo
        'role' => strtoupper($this->role),                  // Trasforma il valore
        'registered_at' => $this->created_at->toDateString(), // Formatta la data
    ];
}

Campi condizionali

when() — aggiungere campi in base a una condizione

Per includere un campo solo se una condizione è soddisfatta usa when().

public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        // Incluso solo se l'utente autenticato è admin
        'secret_token' => $this->when(
            $request->user()?->isAdmin(),
            $this->secret_token
        ),
    ];
}

Se la condizione di when() è false, la chiave stessa viene rimossa dalla risposta.

mergeWhen() — aggiungere più campi condizionalmente

Per gestire più campi con la stessa condizione usa mergeWhen().

public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        $this->mergeWhen($request->user()?->isAdmin(), [
            'admin_note' => $this->admin_note,
            'internal_id' => $this->internal_id,
        ]),
    ];
}

whenLoaded() — includere solo relazioni già caricate

Includendo la relazione solo se è già stata caricata con eager loading eviti il problema N+1 e crei risposte flessibili.

use App\Http\Resources\PostResource;

public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        // Incluso solo se posts è stato caricato con with()
        'posts' => PostResource::collection($this->whenLoaded('posts')),
    ];
}

Nel controller decidi se caricare la relazione.

// Restituisce con i posts
return new UserResource($user->load('posts'));

// Restituisce senza posts
return new UserResource($user);

whenCounted() — includere il conteggio condizionalmente

Include il conteggio di una relazione ottenuto con loadCount().

public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'posts_count' => $this->whenCounted('posts'),
    ];
}

return new UserResource($user->loadCount('posts'));

Resource annidate

Annidando una relazione con un’altra classe resource mantieni una struttura coerente.

// app/Http/Resources/PostResource.php
class PostResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'body' => $this->body,
            'author' => new UserResource($this->whenLoaded('user')),
            'comments' => CommentResource::collection($this->whenLoaded('comments')),
            'published_at' => $this->published_at?->toDateString(),
        ];
    }
}

// Controller
$post = Post::with(['user', 'comments'])->findOrFail($id);

return new PostResource($post);

{
  "data": {
    "id": 1,
    "title": "API Resource in Laravel",
    "author": {
      "id": 5,
      "name": "Mario Rossi",
      "email": "[email protected]"
    },
    "comments": [
      { "id": 10, "body": "Molto utile!" }
    ]
  }
}

Aggiungere metadati

with() — metadati top-level

Per aggiungere metadati all’intera collection sovrascrivi il metodo with().

class UserCollection extends ResourceCollection
{
    public function toArray(Request $request): array
    {
        return parent::toArray($request);
    }

    public function with(Request $request): array
    {
        return [
            'meta' => [
                'version' => '1.0',
                'generated_at' => now()->toIso8601String(),
            ],
        ];
    }
}

Esempio di risposta:

{
  "data": [...],
  "meta": {
    "version": "1.0",
    "generated_at": "2024-01-15T10:00:00+00:00"
  }
}

additional() — aggiungere metadati dinamicamente

Se vuoi aggiungere metadati dinamicamente dal controller usa additional().

return User::all()
    ->load('roles')
    ->toResourceCollection()
    ->additional(['meta' => [
        'total_admins' => User::where('role', 'admin')->count(),
    ]]);

Combinazione con la paginazione

Passando un risultato paginato alla resource, meta e links vengono aggiunti automaticamente.

Route::get('/users', function () {
    return UserResource::collection(User::paginate(15));
});

Oppure:

return User::paginate(15)->toResourceCollection();

Esempio di risposta:

{
  "data": [
    { "id": 1, "name": "Mario Rossi" },
    { "id": 2, "name": "Giulia Bianchi" }
  ],
  "links": {
    "first": "https://example.com/users?page=1",
    "last": "https://example.com/users?page=5",
    "prev": null,
    "next": "https://example.com/users?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 15,
    "to": 15,
    "total": 72
  }
}

Nelle risposte paginate, anche se hai chiamato withoutWrapping(), la chiave data viene sempre inclusa per coesistere con le chiavi meta e links della paginazione.

Disabilitare il wrapping

Di default la resource più esterna viene wrappata nella chiave data. Per disabilitarlo chiama withoutWrapping() in boot() di AppServiceProvider.

use Illuminate\Http\Resources\Json\JsonResource;

public function boot(): void
{
    JsonResource::withoutWrapping();
}

withoutWrapping() agisce solo sul wrapping più esterno. Le chiavi data che definisci tu non vengono rimosse.

Esempio pratico: implementazione di un’API utenti

Progettazione di risposte coerenti tramite resource per un’API di gestione utenti.

UserResource

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'avatar_url' => $this->avatar_url,
            'role' => $this->role,
            // Mostrato solo agli admin
            'created_at' => $this->when(
                $request->user()?->isAdmin(),
                $this->created_at->toDateString()
            ),
            // Incluso solo se caricato
            'posts' => PostResource::collection($this->whenLoaded('posts')),
            'posts_count' => $this->whenCounted('posts'),
        ];
    }
}

UserController

<?php

namespace App\Http\Controllers\Api;

use App\Http\Resources\UserResource;
use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;

class UserController extends Controller
{
    public function index(): AnonymousResourceCollection
    {
        $users = User::withCount('posts')->paginate(20);

        return UserResource::collection($users);
    }

    public function show(User $user): UserResource
    {
        $user->loadCount('posts')->load('posts');

        return new UserResource($user);
    }
}

Cosa sono le API Resource

Creazione di una resource

Uso nel controller

Resource collection

Resource collection personalizzata

Trasformazione dei campi

Campi condizionali

when() — aggiungere campi in base a una condizione

mergeWhen() — aggiungere più campi condizionalmente

whenLoaded() — includere solo relazioni già caricate

whenCounted() — includere il conteggio condizionalmente

Resource annidate

Aggiungere metadati

with() — metadati top-level

additional() — aggiungere metadati dinamicamente

Combinazione con la paginazione

Disabilitare il wrapping

Esempio pratico: implementazione di un’API utenti

UserResource

UserController

Pagine correlate

Introduzione alle relazioni Eloquent

Paginazione

​Cosa sono le API Resource

​Creazione di una resource

​Uso nel controller

​Resource collection

​Resource collection personalizzata

​Trasformazione dei campi

​Campi condizionali

​when() — aggiungere campi in base a una condizione

​mergeWhen() — aggiungere più campi condizionalmente

​whenLoaded() — includere solo relazioni già caricate

​whenCounted() — includere il conteggio condizionalmente

​Resource annidate

​Aggiungere metadati

​with() — metadati top-level

​additional() — aggiungere metadati dinamicamente

​Combinazione con la paginazione

​Disabilitare il wrapping

​Esempio pratico: implementazione di un’API utenti

​UserResource

​UserController

​Pagine correlate

Introduzione alle relazioni Eloquent

Paginazione

Cosa sono le API Resource

Creazione di una resource

Uso nel controller

Resource collection

Resource collection personalizzata

Trasformazione dei campi

Campi condizionali

when() — aggiungere campi in base a una condizione

mergeWhen() — aggiungere più campi condizionalmente

whenLoaded() — includere solo relazioni già caricate

whenCounted() — includere il conteggio condizionalmente

Resource annidate

Aggiungere metadati

with() — metadati top-level

additional() — aggiungere metadati dinamicamente

Combinazione con la paginazione

Disabilitare il wrapping

Esempio pratico: implementazione di un’API utenti

UserResource

UserController

Pagine correlate