Eloquent Mutators e Casting

Eloquent Mutators e Casting: No Laravel, o Eloquent ORM oferece mecanismos poderosos para transformar os dados dos atributos de um Model automaticamente, seja na leitura (recuperação do banco), na escrita (salvamento no banco), ou na conversão de tipos. Essas ferramentas são os Accessors, Mutators e Casting.

Este artigo detalha como usar esses recursos para manipular e formatar dados de forma elegante e centralizada.

1. 📖 Accessors e Mutators (Laravel 9 e Anteriores)

Accessors e Mutators são métodos definidos no Model que interceptam a leitura ou escrita de atributos, permitindo a execução de lógica de formatação ou transformação.

A. Accessors (Leitura)

Formata um atributo quando ele é acessado. O nome do método segue o padrão get{NomeDoAtributo}Attribute. O NomeDoAtributo é o nome do atributo que você usará no código, em camel case.

Exemplo: Criar um atributo virtual nome_completo a partir de first_name e last_name armazenados no banco.

PHP

// app/Models/User.php
class User extends Model
{
    public function getNomeCompletoAttribute()
    {
        // Concatena atributos do banco de dados (que estão em $this->attributes)
        return $this->first_name . ' ' . $this->last_name;
    }
}

// Utilização:
$user = User::find(1);
echo $user->nome_completo; // Acessa o atributo virtual

B. Mutators (Escrita)

Modifica um atributo antes de ser armazenado no banco de dados. O nome do método segue o padrão set{NomeDoAtributo}Attribute.

Exemplo: Forçar o armazenamento de um nome em letras maiúsculas no banco de dados.

PHP

// app/Models/User.php
class User extends Model
{
    public function setNomeAttribute($value)
    {
        // Define o valor modificado diretamente no array de atributos
        $this->attributes['nome'] = strtoupper($value);
    }
}

// Utilização:
$user = new User;
$user->nome = 'alice silva';
$user->save(); // No DB, 'nome' será armazenado como 'ALICE SILVA'

2. 🔀 Attribute Casting (Conversão de Tipos)

O Attribute Casting é a maneira mais limpa e performática de garantir que um atributo do banco de dados seja convertido automaticamente para um tipo PHP específico (ou vice-versa) ao ser lido ou escrito.

Você define as conversões na propriedade $casts do seu Model.

A. Tipos de Casting Comuns

Exemplo Prático de Casting

PHP

// app/Models/Product.php
class Product extends Model
{
    protected $casts = [
        'is_active' => 'boolean',
        'price' => 'decimal:2', // Garantir 2 casas decimais
        'data_publicacao' => 'datetime',
        'tags' => 'array',       // Armazenado como JSON no BD
    ];
}

// Utilização:
$product = Product::find(1);

// 1. Acessando booleano e data (como objeto Carbon)
if ($product->is_active) { /* ... */ }
echo $product->data_publicacao->format('Y-m-d'); 

// 2. Manipulando arrays
$product->tags[] = 'novo';
$product->save(); // O array será convertido para JSON antes de salvar

3. 🛡️ Custom Casts (Conversão Personalizada)

Para lógica de transformação complexa (ex: lidar com objetos de valor, URLs, ou formatos específicos), você pode criar classes de Casting Personalizadas.

1- Criando a Classe de Cast: Implemente a interface CastsAttributes

PHP

// app/Casts/Endereco.php 

class Endereco implements CastsAttributes { 
    public function get($model, $key, $value, $attributes) { 
        // Lógica de LEITURA: JSON (DB) -> Objeto PHP (Model) 
        $data = json_decode($value, true); 
        return new \stdClass($data); 
    } 

    public function set($model, $key, $value, $attributes) { 
        // Lógica de ESCRITA: Objeto PHP (Model) -> JSON (DB) 
        return json_encode($value); 
    } 
}

2 – Use no Model: Referencie a classe no array $casts

PHP

// app/Models/User.php 

use App\Casts\Endereco; 

protected $casts = [ 'billing_address' => Endereco::class, ];

3 – Utilização:

PHP

$user = User::find(1); 

// Acessado como objeto PHP (gracas ao get() do Custom Cast) 
echo $user->billing_address->rua; 

// Passando um array (será convertido pelo set() do Custom Cast) 
$user->billing_address = ['rua' => 'Nova', 'cidade' => 'SP']; 
$user->save();

4. 🚀 Accessors e Mutators Modernos (Laravel 10+)

A partir do Laravel 10, Accessors e Mutators foram unificados usando a classe Illuminate\Database\Eloquent\Casts\Attribute, simplificando a definição.

PHP

// Laravel 10+
use Illuminate\Database\Eloquent\Casts\Attribute;

class User extends Model
{
    protected function nomeCompleto(): Attribute
    {
        return Attribute::make(
            // Accessor (ocorre ao LER $user->nome_completo)
            get: fn (string $value, array $attributes) => $attributes['first_name'] . ' ' . $attributes['last_name'],
            
            // Mutator (ocorre ao ESCREVER $user->nome_completo = '...')
            set: fn (string $value) => [
                'first_name' => explode(' ', $value)[0],
                'last_name' => end(explode(' ', $value)),
            ],
        );
    }
}

✅ Conclusão Eloquent Mutators e Casting

Eloquent Mutators e Casting: Accessors, Mutators e Casting são essenciais para manter a integridade e a legibilidade dos seus dados. Eles garantem que:

1. Os dados lidos do banco estejam no formato/tipo PHP correto (Carbon, bool, array).
2. Os dados escritos no banco sigam as regras de formatação (ex: letras maiúsculas, hash de senha).

Dominar o Casting para tipos básicos e o uso de Custom Casts para tipos de dados complexos é fundamental para otimizar o fluxo de dados em aplicações 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: