Database System

Estrutura Básica de um Modelo

<?php

namespace Og\Modules\Tax\Models;

use Og\Modules\Common\Database\Model;

/**
 * Modelo de IVA (Taxas de Imposto).
 * 
 * @property-read string $codiva       Código do IVA
 * @property-read string $designacao   Descrição da taxa
 * @property-read float $iva           Percentagem de IVA
 * @property-read Carbon $date_reg     Data de registo
 */
class Vat extends Model
{
    protected string $table = TABLE_IVAS;
    
    protected string|array $primaryKey = 'CodIVA';
    
    protected array $casts = [
        'iva' => 'decimal:2',
        'date_reg' => 'datetime',
        'date_alter' => 'datetime',
    ];
}

Uso Básico

// Obter todos os IVAs
$vats = Vat::all();

// Obter um IVA específico por primary key
$vat = Vat::find('NOR');

	// Acessar propriedades com tipagem
	echo $vat->designacao;  // string
	echo $vat->iva;         // string (decimal:2, ex.: "23.00")
	echo $vat->date_reg;    // Carbon (objeto de data)

// Filtrar com where
$normalVats = Vat::where('tipotaxa', 'NOR')
    ->where('iva', '>', 0)
    ->get();

Casts Simples (String)

protected array $casts = [
    'is_active' => 'bool',       // "T" → true
    'price' => 'decimal:2',      // "23.000" → "23.00"
    'settings' => 'json',        // JSON string → array
    'created_at' => 'datetime',  // String → Carbon
    'quantity' => 'int',         // "123" → 123
];

Cast Customizado

use Og\Modules\Common\Database\Casts\CastInterface;

class MoneyCast implements CastInterface
{
    public function get(mixed $value, array $attributes = []): Money
    {
        return new Money((int) $value, $attributes['currency'] ?? 'EUR');
    }

    public function set(mixed $value, array $attributes = []): int
    {
        return $value instanceof Money ? $value->cents : (int) $value;
    }
}

// Uso no Model
protected array $casts = [
    'total_cents' => MoneyCast::class,
];

Mutator (#[Mutator])

use Og\Modules\Common\Database\Attributes\Mutator;

class User extends Model
{
    #[Mutator]
    protected function password(string $value): void
    {
        $this->attributes['password'] = password_hash($value, PASSWORD_DEFAULT);
    }
}

$user->password = 'minhasenha';  // Automaticamente hashed!

Métodos de Criação

// Encontrar ou criar (NÃO salva automaticamente)
$vat = Vat::firstOrNew(
    ['codiva' => 'NEW'],                        // Critério de busca
    ['iva' => 23, 'designacao' => 'Novo']       // Valores para nova instância
);

// Encontrar ou criar E SALVAR
$vat = Vat::firstOrCreate(
    ['codiva' => 'NEW'],
    ['iva' => 23, 'designacao' => 'Novo']
);

// Atualizar ou criar
$vat = Vat::updateOrCreate(
    ['codiva' => 'NEW'],
    ['iva' => 25]
);

Cache de Queries e Modo Híbrido

// Cache por 5 minutos (300 segundos)
$vats = Vat::where('tipotaxa', 'NOR')
    ->cached('vats:normal', 300)
    ->get();

	// Modo híbrido para relatórios (sem hidratar Models)
	// Usa asArray() para receber arrays
	$data = Vat::query()->asArray()->get();

class User extends Model
{
    // Whitelist - campos permitidos em fill()
    protected array $fillable = ['name', 'email', 'password'];
    
    // Ou Blacklist - bloquear específicos
    protected array $guarded = ['id', 'is_admin', 'role'];
}

Criar Tabela

$this->dbforge
    ->add_field([
        'id' => ['type' => 'INT', 'constraint' => 11, 'auto_increment' => true],
        'user_id' => ['type' => 'INT', 'constraint' => 11, 'null' => false],
        'email' => ['type' => 'VARCHAR', 'constraint' => 255, 'null' => false],
        'created_at' => ['type' => 'DATETIME', 'null' => true, 'default' => RawSql::currentTimestamp()],
    ])
    ->primary('id')
    ->unique('email')
    ->index(['user_id', 'created_at'])
    ->addForeignKey('user_id', 'users', 'id', 'CASCADE', 'CASCADE')
    ->create_table('user_emails', true);  // true = IF NOT EXISTS

Padrões de Campos (Atalhos)

// Timestamps: date_reg e date_alter com defaults
$this->dbforge->timestamps();

// Soft deletes: deleted_at + índice
$this->dbforge->softDeletes();

// User tracking: oper_reg e oper_alter com FKs
$this->dbforge->userTracking();

Desativar Timestamps

// Permanentemente no modelo
class LogEntry extends Model
{
    protected bool $timestamps = false;
}

// Temporariamente para uma operação
$model->withoutTimestamps()->save();

class User extends Model
{
    // Ocultar sempre (excluídos de toArray, retornam null no acesso)
    protected array $hidden = ['password', 'api_token', 'remember_token'];
    
    // Modo whitelist: SÓ estes aparecem em toArray()
    protected array $visible = ['id', 'name', 'email', 'avatar'];
    
    // Computed properties a incluir automaticamente
    protected array $appends = ['full_name', 'profile_url'];
}

class Vat extends Model
{
    // Opções: null (desativado), 'lower', 'snake'
    protected ?string $normalizeKeys = 'lower';
}

// SAFTTaxCode e safttaxcode → apenas safttaxcode
// Evita duplicação no toArray()

ArrayAccess

Acesso estilo array para compatibilidade com código legado.

$user = User::query()->find(1);

// Acesso por array (equivalente a ->name)
echo $user['name'];
$user['email'] = 'new@example.com';

// Verificação
isset($user['name']);  // true
unset($user['temp']);  // remove atributo

Exemplo Completo: Entidade Rica

class Order extends Model
{
    #[Computed]
    protected function total(): float {
        return $this->subtotal + $this->tax - $this->discount;
    }
    
    public function isPending(): bool { return $this->status === 'pending'; }
    public function isPaid(): bool { return $this->status === 'paid'; }
    public function canBeCancelled(): bool {
        return in_array($this->status, ['pending', 'confirmed']);
    }
    
    public function confirm(): void {
        if (!$this->isPending()) {
            throw new \DomainException('Só pedidos pendentes podem ser confirmados');
        }
        $this->status = 'confirmed';
        $this->confirmed_at = now();
        $this->save();
    }
    
    public function cancel(string $reason): void {
        if (!$this->canBeCancelled()) {
            throw new \DomainException('Este pedido não pode ser cancelado');
        }
        $this->status = 'cancelled';
        $this->cancellation_reason = $reason;
        $this->save();
    }
}