camelia-orm
Lightweight attribute-mapped Active Record ORM for MariaDB/MySQL over PDO, by Dr2g Sistemas.
- Package:
camelia/orm· Namespace:Camelia\Orm - PHP
>=8.3, extensionspdo_mysqlandmbstring - Runtime dependencies:
psr/log(PSR-3, optional usage).brick/mathis a suggestion forBigDecimalproperties.
The contract lives in especificaciones-orm.md; this file only shows usage.
The full developer guide, organised by task, is in docs/GUIA-PROGRAMADOR.md.
Install
composer require camelia/orm
Bootstrap
use Camelia\Orm\Orm;
$orm = Orm::fromArray([
'host' => '127.0.0.1',
'user' => 'app',
'password' => 'secret',
'database' => 'erp',
]);
// or from CAMELIA_DB_HOST, CAMELIA_DB_USER, CAMELIA_DB_NAME, CAMELIA_DB_PASS
$orm = Orm::fromEnv();
Declare a model
use Camelia\Orm\Attribute\{TableName, PrimaryKey, AutoIncrement, Guarded};
use Camelia\Orm\Model;
#[TableName('usuarios')]
final class Usuario extends Model
{
#[PrimaryKey, AutoIncrement]
public ?int $codigo = null;
public string $nombre = '';
#[Guarded]
public string $passwordHash = '';
}
#[TableName] and exactly one #[PrimaryKey] are mandatory. A model that violates the rules throws
MetadataException on first use instead of failing silently later.
Read
$repo = $orm->repository(Usuario::class);
$repo->find(['activo' => true], [['nombre', 'ASC']], limit: 20);
$repo->findFirst(['correo' => 'a@x']);
$repo->findByPk(5);
$repo->findByPkOrFail(5); // throws RecordNotFoundException
$repo->count(['activo' => true]);
$repo->page(['activo' => true], [], page: 2, perPage: 25);
Fluent queries are immutable:
use Camelia\Orm\Query\{Cond, GroupCond};
$repo->query()
->where('activo', true)
->where('fecha', Cond::between('2024-01-01', '2024-12-31'))
->whereGroup(fn (GroupCond $g) => $g->or('correo', Cond::like('%@camelia.dev')))
->orderByDesc('fecha')
->with(['cliente.ciudad'])
->page(page: 1, perPage: 25);
Write
$repo->save($usuario); // INSERT or UPDATE, decided by the primary key
$repo->create(['nombre' => 'Ana']); // new + hydrate + insert
$repo->update($usuario); // always UPDATE, all writable columns
$repo->delete($usuario);
$repo->patch(5, ['nombre' => 'Bea']); // partial update by primary key
$repo->remove(5);
update() writes the whole row. There is no dirty tracking: use patch() for partial updates.
Writing a model hydrated through select() throws PartialModelException.
Transactions
$orm->transaction(function (Orm $orm) {
$orm->repository(Usuario::class)->save($usuario);
});
Nested calls use savepoints and the original exception is rethrown.
Errors
Every read and write throws on failure. Silent degradation to [] is deliberately absent: it hides
connection failures as empty results. Catch DatabaseException (or DuplicateKeyException,
ForeignKeyViolationException, LockTimeoutException) where degradation is genuinely intended.
Development
The toolchain is Mago plus PHPUnit and PHPStan.
composer install
composer fmt # format with Mago
composer fmt:check # CI: formatting must be clean
composer lint # CI: Mago linter
composer analyze # CI: Mago analyzer
composer phpstan # CI: PHPStan level 8
composer test # CI: PHPUnit
composer check # runs the five gates above, in order
composer test:integration # requires CAMELIA_TEST_DSN
Configuration:
| File | Purpose |
|---|---|
mago.toml |
formatter, linter, analyzer |
mago-baseline.toml |
accepted analyzer findings (values coming from PDO) |
phpstan.neon |
level 8, phpVersion: 80300 |
phpunit.xml.dist |
unit suite |
phpunit.integration.xml.dist |
integration suite, skipped without CAMELIA_TEST_DSN |
mago.toml pins php-version = "8.3". Do not raise it to 8.4: with 8.4 the formatter emits
new Foo()->bar(), which the package cannot ship because it promises PHP 8.3 support.
License
MIT. See LICENSE.