Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


GitHub Actions Build Status Issues License PHP Version Current Version

Read-Models are a companion resource to a Doctrine ORM entity based project. They provide an active-record style data access layer, designed for presentational purposes only. This allows your domain objects to remain completely focused on managing your data and not getting sidelined with presentational concerns.

To further highlight this tight integration, read-models uses DBAL and the DBAL type system under-the-hood. Any registered types will be used during model hydration and even embeddables can be reused.

Note that unlike standard active-record packages, there is no write support at all nor will this be added. This package is purely focused on reading and querying data with objects / query builders for use in the presentation layer.

A lot of the internal arrangement is heavily inspired by Laravels Eloquent and other active-record projects including GranadaORM (IdiORM), PHP ActiveRecord and others.

Supported Features

  • active-record query model
  • read-only - no ability to change your db through the built-in methods
  • read-only models - no mutation methods, models are immutable once loaded
  • support for attribute casting
  • support for embedded objects via attribute casting
  • support for exporting as JSON / Array data (configurable)
  • eager loading of relationships including batch loading
  • relationships (1:1, 1:m, m:m, 1:m reversed)
  • identity map
  • pluggable attribute casting / cast to value-objects


  • PHP 8.1+
  • mb_string
  • doctrine/dbal
  • somnambulist/collection


Install using composer, or checkout / pull the files from

  • composer require somnambulist/read-models
  • instantiate Manager with your connection mappings and any attribute casters
  • add models extending the Model class, being sure to set the table name property
  • load some data: <model>::find()

For example:

use Doctrine\DBAL\DriverManager;
use Somnambulist\Components\ReadModels\Manager;
use Somnambulist\Components\ReadModels\TypeCasters\DoctrineTypeCaster;

new Manager(
    User::class => $conn = DriverManager::getConnection(['url' => 'sqlite://db.sqlite']),
    'default'   => $conn,
    new DoctrineTypeCaster($conn),


Extend Somnambulist\Components\ReadModels\Model and add casts, define relationships, exports etc.

class User extends Model
    protected string $table = 'users';

You can add a default table alias by setting the property: $tableAlias. Other defaults can be overridden by defining the property:

class User extends Model
    protected string $table = 'tbl_users';
    protected ?string $tableAlias = 'u';
    protected string $primaryKey = 'uuid';

Note: properties are defined with types and must follow those defined in the base class.

To load a record:

$model = User::find(1);

$results = User::query()->whereColumn('name', 'like', '%bob%')->orderBy('created_at', 'desc')->limit(5)->fetch();

Access properties directly or via method calls:

$model = User::find(1);


You cannot set, unset, or change the returned models.

You can define attribute mutators in the same way as Laravels Eloquent:

class User extends Model
    protected function getUsernameAttribute($username)
        return Str::capitalize($username);

// user:{username: bob was here} -> returns Bob Was Here


Note: these methods should be protected as they expect the current value to be passed from the loaded model attributes.

Or create virtual properties, that exist at run time:

class User extends Model
    protected function getAnniversayDayAttribute()
        return $this->created_at->format('l');

// user:{created_at: '2019-07-15 14:23:21'} -> "Monday"


Or for micro-optimizations, add the method directly:

class User extends Model
    public function anniversayDay()
        return $this->created_at->format('l');

// user:{created_at: '2019-07-15 14:23:21'} -> "Monday"


Note: to access properties via the magic __get/call the property name must be a valid PHP property/method name. Keys that start with numbers (for example), will not work. Any virtual methods / properties should be documented using @property-read tags on the class level docblock comment. Additionally: virtual methods can be tagged using @method.

Note: to get a raw attribute value, use ->getRawAttribute(). This will return null if the attribute is not found, but could also return null for the specified key.

When returning sets of Model objects, the returned set can be customised per model to allow for specific filters on the collection or other behaviour. Override the collectionClass property with the class name to use. This class must implement the Collection contract from the somnambulist/collection project and must have extract() and add() methods.

More Reading

Auto-generated API docs are available in the docs folder.


If you use Symfony; using the standard Doctrine DBAL connection from your entity manager will automatically ensure that ALL SQL queries are added to the profiler without having to do anything else! You get full insight into the query that was executed, the data bound etc. For further insights consider using an application profiler such as:

For other frameworks; as DBAL is used, hook into the Configuration object and add an SQL logger instance that can report to your frameworks profiler.

Test Suite

The test suite uses an SQlite database file named "users.db" that simulates a possible User setup with Roles, Permissions, Contacts and Addresses. Before running the test suite, be sure to generate some test data using: tests/resources/seed.php. This console app has a couple of commands:

  • db:create - builds the table structure
  • db:seed - generate base records and --records=XX random records
  • db:destroy - deletes all test data and tables

For the test suite to run and be able to test various relationships / eager loading etc a reasonable number of test records are needed. The suite was built against a random sample of 150 records.

The DataGenerator attempts some amount of random allocation of addresses, contacts and roles to each user; however data integrity was not the goal, merely usable data.

To run the tests: vendor/bin/phpunit.


A simple active-record style front-end for Doctrine ORM to provide read-only models








No packages published