MicroOrm for PHP

A small ORM that maps any class to a table, and lets you choose the pattern per entity: Repository, Data Mapper or Active Record.

Why

Full ORMs pick the pattern for the whole application: Eloquent is Active Record and your models extend its base class, Doctrine is Data Mapper with its unit of work. Changing your mind later means rewriting the models.

MicroORM maps a plain class (public properties, or getters and setters) with attributes or a separate Mapper, and every way of using it shares that mapper:

$repository = new Repository($executor, User::class);   // Repository + Data Mapper
$user = $repository->get(1);

$user = User::get(1);                                   // Active Record (the ActiveRecord trait)

• Choose the pattern per entity. A simple lookup table can be Active Record while the entity with the business rules gets a repository. See Choosing a Pattern.
• Observers on every write. An observer is notified of each insert, update and delete on its table, whatever code path made the write.

Key Features:

• Can be used with any DTO, Entity, Model or whatever class with public properties or with getter and setter
• The repository support a variety of datasources: MySql, Sqlite, Postgres, MySQL, Oracle (see byjg/anydataset)
• A class Mapper is used for mapping the Entity and the repository
• Powerful mapper functions for automatic data transformation between models and database
• Small and simple to use

Architecture

MicroORM implements Martin Fowler's enterprise patterns:

• Repository: Mediates between domain and data mapping layers
• Data Mapper: Separates domain objects from database tables
• Active Record: Wraps database rows with domain logic, as a facade over the two above

They are layers, not alternatives. The Mapper (Data Mapper) and the Repository are always there; the ActiveRecord trait is a facade that creates them for the model. What you choose is where the mapping lives (a Mapper object or attributes on the model) and where the persistence calls live (a repository or the model itself). See Choosing a Pattern.

These are the key components:

┌──────────────────────────┐
│ Repository               │              ┌─────────────────────┐
│                          │         ┌────│        Model        │
│                          │         │    └─────────────────────┘
│          ┌───────────────┴─────┐   │               │
│          │       Mapper        │───┤               │
│          └───────────────┬─────┘   │               │
│                     │    │         │    ┌─────────────────────┐
│                     │    │         └────│    FieldMapping     │
│                     │    │              └─────────────────────┘
│                     │    │
│          ┌───────────────┴─────┐
│          │        Query        │
│          └───────────────┬─────┘
│                     │    │
│          ┌───────────────┴─────┐        ┌──────────────────────┐  
│          │  DatabaseExecutor   │────────│   DbDriverInterface  │  
│          └───────────────┬─────┘        └────────────┬─────────┘  
│                          │                           │                
└──────────────────────────┘                      .─────────.           
                                                 │           │          
                                                 │`─────────'│          
                                                 │           │          
                                                 │    DB     │          
                                                 │           │          
                                                 │           │          
                                                  `─────────'           

• Model can be any class with public properties or with getter and setter. It is used to retrieve or save the data into the database
• Mapper defines the relationship between the Model properties and the database fields
• FieldMapping defines individual field mappings within the Mapper (field names, transformations, relationships via parentTable)
• Query defines what to retrieve from/update in the database. It uses the Mapper to prepare the query to the database converting the Model properties to database fields
• DatabaseExecutor (external package) wraps the DbDriver and provides transaction management, query execution, and access to database helpers
• DbDriverInterface (external package) is the actual database driver implementation that connects to the database
• Repository orchestrates all MicroORM components and uses DatabaseExecutor to interact with the database

For a detailed explanation of the architecture and when to use each layer, see Architecture Layers: Infrastructure vs Domain.

Getting Started

Table Structure

We have the following table structure in the database for this example:

CREATE TABLE `mytable` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `name` varchar(255) DEFAULT NULL,
  `company_id` int(11) DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

We want to be able to interact with this table using the ORM.

Defining the Model

A Model in our context is a class that symbolizes the data you wish to store or fetch from the database. This Model class can be as simple as a class with public properties. Alternatively, it can be a class equipped with getter and setter methods for more controlled access and manipulation of the data.

To map the database fields, you can add attributes to the Model class. Each property in the Model class represents a field in the database.

Let's look at an example:

#[TableAttribute(tableName: 'mytable')]
class MyModel
{
    #[FieldAttribute(primaryKey: true)]
    public ?int $id = null;

    #[FieldAttribute()]
    public ?string $name = null;

    #[FieldAttribute(fieldName: 'company_id')]
    public ?int $companyId = null;
}

In this example, we have a class MyModel with three properties: id, name, and companyId.

• The id property is marked as a primary key.
• The name property is a simple field.
• The companyId property is a field with a different name in the database company_id.

The TableAttribute is used to define the table name in the database.

Connecting the repository

After defining the Model, you can connect the Model with the repository.

$dbDriver = \ByJG\AnyDataset\Db\Factory::getDbInstance('mysql://user:password@server/schema');
$executor = \ByJG\AnyDataset\Db\DatabaseExecutor::using($dbDriver);
$repository = new \ByJG\MicroOrm\Repository($executor, MyModel::class);

Querying the database

You can query the database using the repository.

$myModel = $repository->get(1);

or

$query = Query::getInstance()
    ->field('name')
    ->where('company_id = :cid', ['cid' => 1]);

$result = $repository->getByQuery($query);

or, the same example above:

$filterModel = $repository->entity([
    'company_id' => 1
]);

$query = $repository->queryInstance($filterModel);
$query->field('name');

$result = $repository->getByQuery($query);

Basics

• Defining the Model
• Choosing a Pattern
• Querying the Database
• Updating the database
• Using the Mapper Object
• The Model Attributes
• The Repository Class
• Common Traits for Timestamp Fields
• Architecture Layers: Infrastructure vs Domain
• Comparison with Other ORMs (Eloquent, Doctrine)

Advanced Topics

• Active Record
• Auto Discovering Relationship
• The Literal Object
• Soft Delete
• Caching the Results
• Observing the Database
• Controlling the data queried/updated
• Mapper Functions
• Using FieldAlias
• Tables without auto increments fields
• Using With Recursive SQL Command
• QueryRaw (raw SQL)
• Update Constraints
• Building SQL Queries
• UUID Support

Related Projects

• Database Migration
• Anydataset
• PHP Rest Template
• USDocker
• Serializer

Installation

Just type:

composer require "byjg/micro-orm"

Running Tests

./vendor/bin/phpunit

---

Open source ByJG