Download the PHP package ez-php/orm without Composer

ez-php/orm

ORM module for the ez-php framework — Data Mapper pattern with Entity, AbstractRepository, a fluent QueryBuilder, and a Schema builder.

Requirements

• PHP 8.5+
• ext-pdo
• ez-php/framework 0.*

Installation

Setup

Register the service providers:

Usage

Defining an entity

Defining a repository

Persisting

Querying

Large result sets: chunk() pages with LIMIT/OFFSET. chunkById() and lazy() page by key instead (WHERE id > last ORDER BY id) — every page costs the same, and rows the callback updates or deletes do not make later pages skip or repeat rows. Both keep the query's where() clauses and the soft-delete filter; the key column (default id) must be unique and selected:

Column names are validated and quoted in every clause. having() and select() take a plain column or one aggregate over a column or * — COUNT, SUM, AVG, MIN, MAX, optionally DISTINCT (select() also accepts AS alias). For any other SQL expression use selectRaw(), which is emitted verbatim — never pass user input to it:

Soft deletes

Relations

Define relation helpers on the repository, then call them on an entity. Each helper takes the related repository instance, the key columns and the owning entity's key value:

with() already loads a relation for a whole result set in one query. If you instead access relations lazily inside a loop, RelationBatcher (requires ez-php/dataloader) collapses those per-entity queries into one per relation:

hasOne(), hasMany() and belongsToMany() work the same way (hasMany/belongsToMany resolve to a list, empty when there are none). belongsToMany() loads every queued owner through one pivot join:

Custom casts

Entity lifecycle observers

Attach observers to a repository to react to create/update/delete events:

The *ing hooks fire before the DB operation; *ed hooks fire after.

Append-only repositories

For insert-only tables (audit logs, event logs, immutable records) extend AppendOnlyRepository instead of AbstractRepository. create() inserts and returns the entity with its generated primary key; save() and delete() throw LogicException, so the constraint is enforced by the type rather than by convention.

Typed attribute getters

Entity::getAttribute() returns mixed. Use the TypedAttributes trait for typed access that satisfies PHPStan level 9 without per-call narrowing:

getInt()/getString() fall back to a default for non-numeric/non-scalar values; getNullableDatetime() parses Y-m-d H:i:s and returns null otherwise.

Schema builder

Query logging

LoggingDatabase decorates any DatabaseInterface and logs SQL + bindings + duration for every query()/execute() call via ez-php/logging (a soft dependency — install it separately, since it's declared in require-dev here, not require):

Opt-in only — wrap the connection you pass in yourself; nothing logs by default.

Console commands

Both are registered automatically by EntityServiceProvider::boot() when the application implements CommandRegistryInterface (the ez-php Application does). They write relative to the working directory (<cwd>/app/…) — run php ez from the project root.

Classes

License

MIT — Andreas Uretschnig