Eloquent Serialization

Eloquent Serialization: A Serialização no Laravel Eloquent é o processo de transformar um objeto Model (ou uma Collection de Models) em um formato que pode ser facilmente transmitido (ex: JSON para APIs) ou armazenado (ex: array para cache). O Laravel Eloquent Serialization fornece métodos e propriedades para controlar precisamente quais atributos são incluídos e como eles são formatados.

Dominar essa etapa é crucial para a segurança e consistência das respostas da sua API.

1. 📝 Métodos Básicos de Serialização

O Eloquent oferece dois métodos principais para a serialização, dependendo do formato de saída desejado.

A. Exemplo de Serialização

PHP

use App\Models\User;

$user = User::with('posts')->find(1); // Carregando relacionamentos

// Converte o Model e seus relacionamentos carregados para um array
$userArray = $user->toArray(); 

// Converte para uma string JSON
$userJson = $user->toJson(); 

// O Laravel implicitamente chama toJson() quando um Model/Collection é retornado em um controller ou convertido para string.
return response()->json($user); 

2. 🚫 Controlando Atributos

Você pode definir quais atributos devem ser omitidos ou incluídos dinamicamente na serialização.

A. Ocultando Atributos ($hidden)

Use a propriedade $hidden no Model para omitir atributos sensíveis ou internos da serialização.

PHP

// app/Models/User.php
class User extends Model
{
    protected $hidden = [
        'password', 
        'remember_token',
        'is_admin', // Oculta flags internas
    ];
}

// O JSON/Array resultante NÃO conterá estes campos.

B. Adicionando Atributos Calculados ($appends)

Use a propriedade $appends para incluir Accessors (atributos virtuais, ou seja, que não estão no banco de dados) na serialização. O Accessor correspondente deve ser definido no Model (ex: getNomeCompletoAttribute).

PHP

// app/Models/User.php
class User extends Model
{
    // O atributo 'nome_completo' será incluído na serialização
    protected $appends = [
        'nome_completo', 
    ];

    // Accessor para calcular o valor
    public function getNomeCompletoAttribute()
    {
        return $this->first_name . ' ' . $this->last_name;
    }
}

C. Expondo Atributos ($visible)

Se você tem muitos atributos e prefere especificar quais devem ser incluídos em vez de quais devem ser ocultados, use $visible. Se $visible for definido, todos os outros atributos serão ocultados por padrão.

PHP

class Post extends Model
{
    // Apenas 'title' e 'content' serão serializados
    protected $visible = ['title', 'content'];
}

3. 📅 Formatação de Datas

O Eloquent lida com datas através da biblioteca Carbon. Ao serializar para JSON, as datas são formatadas por padrão como timestamps ISO 8601.

A. Customizando o Formato JSON

Use a propriedade $dateFormat para especificar um formato de saída para as datas ao usar toJson() (o formato se baseia na sintaxe date() do PHP).

PHP

class Order extends Model
{
    // Datas serão formatadas como 'Y-m-d H:i:s' na saída JSON
    protected $dateFormat = 'Y-m-d H:i:s'; 
}

B. Formatando na Leitura ($casts)

Para controlar a formatação de datas ao serem lidas do banco (o que também afeta a serialização), use o Casting com o formato de data desejado:

PHP

class Order extends Model
{
    protected $casts = [
        // Converte a data para Carbon, mas formata a saída como 'd/m/Y'
        'created_at' => 'datetime:d/m/Y', 
    ];
}

// A serialização (toJson) usará este formato específico:
// "created_at": "27/10/2024"

4. 🗂️ Serializando Relacionamentos

A serialização de um Model ou Collection automaticamente inclui todos os relacionamentos que foram carregados (eager loaded).

Exemplo:

PHP

// No Controller:
$user = User::with('posts', 'profile')->find(1); 
return response()->json($user);

// JSON resultante:
/* {
    "id": 1,
    // ...
    "posts": [ ... ],   // Incluído porque 'posts' foi eager loaded
    "profile": { ... } // Incluído porque 'profile' foi eager loaded
}
*/

Nota: Se você não usar o Eager Loading (with()), os relacionamentos não serão serializados, a menos que você os acesse explicitamente no Model antes da serialização (o que causa o problema N+1).

✅ Conclusão Eloquent Serialization

Eloquent Serialization: A serialização é a ponte entre a camada de dados e a camada de apresentação da sua aplicação. Com as ferramentas do Eloquent – $hidden para segurança, $appends para valor agregado e $casts para formatação de datas – você garante que suas respostas de API sejam seguras (sem dados sensíveis), consistentes e precisamente formatadas, otimizando a comunicação com os clientes da sua API.

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: