Doplňující taktické vzory: Specifications, Domain Services, Factories, Modules

interface Specification
{
    public function isSatisfiedBy(mixed $candidate): bool;
}

<?php

declare(strict_types=1);

namespace App\SharedKernel\Domain\Specification;

/**
 * Doménová specifikace – prvotřídní objekt zapouzdřující booleovský predikát.
 *
 * @template T
 */
interface Specification
{
    /** @param T $candidate */
    public function isSatisfiedBy(mixed $candidate): bool;

    /**
     * @param Specification<T> $other
     * @return Specification<T>
     */
    public function and(self $other): self;

    /**
     * @param Specification<T> $other
     * @return Specification<T>
     */
    public function or(self $other): self;

    /** @return Specification<T> */
    public function not(): self;
}

<?php

declare(strict_types=1);

namespace App\SharedKernel\Domain\Specification;

/**
 * @template T
 * @implements Specification<T>
 */
abstract class CompositeSpecification implements Specification
{
    /** @param T $candidate */
    abstract public function isSatisfiedBy(mixed $candidate): bool;

    public function and(Specification $other): Specification
    {
        return new AndSpecification($this, $other);
    }

    public function or(Specification $other): Specification
    {
        return new OrSpecification($this, $other);
    }

    public function not(): Specification
    {
        return new NotSpecification($this);
    }
}

<?php

declare(strict_types=1);

namespace App\SharedKernel\Domain\Specification;

/**
 * @template T
 * @extends CompositeSpecification<T>
 */
final class AndSpecification extends CompositeSpecification
{
    /**
     * @param Specification<T> $left
     * @param Specification<T> $right
     */
    public function __construct(
        private readonly Specification $left,
        private readonly Specification $right,
    ) {}

    public function isSatisfiedBy(mixed $candidate): bool
    {
        return $this->left->isSatisfiedBy($candidate)
            && $this->right->isSatisfiedBy($candidate);
    }
}

<?php

declare(strict_types=1);

namespace App\SharedKernel\Domain\Specification;

/**
 * @template T
 * @extends CompositeSpecification<T>
 */
final class OrSpecification extends CompositeSpecification
{
    /**
     * @param Specification<T> $left
     * @param Specification<T> $right
     */
    public function __construct(
        private readonly Specification $left,
        private readonly Specification $right,
    ) {}

    public function isSatisfiedBy(mixed $candidate): bool
    {
        return $this->left->isSatisfiedBy($candidate)
            || $this->right->isSatisfiedBy($candidate);
    }
}

<?php

declare(strict_types=1);

namespace App\SharedKernel\Domain\Specification;

/**
 * @template T
 * @extends CompositeSpecification<T>
 */
final class NotSpecification extends CompositeSpecification
{
    /** @param Specification<T> $inner */
    public function __construct(private readonly Specification $inner) {}

    public function isSatisfiedBy(mixed $candidate): bool
    {
        return !$this->inner->isSatisfiedBy($candidate);
    }
}

<?php

declare(strict_types=1);

namespace App\Ordering\Domain\Specification;

use App\Ordering\Domain\Order;
use App\SharedKernel\Domain\Money;
use App\SharedKernel\Domain\Specification\CompositeSpecification;

/**
 * Objednávka má nárok na dopravu zdarma, pokud její celková hodnota
 * dosahuje nebo přesahuje stanovený limit.
 *
 * @extends CompositeSpecification<Order>
 */
final class EligibleForFreeShipping extends CompositeSpecification
{
    public function __construct(private readonly Money $threshold) {}

    public function isSatisfiedBy(mixed $candidate): bool
    {
        assert($candidate instanceof Order);

        return $candidate->total()->isGreaterThanOrEqual($this->threshold);
    }
}

<?php

declare(strict_types=1);

namespace App\Ordering\Domain\Specification;

use App\Ordering\Domain\Order;
use App\SharedKernel\Domain\Country;
use App\SharedKernel\Domain\Specification\CompositeSpecification;

/**
 * Doručovací adresa objednávky se nachází v zemi EU.
 *
 * @extends CompositeSpecification<Order>
 */
final class InEUCountry extends CompositeSpecification
{
    public function __construct(private readonly Country $country) {}

    public function isSatisfiedBy(mixed $candidate): bool
    {
        assert($candidate instanceof Order);

        return $this->country->isInEU()
            && $candidate->shippingAddress()->country()->equals($this->country);
    }
}

<?php

declare(strict_types=1);

namespace App\Ordering\Domain\Specification;

use App\Ordering\Domain\Order;
use App\SharedKernel\Domain\CustomerId;
use App\SharedKernel\Domain\Specification\CompositeSpecification;

/**
 * Zákazník není uveden na doménovém blacklistu (např. fraud detection).
 *
 * @extends CompositeSpecification<Order>
 */
final class NotInBlacklist extends CompositeSpecification
{
    /** @param list<CustomerId> $blacklist */
    public function __construct(private readonly array $blacklist) {}

    public function isSatisfiedBy(mixed $candidate): bool
    {
        assert($candidate instanceof Order);

        foreach ($this->blacklist as $blocked) {
            if ($blocked->equals($candidate->customerId())) {
                return false;
            }
        }

        return true;
    }
}

<?php

declare(strict_types=1);

namespace App\Ordering\Application\CommandHandler;

use App\Ordering\Domain\Order;
use App\Ordering\Domain\Specification\EligibleForFreeShipping;
use App\Ordering\Domain\Specification\InEUCountry;
use App\Ordering\Domain\Specification\NotInBlacklist;
use App\SharedKernel\Domain\Country;
use App\SharedKernel\Domain\Money;

final class ApplyFreeShippingHandler
{
    public function __construct(private readonly BlacklistRegistry $blacklist) {}

    public function __invoke(Order $order): void
    {
        $promo = (new EligibleForFreeShipping(Money::czk(100_000))) // 1000 Kč v haléřích
            ->and(new InEUCountry($order->shippingAddress()->country()))
            ->and(new NotInBlacklist($this->blacklist->all()));

        if ($promo->isSatisfiedBy($order)) {
            $order->markEligibleForFreeShipping();
        }
    }
}

<?php

declare(strict_types=1);

namespace App\SharedKernel\Domain\Specification;

use Doctrine\ORM\QueryBuilder;

/**
 * Specifikace, která ví, jak se převést na Doctrine kritérium.
 * Implementuje double-dispatch: specifikace zná své pravidlo,
 * repozitář ví, jak ho aplikovat na QueryBuilder.
 *
 * @template T
 * @extends Specification<T>
 */
interface QuerySpecification extends Specification
{
    public function asDoctrineCriteria(QueryBuilder $qb, string $alias): void;
}

<?php

declare(strict_types=1);

namespace App\Ordering\Domain\Specification;

use App\Ordering\Domain\Order;
use App\SharedKernel\Domain\Money;
use App\SharedKernel\Domain\Specification\CompositeSpecification;
use App\SharedKernel\Domain\Specification\QuerySpecification;
use Doctrine\ORM\QueryBuilder;

/**
 * @extends CompositeSpecification<Order>
 * @implements QuerySpecification<Order>
 */
final class EligibleForFreeShipping extends CompositeSpecification implements QuerySpecification
{
    public function __construct(private readonly Money $threshold) {}

    public function isSatisfiedBy(mixed $candidate): bool
    {
        assert($candidate instanceof Order);

        return $candidate->total()->isGreaterThanOrEqual($this->threshold);
    }

    public function asDoctrineCriteria(QueryBuilder $qb, string $alias): void
    {
        $qb->andWhere(sprintf('%s.totalAmount >= :threshold', $alias))
           ->setParameter('threshold', $this->threshold->amount());
    }
}

<?php

declare(strict_types=1);

namespace App\Ordering\Infrastructure\Doctrine;

use App\Ordering\Domain\Order;
use App\Ordering\Domain\OrderRepository;
use App\SharedKernel\Domain\Specification\QuerySpecification;
use Doctrine\ORM\EntityManagerInterface;

final class DoctrineOrderRepository implements OrderRepository
{
    public function __construct(private readonly EntityManagerInterface $em) {}

    /**
     * @param QuerySpecification<Order> $spec
     * @return list<Order>
     */
    public function match(QuerySpecification $spec): array
    {
        $qb = $this->em->createQueryBuilder()
            ->select('o')
            ->from(Order::class, 'o');

        $spec->asDoctrineCriteria($qb, 'o');

        return $qb->getQuery()->getResult();
    }
}

<?php

declare(strict_types=1);

namespace App\Banking\Domain\Service;

use App\Banking\Domain\Account;
use App\Banking\Domain\Exception\InsufficientFunds;
use App\Banking\Domain\TransferReference;
use App\SharedKernel\Domain\Money;

/**
 * Domain Service – převod peněz mezi dvěma účty.
 *
 * Operace nepatří do žádného z účtů, protože jeden z nich nesmí znát
 * druhý: agregáty jsou autonomní. Jde o doménovou logiku (validace
 * dostupnosti prostředků, kontrola limitu), nikoliv o aplikační koordinaci.
 *
 * Stateless – bez instance variables, bez vedlejších efektů na kolaborátorech.
 */
final class MoneyTransferService
{
    public function transfer(
        Account $from,
        Account $to,
        Money $amount,
        TransferReference $reference,
        \DateTimeImmutable $when,
    ): void {
        if (!$from->canWithdraw($amount, $when)) {
            throw InsufficientFunds::onAccount($from->id(), $amount);
        }

        if (!$from->currency()->equals($to->currency())) {
            throw new \DomainException(
                'Currency mismatch – use FxTransferService for cross-currency transfers.',
            );
        }

        $from->withdraw($amount, $reference, $when);
        $to->deposit($amount, $reference, $when);
    }
}

<?php

declare(strict_types=1);

namespace App\Ordering\Domain;

use App\Ordering\Domain\Event\OrderPlaced;
use App\Ordering\Domain\Exception\EmptyOrder;
use App\SharedKernel\Domain\AggregateRoot;
use App\SharedKernel\Domain\CustomerId;

final class Order extends AggregateRoot
{
    /** @var list<OrderItem> */
    private array $items;

    /** @param list<OrderItem> $items */
    private function __construct(
        private readonly OrderId $id,
        private readonly CustomerId $customerId,
        array $items,
        private readonly OrderType $type,
        private readonly \DateTimeImmutable $placedAt,
    ) {
        $this->items = $items;
        $this->recordEvent(new OrderPlaced($id, $customerId, $placedAt));
    }

    /**
     * Standardní vznik objednávky se zbožím.
     *
     * @param list<OrderItem> $items
     */
    public static function place(
        CustomerId $customerId,
        array $items,
        \DateTimeImmutable $placedAt,
    ): self {
        if (count($items) === 0) {
            throw EmptyOrder::cannotBePlaced();
        }

        return new self(
            id: OrderId::generate(),
            customerId: $customerId,
            items: $items,
            type: OrderType::Physical,
            placedAt: $placedAt,
        );
    }

    /**
     * Polymorfní vznik – pouze digitální obsah, jiná pravidla
     * (žádná dopravní adresa, instantní doručení).
     *
     * @param list<DigitalItem> $items
     */
    public static function placeDigital(
        CustomerId $customerId,
        array $items,
        \DateTimeImmutable $placedAt,
    ): self {
        if (count($items) === 0) {
            throw EmptyOrder::cannotBePlaced();
        }

        return new self(
            id: OrderId::generate(),
            customerId: $customerId,
            items: array_map(static fn (DigitalItem $i): OrderItem => $i->toOrderItem(), $items),
            type: OrderType::Digital,
            placedAt: $placedAt,
        );
    }

    /**
     * Vznik z importu – odlišná validace, neidentifikuje zákazníka přes CustomerId,
     * ale přes externí key, který se uvnitř naváže na guest CustomerId.
     */
    public static function fromImport(
        ImportedOrderRow $row,
        CustomerLookup $lookup,
        \DateTimeImmutable $placedAt,
    ): self {
        $customerId = $lookup->byEmail($row->customerEmail) ?? CustomerId::guest();
        $items = ImportedItems::map($row->items);

        return self::place($customerId, $items, $placedAt);
    }
}

<?php

declare(strict_types=1);

namespace App\Ordering\Domain\Factory;

use App\Ordering\Domain\Cart\CartId;
use App\Ordering\Domain\Cart\CartRepository;
use App\Ordering\Domain\Order;
use App\Ordering\Domain\Pricing\PricingService;
use App\SharedKernel\Domain\CustomerId;
use Psr\Clock\ClockInterface;

/**
 * Factory class – vznik objednávky z košíku vyžaduje
 * načtení košíku a aplikaci aktuálního pricingu.
 * Static method by tyto závislosti nemohla převzít.
 */
final class OrderFromCartFactory
{
    public function __construct(
        private readonly CartRepository $carts,
        private readonly PricingService $pricing,
        private readonly ClockInterface $clock,
    ) {}

    public function fromCart(CartId $cartId, CustomerId $customer): Order
    {
        $cart = $this->carts->getById($cartId);

        if ($cart->isEmpty()) {
            throw new \DomainException('Cannot place order from empty cart.');
        }

        $pricedItems = $this->pricing->priceItems($cart->items(), $customer);

        return Order::place(
            customerId: $customer,
            items: $pricedItems,
            placedAt: $this->clock->now(),
        );
    }
}

/**
 * Rekonstituce ze stavu načteného z DB / event streamu.
 * Tento pojmenovaný konstruktor neaplikuje invarianty –
 * rekonstruovaný stav je z definice valid, jinak by se nedostal do persistence.
 *
 * @internal Smí volat pouze infrastruktura repozitáře.
 *
 * @param list<OrderItem> $items
 */
public static function reconstitute(
    OrderId $id,
    CustomerId $customerId,
    array $items,
    OrderType $type,
    \DateTimeImmutable $placedAt,
): self {
    return new self($id, $customerId, $items, $type, $placedAt);
}

src/
  Ordering/                                  ← MODULE = Bounded Context
    Domain/
      Order.php                              ← Aggregate Root
      OrderRepository.php                    ← Interface
      OrderItem.php
      Specification/
        EligibleForFreeShipping.php
        InEUCountry.php
      Service/
        PricingService.php                   ← Domain Service
      Factory/
        OrderFromCartFactory.php
      Event/
        OrderPlaced.php
      Exception/
        EmptyOrder.php
    Application/
      Command/
        PlaceOrderCommand.php
      CommandHandler/
        PlaceOrderHandler.php
      Query/
        ListOrdersQuery.php
      QueryHandler/
        ListOrdersHandler.php
    Infrastructure/
      Doctrine/
        DoctrineOrderRepository.php
        OrderMapping.orm.xml
      Http/
        OrderController.php
      Messenger/
        OrderPlacedSubscriber.php
  Billing/                                   ← Jiný BC = jiný modul
    Domain/
      Invoice.php
      ...
    Application/
      ...
    Infrastructure/
      ...
  SharedKernel/                              ← Sdílený jazyk a typy
    Domain/
      Money.php
      Currency.php
      Country.php
      AggregateRoot.php
      Specification/
        Specification.php
        CompositeSpecification.php
        AndSpecification.php
        OrSpecification.php
        NotSpecification.php
        QuerySpecification.php

{
    "name": "your-org/your-app",
    "type": "project",
    "require": {
        "php": ">=8.4",
        "symfony/framework-bundle": "^8.0",
        "doctrine/orm": "^3.0"
    },
    "autoload": {
        "psr-4": {
            "App\\Ordering\\":     "src/Ordering/",
            "App\\Billing\\":      "src/Billing/",
            "App\\Inventory\\":    "src/Inventory/",
            "App\\Shipping\\":     "src/Shipping/",
            "App\\SharedKernel\\": "src/SharedKernel/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "App\\Tests\\Ordering\\":  "tests/Ordering/",
            "App\\Tests\\Billing\\":   "tests/Billing/"
        }
    }
}

services:
    _defaults:
        autowire: true
        autoconfigure: true

    # Auto-registrace všech služeb v každém modulu, v jejich Infrastructure
    # a Application vrstvách. Doménová vrstva je bez auto-konfigurace
    # – doménové objekty žijí mimo container.
    App\Ordering\Application\:
        resource: '../src/Ordering/Application/'
    App\Ordering\Infrastructure\:
        resource: '../src/Ordering/Infrastructure/'
    App\Billing\Application\:
        resource: '../src/Billing/Application/'
    App\Billing\Infrastructure\:
        resource: '../src/Billing/Infrastructure/'
    # ...

    # Controllery z modulů – Symfony je standardně hledá v App\Controller\
    App\Ordering\Infrastructure\Http\:
        resource: '../src/Ordering/Infrastructure/Http/'
        tags: ['controller.service_arguments']

composer require --dev phparkitect/phparkitect

<?php

declare(strict_types=1);

use Arkitect\ClassSet;
use Arkitect\CLI\Config;
use Arkitect\Expression\ForClasses\NotDependsOnAnyOfTheseNamespaces;
use Arkitect\Expression\ForClasses\NotDependsOnTheseNamespaces;
use Arkitect\Expression\ForClasses\ResideInOneOfTheseNamespaces;
use Arkitect\Rules\Rule;

return static function (Config $config): void {
    $classSet = ClassSet::fromDir(__DIR__ . '/src');

    // Pravidlo 1: Ordering BC nesmí přímo závisět na Billing BC.
    // Integrace musí probíhat přes events (publish/subscribe),
    // nikdy přímým voláním třídy z druhého modulu.
    $orderingIsolated = Rule::allClasses()
        ->that(new ResideInOneOfTheseNamespaces('App\\Ordering'))
        ->should(new NotDependsOnAnyOfTheseNamespaces([
            'App\\Billing',
            'App\\Inventory',
            'App\\Shipping',
        ]))
        ->because(
            'Ordering BC je autonomní – integrace s ostatními BC '
          . 'probíhá výhradně přes domain events (Outbox).',
        );

    // Pravidlo 2: Doménová vrstva nesmí znát infrastrukturu.
    // Žádný import z Doctrine, Symfony HTTP, Mailer, Messenger atd.
    $domainPure = Rule::allClasses()
        ->that(new ResideInOneOfTheseNamespaces('App\\Ordering\\Domain'))
        ->should(new NotDependsOnAnyOfTheseNamespaces([
            'Doctrine',
            'Symfony',
            'App\\Ordering\\Infrastructure',
            'App\\Ordering\\Application',
        ]))
        ->because(
            'Domain layer musí být framework-agnostic; '
          . 'porty se definují jako interface a implementují v Infrastructure.',
        );

    // Pravidlo 3: Application vrstva nesmí znát Infrastructure detaily.
    $applicationCleanArch = Rule::allClasses()
        ->that(new ResideInOneOfTheseNamespaces('App\\Ordering\\Application'))
        ->should(new NotDependsOnTheseNamespaces([
            'App\\Ordering\\Infrastructure',
            'Doctrine\\ORM',
        ]))
        ->because(
            'Application orchestrace závisí na port (interface) z Domain, '
          . 'ne na adapteru z Infrastructure.',
        );

    $config
        ->add($classSet, $orderingIsolated, $domainPure, $applicationCleanArch);
};

# CI runner spustí pravidla a selže build, pokud došlo k porušení.
vendor/bin/phparkitect check --config=phparkitect.php

# Doporučujeme zařadit do CI workflow před fázi "tests":
#   - composer install
#   - vendor/bin/phparkitect check
#   - vendor/bin/phpstan analyse
#   - vendor/bin/phpunit