Models

Um model é a ponte entre seu código e uma tabela do banco. Em vez de escrever SQL manualmente para cada operação, você usa métodos simples comofind(), where() e create().

ℹ️Onde ficam os models?

Cada model pertence ao módulo que o usa:app/modules/nome_modulo/models/. Não existe pasta global de models.

Localização

app/modules/shop/models/shop_item.php
app/modules/account/models/customer.php
app/modules/blog/models/post.php

Model básico

Sempre estenda MUCRM\engine\database\schema. Classes e namespaces emsnake_case:

<?php

namespace MUCRM\modules\shop\models;

use MUCRM\engine\database\schema;

class shop_item extends schema
{
    protected string $table = 'shop_items';
    protected string $primaryKey = 'id';

    protected array $fillable = ['name', 'price', 'active'];

    protected array $hidden = [];
}

Propriedades importantes

Propriedade	O que faz	Exemplo
$table	Nome da tabela no banco	'shop_items'
$primaryKey	Coluna de ID (usada no find)	'id'
$fillable	Colunas aceitas no create/fill	['name', 'price']
$hidden	Campos ocultos em JSON	['password']
$timestamps	Gerencia created_at/updated_at	false (tabelas legadas)

Tabelas sem timestamps

Bancos legados ou tabelas importadas geralmente não têm colunas de data automática. Desative timestamps:

<?php

namespace MUCRM\modules\account\models;

use MUCRM\engine\database\schema;

class customer extends schema
{
    protected string $table = 'customers';
    protected string $primaryKey = 'id';
    protected bool $timestamps = false;
}

Consultar, criar, atualizar e deletar

// Buscar
$item = shop_item::find(5);
$items = shop_item::where('active', 1)->order_by('name')->get();

// Criar
shop_item::create(['name' => 'Plano Básico', 'price' => 29.90, 'active' => 1]);

// Atualizar
$item->price = 39.90;
$item->save();

// Deletar
$item->delete();

Relacionamentos

Conecte tabelas com has_one(), has_many() e belongs_to(). Métodos sempre em snake_case:

public function order_items()
{
    return $this->has_many(
        order_item::class,
        'customer_id',
        'id'
    );
}

// Uso:
$customer = customer::find(1);
foreach ($customer->order_items as $item) {
    echo e($item->name);
}

Guia completo em Relacionamentos.

Usando no handler

<?php

namespace MUCRM\modules\shop\handlers;

use MUCRM\http\handler;
use MUCRM\modules\shop\models\shop_item;

class web_handler extends handler
{
    public function show(int $id)
    {
        $item = shop_item::find_or_fail($id);

        return $this->view('Shop.show', compact('item'))
            ->title($item->name);
    }
}

Boas práticas

Model dentro do módulo

Cada funcionalidade tem seus próprios models em app/modules/.../models/.

Valide no handler

Use $req->check() antes de salvar dados do formulário.

snake_case em tudo

Classes, métodos de relação e propriedades seguem o padrão nome_assim.

Proteja dados sensíveis

Coloque senhas e tokens em $hidden.