Building Domain Events with PHP shows how to apply a focused PHP technique using understandable, runnable examples and clearly defined constraints.
What Problem Does This Solve?
Model domain invariants in constructors and methods; separate expected validation failures from infrastructure errors and avoid hiding exceptions.
Core Concepts
- Identify the data entering the operation and the expected output.
- Model domain invariants in constructors and methods; separate expected validation failures from infrastructure errors and avoid hiding exceptions.
- Handle expected failures and test boundary conditions rather than assuming success.
Example 1: A Small Working Example
Start with a small input so the behavior is easy to follow.
<?php
readonly class OrderCreated { public function __construct(public int $orderId, public DateTimeImmutable $occurredAt) {} }
$event = new OrderCreated(42, new DateTimeImmutable("2026-01-01T10:00:00+00:00"));
echo $event->orderId;
The object validates its state at construction and prevents later modification of promoted readonly properties. This makes invalid domain values harder to create accidentally.
Example 2: A Different Case
The second example changes the task or data while using the same general technique.
<?php
readonly class AccountActivated { public function __construct(public int $accountId) {} }
$events = [new AccountActivated(10), new AccountActivated(11)];
echo count($events);
The object validates its state at construction and prevents later modification of promoted readonly properties. This makes invalid domain values harder to create accidentally.
Practical Example
This practical example is a complete standalone PHP snippet to adapt to a real application.
<?php
readonly class AccountActivated { public function __construct(public int $accountId) {} }
$events = [new AccountActivated(10), new AccountActivated(11)];
echo count($events);
// Inspect the next distinct state after the operation.
echo "\nSecond scenario complete";
The object validates its state at construction and prevents later modification of promoted readonly properties. This makes invalid domain values harder to create accidentally.
Important Behavior and Edge Cases
- Validate XML size and disable untrusted external resource loading. XMLReader is forward-only; DOM materializes a tree and can consume much more memory.
- Model domain invariants in constructors and methods; separate expected validation failures from infrastructure errors and avoid hiding exceptions.
- Test a malformed input, a missing dependency and a boundary value when those cases apply.
Comparison With Related Approaches
| Approach | Trade-off |
|---|---|
| Building Domain Events | Model domain invariants in constructors and methods; separate expected validation failures from infrastructure errors and avoid hiding exceptions. |
| Related PHP approach | Immutable value objects protect validated state; mutable arrays are more flexible but cannot enforce invariants automatically. |
Common Beginner Mistakes
| Mistake | Correct Approach |
|---|---|
| Skipping a relevant boundary or security check | Validate XML size and disable untrusted external resource loading. XMLReader is forward-only; DOM materializes a tree and can consume much more memory. |
| Choosing a technique without considering its trade-off | Immutable value objects protect validated state; mutable arrays are more flexible but cannot enforce invariants automatically. |
| Assuming sample data behaves like production input | Test missing fields, unexpected types, failures and the application’s actual trust boundaries. |
Key Takeaways
- Model domain invariants in constructors and methods; separate expected validation failures from infrastructure errors and avoid hiding exceptions.
- Immutable value objects protect validated state; mutable arrays are more flexible but cannot enforce invariants automatically.
- Write tests around the inputs and failure cases most likely in your application.
Use these examples as a starting point and adapt the validations and boundaries to the specific application.