README

Componente oficial de persistência PDO do MovesOS. Implementa Active Record, consultas preparadas, hidratação de models, CRUD, paginação e transações.

Requisitos e instalação

PHP 8.2+
PDO
driver PDO do banco utilizado

composer require movescode/model:^1.0

Configurar conexão

use MovesCode\Model\Connection;

$pdo = new PDO(
    'mysql:host=localhost;dbname=app;charset=utf8mb4',
    'usuario',
    'senha'
);

Connection::configure($pdo);

A configuração ativa exceções PDO e fetch associativo. Credenciais devem vir de variáveis de ambiente.

Criar um model

use MovesCode\Model\Model;

final class User extends Model
{
    public function __construct()
    {
        parent::__construct(
            entity: 'users',
            protected: ['id'],
            required: ['name', 'email']
        );
    }

    public function displayName(): string
    {
        return $this->name;
    }
}

Campos protegidos, chave primária e timestamps não são enviados automaticamente em create/update.

Consultar

$users = (new User())
    ->find('status = :status', ['status' => 'active'])
    ->order('name ASC')
    ->limit(20)
    ->offset(0)
    ->fetch(true);

fetch() retorna um model ou null. fetch(true) retorna array de models ou null.

Também são suportados parâmetros no formato de query string:

$user = (new User())
    ->find('email = :email', http_build_query(['email' => $email]))
    ->fetch();

Buscar por ID, IN e contagem

$user = (new User())->findById(10);
$selected = (new User())->find()->in('id', [1, 2, 3])->fetch(true);
$total = (new User())->find('status = :s', ['s' => 'active'])->count();

Criar e atualizar

$user = new User();
$user->name = 'Ana';
$user->email = 'ana@example.com';

if (!$user->save()) {
    echo $user->message()->render();
}

$user->name = 'Ana Martins';
$user->save();

Sem chave primária, save() cria o registro e hidrata o ID. Com chave primária, atualiza o registro existente. Valores 0 são aceitos em campos obrigatórios.

Excluir

$user = (new User())->findById(10);
$user?->destroy();

(new User())->delete('status = :status', ['status' => 'inactive']);

Paginação

$query = (new User())->find();
$total = $query->count();

$users = $query
    ->order('id DESC')
    ->limit($pager->limit())
    ->offset($pager->offset())
    ->fetch(true);

Transações

Connection::transaction(function (): void {
    $user = new User();
    $user->name = 'Ana';
    $user->email = 'ana@example.com';

    if (!$user->save()) {
        throw new RuntimeException('Falha ao salvar');
    }
});

A transação faz commit no sucesso e rollback em qualquer exceção. Transações já existentes não são encerradas pelo componente.

Estado e erros

data(): objeto com os campos.
fail(): última PDOException.
message(): mensagem de validação ou persistência.
filter(): normaliza um array.
lastId(): próximo ID numérico estimado.
idLast() e userLastId(): maior ID existente.

Não use métodos de maior/próximo ID para reservar chaves; em concorrência, use auto incremento e lastInsertId().

Segurança

Valores são vinculados por prepared statements. Nomes de tabela, campos e ordenação são validados. Termos de consulta são código da aplicação e nunca devem receber fragmentos SQL enviados pelo usuário.

Veja exemple/index.php. Licença MIT.

movescode / model

Maintainers

Package info

Statistics

Security