Data and ORM

The ORM gives you a few layers to work with persisted data:

  • entities model stored shape
  • repositories handle entity-scoped CRUD work
  • the entity manager coordinates broader persistence workflows
  • the query builder gives you lower-level SQL-family control when you need it

The supported SQL family today is:

  • MySQL
  • MariaDB
  • PostgreSQL
  • SQLite
  • MSSQL

In Assegai, modules point to a data_source rather than a database. That keeps the configuration centered on a named persistence endpoint instead of assuming one specific SQL engine.

What this section teaches

By the end of this track, you should understand:

  • what a data source is and why the framework uses that term
  • how to configure the ORM in a standalone project or an Assegai app
  • how entities map PHP classes to stored records
  • how relations model ownership and navigation between entities
  • how migrations keep schema changes deliberate and repeatable
  • when to use repositories, when to use the entity manager, and when to drop to the query builder
  • how driver choice affects configuration and query fluency

Recommended reading path

Read these in order if you are new to the ORM:

  1. Getting Started
  2. Data Sources
  3. Entities
  4. Relations
  5. Migrations
  6. Working with Entity Manager
  7. Query Builder
  8. Drivers

Two practical starting paths

If you are building an Assegai app, the smoothest route is usually:

  1. assegai add orm
  2. use the CLI to configure the data source for your driver
  3. use assegai database:setup ... and assegai migration:setup ... when that fits your backend
  4. set a module-level data_source
  5. inject a repository into a service

If you are using the ORM without Assegai, the smoothest route is usually:

  1. composer require assegaiphp/orm
  2. enable only the PDO extension for the driver you want
  3. configure OrmRuntime or create a DataSource directly
  4. fetch a repository or work through the entity manager

A mental model that holds up

If the ORM feels abstract at first, this model usually helps:

  • a driver knows how to speak to a specific backend family such as MySQL or PostgreSQL
  • a data source is a named configured store that uses one of those drivers
  • an entity describes how a PHP class maps to stored data
  • a repository is the everyday entity-scoped API for CRUD-style work
  • the entity manager is the broader coordination layer underneath repositories
  • the query builder is the lower-level fluent API for SQL-family work when repository options are not enough
  • migrations capture schema changes so environments do not drift apart

Where to go next

If you want the fastest route to a working feature, start with Getting Started.

If you already know you need to reason about configuration first, jump straight to Data Sources.