Download the PHP package wscore/decaorm without Composer

DecaORM

DecaORM is a simple, lightweight data-mapper ORM for PHP 8. It uses PHP 8 attributes to map entity classes to database tables and provides flexible data access via the repository pattern.

Support

PHP: 8.1, 8.2, 8.3, 8.4
Databases: SQLite, MySQL, PostgreSQL

Features

• Attribute mapping — Define mapping with attributes on the entity: #[Table], #[Column], #[Id], etc.
• Repository pattern — Data access logic lives in repositories for clearer, maintainable code.
• Relations — One-to-one, one-to-many, many-to-many, and polymorphic (#[MorphTo], #[MorphToOne]) via #[HasOne], #[HasMany], #[BelongsTo], #[BelongsToOne], #[ManyToMany].
• Lazy loading — Call load() inside a getter so the relation is loaded on first access.
• Batch loading — Load relations for many entities in one query to avoid N+1.
• Identity map — Ensures a single in-memory instance per primary key.
• Dirty tracking — Only changed fields are updated, reducing unnecessary UPDATEs.
• Lifecycle — #[CreatedAt] and #[UpdatedAt] for automatic timestamps.
• Hydrator — Default AttributeHydrator plus support for custom hydrators.
• Explicit design — Behavior is predictable from reading the code.
• Repository hooks — Optional RepositoryHooksInterface for cross-cutting rules (tenant scope, soft delete, optimistic locking); see repository-hooks-en.md.

Not supported

• Unit of Work (UoW) — No automatic save ordering or deferred flush. You must save in dependency order (e.g. parent before children).
• Cascade delete — Deleting a parent does not delete related children; delete them explicitly.
• Eager loading — Relations are not loaded automatically. Use load() (or lazy loading in getters) when needed.

License

MIT License

Installation

Install with Composer:

Documentation

• Entity mapping (entity-en.md)
• SQL builder (sql-en.md)
• Repository hooks (repository-hooks-en.md)

Japanese: Repository hooks

⚠ Raw API safety

whereRaw, havingRaw, joinRaw, withRaw, fromRaw, setRaw, selectRaw, and orderByRaw append SQL fragments as-is. DecaORM does not apply SQL injection protections to these methods.

• Do not concatenate untrusted input (request/user input) into Raw SQL strings.
• Use placeholders (bound parameters) for value conditions.
• Prefer orderBy($column, $direction) for sorting, and use orderByRaw() only when a raw expression is required.
• Do not build table names, column names, or ORDER BY expressions directly from external input.

Quick start

1. Define an entity

Use attributes from WScore\DecaORM\Attribute and implement EntityInterface with EntityTrait.

See entity-en.md for property types and attributes.

2. Implement a repository

Extend AbstractRepository for your entity.

3. Basic CRUD

Relations

Relations are not loaded automatically. Call load() explicitly or use lazy loading in getters.

Parent entity (e.g. User)

Child entity (e.g. Post)

Lazy loading

Calling load($relationName) in a getter loads the relation on first access and returns the cached value afterward.

Associating relations with associate()

Use the public API associate($relationName, $targetOrTargets) to set relations. DecaORM updates FKs and inverse references accordingly.

• BelongsTo / BelongsToOne / HasOne: pass a single entity or null.
• MorphTo / MorphToOne: pass a single entity or null.
• HasMany / ManyToMany: pass an EntityCollection or iterable, or null.

Note: associate() only updates in-memory links. For ManyToMany, call the repository’s syncManyToMany($entity, $relationName) to persist the join table.

Batch loading (avoiding N+1)

Load a relation for many entities in one query.

EntityCollection

Use the collection for filtering, batch loading, and saving.

Many-to-many

Many-to-many uses a join table. Specify the table and column names in the #[ManyToMany] attribute (no separate entity/repository for the join table).

Loading: use $user->load('roles') or batch load: $users->load('roles').

Syncing: use ManyToManyTrait in the repository and call syncManyToMany() after changing the relation on the entity. It will INSERT/DELETE rows in the join table as needed.

Polymorphic (Morph) relations

When a child row can point to more than one parent type (e.g. a comment on either a post or a video), use:

• Child: #[MorphTo] (many-to-one) or #[MorphToOne] (one-to-one on the FK side) with foreignKey, typeColumn (discriminator stored in the DB), and typeMap (discriminator string → entity class). Optional inversedBy matches the parent’s #[HasMany] / #[HasOne] property name.
• Parent: unchanged #[HasMany] / #[HasOne] with mappedBy set to the child’s morph property name.

Loading the morph parent from the child returns a generic Collection, not EntityCollection, because parent instances may belong to different classes. Parents are resolved per child row. There is no extra method on RepositoryInterface; inverse queries are built in MappedByQuery using the usual repository API.

See README-ja.md (Japanese) for a longer explanation and examples.

Saving and dependency order

DecaORM has no Unit of Work. You must save in dependency order (e.g. parent before children).

• Create entities and associate them in memory in any order.
• Save parent first so its ID is set; then save children (FKs are set automatically for BelongsTo/HasMany).
• Use transactions when saving multiple entities.

Example with transaction:

Default container (once at app bootstrap)

Per-request container (e.g. multi-tenant)

OrmManager resolves PDO::class and repository entries from the single container passed to initialize(). After you know the tenant, build a container that already holds that tenant’s PDO (and repositories), then call OrmManager::initialize($container) for that request—or inject an OrmManager constructed for that container. For more than one connection in the same process, use separate OrmManager instances (each has its own identity map and dirty tracker); nested container scopes are not supported.

Summary of limitations

1. Save order — No UoW; save parents before children.
2. Transactions — Use them when saving multiple entities.
3. Relations — Never auto-loaded; call load() when needed.
4. Foreign keys — Use DB constraints for integrity.
5. New vs update — Determined by presence of ID; you can also call insertEntity() or updateEntity() explicitly.