Download the PHP package marekskopal/orm without Composer

ORM

A lightweight Object-Relational Mapping (ORM) library for PHP.

Features

• Simple and intuitive declaration of entities by adding Column Attributes to class properties
• Supports various property types including Uuid, DateTime and Enums
• Handles one-to-many, many-to-one, one-to-one, and many-to-many relationships
• Query provider for database interactions
• Migration module for creating and updating database schema
• Very fast in comparison to other ORM libraries - see benchmarks

Supported Databases

• MySQL
• PostgreSQL
• SQLite

Installation

Install via Composer:

Basic Usage

Entity Declaration

You can declare entities by adding Entity attribute to class and Column attribute to class properties.

Table and column names are derived from class name and parameters, but can be customized by providing additional parameters to attributes.

Relationships

ManyToOne and OneToMany

OneToOne

Use #[OneToOne] for a unique relationship between two entities. The owning side holds the foreign key column; the inverse side uses mappedBy pointing to the owning property name.

ManyToMany

Use #[ManyToMany] for a join-table relationship. The owning side declares the join table and column names; the inverse side uses mappedBy.

Column names default to the entity short name with an Id suffix (e.g. user_id, tag_id) when not specified explicitly.

Cascade Operations

Relations support cascade operations via the cascade parameter. Supported values are CascadeEnum::Persist and CascadeEnum::Remove.

CascadeEnum::Persist — when persist() is called on the owning entity, all related entities are persisted automatically:

CascadeEnum::Remove — when delete() is called on the owning entity, all related entities are deleted automatically before the owner (to avoid FK constraint violations):

Cascade is supported on OneToMany, ManyToOne, OneToOne, and ManyToMany relations. For ManyToMany, cascade remove deletes the join table rows; cascade persist syncs the join table after persisting.

Dates

You can use DateTime or DateTimeImmutable properties in entities. The library will automatically convert datetime or timestamp columns values to those to objects.

Enums

You can use native PHP enums in entities. The library will automatically convert enum column values to enum objects.

Repository declaration

You can declare you repositories by extending AbstractRepository class and providing repository class in Entity attribute on entity class.

Queries

You can use QueryProvider to create queries.

Select

You can create select queries using Select builder.

Where

You can use where method to filter results.

Multiple AND conditions can be crated either by passing array of conditions or by chaining where method.

OR conditions can be created by using orWhere method.

You can also use where method with nested conditions by passing function.

You can pass another instance of Select object to where method to create subquery.

Eager loading relations (with)

By default, ManyToOne and OneToOne relations are loaded lazily — accessing the relation property triggers a query the first time. When iterating result sets that traverse such relations, this leads to N+1 queries (one extra query per row).

Use with() to eager-load related entities in a single batched WHERE id IN (...) query, regardless of how many parent rows you have.

Eager loading is currently supported for ManyToOne and OneToOne relations.

Insert

You can insert entities using Insert builder.

Insert multiple entities

You can insert multiple entities at once in one insert query.

On PostgreSQL and SQLite the generated primary keys are read back via INSERT ... RETURNING, so the assigned ids are always exact. MySQL has no RETURNING; ids are derived from lastInsertId() plus row offset, which relies on auto-increment values within one statement being consecutive. That is guaranteed with innodb_autoinc_lock_mode 0 or 1, but not with mode 2 (the MySQL 8 default) under concurrent insert load. If you batch-insert on MySQL with lock mode 2 and concurrent writers, either set innodb_autoinc_lock_mode = 1 or persist entities one at a time.

Update

You can update entities using Update builder.

Delete

You can delete entities using Delete builder.

Delete multiple entities

You can delete multiple entities at once in one delete query.

Transactions

Use getTransactionProvider() to run operations inside a database transaction. The callback is committed on success and automatically rolled back if any exception is thrown.

You can also manage the transaction manually:

Nesting transactions is not supported — calling transaction() inside an active transaction throws a TransactionException.

Long-running applications

If you are using ORM in long-running PHP applications like FrankenPHP, Roadrunner or Swoole, you should call clear method on ORM cache after each request to free memory.

Security considerations

All values in queries are bound through prepared-statement placeholders. Column names are restricted to [A-Za-z0-9_]+ and quoted, and where-condition operators are validated against an allowlist (=, !=, <>, <, <=, >, >=, LIKE, NOT LIKE, IN, NOT IN), so user input can safely be passed as values, column names, or operators — invalid input throws InvalidArgumentException instead of reaching the database.

Raw SQL expressions

SQL expressions (function calls, computed columns) must be wrapped in RawExpression, which is used verbatim in the query:

Never build a RawExpression from user input — it bypasses all escaping and validation.

Exception messages

QueryException and ConstrainException carry the executed SQL (via getQuery()) and the raw driver error message. Log them server-side, but never render them to end users — they disclose schema and query structure.

LIKE wildcards

Values bound to LIKE conditions are safely parameterized, but % and _ inside the value still act as wildcards. If user input must be matched literally, escape those characters yourself (e.g. addcslashes($value, '%_\\') on MySQL/PostgreSQL).