Implementing a DDD Use Case for in PHP

This article explores a Domain-Driven Design (DDD) Use Case model in PHP, demonstrating how to utilize interfaces and domain-specific classes to manage data persistence. We'll examine the TaxPersistUseCase class, which uses a persistence manager (TaxManagerInterface) to save an entity of type Tax, representing a tax.

This model emphasizes DDD principles : each component is clearly separated into interfaces, concrete implementations, and exceptions, following best practices in dependency injection and error handling.

Structure of the TaxPersistUseCase

The TaxPersistUseCase class handles the business logic associated with persisting a tax. It’s divided into several sections to clarify the logic and structure of this approach.

Dependency Declarations

namespace Domain\Application\UseCase\Order;

use Domain\Application\Entity\Order\Tax;
use Domain\Application\Gateway\Manager\Order\TaxManagerInterface;
use Domain\Application\UseCase\Order\Exception\NotFoundException;
use Domain\Application\UseCase\Order\Interfaces\TaxPersistRequestInterface;
use Domain\Application\UseCase\Order\Interfaces\TaxPersistResponseInterface;
use Domain\Exception\BadRequestException;
use Domain\Exception\FormException;
use Small\CleanApplication\Contract\UseCaseInterface;
use Small\Collection\Collection\StringCollection;
use Small\SwooleEntityManager\EntityManager\Exception\EmptyResultException;

The TaxPersistUseCase class depends on several interfaces and exceptions to handle tax persistence. Here’s a breakdown of their roles:

TaxManagerInterface : Interface for the tax persistence manager.

TaxPersistRequestInterface and TaxPersistResponseInterface : Interfaces for the Use Case’s request and response.
Exceptions: Various exceptions, such as BadRequestException, FormException, and NotFoundException, help manage context-specific errors.

Implementation of the TaxPersistUseCase Class

class TaxPersistUseCase implements UseCaseInterface
{

    public function __construct(
        protected TaxManagerInterface $taxManager,
    ) {}

    public function execute(mixed $request): TaxPersistResponseInterface
    {

        if (!$request instanceof TaxPersistRequestInterface) {
            throw new BadRequestException(
                self::class . ' accepts only request instance of ' . TaxPersistRequestInterface::class
            );
        }

        $tax = $request->getTax();
        $messages = new StringCollection();

        try {
            $this->taxManager->applicationPersist($tax);
        } catch (EmptyResultException $e) {
            throw new NotFoundException($e->getMessage());
        } catch (FormException $e) {
            $messages = $e->getFormMessages();
        }

        return new class($tax, $messages) implements TaxPersistResponseInterface
        {
            public function __construct(
                protected readonly Tax $tax,
                protected readonly StringCollection $messages,
            ) {}

            public function getTax(): Tax
            {
                return $this->tax;
            }

            public function getMessages(): StringCollection
            {
                return $this->messages;
            }
        };

    }

}

• Constructor and Dependency Injection : The constructor injects an instance of TaxManagerInterface, delegating the persistence of Tax objects to this instance without coupling TaxPersistUseCase to a specific implementation.
• Request Type Checking: The execute method verifies that the $request object implements the TaxPersistRequestInterface. This ensures that the request received conforms to the expected contract, providing interface-level validation.
• Persisting the Tax Object : If the request is valid, the Use Case extracts the Tax object from $request via getTax() and calls the applicationPersist method on TaxManagerInterface. This persistence process is encapsulated within a try-catch block to handle potential exceptions
• EmptyResultException: If the Tax entity is not found, this exception is caught and a NotFoundException is thrown to signal the error.
• FormException: If form validation fails, a FormException is captured, and error messages are stored in a StringCollection.
• Dynamic Response via Anonymous Class : An anonymous class implements TaxPersistResponseInterface to return the Use Case’s response. It includes getTax() and getMessages() methods, allowing access to the Tax entity and any error messages, respectively.

Use Case Interfaces

The interfaces define the contracts that each component must adhere to, promoting decoupling and testability.

TaxManagerInterface

This interface specifies the methods for managing taxes, including retrieval and persistence :

interface TaxManagerInterface
{
    public function findById(int $id): Tax;
    public function findByName(string $name): Tax;
    public function applicationPersist(Tax $tax): self;
}

• findById() and findByName(): These methods enable retrieving a tax by ID or name.
• applicationPersist(): This method ensures the Tax entity’s persistence.

TaxPersistRequestInterface

This interface defines the structure of the request expected by TaxPersistUseCase:

interface TaxPersistRequestInterface extends RequestInterface
{
    public function getTax(): Tax;
}

• getTax() : This method returns the Tax entity to be persisted, allowing the Use Case to directly access the relevant domain object. TaxPersistResponseInterface
• The response interface ensures that TaxPersistUseCase returns a compliant response:

interface TaxPersistResponseInterface extends ResponseInterface
{
    public function getTax(): ?Tax;
    public function getMessages(): StringCollection;
}

• getTax(): Returns the persisted Tax entity or null if an error occurred.
• getMessages(): Returns a StringCollection containing error messages, if form errors occurred.

Error and Exception Handling

Exceptions play an important role in DDD by capturing domain-specific errors:

• BadRequestException: Thrown if the Use Case receives a request of an incorrect type.
• NotFoundException: Thrown when the Tax entity sought is not found.
• FormException: Caught to handle validation errors, with error messages returned in a StringCollection.