Laravel Eloquent

Tempo de leitura: 4 minutos

Laravel Eloquent: O Eloquent ORM (Mapeador Objeto-Relacional) é a forma mais popular de interagir com o banco de dados no Laravel. Ele permite que as tabelas do banco de dados sejam tratadas como classes PHP (Models) e os registros, como instâncias de objetos, eliminando a necessidade de escrever SQL complexo para operações CRUD (Create, Read, Update, Delete).

Este artigo explora a fundo a utilização do Eloquent, desde as convenções até os recursos avançados de Query Scopes.

1. 🏗️ Modelos Eloquent e Convenções

Um Model Eloquent é uma classe que estende Illuminate\Database\Eloquent\Model.

A. Geração

Para criar um novo Model (ex: Post), use o Artisan:

Bash

php artisan make:model Post
# Para criar também Migration, Factory, Controller e Seeder:
php artisan make:model Post -mfcs

B. Convenções Padrão

O Eloquent segue o princípio de “convenção sobre configuração”:

Propriedade	Convenção Padrão	Personalização
Nome da Tabela	Plural do nome do Model em snake case (Ex: `User` -> `users`)	`protected $table = 'meus_usuarios';`
Chave Primária	`id`	`protected $primaryKey = 'codigo';`
Timestamps	Usa `created_at` e `updated_at`	`public $timestamps = false;`
Conexão	`DB_CONNECTION` do `.env`	`protected $connection = 'mysql2';`

2. 🔍 Recuperando Dados (Read)

O Eloquent fornece uma API fluente para construir consultas.

Método	Função	Exemplo
`all()`	Retorna todos os registros (como uma `Collection`).	`$users = User::all();`
`find()`	Busca por Chave Primária.	`$user = User::find(1);`
`findOrFail()`	Busca por PK ou lança exceção 404.	`$user = User::findOrFail(1);`
`get()`	Executa a consulta e retorna uma `Collection`.	`User::where('active', 1)->get();`
`first()`	Retorna apenas o primeiro resultado.	`User::where('status', 'A')->first();`
`chunk()`	Processa grandes resultados em pedaços (otimização de memória).	`User::chunk(100, function ($users) { /* ... */ });`

Exemplo de Filtragem:

PHP

// SELECT * FROM users WHERE active = 1 AND name LIKE '%João%'
$users = User::where('active', 1)
             ->where('name', 'like', '%João%')
             ->orderBy('created_at', 'desc')
             ->get();

3. ✍️ Modificação de Dados (Create, Update, Delete)

A. Inserir (Create)

Você pode instanciar o objeto ou usar o método estático create() (requer a propriedade $fillable no Model).

PHP

// 1. Instanciando e Salvando
$user = new User;
$user->name = 'Novo Usuário';
$user->email = '[email protected]';
$user->save();

// 2. Criação Massiva (Mass Assignment)
User::create([
    'name' => 'Usuário X',
    'email' => '[email protected]',
    'password' => bcrypt('senha'),
]);

B. Atualizar (Update)

PHP

// 1. Atualizando por Objeto (dispara eventos do Model)
$user = User::find(1);
$user->name = 'Nome Atualizado';
$user->save();

// 2. Atualização Massiva (via Query Builder)
User::where('id', 1)->update(['name' => 'Nome Atualizado']);

C. Excluir (Delete)

PHP

// 1. Exclusão por Objeto
$user = User::find(1);
$user->delete();

// 2. Exclusão por Chave(s) Primária(s)
User::destroy(1);
User::destroy([1, 2, 3]);

4. 🗑️ Soft Deletes (Exclusão Suave)

O Soft Deletes (Exclusão Suave) marca um registro como deletado, preenchendo a coluna deleted_at, ao invés de removê-lo fisicamente do banco de dados.

Migration: Adicione a coluna deleted_at.
PHP
$table->softDeletes();
Model: Adicione a Trait SoftDeletes.
PHP
use Illuminate\Database\Eloquent\SoftDeletes;
class User extends Model { use SoftDeletes; // ... }
Consultas:

Ação	Método	Efeito
Padrão	`User::all()`	Exclui registros deletados dos resultados.
Incluir Deletados	`User::withTrashed()->get()`	Retorna todos (deletados e não deletados).
Apenas Deletados	`User::onlyTrashed()->get()`	Retorna apenas os registros deletados.
Restaurar	`$user->restore()`	Define `deleted_at` como `NULL`.
Deletar Final	`$user->forceDelete()`	Remove o registro permanentemente do BD.

5. 🔭 Query Scopes (Escopos de Consulta)

Os Escopos permitem definir conjuntos de restrições de query reutilizáveis e fáceis de chamar.

A. Definindo Escopos Locais

Crie um método no Model prefixado com scope. Ele aceita a instância do Query Builder ($query) como primeiro argumento.

PHP

class User extends Model
{
    // Escopo Simples (ex: status ativo)
    public function scopeActive($query)
    {
        return $query->where('active', 1);
    }

    // Escopo com Parâmetros (ex: busca por nome)
    public function scopeSearchByName($query, $name)
    {
        return $query->where('name', 'like', "%$name%");
    }
}

B. Utilizando Escopos

Chame o escopo como um método do Model, sem o prefixo scope:

PHP

// SELECT * FROM users WHERE active = 1
$activeUsers = User::active()->get();

// SELECT * FROM users WHERE active = 1 AND name LIKE '%João%'
$usersFiltrados = User::active()->searchByName('João')->paginate(10);

✅ Conclusão Laravel Eloquent

Laravel Eloquent: O Eloquent transforma a interação com o banco de dados em uma experiência intuitiva e orientada a objetos. Dominar as convenções, o uso de Soft Deletes e, principalmente, a criação de Query Scopes é fundamental para escrever código Laravel limpo, produtivo e altamente manutení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: