Merge branch 'release/2.0.0-rc.3'

.github/workflows/tests.yml

@@ -14,7 +14,7 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        php: [ 8.1, 8.2, 8.3 ]
+        php: [ 8.1, 8.2, 8.3, 8.4 ]
 
     steps:
       - name: Checkout Code

CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file. This projec
 
 ## Unreleased
 
+## [2.0.0-rc.3] - 2024-10-13
+
+### Added
+
+- The result class now has a `Result::fail()` static method to create a failed result. This is an alias of the
+  existing `Result::failed()` method.
+- **BREAKING** The `Entity` interface (and therefore the `Aggregate` interface too) now has a `getIdOrFail()` method on
+  it. Although technically breaking, if you are using the `IsEntity` or `IsEntityWithNullableId` traits then this method
+  is already implemented.
+- New `AggregateRoot` interface so that an aggregate root can be distinguished from a regular aggregate or entity.
+
 ## [2.0.0-rc.2] - 2024-07-27
 
 ### Added

docs/.vitepress/config.mts

@@ -40,7 +40,7 @@ export default defineConfig({
                     text: 'Domain Layer',
                     collapsed: false,
                     items: [
-                        {text: 'Entities & Aggregates', link: '/guide/domain/entities'},
+                        {text: 'Aggregates & Entities', link: '/guide/domain/entities'},
                         {text: 'Value Objects', link: '/guide/domain/value-objects'},
                         {text: 'Events', link: '/guide/domain/events'},
                         {text: 'Services', link: '/guide/domain/services'},

docs/guide/domain/entities.md

@@ -1,10 +1,12 @@
-# Entities & Aggregates
+# Aggregates & Entities
 
 The business logic in your domain layer will be defined in terms of the following concepts:
 
 - **Entity** - an object that has an identity and has state that can change in-line with business logic.
-- **Aggregate Roots** - an entity that is the root of an aggregate. An aggregate is a group of entities that are treated
-  as a single unit for the purpose of state changes in line with business logic.
+- **Aggregate** - a group of entities that are treated as a single unit for the purpose of state changes in line with
+  business logic.
+- **Aggregate Root** - an entity that is the root of an aggregate. This is the entity that controls the access and
+  behavior of the other objects in the aggregate.
 - **Value Object** - an object that has no identity and is immutable. It is used to describe a characteristic (or
   characteristics) of an entity, and to define data types specific to the domain that are not represented by primitives.
   (The [next chapter](./value-objects) covers these in detail.)
@@ -75,17 +77,17 @@ This trait provides a method for setting the identifier - `setId()`.
 
 ## Aggregates
 
-To define an aggregate root, use the `Aggregate` interface. For example:
+To define an aggregate root, use the `AggregateRoot` interface. For example:
 
 ```php
 namespace App\Modules\EventManagement\Domain;
 
 use App\Modules\EventManagement\Domain\ValueObjects\Customer;
-use CloudCreativity\Modules\Contracts\Domain\Aggregate;
+use CloudCreativity\Modules\Contracts\Domain\AggregateRoot;
 use CloudCreativity\Modules\Contracts\Toolkit\Identifiers\Identifier;
 use CloudCreativity\Modules\Domain\IsEntity;
 
-class Attendee implements Aggregate
+class Attendee implements AggregateRoot
 {
     use IsEntity;
 
@@ -101,9 +103,13 @@ class Attendee implements Aggregate
 }
 ```
 
-The aggregate interface extends the entity interface - there is no additional functionality. It is used to indicate
-that the entity is the root of an aggregate. In the example, the `Attendee` aggregate root has a `ListOfTickets`,
-which is a value object that holds a list of `Ticket` entities.
+If you want to designate an entity as an aggregate, but one that is not the root of an aggregate, use the `Aggregate`
+interface instead.
+
+The `AggregateRoot` and `Aggregate` interfaces extend the entity interface - there is no additional functionality. They
+are used to indicate that the entity is an aggregate containing other entities, or the root aggregate that controls
+behaviour. In the example, the `Attendee` aggregate root has a `ListOfTickets`, which is a value object that holds a
+list of `Ticket` entities.
 
 ## Identifiers
 
@@ -146,11 +152,11 @@ enforce in the constructor:
 ```php
 namespace App\Modules\EventManagement\Domain;
 
-use CloudCreativity\Modules\Contracts\Domain\Aggregate;
+use CloudCreativity\Modules\Contracts\Domain\AggregateRoot;
 use CloudCreativity\Modules\Contracts\Toolkit\Identifiers\Identifier;
 use CloudCreativity\Modules\Domain\IsEntity;
 
-class Attendee implements Aggregate
+class Attendee implements AggregateRoot
 {
     use IsEntity;
 

docs/guide/domain/events.md

@@ -167,10 +167,10 @@ use App\Modules\EventManagement\Domain\{
    Enums\CancellationReasonEnum,
    Events\AttendeeTicketWasCancelled,
 };
-use CloudCreativity\Modules\Contracts\Domain\Aggregate;
+use CloudCreativity\Modules\Contracts\Domain\AggregateRoot;
 use CloudCreativity\Modules\Contracts\Toolkit\Identifiers\Identifier;
 
-class Attendee implements Aggregate
+class Attendee implements AggregateRoot
 {
     // ...other methods
 

docs/guide/toolkit/results.md

@@ -23,6 +23,7 @@ return Result::ok();
 
 // failure
 return Result::failed('Something went wrong.');
+return Result::fail('Something went wrong.'); // alias for "failed"
 ```
 
 Calling code can check whether the result object represents a success or failure using the `didSucceed()` or

docs/guide/upgrade.md

@@ -116,8 +116,8 @@ updated [Integration Events Chapter.](./application/integration-events)
 
 ### Aggregates & Entities
 
-Aggregates must now implement the `Contracts\Domain\Aggregate` interface. Likewise, for entities the interface is
-now `Contracts\Domain\Entity`. The traits have been renamed as follows:
+Aggregates must now implement either the `Contracts\Domain\AggregateRoot` or `Contracts\Domain\Aggregate` interfaces.
+Likewise, for entities the interface is now `Contracts\Domain\Entity`. The traits have been renamed as follows:
 
 - `Domain\EntityTrait` is now `Domain\IsEntity`
 - `Domain\EntityWithNullableIdTrait` is now `Domain\IsEntityWithNullableId`.