Eloquent API Resources

Tempo de leitura: 4 minutos

Eloquent API Resources: Construir APIs RESTful eficientes e bem estruturadas é uma parte crucial do desenvolvimento web moderno. O Laravel, com seu ecossistema robusto, oferece uma solução elegante para essa tarefa através do laravel eloquent api resources. Os API Resources fornecem uma camada de transformação entre seus models Eloquent e as respostas JSON que sua API retorna. Isso permite um controle granular sobre a serialização dos seus models e seus relacionamentos, garantindo que você entregue exatamente os dados que o cliente precisa, no formato correto.

Este artigo explora em detalhes o uso de laravel eloquent api resources, desde a geração até a personalização avançada.

O que são Laravel Eloquent API Resources?

Em essência, os API Resources são classes PHP que definem o formato da resposta JSON para um ou mais models Eloquent. Eles atuam como uma camada de apresentação para seus dados, separando a lógica de negócios da lógica de apresentação da API. Isso traz diversos benefícios:

Desacoplamento: Separa a estrutura da API da estrutura do banco de dados, permitindo mudanças independentes.
Consistência: Garante um formato de resposta consistente em toda a API.
Flexibilidade: Permite formatar dados, adicionar metadados e incluir relacionamentos condicionalmente.
Legibilidade: Torna o código mais limpo e fácil de entender.

Gerando Resources

O Laravel Artisan facilita a criação de API Resources com o comando make:resource:

Bash

php artisan make:resource UserResource

Este comando criará um arquivo UserResource.php no diretório app/Http/Resources. Para gerar um resource para uma collection, use a opção --collection:

Bash

php artisan make:resource UserCollection --collection

Isso criará um arquivo UserCollection.php.

Resource Collections

As Resource Collections são usadas para formatar coleções de models. Elas estendem a classe Illuminate\Http\Resources\Json\ResourceCollection. O método toArray recebe o $request e deve retornar um array formatado.

Exemplo:

PHP

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    public function toArray($request)
    {
        return $this->collection->map(function ($user) {
            return [
                'id' => $user->id,
                'nome' => $user->name,
                'email' => $user->email,
                'data_criacao' => $user->created_at->format('d/m/Y'),
            ];
        })->toArray();
    }
}

Writing Resources

Os Resources individuais, que estendem Illuminate\Http\Resources\Json\JsonResource, são usados para formatar um único model. O método principal é o toArray, que recebe o $request e deve retornar um array associativo representando a estrutura JSON desejada.

Exemplo:

PHP

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    public function toArray($request)
    {
        return [
            'id' => $this->id,
            'nome' => $this->name,
            'email' => $this->email,
            'data_criacao' => $this->created_at->format('Y-m-d H:i:s'),
            'posts' => PostResource::collection($this->posts), // Incluindo relacionamento
            'ultimo_login' => $this->last_login ? $this->last_login->format('Y-m-d H:i:s') : null, // Exemplo de formatação condicional
        ];
    }
}

Neste exemplo, incluímos um relacionamento (posts) usando outro resource (PostResource). Também demonstramos formatação condicional usando um operador ternário para lidar com valores nulos.

Incluindo Relacionamentos:

Para incluir relacionamentos, você pode usar a sintaxe Resource::collection() para relacionamentos “um para muitos” ou simplesmente instanciar o resource para relacionamentos “um para um”:

PHP

// Um para muitos
'posts' => PostResource::collection($this->posts),

// Um para um
'profile' => new ProfileResource($this->profile),

Conditional Attributes

Você pode incluir atributos condicionalmente usando o método when:

PHP

'email' => $this->when($request->user()->isAdmin(), $this->email),

Neste exemplo, o email só será incluído na resposta se o usuário autenticado for um administrador.

Data Wrapping

Por padrão, os recursos do Laravel envolvem seus dados em um envelope de dados. Por exemplo:

JSON

{
    "data": {
        "id": 1,
        "nome": "João",
        // ...
    }
}

Você pode desativar esse comportamento definindo a propriedade $wrap como null no seu resource:

PHP

public static $wrap = null;

Metadados

Você pode adicionar metadados à resposta usando o método with no controller:

PHP

return UserResource::collection(User::paginate())->additional([
    'meta' => [
        'total_usuarios' => User::count(),
    ],
]);

Resource Responses

No seu controller, você pode retornar um resource diretamente:

PHP

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

public function show(User $user)
{
    return new UserResource($user);
}

public function index()
{
    return new UserCollection(User::paginate());
}

O Laravel automaticamente converterá o resource para uma resposta JSON.

Exemplo Completo: Listando usuários com posts e paginação

Models:

PHP

// User.php
public function posts() {
    return $this->hasMany(Post::class);
}

// Post.php
// ...

Resources:

PHP

// PostResource.php
public function toArray($request)
{
    return [
        'id' => $this->id,
        'titulo' => $this->titulo,
        'conteudo' => $this->conteudo,
    ];
}

// UserResource.php (como no exemplo anterior, incluindo posts)
// ...

Controller:

PHP

public function index()
{
    $users = User::with('posts')->paginate(10); // Carregamento adiantado para otimização
    return UserResource::collection($users);
}

Resultado JSON (exemplo):

JSON

{
    "data": [
        {
            "id": 1,
            "nome": "João",
            "email": "[email protected]",
            "data_criacao": "2024-10-27 10:00:00",
            "posts": [
                {
                    "id": 1,
                    "titulo": "Meu primeiro post",
                    "conteudo": "Conteúdo do post..."
                },
                // ...
            ]
        },
        // ...
    ],
    "links": {
        "first": "http://localhost/api/users?page=1",
        "last": "http://localhost/api/users?page=2",
        // ...
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 2,
        // ...
    }
}

Conclusão

Eloquent API Resources: Os laravel eloquent api resources são uma ferramenta poderosa para construir APIs RESTful robustas e fáceis de manter. Eles oferecem um controle granular sobre a serialização de dados, permitindo a criação de respostas JSON consistentes e personalizadas.

Ao utilizar os recursos apresentados neste artigo, você poderá otimizar o desenvolvimento das suas APIs Laravel e entregar uma melhor experiência para os seus clientes. A separação de responsabilidades proporcionada pelos Resources resulta em um código mais limpo, organizado e escalável.

Mas antes de dominar o Laravel, se for o seu caso, toda jornada tem um início. Vamos entender quais são os conhecimentos básicos necessários para aproveitar ao máximo este poderoso framework. Para iniciar seus estudos no Laravel, você precisará dominar as seguintes tecnologias: