othercode/complex-heart

Domain driven design tools.

v0.4.7 2023-01-10 14:08 UTC

Requires

• php: ^7.4|^8.0
• ext-json: *
• doctrine/instantiator: ^1.4
• illuminate/collections: ^8.20
• lambdish/phunctional: ^2.1
• nesbot/carbon: ^2.40
• ramsey/uuid: ^4.1
• spatie/data-transfer-object: ^2.6

Requires (Dev)

• fakerphp/faker: ^1.9.1
• mockery/mockery: ^1.4
• phpstan/phpstan: ^0.12.64
• phpunit/phpunit: ^9.3

MIT

• Unay Santisteban

README

About

The Complex Heart name stands from "Domain-Driven Design: Tackling Complexity in the Heart of Software" Eric Evans Book. This project intends to provide a set of useful classes and tools to ease the adoption of Domain Driven Design into your project.

Domain Modeling: Aggregates, Entities and Value Objects

Complex Heart allows you to model your domain Aggregates, Entities, and Value Objects using a set of traits. Great, but why traits and not classes? Well, sometimes you have some kind of inheritance in your classes. Being forced to use a certain base class is too invasive and personally, I don't like it. By using a set of traits and interfaces you have all the functionality you need without compromising the essence of your own domain.

Let's see a very basic example:

use OtherCode\ComplexHeart\Domain\Contracts\ValueObject;
use OtherCode\ComplexHeart\Domain\Traits\IsValueObject;

/**
 * Class Color
 * @method string value()
 */
final class Color implements ValueObject 
{
    use IsValueObject;
    
    private string $value;
 
    public function __construct(string $value) {
        $this->initialize(['value' => $value]);
    }
    
    protected function invariantValueMustBeHexadecimal(): bool {
        return preg_match('/^#(?:[0-9a-fA-F]{3}){1,2}$/', $this->value) === 1;
    }
    
    public function __toString(): string {
        return $this->value();
    }
}

$red = new Color('#ff0000');
$red->equals(new Color('#00ff00')); // false
$red->value(); // #ff0000
$magenta = new Color('ff00ff'); // Exception InvariantViolation: Value must be hexadecimal.

To define a Value Object you only need to use the IsValueObject trait, this will allow you to use some functions like equals() that will automatically compare the value of the objects or initialize() that will allow you to run invariant validations against the object values. Optionally, and recommended, you can use the ValueObject interface.

The available traits are:

• HasAttributes Provide some functionality to manage attributes.
• HasEquality Provide functionality to handle equality between objects.
• HasInvariants Allow invariant checking on instantiation (Guard Clause).
• HasIdentity Define the Entity/Aggregate identity.
• HasDomainEvents Provide domain event management.

On top of those base traits Complex Heart provide ready to use compositions:

• IsModel composed by HasAttributes and HasInvariants
• IsValueObject composed by IsModel and HasEquality
• IsEntity composed by IsModel, HasIdentity, HasEquality
• IsAggregate composed by IsEntity, HasDomainEvents

Service Bus: Commands, Queries and Events

The Service Bus integration contains some basic interfaces (ServiceBus, CommandBus, QueryBus, and EventBus) and classes to build on top of them.

• Message Base DTO to transfer objects between layers.
  • Request
    • Command Command DTO.
    • Event Event DTO.
    • Query Query DTO.
  • Response

Check this small example of the usage:

$response = $queryBus->ask(new GetUserQuery('some-uuid-value'));

Check the wiki for more detailed examples.

References

• Pro Codely TV
• martinFowler.com
• Clean Architecture
• Clean Code
• Domain-Driven Design: Tackling Complexity in the Heart of Software