A lightweight, zero-dependency PHP ORM with Laravel/Eloquent-inspired syntax. Built on top of PDO, it supports multiple named connections, soft deletes, timestamps, eager loading, and pivot table relationships.

Installation

composer install

No external dependencies. PHP 8.0+ required.

Setup

require 'vendor/autoload.php';

use ORM\Connection;
use ORM\Connections;

// Using the factory helper
$pdo = Connection::open('pgsql', 'dbname=mydb host=localhost', 'user', 'pass', 'myprefix_');

// Or register a raw PDO
$pdo = new PDO("pgsql:dbname=mydb;host=localhost", 'user', 'pass');
$pdo->prefix = 'myprefix_';
Connections::addConnection($pdo);              // 'default'
Connections::addConnection($pdo, 'secondary'); // named connection

Supported drivers: pgsql, mysql, sqlite, firebird, oracle, mssql.

Defining a Model

use ORM\Entity;

class User extends Entity {
    const _tableName      = 'users';
    const _connectionName = 'default';    // optional, defaults to 'default'
    const _softdelete     = true;         // filters deleted_at IS NULL on all queries
    const _timestamps     = true;         // auto-sets created_at / updated_at on save
    const _ignore         = ['password_confirm']; // excluded from INSERT / UPDATE
    const _idPolice       = [             // optional custom ID strategy
        'type' => 'nextval',
        'min'  => 500,
        'max'  => 9999,
        'step' => 10,
    ];

    protected function posts() {
        return $this->hasMany(Post::class, 'user_id');
    }

    protected function country() {
        return $this->belongsTo(Country::class, 'country_id', 'id');
    }

    protected function roles() {
        return $this->belongsToMany(Role::class, 'role_user', 'user_id', 'role_id');
    }
}

Features

CRUD

// Create
$user = new User(['name' => 'Alice', 'email' => 'alice@example.com']);
$user->save(); // INSERT; $user->id is populated after

// Read
$user  = User::findOne(42);
$user  = User::findOne(['email' => ['=', 'alice@example.com']]);
$users = User::findAll();
$users = User::findMany(['active' => ['=', 1]], ['*'], ['LIMIT' => 10, 'OFFSET' => 0]);
$n     = User::count(['active' => ['=', 1]]);

// Update
$user->name = 'Bob';
$user->save(); // UPDATE because $user->id exists

// Delete
$user->delete(); // soft-delete if _softdelete=true, otherwise hard-delete
$user->purge();  // always hard-delete
$user->restore(); // clears deleted_at (soft-delete models only)

Criteria format: ['column' => ['operator', value]] Supported operators: =, <, >, <=, >=, IN, LIKE

Soft Delete

When _softdelete = true, all findAll, findOne, findMany, and count calls automatically append WHERE deleted_at IS NULL. Pass true as the last argument to include trashed records:

$all     = User::findAll(['*'], [], true);   // includes soft-deleted
$trashed = User::findOne(42, ['*'], true);

Timestamps

When _timestamps = true, created_at and updated_at are set on construction and updated_at is refreshed on every save().

Relationships

Method	Description
`hasOne(Class, $remoteField)`	One child record keyed by local id
`hasMany(Class, $remoteField)`	Many child records keyed by local id
`belongsTo(Class, $localField, $remoteField)`	Parent record
`belongsToMany(Class, $pivot, $localKey, $remoteKey)`	Many-to-many via pivot
`belongsToManyExtended(...)`	Many-to-many via pivot; returns pivot rows with foreign object in `->childElement`

// Lazy load (fires a query on access)
$posts   = $user->posts()->get();
$country = $user->country;   // magic __get shorthand

// Eager load on a Collection
$users = User::findAll()->with(['posts', 'country']);

// Eager load on a single Entity
$user->with(['posts', 'country']);

Multiple Named Connections

Connections::addConnection($pdo1);              // 'default'
Connections::addConnection($pdo2, 'analytics'); // 'analytics'

class Event extends Entity {
    const _connectionName = 'analytics';
}

Custom ID Strategy (`_idPolice`)

When type = 'nextval' the ORM computes the next ID from MAX(id) before inserting, respecting min, max, and step. Useful for databases without auto-increment sequences.

Raw Query Helpers (`DBInstance`)

For queries that don't fit the Entity API:

use ORM\DBInstance;

// Single record with prepared statement
$row  = DBInstance::getRecord('users', ['email' => ['=', $email]]);

// Multiple records
$rows = DBInstance::getRecords('users', ['active' => ['=', 1]], ['id', 'name'], ['LIMIT' => 50]);

// Free SQL
$rows = DBInstance::getRecordsSql("SELECT * FROM {users} WHERE created_at > ?", [$date]);

// Insert and get last id
$id = DBInstance::insertRecord('logs', ['action' => 'login', 'user_id' => 1]);

// Update a single field
DBInstance::setField('users', 'active', 0, $id);

// Direct query
DBInstance::execute("UPDATE {users} SET score = score + 1 WHERE id = ?", [$id]);

Table names always use {tableName} placeholder syntax so the connection prefix is applied automatically.

SQL Tracing

$pdo->traceSQL = true; // prints every query to stdout

Known Bugs

#	Location	Description
1	`Collection::with()`	After the Relations namespace refactor, the `switch` class-name checks still use old names (`ORM\HasMany`, etc.) — all branches fall to `default`, which works but is inaccurate
2	`Entity::findMany()`, `Entity::count()`	When no criteria are given and `_softdelete = true`, `AND deleted_at IS NULL` is appended without a preceding `WHERE`, producing invalid SQL
3	`Entity` constructor / `update()`	Timestamp format uses `date('Y-m-d h:m:s')` — `h` is 12-hour clock and the second `m` is month; should be `date('Y-m-d H:i:s')`
4	`Entity::__get()`	Returns `0` for any undefined property, silently masking typos
5	`DBInstance::queryOne()`	When called with `$data`, it delegates to `queryPrepare()` which calls `fetchAll()` and returns an array, not a single object
6	`DBInstance::setField()`	Uses PHP string interpolation `{$table}` instead of the ORM's `{tableName}` syntax, so the connection prefix is never applied
7	`Entity::findMany()`	Values are interpolated directly into SQL (no prepared statements), making this method unsafe for user-supplied input

To Do

Fix findMany() and count() soft-delete WHERE clause when no other criteria exist
Fix timestamp format (H:i:s)
Fix Collection::with() class-name checks after Relations namespace refactor
Fix DBInstance::setField() table prefix placeholder
Fix DBInstance::queryOne() to actually return one record
Make findMany() use prepared statements
Collection::with() — use a bulk IN (...) query instead of one query per item (N+1 problem)
Relations cannot be iterated in Mustache / template engines (magic __get on Entity calls ->get() but templates can't iterate the result transparently)
__get() should return null instead of 0 for undefined properties
Add formal test suite (PHPUnit)
Support ORDER BY in findAll() and findMany()
Support whereNull / whereNotNull criteria shorthand

README.md

urfat-orm