Eloquent é o nome do ORM (Object Relational Mapping) nativo no Framework PHP Laravel, que facilita (e muito) toda a manipulação do banco de dados. Não importa se é uma simples inserção de dados ou uma busca extremamente complexa com relações entre tabelas, o Eloquent dispõe de métodos de fácil compreensão e conta com uma documentação completa de como funciona dentro do Laravel.

Este artigo traz nove truques que todo desenvolvedor PHP deveria conhecer sobre o Eloquent, principalmente os que utilizam o Framework Laravel. Após a leitura, recomendo que faça a instalação, popule o banco de dados e comece a testar os métodos apresentados aqui.

Validação automática do modelo

Às vezes, pode ser conveniente validar automaticamente seu modelo quando recebe uma inserção ou atualização de dados. Isto é facilmente alcançado com o Laravel através do uso de eventos do Modelo.

class Cliente extends Eloquent
{
    public static $autoValidates = true;
    protected static $rules = [];
    protected static function boot()
    {
        parent::boot();
        // or static::creating, or static::updating
        static::saving(function($model)
        {
            if ($model::$autoValidates) {
                return $model->validate();
            }
        });
    }
    public function validate()
    {
    }
}

Proibir atualizações

Existem casos onde o seu registro, uma vez criado, não deve sofrer alterações. Para aumentar a garantia de que uma tabela do seu banco de dados não sofrerá atualizações basta informar, no próprio Modelo, que a ação de atualizar deve ser barrada.

class Cliente extends Eloquent
{
    protected static function boot()
    {
        parent::boot();
        static::updating(function($model)
        {
            return false;
        });
    }
}

Relações condicionais

Essa é mais uma facilidade que o Laravel traz com a sua forma de construir relações entre tabelas, as relações que só existirão caso alguma condição seja atendida. Basta usar métodos do Eloquent na própria função.

class Cliente extends Model
{
    public function category()
    {
        return $this->belongsTo('Cupom', 'cupom_id')
            ->where('usuario_id', Auth::user()->id);
    }
}

Expressões da Sintaxe “Where”

Uma busca utilizando o método “where” pode ser feita de várias formas. Pode-se usar operadores (linha 1), mas por padrão o método “where” sempre busca utilizando o operador “=”, portanto não é necessário informá-lo (linha 3). Há também a forma mais abreviada que o Laravel Eloquent proporciona, onde é necessário apenas informar o nome da coluna que deseja utilizar na busca após o termo “where”, como um método (linha 5).

$cupons = Cupom::where('categoria', '=', 3)->get();
$cupons = Cupom::where('categoria', 3)->get();
$cupons = Cupom::whereCategoria(3)->get();

Query Builder: Having Raw

Os métodos o Laravel Eloquent também aceitam expressões Raw, o que facilita muito a escrita de uma busca mais complexa no banco de dados. É possível utilizar métodos Eloquent juntamente com o método estático “raw” da classe “DB”, que já é nativa do Laravel.

SELECT *, COUNT(*) FROM cupons GROUP BY categoria_id HAVING count(*) > 1;
DB::table('cupons')
    ->select('*', DB::raw('COUNT(*) as cupons_count'))
    ->groupBy('categoria_id')
    ->having('cupons_count', '>', 1)
    ->get();

Filtro de data simples

O Carbon é utilizado como padrão para manipular datas no Laravel. Portanto, a busca no banco de dados, quando feita por data, fica muito fácil de compreender devido aos métodos do Laravel Eloquent.

$q->whereDate('created_at', date('Y-m-d'));
$q->whereDay('created_at', date('d'));
$q->whereMonth('created_at', date('m'));
$q->whereYear('created_at', date('Y'));

Opções na hora de inserir ou atualizar dados

Dependendo da necessidade do sistema, existem campos da tabela que só podem sofrer alterações se alguma condição for atendida. O Laravel Eloquent permite a criação de métodos para executar este controle.

// src/Illuminate/Database/Eloquent/Model.php
public function save(array $options = [])
// src/Illuminate/Database/Eloquent/Model.php
protected function performUpdate(Builder $query, array $options=[])
{
    if ($this->timestamps && array_get($options, 'timestamps', true))
    {
        $this->updateTimestamps();
    }
}
$cupom = Cupom::find($id);
$cupom->updated_at = '2019-01-20 00:00:00';
$cupom->save(['timestamps'=>false]);

Busca aleatória de dados

Por permitir o uso de expressões Raw em seu métodos, o Eloquent consegue realizar buscas randômicas sem precisar de recursos externos.

$cupons = Cupom::orderByRaw('RAND()')->take(10)->get();

UUID como chave primária

O Laravel Eloquent também oferece ferramentas para trabalhar com sistemas Multitenancy (com dois ou mais bancos de dados). Em casos como esse é mais interessante utilizar o UUID como chave primária. Isso é facilmente alcançado com a instalação de um pacote e criação de uma trait.

use Ramsey\Uuid\Uuid;
trait UUIDModel
{
    public $incrementing = false;
    protected static function boot()
    {
        parent::boot();
        static::creating(function ($model)
        {
            $key = $model->getKeyName();
            if (empty($model->{$key})) {
                $model->{$key} = (string) $model->generateNewUuid();
            }
        });
    }
    public function generateNewUuid()
    {
        return Uuid::uuid4();
    }
}

Essa é a ponta do iceberg de funções, truques e facilitadores do Laravel Eloquent. Se você busca um código limpo, expressivo, de fácil compreensão, o Laravel Eloquent cairá como uma luva. Para testar as funcionalidades do Laravel Eloquent, basta realizar a instalação do Laravel e popular o seu banco de dados.