michaelrushton/orm

A library to extend https://github.com/MichaelRushton/php-db with an ORM.

dev-main 2025-12-05 18:59 UTC

Requires

• php: ^8.4
• michaelrushton/db: dev-main

Requires (Dev)

• pestphp/pest: ^4.1

MIT

README

A PHP library to extend https://github.com/MichaelRushton/php-db with an ORM.

Installation

composer require michaelrushton/orm

Documentation

Entity Manager

See PHP DB for documentation on creating a connection to a database.

use MichaelRushton\ORM\EntityManager;

$entity_manager = new EntityManager($connection);

Defining an entity

Add the Table attribute to a class to define the table name and a Column attribute to each property that represents a column in the table.

#[Table(name: 'users')]
class User
{
    #[Column]
    public int $id;

    #[Column]
    public string $name;
}

If the primary key of the table is not an id column then add the PrimaryKey attribute to the class to define the primary key. You may pass an array of column names if the primary key is a composite key. If the primary key does not auto increment then pass increments: false to the attribute. Composite primary keys are automatically set to not auto increment.

#[Table(name: 'users')]
#[PrimaryKey(column: 'user_id')]
class User
{
    #[Column]
    public int $user_id;

    #[Column]
    public string $name;
}

If the property name does not match the column name then pass the column name to the Column attribute.

#[Table(name: 'users')]
#[PrimaryKey(column: 'user_id')]
class User
{
    #[Column(column: 'user_id')]
    public int $id;

    #[Column]
    public string $name;
}

Fetching entities

To fetch an entity pass the entity class name and the primary key value to the fetch method. An array can be passed for composite primary keys, where the array key is the column name.

$user = $entity_manager->fetch(User::class, 1);

You may also pass a callable instead of a primary key for more complex WHERE conditions. See the documentation here for more information.

use MichaelRushtwhere\DB\SQL\Components\Where;

$user = $entity_manager->fetch(User::class, function (Where $where)
{
    $where->where('id', 1)
    ->whereNull('deleted_at');
});

The require method is identical to the fetch method except an EntityNotFoundException exception will be thrown if the entity does not exist.

use MichaelRushton\ORM\Exceptions\EntityNotFoundException;

try {
    $user = $entity_manager->require(User::class, 1);
}

catch (EntityNotFoundException $e) {

}

Use the fetchAll method to fetch an array of entities, optionally passing an array of column values (or a callable; see above) to be used as the WHERE condition.

$users = $entity_manager->fetchAll(User::class, ['active' => 1]);

The yield method is identical to the fetchAll method except that a Generator will be returned instead of an array.

$users = $entity_manager->yield(User::class, ['active' => 1]);

Inserting an entity

Use the insert method to insert an entity into the database. If the primary key auto increments then the corresponding property will be set after a successful insert.

$user = new User;
$user->name = 'Michael';

$entity_manager->insert($user);

echo $user->id;

Updating an entity

Use the update method to update an entity's database record.

$user = $entity_manager->require(User::class, 1);

$user->active = 0;

$entity_manager->update($user);

Deleting an entity

Use the delete method to delete an entity's database record.

$user = $entity_manager->require(User::class, 1);

$entity_manager->delete($user);

Querying the database for entities

Use the query method to perform more complex fetches. This method returns a slimmed-down version of the SELECT statement builder documented here. Entities can be retrieved using the fetch, require, fetchAll, or yield methods.

$users = $entity_manager->query(User::class)
->where('active', 1)
->orderBy('id')
->limit(100, 100)
->fetchAll();

The following notable method groups are not supported by the entity query builder:

• distinct (applies by default)
• columns (all, and only, columns from the entity's table will be selected)
• union/except/intersect
• group by
• having

Active records

An Active Record pattern is also available. To use active records, first attach an entity manager to the ActiveRecord class.

use MichaelRushton\ORM\ActiveRecord;

ActiveRecord::setEntityManager($entity_manager);

Defining an active record

Active records must extend the ActiveRecord class, setting the Table and (optionally) PrimaryKey attributes as required. Columns do not need to be defined as they will be accessed using the __get and __set magic methods

#[Table(name: 'users')]
class User extends ActiveRecord {}

Fetching active records

To fetch an active record pass the primary key value to the static fetch method. An array can be passed for composite primary keys, where the array key is the column name.

$user = User::fetch(1);

You may also pass a callable instead of a primary key for more complex WHERE conditions. See the documentation here for more information.

use MichaelRushtwhere\DB\SQL\Components\Where;

$user = User::fetch(function (Where $where)
{
    $where->where('id', 1)
    ->whereNull('deleted_at');
});

The static require method is identical to the fetch method except an EntityNotFoundException exception will be thrown if the active record does not exist.

use MichaelRushton\ORM\Exceptions\EntityNotFoundException;

try {
    $user = User::require(1);
}

catch (EntityNotFoundException $e) {

}

Use the static fetchAll method to fetch an array of active records, optionally passing an array of column values (or a callable; see above) to be used as the WHERE condition.

$users = User::fetchAll(['active' => 1]);

The static yield method is identical to the fetchAll method except that a Generator will be returned instead of an array.

$users = User::yield(['active' => 1]);

Inserting an active record

Use the insert method to insert an active record into the database. If the primary key auto increments then the corresponding property will be set after a successful insert.

$user = new User([
    'name' => 'Michael',
]);

$user->insert();

echo $user->id;

You may also pass an array of column values directly to the insert method. This data will then be merged with any existing data.

$user = new User([
    'name' => 'Michael',
]);

$user->insert([
    'email_address' => '[e-mail]',
]);

The static create method can also be used to insert an active record.

$user = User::create([
    'name' => 'Michael',
]);

Updating an active

Use the update method to update an active record.

$user = User::require(1);

$user->active = 0;

$user->update();

You may also pass an array of column values directly to the update method. This data will then be merged with any existing data.

$user = User::require(1);

$user->update([
    'active' => 0,
]);

Deleting an entity

Use the delete method to delete an active record.

$user = User::require(1);

$user->delete();

Querying the database for active records

Use the static query method to perform more complex fetches. This method returns a slimmed-down version of the SELECT statement builder documented here. Entities can be retrieved using the fetch, require, fetchAll, or yield methods.

$users = User::query()
->where('active', 1)
->orderBy('id')
->limit(100, 100)
->fetchAll();