PHPackages                             tiny-blocks/building-blocks - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. tiny-blocks/building-blocks

ActiveLibrary[Utility & Helpers](/categories/utility)

tiny-blocks/building-blocks
===========================

Implements tactical DDD building blocks for PHP: entities, aggregate roots, domain events, snapshots, and upcasters.

5.1.0(1mo ago)1821MITPHP ^8.5

Since Apr 18Compare

[ Source](https://github.com/tiny-blocks/building-blocks)[ Packagist](https://packagist.org/packages/tiny-blocks/building-blocks)[ Docs](https://github.com/tiny-blocks/building-blocks)[ RSS](/packages/tiny-blocks-building-blocks/feed)WikiDiscussions Synced 3w ago

READMEChangelog (10)Dependencies (21)Versions (11)Used By (1)

Building Blocks
===============

[](#building-blocks)

[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](https://github.com/tiny-blocks/building-blocks/blob/main/LICENSE)

- [Overview](#overview)
- [Installation](#installation)
- [How to use](#how-to-use)
    - [Entity](#entity)
        - [Single-field identity](#single-field-identity)
        - [Compound identity](#compound-identity)
        - [Identity access on entities](#identity-access-on-entities)
    - [Aggregate](#aggregate)
    - [Domain events with transactional outbox](#domain-events-with-transactional-outbox)
        - [Declaring events](#declaring-events)
        - [Emitting events from the aggregate](#emitting-events-from-the-aggregate)
        - [Draining events](#draining-events)
        - [Restoring aggregate version on reload](#restoring-aggregate-version-on-reload)
        - [Constructing event records directly](#constructing-event-records-directly)
    - [Integration events and the Anti-Corruption Layer](#integration-events-and-the-anti-corruption-layer)
        - [Declaring integration events](#declaring-integration-events)
        - [Writing a translator](#writing-a-translator)
        - [Registering translators](#registering-translators)
        - [Constructing integration event records directly](#constructing-integration-event-records-directly)
    - [Event sourcing](#event-sourcing)
        - [Applying events to state](#applying-events-to-state)
        - [Creating a blank aggregate](#creating-a-blank-aggregate)
        - [Replaying an event stream](#replaying-an-event-stream)
    - [Snapshots](#snapshots)
        - [Capturing aggregate state](#capturing-aggregate-state)
        - [Taking a snapshot](#taking-a-snapshot)
        - [Persisting snapshots](#persisting-snapshots)
        - [Built-in conditions](#built-in-conditions)
    - [Upcasting](#upcasting)
        - [Defining an upcaster](#defining-an-upcaster)
        - [Chaining upcasters](#chaining-upcasters)
        - [Default values for new fields](#default-values-for-new-fields)
- [FAQ](#faq)
- [License](#license)
- [Contributing](#contributing)

Overview
--------

[](#overview)

The `Building Blocks` library provides the tactical design building blocks of Domain-Driven Design: `Entity`, `Identity`, `AggregateRoot`, and the infrastructure required to carry domain events through a transactional outbox or an event-sourced store.

This library implements the tactical patterns from Evans (Entity, Identity, Aggregate Root, Value Object) and Vernon (Domain Event) together with pragmatic extensions that production code needs but the original DDD literature does not address: aggregate versioning for optimistic offline locking (Fowler PEAA), model versioning and rolling snapshots for event-sourced aggregates (Greg Young), event upcasting for schema evolution (Greg Young), and an event envelope decoupling domain events from infrastructure metadata (Hohpe/Woolf EIP). Every extension is annotated in its own PHPDoc with its source.

Domain events defined here are plain PHP objects fully compatible with any PSR-14 dispatcher. The library does not replace PSR-14, it defines what flows through it. Serialization to wire formats is delegated to adapters such as [`tiny-blocks/outbox`](https://github.com/tiny-blocks/outbox).

Installation
------------

[](#installation)

```
composer require tiny-blocks/building-blocks

```

How to use
----------

[](#how-to-use)

The library exposes three styles of aggregate modeling through sibling interfaces:

- `AggregateRoot` for plain DDD modeling without events.
- `EventualAggregateRoot` for aggregates that persist state and emit events as side effects via a transactional outbox.
- `EventSourcingRoot` for aggregates whose state is derived entirely from their ordered event stream.

### Entity

[](#entity)

Every entity declares which property holds its `Identity`. By default, the property is named `id`, aggregates with a differently named property override `identityProperty()`.

#### Single-field identity

[](#single-field-identity)

- `SingleIdentity`: identity backed by a single scalar value (UUID, auto-increment integer, slug).

    ```