Eloquent API Resources

Eloquent API Resources: No desenvolvimento de APIs RESTful, a forma como os dados do banco de dados são apresentados aos clientes é crucial. O Laravel Eloquent API Resources fornece uma camada de transformação que atua entre seus Models Eloquent e a resposta JSON. Isso permite um controle granular, garantindo que a API retorne dados formatados e estruturados de maneira limpa e consistente.

Este artigo detalha a criação e o uso de Resources e Resource Collections para construir APIs robustas.

1. 📝 Gerando e Escrevendo Resources

Um Resource é uma classe que define o mapeamento dos atributos do Model para a estrutura JSON de saída.

A. Geração de Resources

Use o Artisan para criar um Resource Individual (para um único Model) e uma Resource Collection (para listar múltiplos Models).

Bash

# Resource Individual (para User::find(1))
php artisan make:resource UserResource

# Resource Collection (para User::all() ou User::paginate())
php artisan make:resource UserCollection --collection 

B. O Método toArray

Em um Resource Individual (UserResource), o objeto $this dentro do método toArray() representa a instância do Model sendo transformada.

PHP

// app/Http/Resources/UserResource.php

use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    public function toArray($request)
    {
        return [
            // Mapeamento Direto
            'id_usuario' => $this->id,
            'nome' => $this->name,
            
            // Formatação/Transformação
            'data_registro' => $this->created_at->format('Y-m-d H:i:s'),

            // Atributo Condicional (só inclui se $this->is_admin for verdadeiro)
            'token_admin' => $this->when($this->is_admin, 'admin-token-123'),
        ];
    }
}

2. 🔗 Relacionamentos e Collections

A. Transformando Relacionamentos

Você deve usar Resources para transformar relacionamentos. Isso garante que os dados aninhados também sigam o formato da API.

PHP

// Incluindo Posts (Has Many) dentro do UserResource
class UserResource extends JsonResource
{
    public function toArray($request)
    {
        return [
            // ... atributos de User ...
            'posts' => PostResource::collection($this->whenLoaded('posts')), // Só carrega se Eager Loaded
        ];
    }
}

Dica: Use whenLoaded('relacionamento') para garantir que o relacionamento só seja incluído se tiver sido carregado via Eager Loading (User::with('posts')). Isso evita consultas desnecessárias e ajuda a prevenir o problema N+1.

B. Resource Collections

Para listar vários usuários (com paginação, por exemplo), use o Resource Collection (UserCollection). Ele recebe a Collection/Paginator no construtor.

PHP

// app/Http/Resources/UserCollection.php
use Illuminate\Http\Resources\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    public function toArray($request)
    {
        // Chama o UserResource para transformar cada item da coleção ($this->collection)
        return $this->collection->map(function ($user) {
            return new UserResource($user);
        })->all(); 
    }
    
    // Você pode adicionar metadados aqui (ex: cabeçalhos para o total)
    public function with($request)
    {
        return [
            'status' => 'success',
        ];
    }
}

3. 🚦 Atributos e Metadados Condicionais

A. Inclusão Condicional (when)

O método when(boolean $condition, mixed $value, mixed $default = UNSET) inclui o atributo apenas se a condição for verdadeira.

PHP

// Inclui o 'salario' somente se o usuário autenticado for um manager
'salario' => $this->when($request->user()->can('view-salary'), $this->salary),

// Inclui a 'bio' se estiver carregada, ou null
'bio' => $this->whenLoaded('profile.bio', null),

B. Adicionando Metadados

Você pode adicionar metadados à resposta (além do envelope data) no seu Controller ou no Resource Collection.

PHP

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

public function index()
{
    // Adiciona o total de usuários na resposta JSON
    return UserResource::collection(User::paginate(10))
        ->additional([
            'metadados' => [
                'total_geral' => User::count(),
                'version' => '1.0.0',
            ],
        ]);
}

4. 🚀 Retornando Resources no Controller

Basta retornar a instância do Resource ou Resource Collection do seu método do Controller. O Laravel fará a serialização JSON automaticamente.

PHP

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

public function show(User $user)
{
    // Retorna um único Resource
    return new UserResource($user);
}

public function index()
{
    $users = User::with('posts')->paginate(10);
    
    // Retorna uma Collection de Resources
    return UserResource::collection($users);
}

Nota sobre Paginação: Quando você retorna uma coleção de resources a partir de um paginador (ex: User::paginate()), o Laravel automaticamente inclui os metadados de paginação (links, meta, current_page, etc.) na resposta JSON, seguindo as especificações JSON:API.

✅ Conclusão Eloquent API Resources

Eloquent API Resources: Os API Resources são cruciais para a separação de responsabilidades (dados do BD vs. apresentação da API). Eles fornecem um controle inigualável sobre a serialização JSON, permitindo que você formate dados, inclua relacionamentos de forma inteligente (via whenLoaded) e adicione atributos condicionais. O domínio dos Resources é essencial para construir APIs consistentes, seguras e altamente manuteníveis em Laravel.

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:

E se você gosta do nosso conteúdo, não deixe de contribuir adquirindo os serviços e produtos dos nossos apoiadores e empresas que somos associados: