Проектирование сущностей предметной области

{
    id: 25
    name: {
        last: 'Пупкин',
        first: 'Василий',
        middle: 'Петрович',
    },
    address: {
        country: 'Россия',
        state: 'Липецкая обл.',
        city: 'г. Пушкин',
        street: 'ул. Ленина',
        house: 25
    }
    phones: [
        {country: 7, code: 920, number: 0000001},
        {country: 7, code: 910, number: 0000002},
    ],
    create_date: '2016-04-12 12:34:00',
    current_status = 'active',
    statuses: [
        {status: 'active', date: '2016-04-12 12:34:07'},
        {status: 'archive', date: '2016-04-13 12:56:23'},
        {status: 'active', date: '2016-04-16 14:02:10'},
    ];
}

$employee = new Employee(
    new Id(25),
    new \DateTimeImmutable(),
    new Name('Пупкин', 'Василий', 'Петрович'),
    new Address('Россия', 'Липецкая обл.', 'г. Пушкин', 'ул. Ленина', 25),
    [
        new Phone(7, '920', '00000001'),
        new Phone(7, '910', '00000002'),
    ]
);

namespace tests\unit\entities\Employee;
 
use app\entities\Employee\Address;
use app\entities\Employee\Employee;
use app\entities\Employee\Id;
use app\entities\Employee\Name;
use app\entities\Employee\Phone;
use Codeception\Test\Unit;
 
class CreateTest extends Unit
{
    public function testSuccess(): void
    {
        $employee = new Employee(
            $id = new Id(25),
            $date = new \DateTimeImmutable(),
            $name = new Name('Пупкин', 'Василий', 'Петрович'),
            $address = new Address('Россия', 'Липецкая обл.', 'г. Пушкин', 'ул. Ленина', 25),
            $phones = [
                new Phone(7, '920', '00000001'),
                new Phone(7, '910', '00000002'),
            ]
        );
 
        $this->assertEquals($id, $employee->getId());
        $this->assertEquals($date, $employee->getCreateDate());
        $this->assertEquals($name, $employee->getName());
        $this->assertEquals($address, $employee->getAddress());
        $this->assertEquals($phones, $employee->getPhones());
    }
}

$id = new Id(25);

$id = new Id(Uuid::uuid4()->toString());

$id = new Id(Uuid::uuid4()->toString());

$id = Id::next();

class CreateTest extends Unit
{
    public function testSuccess(): void
    {
        $employee = new Employee(
            $id = Id::next(),
            $date = new \DateTimeImmutable(),
            $name = new Name('Пупкин', 'Василий', 'Петрович'),
            $address = new Address('Россия', 'Липецкая обл.', 'г. Пушкин', 'ул. Ленина', 25),
            $phones = [
                new Phone(7, '920', '00000001'),
                new Phone(7, '910', '00000002'),
            ]
        );
 
        $this->assertEquals($id, $employee->getId());
        $this->assertEquals($date, $employee->getCreateDate());
        $this->assertEquals($name, $employee->getName());
        $this->assertEquals($address, $employee->getAddress());
        $this->assertEquals($phones, $employee->getPhones());
 
        $this->assertNotNull($employee->getCreateDate());
 
        $this->assertTrue($employee->isActive());
 
        $this->assertCount(1, $statuses = $employee->getStatuses());
        $this->assertTrue(end($statuses)->isActive());
 
        $this->assertNotEmpty($events = $employee->releaseEvents());
        $this->assertInstanceOf(EmployeeCreated::class, end($events));
    }
}

class CreateTest extends Unit
{
    ...
 
    public function testWithoutPhones(): void
    {
        $this->expectExceptionMessage('Employee must contain at least one phone.');
 
        new Employee(
            Id::next(),
            new \DateTimeImmutable(),
            new Name('Пупкин', 'Василий', 'Петрович'),
            new Address('Россия', 'Липецкая обл.', 'г. Пушкин', 'ул. Ленина', 25),
            []
        );
    }
 
    public function testWithSamePhoneNumbers(): void
    {
        $this->expectExceptionMessage('Phone already exists.');
 
        new Employee(
            Id::next(),
            new \DateTimeImmutable(),
            new Name('Пупкин', 'Василий', 'Петрович'),
            new Address('Россия', 'Липецкая обл.', 'г. Пушкин', 'ул. Ленина', 25),
            [
                new Phone(7, '920', '00000001'),
                new Phone(7, '920', '00000001'),
            ]
        );
    }
}

namespace tests\unit\entities\Employee;
 
use app\entities\Employee\Address;
use app\entities\Employee\Employee;
use app\entities\Employee\Id;
use app\entities\Employee\Name;
use app\entities\Employee\Phone\Phone;
 
class EmployeeBuilder
{
    private $id;
    private $date;
    private $name;
    private $address;
    private $phones = [];
    private $archived = false;
 
    public function __construct()
    {
        $this->id = Id::next();
        $this->date = new \DateTimeImmutable();
        $this->name = new Name('Пупкин', 'Василий', 'Петрович');
        $this->address = new Address('Россия', 'Липецкая обл.', 'г. Пушкин', 'ул. Ленина', 25);
        $this->phones[] = new Phone(7, '000', '00000000');
    }
 
    public function withId(Id $id): self
    {
        $clone = clone $this;
        $clone->id = $id;
        return $clone;
    }
 
    public function withPhones(array $phones): self
    {
        $clone = clone $this;
        $clone->phones = $phones;
        return $clone;
    }
 
    public function archived(): self
    {
        $clone = clone $this;
        $clone->archived = true;
        return $clone;
    }
 
    public function build(): Employee
    {
        $employee = new Employee(
            $this->id,
            $this->date,
            $this->name,
            $this->address,
            $this->phones
        );
        if ($this->archived) {
            $employee->archive(new \DateTimeImmutable());
        }
        return $employee;
    }
}

$employee = (new EmployeeBuilder())->build();

$employee1 = (new EmployeeBuilder())->withId(new Id('id-1'))->build();
$employee2 = (new EmployeeBuilder())->withId(new Id('id-2'))->build();

class RenameTest extends Unit
{
    public function testSuccess(): void
    {
        $employee = (new EmployeeBuilder())->build();
 
        $employee->rename($name = new Name('New', 'Test', 'Name'));
        $this->assertEquals($name, $employee->getName());
 
        $this->assertNotEmpty($events = $employee->releaseEvents());
        $this->assertInstanceOf(EmployeeRenamed::class, end($events));
    }
}

class ChangeAddressTest extends Unit
{
    public function testSuccess(): void
    {
        $employee = (new EmployeeBuilder())->build();
 
        $employee->changeAddress($address = new Address('New', 'Test', 'Address', 'Street', '25a'));
        $this->assertEquals($address, $employee->getAddress());
 
        $this->assertNotEmpty($events = $employee->releaseEvents());
        $this->assertInstanceOf(EmployeeAddressChanged::class, end($events));
    }
}

class ArchiveTest extends Unit
{
    public function testSuccess(): void
    {
        $employee = (new EmployeeBuilder())->build();
 
        $this->assertTrue($employee->isActive());
        $this->assertFalse($employee->isArchived());
 
        $employee->archive($date = new \DateTimeImmutable('2011-06-15'));
 
        $this->assertFalse($employee->isActive());
        $this->assertTrue($employee->isArchived());
 
        $this->assertNotEmpty($statuses = $employee->getStatuses());
        $this->assertTrue(end($statuses)->isArchived());
 
        $this->assertNotEmpty($events = $employee->releaseEvents());
        $this->assertInstanceOf(EmployeeArchived::class, end($events));
    }
 
    public function testAlreadyArchived(): void
    {
        $employee = (new EmployeeBuilder())->archived()->build();
 
        $this->expectExceptionMessage('Employee is already archived.');
        $employee->archive(new \DateTimeImmutable('2011-06-15'));
    }
}

class PhoneTest extends Unit
{
    public function testAdd(): void
    {
        $employee = (new EmployeeBuilder())->build();
 
        $employee->addPhone($phone = new Phone(7, '888', '00000001'));
 
        $this->assertNotEmpty($phones = $employee->getPhones());
        $this->assertEquals($phone, end($phones));
 
        $this->assertNotEmpty($events = $employee->releaseEvents());
        $this->assertInstanceOf(EmployeePhoneAdded::class, end($events));
    }
 
    public function testAddExists(): void
    {
        $employee = (new EmployeeBuilder())
            ->withPhones([$phone = new Phone(7, '888', '00000001')])
            ->build();
 
        $this->expectExceptionMessage('Phone already exists.');
 
        $employee->addPhone($phone);
    }
 
    public function testRemove(): void
    {
        $employee = (new EmployeeBuilder())
            ->withPhones([
                new Phone(7, '888', '00000001'),
                new Phone(7, '888', '00000002'),
            ])
            ->build();
 
        $this->assertCount(2, $employee->getPhones());
 
        $employee->removePhone(1);
 
        $this->assertCount(1, $employee->getPhones());
 
        $this->assertNotEmpty($events = $employee->releaseEvents());
        $this->assertInstanceOf(EmployeePhoneRemoved::class, end($events));
    }
 
    public function testRemoveNotExists(): void
    {
        $employee = (new EmployeeBuilder())->build();
 
        $this->expectExceptionMessage('Phone is not found.');
 
        $employee->removePhone(42);
    }
 
    public function testRemoveLast(): void
    {
        $employee = (new EmployeeBuilder())
            ->withPhones([
                new Phone(7, '888', '00000001'),
            ])
            ->build();
 
        $this->expectExceptionMessage('Cannot remove the last phone.');
 
        $employee->removePhone(0);
    }
}

class RemoveTest extends Unit
{
    public function testSuccess(): void
    {
        $employee = (new EmployeeBuilder())->archived()->build();
 
        $employee->remove();
 
        $this->assertNotEmpty($events = $employee->releaseEvents());
        $this->assertInstanceOf(EmployeeRemoved::class, end($events));
    }
 
    public function testNotArchived(): void
    {
        $employee = (new EmployeeBuilder()))->build();
 
        $this->expectExceptionMessage('Cannot remove active employee.');
 
        $employee->remove();
    }
}

vendor/bin/codecept run unit entities

class PhoneTest extends Unit
{
    public function testIsEqual(): void
    {
        $phone1 = new Phone(7, '920', '0000001');
        $phone2 = new Phone(7, '920', '0000001');        
        $this->assertTrue($phone1->isEqualTo($phone2));
    }
 
    public function testIsNotEqual(): void
    {
        $phone1 = new Phone(7, '920', '0000001');
        $phone2 = new Phone(7, '900', '0000002');        
        $this->assertFalse($phone1->isEqualTo($phone2));
    }
}

namespace app\entities\Employee;
 
class Employee
{    
    public function __construct(Id $id, DateTimeImmutable $date, Name $name, Address $address, array $phones) { ... }
 
    public function rename(Name $name): void { ... }
 
    public function changeAddress(Address $address): void { ... }
 
    public function addPhone(Phone $phone): void { ... }
 
    public function removePhone($index): void { ... }
 
    public function archive(\DateTimeImmutable $date): void { ... }
 
    public function reinstate(\DateTimeImmutable $date): void { ... }
 
    public function remove(): void { ... }
 
    public function isActive(): bool { ... }    
    public function isArchived(): bool { ... }
 
    public function getId(): Id { return $this->id; }
    public function getName(): Name { return $this->name; }
    public function getPhones(): array { return $this->phones; }
    public function getAddress(): Address { return $this->address; }
    public function getCreateDate(): \DateTimeImmutable { return $this->createDate; }
    public function getStatuses(): array { return $this->statuses; }
}

class Employee
{
    private $id;
    private $name;
    private $address;
    private $phones = [];
    private $createDate;
    private $statuses = [];
 
    public function __construct(Id $id, \DateTimeImmutable $date, Name $name, Address $address, array $phones)
    {    
        if (!$phones) {
            throw new \DomainException('Employee must contain at least one phone.');
        }    
        $this->id = $id;
        $this->name = $name;
        $this->address = $address;
        $this->phones = [];
        $this->createDate = $date;
        $this->addStatus(Status::ACTIVE, $date);        
        foreach ($phones as $phone) {
            foreach ($this->phones as $current) {
                if ($current->isEqualTo($phone)) {
                    throw new \DomainException('Phone already exists.');                 
                }
            }
            $this->phones[] = $phone;
        }
        $this->recordEvent(new Events\EmployeeCreated($this->id));
    }
 
    ...
 
    private function addStatus($value, \DateTimeImmutable $date): void
    {
        $this->statuses[] = new Status($value, $date);
    }
}

class Employee
{
    private $id;
    private $name;
    private $address;
    private $phones;
    private $createDate;
    private $statuses = [];
 
    public function __construct(Id $id, Name $name, Address $address, array $phones)
    {
        $this->id = $id;
        $this->name = $name;
        $this->address = $address;
        $this->phones = new Phones($phones);
        $this->createDate = new \DateTimeImmutable();
        $this->addStatus(Status::ACTIVE, $this->createDate);
        $this->recordEvent(new Events\EmployeeCreated($this->id));
    }
 
    ...
 
    private function addStatus($value, \DateTimeImmutable $date): void
    {
        $this->statuses[] = new Status($value, $date);
    }
}

namespace app\entities\Employee;
 
use app\entities\Employee\Events;
 
class Employee
{
    ...
 
    public function rename(Name $name): void
    {
        $this->name = $name;
        $this->recordEvent(new Events\EmployeeRenamed($this->id, $name));
    }
 
    public function changeAddress(Address $address): void
    {
        $this->address = $address;
        $this->recordEvent(new Events\EmployeeAddressChanged($this->id, $address));
    }
 
    ...
}

class Employee
{
    private $events = [];
 
    protected function recordEvent($event): void
    {
        $this->events[] = $event;
    }
 
    public function releaseEvents(): array
    {
        $events = $this->events;
        $this->events = [];
        return $events;
    }
 
    ...
}

namespace app\entities;
 
interface AggregateRoot
{
    public function releaseEvents();
}

namespace app\entities;
 
trait EventTrait
{
    private $events = [];
 
    protected function recordEvent($event): void
    {
        $this->events[] = $event;
    }
 
    public function releaseEvents(): array
    {
        $events = $this->events;
        $this->events = [];
        return $events;
    }
}

namespace app\entities\Employee;
 
use app\entities\AggregateRoot;
use app\entities\EventTrait;
 
class Employee implements AggregateRoot
{
    use EventTrait;
 
    ...
}

class Employee implements AggregateRoot
{
    use EventTrait;
 
    private $statuses = [];
 
    ...
 
    public function archive(\DateTimeImmutable $date): void
    {
        if ($this->isArchived()) {
            throw new \DomainException('Employee is already archived.');
        }
        $this->addStatus(Status::ARCHIVED, $date);
        $this->recordEvent(new Events\EmployeeArchived($this->id, $date));
    }
 
    public function reinstate(\DateTimeImmutable $date): void
    {
        if (!$this->isArchived()) {
            throw new \DomainException('Employee is not archived.');
        }
        $this->addStatus(Status::ACTIVE, $date);
        $this->recordEvent(new Events\EmployeeReinstated($this->id, $date));
    }
 
    public function isActive(): bool
    {
        return $this->getCurrentStatus()->isActive();
    }
 
    public function isArchived(): bool
    {
        return $this->getCurrentStatus()->isArchived();
    }
 
    private function getCurrentStatus(): Status
    {
        return end($this->statuses);
    }
 
    ...
}

class Employee implements AggregateRoot
{   
    ...
 
    public function remove(): void
    {
        if (!$this->isArchived()) {
            throw new \DomainException('Cannot remove active employee.');
        }
        $this->recordEvent(new Events\EmployeeRemoved($this->id));
    }
 
    ...
}

class Employee implements AggregateRoot
{
    use EventTrait;
 
    private $phones;
 
    ...
 
    public function addPhone(Phone $phone): void
    {
        $this->phones->add($phone);
        $this->recordEvent(new Events\EmployeePhoneAdded($this->id, $phone));
    }
 
    public function removePhone($index): void
    {
        $phone = $this->phones->remove($index);
        $this->recordEvent(new Events\EmployeePhoneRemoved($this->id, $phone));
    }
 
    ...    
 
    public function getPhones(): array { return $this->phones->getAll(); }
}

namespace app\entities\Employee;
 
class Phones
{
    private $phones = [];
 
    public function __construct(array $phones)
    {
        if (!$phones) {
            throw new \DomainException('Employee must contain at least one phone.');
        }
        foreach ($phones as $phone) {
            $this->add($phone);
        }
    }
 
    public function add(Phone $phone): void
    {
        foreach ($this->phones as $item) {
            if ($item->isEqualTo($phone)) {
                throw new \DomainException('Phone already exists.');
            }
        }
        $this->phones[] = $phone;
    }
 
    public function remove($index): Phone
    {
        if (!isset($this->phones[$index])) {
            throw new \DomainException('Phone not found.');
        }
        if (count($this->phones) === 1) {
            throw new \DomainException('Cannot remove the last phone.');
        }
        $phone = $this->phones[$index];
        unset($this->phones[$index]);
        return $phone;
    }
 
    public function getAll(): array
    {
        return $this->phones;
    }
}

public function getPhones(): array
{
    return $this->phones;
}

public function getPhones(): array
{
    return $this->phones->getAll();
}

Assertion::notEmpty($id);

if (empty($id)) {
    thrown new \InvalidArgumentException('Value "id" is empty, but non empty value was expected.');
}

namespace app\entities\Employee;
 
use Assert\Assertion;
use Ramsey\Uuid\Uuid;
 
class Id
{
    private $id;
 
    public function __construct(string $id)
    {
        Assertion::notEmpty($id);
 
        $this->id = $id;
    }
 
    public static function next(): self
    {
        return new self(Uuid::uuid4()->toString());
    }
 
    public function getId(): string
    {
        return $this->id;
    }
 
    public function isEqualTo(self $other): bool
    {
        return $this->getId() === $other->getId();
    }
}

namespace app\entities\Employee;
 
use Assert\Assertion;
 
class Name
{
    private $last;
    private $first;
    private $middle;
 
    public function __construct(string $last, string $first, ?string $middle)
    {
        Assertion::notEmpty($last);
        Assertion::notEmpty($first);
 
        $this->last = $last;
        $this->first = $first;
        $this->middle = $middle;
    }
 
    public function getFull()
    {
        return trim($this->last . ' ' . $this->first . ' ' . $this->middle);
    }
 
    public function getFirst(): string { return $this->first; }
    public function getMiddle(): ?string { return $this->middle; }
    public function getLast(): string { return $this->last; }
}

$employee->getName()->middle = 42;

namespace app\entities\Employee;
 
use Assert\Assertion;
 
class Address
{
    private $country;
    private $region;
    private $city;
    private $street;
    private $house;
 
    public function __construct(string $country, string $region, string $city, string $street, string $house)
    {
        Assertion::notEmpty($country);
        Assertion::notEmpty($city);
 
        $this->country = $country;
        $this->region = $region;
        $this->city = $city;
        $this->street = $street;
        $this->house = $house;
    }
 
    public function getCountry(): string { return $this->country; }
    public function getRegion(): string { return $this->region; }
    public function getCity(): string { return $this->city; }
    public function getStreet(): string { return $this->street; }
    public function getHouse(): string { return $this->house; }
}

namespace app\entities\Employee;
 
use Assert\Assertion;
 
class Status
{
    const ACTIVE = 'active';
    const ARCHIVED = 'archived';
 
    private $value;
    private $date;
 
    public function __construct(string $value, \DateTimeImmutable $date)
    {
        Assertion::inArray($value, [
            self::ACTIVE,
            self::ARCHIVED
        ]);
 
        $this->value = $value;
        $this->date = $date;
    }
 
    public function isActive(): bool
    {
        return $this->value === self::ACTIVE;
    }
 
    public function isArchived(): bool
    {
        return $this->value === self::ARCHIVED;
    }
 
    public function getValue(): string { return $this->value; }
    public function getDate(): \DateTimeImmutable { return $this->date; }
}

namespace app\entities\Employee\Phone;
 
use Assert\Assertion;
 
class Phone
{
    private $country;
    private $code;
    private $number;
 
    public function __construct(int $country, string $code, string $number)
    {
        Assertion::notEmpty($country);
        Assertion::notEmpty($code);
        Assertion::notEmpty($number);
 
        $this->country = $country;
        $this->code = $code;
        $this->number = $number;
    }
 
    public function isEqualTo(self $phone): bool
    {
        return $this->getFull() === $phone->getFull();
    }
 
    public function getFull(): string
    {
        return '+' . $this->country . ' (' . $this->code . ') ' . $this->number;
    }
 
    public function getCountry(): int { return $this->country; }
    public function getCode(): string { return $this->code; }
    public function getNumber(): string { return $this->number; }
}

namespace app\entities\Employee\Events;
 
use app\entities\Employee\Id;
 
class EmployeeCreated
{
    public $employee;
 
    public function __construct(Id $employee)
    {
        $this->employee = $employee;
    }
}

class EmployeePhoneAdded
{
    public $employee;
    public $phone;
 
    public function __construct(Id $employee, Phone $phone)
    {
        $this->employee = $employee;
        $this->phone = $phone;
    }
}

namespace app\entities\Employee;
 
use app\entities\AggregateRoot;
use app\entities\Employee\Events;
use app\entities\EventTrait;
 
class Employee implements AggregateRoot
{
    use EventTrait;
 
    private $id;
    private $name;
    private $address;
    private $phones;
    private $createDate;
    private $statuses = [];
 
    public function __construct(Id $id, Name $name, Address $address, array $phones)
    {
        $this->id = $id;
        $this->name = $name;
        $this->address = $address;
        $this->phones = new Phones($phones);
        $this->createDate = new \DateTimeImmutable();
        $this->addStatus(Status::ACTIVE, $this->createDate);
        $this->recordEvent(new Events\EmployeeCreated($this->id));
    }
 
    public function rename(Name $name): void
    {
        $this->name = $name;
        $this->recordEvent(new Events\EmployeeRenamed($this->id, $name));
    }
 
    public function changeAddress(Address $address): void
    {
        $this->address = $address;
        $this->recordEvent(new Events\EmployeeAddressChanged($this->id, $address));
    }
 
    public function addPhone(Phone $phone): void
    {
        $this->phones->add($phone);
        $this->recordEvent(new Events\EmployeePhoneAdded($this->id, $phone));
    }
 
    public function removePhone($index): void
    {
        $phone = $this->phones->remove($index);
        $this->recordEvent(new Events\EmployeePhoneRemoved($this->id, $phone));
    }
 
    public function archive(\DateTimeImmutable $date): void
    {
        if ($this->isArchived()) {
            throw new \DomainException('Employee is already archived.');
        }
        $this->addStatus(Status::ARCHIVED, $date);
        $this->recordEvent(new Events\EmployeeArchived($this->id, $date));
    }
 
    public function reinstate(\DateTimeImmutable $date): void
    {
        if (!$this->isArchived()) {
            throw new \DomainException('Employee is not archived.');
        }
        $this->addStatus(Status::ACTIVE, $date);
        $this->recordEvent(new Events\EmployeeReinstated($this->id, $date));
    }
 
    public function remove(): void
    {
        if (!$this->isArchived()) {
            throw new \DomainException('Cannot remove active employee.');
        }
        $this->recordEvent(new Events\EmployeeRemoved($this->id));
    }
 
    public function isActive(): bool
    {
        return $this->getCurrentStatus()->isActive();
    }
 
    public function isArchived(): bool
    {
        return $this->getCurrentStatus()->isArchived();
    }
 
    private function getCurrentStatus(): Status
    {
        return end($this->statuses);
    }
 
    private function addStatus($value, \DateTimeImmutable $date): void
    {
        $this->statuses[] = new Status($value, $date);
    }
 
    public function getId(): Id { return $this->id; }
    public function getName(): Name { return $this->name; }
    public function getPhones(): array { return $this->phones->getAll(); }
    public function getAddress(): Address { return $this->address; }
    public function getCreateDate(): \DateTimeImmutable { return $this->createDate; }
    public function getStatuses(): array { return $this->statuses; }
}