README

A domain-first Read Model library that provides a uniform API for querying read-only data from multiple backends. Define your query logic once; plug in Doctrine ORM, raw SQL, JSON-RPC APIs, or Elasticsearch — or use the built-in in-memory implementation for fast, dependency-free tests.

Installation

composer require kraz/read-model

Additional packages

Install any of the following packages which matches your infrastructure requirements:

Documentation

Full documentation lives in the docs/ directory:

• Getting Started
• Core Concepts
• Filtering & Sorting
• Pagination & Limits
• Specifications
• Testing
• Doctrine Backend
• JSON-RPC Backend
• Elasticsearch Backend

Example usage

Raw SQL

use Kraz\ReadModel\ReadDataProviderInterface;
use Kraz\ReadModelDoctrine\DataSource;
use Kraz\ReadModelDoctrine\DataSourceBuilder;
use Kraz\ReadModelDoctrine\RawQueryReadDataProvider;

class ProductsReadModel implements ReadDataProviderInterface
{
    use RawQueryReadDataProvider;

    public function __construct(private readonly Connection $connection) {}

    protected function createDataSource(): DataSource
    {
        return new DataSourceBuilder()
            ->withData(<<<'SQL'
                SELECT r.* FROM (
                    SELECT p.id, p.name, p.price, c.name AS category
                    FROM product p
                    JOIN category c ON c.id = p.category_id
                    WHERE p.deleted_at IS NULL
                ) r
                /*#WHERE#*/
                /*#ORDERBY_B#*/ORDER BY r.id ASC/*#ORDERBY_E#*/
            SQL)
            ->create($this->connection);
    }    
}

The /*#WHERE#*/ and /*#ORDERBY#*/ markers are replaced automatically with generated SQL when filters and sorts are applied. When nothing is applied they are removed cleanly.

ORM QueryBuilder

use Kraz\ReadModelDoctrine\DoctrineReadDataProvider;

class ProductsReadModel implements ReadDataProviderInterface
{
    use DoctrineReadDataProvider;

    public function __construct(private EntityManagerInterface $em) {}

    protected function createDataSource(): DataSource
    {
        $qb = $this->em->createQueryBuilder()
            ->select('r.id, r.name, r.price')
            ->from(Product::class, 'r');

        return new DataSource($qb);
    }
}

Querying

Both styles share the same query API:

// Filters and sorting
$products = $readModel
    ->withQueryExpression(
        $readModel->qry()
            ->andWhere($readModel->expr()->greaterThan('price', 10))
            ->andWhere($readModel->expr()->equalTo('category', 'tools'))
            ->sortBy('name', SortExpression::DIR_ASC)
    )
    ->withPagination(page: 1, itemsPerPage: 20)
    ->getResult();

// $result->data   — items on this page
// $result->page   — current page
// $result->total  — total matching rows

The query expression is serializable and can be stored and/or transferred as needed.

Acknowledgements

The library uses source code from Doctrine Collections which was modified to meet the required behavior.

License

This library is licensed under the MIT License. See the LICENSE file for details.