Creating and grouping value objects

[webdevilopers]

In my Entity EmploymentContract I have the value objects ContractType - "fixed_term" or "permanent" and EmploymentPeriod with "startDate" and "endDate". When the ContractType is "permanent" then the "endDate" should be "null".

My current implementation:

final class EmploymentContract extends AggregateRoot
{
    public static function sign(
        EmploymentContractId $anId, ContractType $aContractType,
        DateTimeImmutable $aStartDate, ?DateTimeImmutable $anEndDate
    ) {
        if ($aContractType->isFixedTerm() && null === $anEndDate) {
            throw new FixedTermContractMustHaveAnEndDateException();
        }

        $employmentPeriod = new EmploymentPeriod($aStartDate, $anEndDate);
    }
}

In this solution the entity (event-sourced aggregate root A+ES) groups the two value objects and protects the invariants / business rules.

In issue #39 we talked about creating Entities through Aggregate roots. No I wonder if this works for value objects too.

Here a two different approaches:

final class EmploymentContract extends AggregateRoot
{
    public static function sign(
        EmploymentContractId $anId, ContractType $aContractType, EmploymentPeriod $aPeriod
    ) {
        // no further validation, the passed value objects are expected too be valid
    }
}

final class EmploymentPeriod
{
    public function __construct(DateTimeImmutable $startDate, ?DateTimeImmutable $endDate)
    {
        if (null !== $endDate) {
            if ($endDate < $startDate) {
                throw new EndDateMustBeGreaterThanStartDateException();
            }
        }

        $this->startDate = $startDate;
        $this->endDate = $endDate;
    }

    public static function withType(
        ContractType $type, DateTimeImmutable $startDate, ?DateTimeImmutable $endDate
    ): EmploymentPeriod
    {
        if ($type->isFixed()) {
            if (null === $endDate) {
                throw new FixedTermContractMustHaveAnEndDateException();
            }
        }

        if ($type->isPermanent()) {
            if (null !== $endDate) {
                throw new PermanentContractMustNotHaveAnEndDateException();
            }
        }

        return new self($startDate, $endDate);
    }
}

Or:

final class EmploymentContract extends AggregateRoot
{
    public static function sign(
        EmploymentContractId $anId, ContractType $aContractType, EmploymentPeriod $aPeriod
    ) {
        // no further validation, the passed value objects are expected too be valid
    }
}

final class ContractType
{
    public function specifyEmploymentPeriod($startDate, $endDate); EmploymentPeriod
    {
        if ($this->isFixed()) {
            if (null === $endDate) {
                throw new FixedTermContractMustHaveAnEndDateException();
            }
        }

        if ($this->isPermanent()) {
            if (null !== $endDate) {
                throw new PermanentContractMustNotHaveAnEndDateException();
            }
        }

        return new EmploymentPeriod($startDate, $endDate);
    }
}

Or should ContractType and EmploymentPeriod event be grouped into a single value object?

Thoughts?

[yvoyer]

Or ContractType is an interface that is in charge of creating the Contract.

inteface ContractType
{
    public function createContract(): EmploymentContract;
}

final class FixedContractType implements ContractType
{
    public function createContract(): EmploymentContract 
    {
        return new FixedContract($this->startDate, $this->endDate)
    }
}

final class PermanentContractType implements ContractType
{
    public function createContract(): EmploymentContract 
    {
        return new PermanentContract($this->startDate)
    }
}

final class FixedContract implements EmploymentContract extends AggregateRoot {}
final class PermanentContract implement EmploymentContract extends AggregateRoot {}

Each EmployementContract would generate distinct event FixedContractSigned and PermanentContractSigned.

Usually when using the Type concept, my development leads to a factory method, while the type is an interface. It allows unit tests to use NullType instead of a mock when needed, and adding new types is easier, as it do not change logics from other type. Or it do not lead to a switch case/ if-else.

This way the invariant are enforced upon the creation of the type. Would it be logical for your case?

[webdevilopers]

Sorry for the late response @yvoyer . I had to think this through for a while. I really like this approach. But currently each "sign" method has about 20 parameters and only differs passing a date for $endDate or NULL. Refactoring the current EmploymentContract Aggregate Root would not be "worth it". The project is almost finished.

But I guess the next time I will try your approach from scratch.

Could I still use a single "Employment Contract Event Store"?

$whateverContract = $sharedContractTypeRepository->ofId($employmentContractId);
$whateverContract->modify($modifyContractCommand);

Or how would you handle the different types "fixed_term" and "permanent" here?

[yvoyer]

The same aggregate could still manage both types:

final class EmploymentContract extends AggregateRoot
{
    protected function onFixedContractWasSigned(FixedContractWasSigned $event): void
    {
        // ...
    }

    protected function onPermanentContractWasSigned(PermanentContractWasSigned $event): void
    {
        // ...
    }

    public static function signed(
        EmploymentContractId $anId,
        ContractType $aContractType
    ) {
        $aggregate = ...;
        $aggregate->applyEvents($aContractType->onSigning($anId));
    }
}

interface ContractType
{
    /**
     * @param EmploymentContractId $id
     * @return DomainEvent[] Events relative to the contract type
     */
    public function onSigning(EmploymentContractId $id): array;
}

final class FixedContractType implements ContractType
{
    private $startDate;
    private $endDate;

    public function __construct(\DateTimeInterface $startDate, \DateTimeInterface $endDate)
    {
        $this->startDate = $startDate;
        $this->endDate = $endDate;
    }

    public function onSigning(EmploymentContractId $id): array
    {
        return [new FixedContractWasSigned($id, $this->startDate, $this->endDate)];
    }
}

final class PermanentContractType implements ContractType
{
    private $startDate;

    public function __construct(\DateTimeInterface $startDate)
    {
        $this->startDate = $startDate;
    }

    public function onSigning(EmploymentContractId $id): array
    {
        return [new PermanentContractWasSigned($id, $this->startDate)];
    }
}

$repos = new EmploymentContractEventStore();
$fixedContract = EmploymentContract::signed(
    $fixedContractId = new EmploymentContractId(),
    new FixedContractType(
        new DateTimeImmutable('2000-01-01'),
        new DateTimeImmutable('2000-12-31')
    )
);
$repos->save($fixedContract);
$repos->getContract($fixedContractId); // Configured as fixed

$permanentContract = EmploymentContract::signed(
    $permanentContractId = new EmploymentContractId(),
    new PermanentContractType(new DateTimeImmutable('2000-01-01'))
);
$repos->save($permanentContract);
$repos->getContract($permanentContractId); // Configured as permanent

If you still need 2 aggregates returned by the same repository, wrap both repos in a single class (using the composite pattern). That way, when fetching an aggregate of type 1, use repos 1, when fetching aggregate of type 2, use repos 2.

Anything is feasible

[pMononoke]

You cannot establish the type of contract without a period of time. ContractType should only be built with EmploymentPeriod.

EmploymentPeriod::withFixedDuraton ($start, $end)
EmploymentPeriod::withVariableDuraton ($start)

should expose a method

EmploymentPeriod->isFixedDuration ();

ContactType accepts EmploymentPeriod in the constructor and determines its own type based on the EmploymentPeriod-> isFixedDuration () method. ContractType should be a simple object, the business roules for dates are in EmploymentPeriod

ContractType::fromEmplymentPeriod($emplymentPeriod);
ContractType->isFixedTerm(); // reflect internal status of EmploymentPeriod->isFixedDuration ()

your aggregate accepts EmplymentPeriod and internally determines the contactType

EmploymentContract::sign(EmploymentContractId $anId, EmploymentPeriod $anEmploymentPeriod);