PHPackages                             complex-heart/domain-events - 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. complex-heart/domain-events

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

complex-heart/domain-events
===========================

Domain event toolset for building rich domain events.

v1.0.0(1mo ago)0831MITPHPPHP ^8.2CI passing

Since Mar 15Pushed 1mo agoCompare

[ Source](https://github.com/ComplexHeart/php-domain-events)[ Packagist](https://packagist.org/packages/complex-heart/domain-events)[ RSS](/packages/complex-heart-domain-events/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (5)Versions (2)Used By (1)

Domain Events
=============

[](#domain-events)

[![Tests](https://github.com/ComplexHeart/php-domain-events/actions/workflows/test.yml/badge.svg)](https://github.com/ComplexHeart/php-domain-events/actions/workflows/test.yml)[![Quality Gate Status](https://camo.githubusercontent.com/4a3d65509da6bfff049df6ec7f5dec12949889bb3d47da6898d4b5a3ca1eb285/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d436f6d706c657848656172745f7068702d646f6d61696e2d6576656e7473266d65747269633d616c6572745f737461747573)](https://sonarcloud.io/summary/new_code?id=ComplexHeart_php-domain-events)[![Coverage](https://camo.githubusercontent.com/2bc88f4f29fa107e97dc7ab8bc8635c9d667e0ee457f56146213435e3fdf45d1/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d436f6d706c657848656172745f7068702d646f6d61696e2d6576656e7473266d65747269633d636f766572616765)](https://sonarcloud.io/summary/new_code?id=ComplexHeart_php-domain-events)

Building Rich Domain Events
---------------------------

[](#building-rich-domain-events)

Complex Heart Domain Events provides a trait-based implementation of the `Event` contract from [php-contracts](https://github.com/ComplexHeart/php-contracts). It auto-generates event metadata so you can focus on defining what happened in your domain without boilerplate.

The available trait:

- `IsDomainEvent` Implements the `Event` contract with auto-generated `eventId`, `eventName`, `payload`, and `occurredOn`.

Key Features
------------

[](#key-features)

- **Auto-Generated Event ID**: Each event instance gets a unique UUID v4 identifier
- **Convention-Based Event Name**: Derives a dotted event name from the class name (`OrderPlaced` → `order.placed`)
- **Automatic Payload**: Builds the payload from public properties via reflection
- **ISO-8601 Timestamps**: Records when the event occurred
- **Factory Method**: Uses `new()` / `make()` static factories consistent with the ComplexHeart ecosystem
- **Framework Agnostic**: Pure PHP, no framework dependencies — works with Laravel, Symfony, or standalone
- **PHPStan Level 8**: Complete static analysis support

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

[](#installation)

```
composer require complex-heart/domain-events
```

Usage
-----

[](#usage)

Define your domain events as simple final classes with public readonly properties:

```
use ComplexHeart\Domain\Contracts\Events\Event;
use ComplexHeart\Domain\Events\IsDomainEvent;

final class OrderPlaced implements Event
{
    use IsDomainEvent;

    public function __construct(
        public readonly string $orderId,
        public readonly string $customerId,
        public readonly float $total,
    ) {
    }
}
```

Create events using the static factory:

```
$event = OrderPlaced::new(
    orderId: 'order-123',
    customerId: 'customer-456',
    total: 99.95,
);

$event->eventId();    // "a1b2c3d4-e5f6-..." (auto-generated UUID)
$event->eventName();  // "order.placed"
$event->payload();    // ['orderId' => 'order-123', 'customerId' => 'customer-456', 'total' => 99.95]
$event->occurredOn(); // "2026-03-15T10:30:00+00:00"

// Direct property access also works
$event->orderId;      // "order-123"
```

Integration with Aggregates
---------------------------

[](#integration-with-aggregates)

Domain events are designed to work with aggregates that use the `HasDomainEvents` trait from [php-domain-model](https://github.com/ComplexHeart/php-domain-model):

```
use ComplexHeart\Domain\Contracts\Model\Aggregate;
use ComplexHeart\Domain\Model\IsAggregate;

class Order extends Model implements Aggregate
{
    use IsAggregate;

    public static function place(string $id, string $customerId, float $total): static
    {
        $order = static::new(id: $id, customerId: $customerId, total: $total);
        $order->registerDomainEvent(
            OrderPlaced::new(orderId: $id, customerId: $customerId, total: $total)
        );
        return $order;
    }
}
```

Then publish events through an `EventBus` implementation in your use case:

```
final readonly class PlaceOrder
{
    public function __construct(
        private OrderRepository $orders,
        private EventBus $eventBus,
    ) {
    }

    public function __invoke(string $id, string $customerId, float $total): Order
    {
        $order = Order::place($id, $customerId, $total);
        $this->orders->store($order);
        $order->publishDomainEvents($this->eventBus);
        return $order;
    }
}
```

For more information and usage examples, please check the wiki.

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance89

Actively maintained with recent releases

Popularity13

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

56d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/7958790dcf5cd51ebbadc52fc7bada326fb3edd4481decf1006e6cfed8e46c43?d=identicon)[usantisteban](/maintainers/usantisteban)

---

Top Contributors

[![othercodes](https://avatars.githubusercontent.com/u/4815856?v=4)](https://github.com/othercodes "othercodes (3 commits)")

---

Tags

ddddomaindomain-driven-designdomain-eventsevent-sourceevents

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/complex-heart-domain-events/health.svg)

```
[![Health](https://phpackages.com/badges/complex-heart-domain-events/health.svg)](https://phpackages.com/packages/complex-heart-domain-events)
```

###  Alternatives

[grumpydictator/firefly-iii

Firefly III: a personal finances manager.

22.8k69.3k](/packages/grumpydictator-firefly-iii)[pocketmine/pocketmine-mp

A server software for Minecraft: Bedrock Edition written in PHP

3.5k74.6k86](/packages/pocketmine-pocketmine-mp)[shlinkio/shlink

A self-hosted and PHP-based URL shortener application with CLI and REST interfaces

4.8k4.3k](/packages/shlinkio-shlink)[getdkan/dkan

DKAN Open Data Catalog

385135.4k2](/packages/getdkan-dkan)[firefly-iii/data-importer

Firefly III Data Import Tool.

7545.8k](/packages/firefly-iii-data-importer)[tomaj/hermes

Simple php background processing library

38251.0k5](/packages/tomaj-hermes)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)