Eloquent Serialization

Tempo de leitura: 5 minutos

Eloquent Serialization: Ao construir APIs ou trabalhar com dados que precisam ser transmitidos ou armazenados em formatos específicos, a serialização se torna uma etapa fundamental. No Laravel, o laravel eloquent serialization oferece uma maneira conveniente e poderosa de converter seus models e collections Eloquent em arrays PHP ou strings JSON. Isso permite um controle preciso sobre quais atributos são incluídos na serialização e como eles são formatados.

Este artigo explora em detalhes como dominar a serialização com Eloquent, desde os conceitos básicos até técnicas avançadas de formatação de datas e ocultação de atributos.

O que é Serialização?

Eloquent Serialization: Serialização é o processo de converter um objeto em um formato que pode ser facilmente armazenado ou transmitido. Em aplicações web, os formatos mais comuns são JSON (JavaScript Object Notation) e arrays PHP. A serialização permite que você represente seus models Eloquent (que são objetos PHP) em formatos que podem ser entendidos por outros sistemas ou armazenados em cache.

Serializando Models e Collections

O Eloquent oferece métodos simples e diretos para serializar models e collections:

toArray(): Converte um model ou uma collection para um array PHP.
toJson(): Converte um model ou uma collection para uma string JSON.

Exemplo com Model:

PHP

use App\Models\User;

$user = User::find(1);

$userArray = $user->toArray(); // Converte o model para um array
$userJson = $user->toJson(); // Converte o model para JSON

// Ou, implicitamente, convertendo para string:
$userJsonImplicit = (string) $user; // Também converte para JSON

Exemplo com Collection:

PHP

use App\Models\User;

$users = User::all();

$usersArray = $users->toArray(); // Converte a collection para um array de arrays
$usersJson = $users->toJson(); // Converte a collection para JSON

Quando um model ou collection é convertido para string (usando (string) $model ou diretamente em uma view Blade com {{ $model }}), o Eloquent implicitamente chama o método toJson().

Serializando para Arrays e para JSON

A principal diferença entre toArray() e toJson() é o formato da saída. toArray() retorna um array PHP, enquanto toJson() retorna uma string JSON. A escolha entre os dois depende do contexto em que você está usando a serialização. Se você precisa manipular os dados em PHP, use toArray(). Se você precisa enviar os dados para um cliente (como em uma API), use toJson().

Exemplo comparativo:

Suponha que um model User tenha os atributos id, name e email.

Resultado de toArray():

PHP

[
    'id' => 1,
    'name' => 'João da Silva',
    'email' => '[email protected]',
    'created_at' => '2024-10-27 10:00:00',
    'updated_at' => '2024-10-27 12:00:00',
]

Resultado de toJson():

JSON

{
    "id": 1,
    "name": "João da Silva",
    "email": "[email protected]",
    "created_at": "2024-10-27T10:00:00.000000Z",
    "updated_at": "2024-10-27T12:00:00.000000Z"
}

Observe a diferença na formatação das datas. toJson() usa o formato ISO 8601 por padrão.

Serializando Datas

O Eloquent formata as datas automaticamente quando você serializa um model para JSON. Por padrão, ele usa o formato ISO 8601. No entanto, você pode personalizar o formato da data definindo a propriedade $dateFormat no seu model:

PHP

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected $dateFormat = 'd/m/Y H:i:s'; // Formato personalizado

    // ...
}

Agora, ao serializar o model para JSON, as datas serão formatadas de acordo com o formato especificado:

JSON

{
    "id": 1,
    "name": "João da Silva",
    "email": "[email protected]",
    "created_at": "27/10/2024 10:00:00", // Formato personalizado
    "updated_at": "27/10/2024 12:00:00" // Formato personalizado
}

Ocultando Atributos:

Você pode ocultar atributos que não devem ser incluídos na serialização definindo a propriedade $hidden no seu model:

PHP

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected $hidden = [
        'password', // Oculta a senha
        'remember_token', // Oculta o token de lembrança
    ];
}

Adicionando Atributos Dinamicamente:

Você pode adicionar atributos que não existem na tabela do banco de dados, mas que são calculados dinamicamente, usando a propriedade $appends:

PHP

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected $appends = [
        'nome_completo', // Adiciona o atributo nome_completo
    ];

    public function getNomeCompletoAttribute()
    {
        return $this->primeiro_nome . ' ' . $this->sobrenome;
    }
}

Agora, o atributo nome_completo será incluído na serialização, mesmo que não exista na tabela users.

Exemplo Completo: Serializando Usuários com Formatação de Data, Ocultando Senha e Adicionando Nome Completo

PHP

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected $hidden = [
        'password',
        'remember_token',
    ];

    protected $appends = [
        'nome_completo',
    ];

    protected $casts = [
        'data_nascimento' => 'date:d/m/Y', // Formata a data de nascimento
    ];

    public function getNomeCompletoAttribute()
    {
        return $this->primeiro_nome . ' ' . $this->sobrenome;
    }
}

// Em um controller:
use App\Models\User;

$user = User::find(1);

return response()->json($user); // Retorna o usuário em JSON

O JSON retornado será semelhante a:

JSON

{
    "id": 1,
    "primeiro_nome": "João",
    "sobrenome": "Silva",
    "email": "[email protected]",
    "data_nascimento": "10/05/1990",
    "nome_completo": "João Silva",
    "created_at": "2024-10-27T10:00:00.000000Z",
    "updated_at": "2024-10-27T12:00:00.000000Z"
}

Observe que a senha e o token de lembrança foram ocultados, o nome completo foi adicionado e a data de nascimento foi formatada.

Conclusão

Eloquent Serialization: A laravel eloquent serialization oferece um controle preciso sobre como seus models e collections são convertidos para arrays e JSON. Com os recursos de ocultação de atributos, formatação de datas e adição de atributos dinâmicos, você pode criar respostas de API consistentes, eficientes e personalizadas.

Dominar a serialização é crucial para construir APIs RESTful robustas e para trabalhar com dados em diversos contextos. Os exemplos e explicações apresentados neste artigo fornecem uma base sólida para você começar a usar a serialização em seus projetos Laravel e otimizar o fluxo de dados na sua aplicação.

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: