Eloquent API-resources - Knowledge of Laravel

Wat zijn API-resources?

Wanneer je een API bouwt en Eloquent-modellen rechtstreeks als JSON teruggeeft, kunnen kolommen die je wilt verbergen uitlekken of stuur je grote hoeveelheden data die de client niet nodig heeft. Eloquent API-resources vormen een transformatielaag tussen je modellen en de JSON-response. In de toArray()-methode definieer je expliciet “wat er in welk formaat in de response komt”. De belangrijkste voordelen zijn:

Volledige controle over welke velden in de response komen
Naamsconversies en waardebewerkingen van velden op één plek gebundeld
Velden voorwaardelijk tonen of verbergen
Relaties nesten met behoud van een consistente structuur

Resources maken

Genereer een resourceklasse met het Artisan-commando make:resource.

php artisan make:resource UserResource

De gegenereerde klasse wordt geplaatst in de map 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,
        ];
    }
}

Met $this heb je rechtstreeks toegang tot de properties van het model. Dat komt doordat de resourceklasse intern de toegang tot het model proxyt.

Gebruik in een controller

Je kunt de gedefinieerde resource teruggeven vanuit een controller of route.

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

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

Of je gebruikt de toResource()-methode van het model.

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

toResource() zoekt automatisch de bijbehorende resourceklasse (UserResource) op basis van de modelnaam. Standaard wordt de response gewrapt in een data-sleutel.

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

Resource-collecties

Wil je meerdere modellen teruggeven, gebruik dan de collection()-methode.

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

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

Of gebruik toResourceCollection() van een Eloquent-collectie.

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

Eigen collectieresources

Wil je metadata toevoegen aan de hele collectie, maak dan een speciale collectieresource.

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());
});

Velden bewerken en transformeren

Binnen toArray() kun je veldnamen wijzigen en waarden bewerken.

public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'full_name' => $this->name,                         // Veldnaam wijzigen
        'email_address' => $this->email,                    // Veldnaam wijzigen
        'role' => strtoupper($this->role),                  // Waarde bewerken
        'registered_at' => $this->created_at->toDateString(), // Datum formatteren
    ];
}

Voorwaardelijke velden

when() — velden toevoegen afhankelijk van een voorwaarde

Wil je een veld alleen opnemen als aan een bepaalde voorwaarde wordt voldaan, gebruik dan when().

public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        // Alleen opnemen als de geauthenticeerde gebruiker beheerder is
        'secret_token' => $this->when(
            $request->user()?->isAdmin(),
            $this->secret_token
        ),
    ];
}

Als de voorwaarde van when() false is, wordt de sleutel zelf uit de response verwijderd.

mergeWhen() — meerdere velden gebundeld voorwaardelijk toevoegen

Om meerdere velden onder dezelfde voorwaarde samen te tonen of te verbergen, gebruik je 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() — alleen geladen relaties opnemen

Door een relatie alleen op te nemen wanneer die eager geladen is, kun je flexibele responses maken en tegelijk het N+1-probleem voorkomen.

use App\Http\Resources\PostResource;

public function toArray(Request $request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        // Alleen opnemen als posts met with() zijn geladen
        'posts' => PostResource::collection($this->whenLoaded('posts')),
    ];
}

Aan de controllerkant bepaal je of de relatie geladen wordt.

// Teruggeven inclusief posts
return new UserResource($user->load('posts'));

// Teruggeven zonder posts
return new UserResource($user);

whenCounted() — tellingen voorwaardelijk opnemen

Neemt de met loadCount() opgehaalde telling van een relatie voorwaardelijk op.

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

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

Geneste resources

Door relaties te nesten met een andere resourceklasse behoud je een consistente structuur.

// 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-resources in Laravel",
    "author": {
      "id": 5,
      "name": "Yamada Taro",
      "email": "[email protected]"
    },
    "comments": [
      { "id": 10, "body": "Erg nuttig!" }
    ]
  }
}

Metadata toevoegen

with() — metadata op het topniveau

Om metadata toe te voegen aan de hele collectie, override je de with()-methode.

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(),
            ],
        ];
    }
}

Voorbeeldresponse:

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

additional() — dynamisch metadata toevoegen

Wil je aan de controllerkant dynamisch metadata toevoegen, gebruik dan additional().

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

Combineren met paginering

Door een pagineringsresultaat aan een resource door te geven, worden meta en links automatisch toegevoegd.

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

Of:

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

Voorbeeldresponse:

{
  "data": [
    { "id": 1, "name": "Yamada Taro" },
    { "id": 2, "name": "Suzuki Hanako" }
  ],
  "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
  }
}

Bij pagineringsresponses wordt de data-sleutel altijd toegevoegd, ook als je withoutWrapping() hebt aangeroepen. Dit is om samen te kunnen bestaan met de meta- en links-sleutels van de paginering.

Datawrapping uitschakelen

Standaard wordt de buitenste resource gewrapt in een data-sleutel. Om dit uit te schakelen, roep je withoutWrapping() aan in de boot() van je AppServiceProvider.

use Illuminate\Http\Resources\Json\JsonResource;

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

withoutWrapping() heeft alleen invloed op de buitenste wrapping. Een data-sleutel die je zelf hebt gedefinieerd, wordt niet verwijderd.

Praktijkvoorbeeld: implementatie van een gebruikers-API

Aan de hand van een gebruikersbeheer-API laten we een consistent responseontwerp met resources zien.

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,
            // Alleen tonen aan beheerders
            'created_at' => $this->when(
                $request->user()?->isAdmin(),
                $this->created_at->toDateString()
            ),
            // Alleen opnemen wanneer geladen
            '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);
    }
}

​Wat zijn API-resources?

​Resources maken

​Gebruik in een controller

​Resource-collecties

​Eigen collectieresources

​Velden bewerken en transformeren

​Voorwaardelijke velden

​when() — velden toevoegen afhankelijk van een voorwaarde

​mergeWhen() — meerdere velden gebundeld voorwaardelijk toevoegen

​whenLoaded() — alleen geladen relaties opnemen

​whenCounted() — tellingen voorwaardelijk opnemen

​Geneste resources

​Metadata toevoegen

​with() — metadata op het topniveau

​additional() — dynamisch metadata toevoegen

​Combineren met paginering

​Datawrapping uitschakelen

​Praktijkvoorbeeld: implementatie van een gebruikers-API

​UserResource

​UserController

​Gerelateerde pagina’s

Introductie tot Eloquent-relaties

Paginering

Wat zijn API-resources?

Resources maken

Gebruik in een controller

Resource-collecties

Eigen collectieresources

Velden bewerken en transformeren

Voorwaardelijke velden

when() — velden toevoegen afhankelijk van een voorwaarde

mergeWhen() — meerdere velden gebundeld voorwaardelijk toevoegen

whenLoaded() — alleen geladen relaties opnemen

whenCounted() — tellingen voorwaardelijk opnemen

Geneste resources

Metadata toevoegen

with() — metadata op het topniveau

additional() — dynamisch metadata toevoegen

Combineren met paginering

Datawrapping uitschakelen

Praktijkvoorbeeld: implementatie van een gebruikers-API

UserResource

UserController

Gerelateerde pagina’s