Skip to content

Open-source event management and ticket selling platform — perfect for concerts, conferences, and everything in between 🎟️ If you find this project helpful, please consider giving us a star ⭐️

17.8 KB
Raw Blame

Domain-Driven Design in Hi.Events

Overview

Hi.Events implements a clean DDD architecture with clear separation between Application Handlers, Domain Services, and Infrastructure Services. This document explains the patterns, responsibilities, and best practices for each layer.

Architecture Layers

graph LR
    A[HTTP Action] --> B[Application Handler]
    B --> C[Domain Service]
    C --> D[Repository Interface]
    D --> E[Eloquent Implementation]
    B --> F[Infrastructure Service]
    C --> G[Domain Events]

1. Application Layer

Location: backend/app/Services/Application/Handlers/

Purpose

Orchestration layer that coordinates domain services and handles cross-cutting concerns.

Responsibilities

  • Receive DTOs from HTTP Actions
  • Orchestrate multiple domain services
  • Manage database transactions
  • Handle logging and error management
  • Dispatch domain events
  • Transform domain objects back to DTOs/responses

Handler Pattern

Each handler:

  • Has a single handle() method
  • Accepts a DTO as input
  • Returns a domain object or DTO
  • Uses dependency injection

Example: backend/app/Services/Application/Handlers/Order/MarkOrderAsPaidHandler.php

class MarkOrderAsPaidHandler
{
    public function __construct(
        private readonly MarkOrderAsPaidService $markOrderAsPaidService,
        private readonly LoggerInterface $logger,
    ) {}

    public function handle(MarkOrderAsPaidDTO $dto): OrderDomainObject
    {
        $this->logger->info(__('Marking order as paid'), [
            'order_id' => $dto->orderId,
            'event_id' => $dto->eventId,
        ]);

        return $this->markOrderAsPaidService->markOrderAsPaid(
            $dto->orderId,
            $dto->eventId,
        );
    }
}

Key Characteristics

  • Thin orchestration - Delegate logic to services
  • Transaction boundaries - Wrap multi-step operations
  • Event dispatching - Trigger side effects
  • Error transformation - Convert domain exceptions

Naming Convention

  • Pattern: {Action}{Entity}Handler
  • Examples: CreateOrderHandler, UpdateEventHandler, DeleteProductHandler

2. Domain Services Layer

Location: backend/app/Services/Domain/

Purpose

Core business logic implementation organized by domain concepts.

Key Domain Areas

  • Order: Order management, payment processing, cancellation
  • Product: Product creation, validation, pricing
  • Event: Event creation, statistics, duplication
  • Auth: Login, password reset, authentication
  • Payment: Stripe integration, refunds, webhooks
  • Attendee: Ticket sending, check-ins
  • Tax: Tax/fee calculations
  • PromoCode: Validation and application

Service Characteristics

class CreateProductService
{
    public function __construct(
        private readonly ProductRepositoryInterface $productRepository,
        private readonly TaxAndProductAssociationService $taxService,
        private readonly ProductPriceCreateService $priceCreateService,
        private readonly HtmlPurifierService $purifier,
        private readonly DomainEventDispatcherService $eventDispatcher,
    ) {}

    public function createProduct(
        ProductDomainObject $product,
        Collection $prices
    ): ProductDomainObject {
        return DB::transaction(function() use ($product, $prices) {
            // 1. Persist product
            $persistedProduct = $this->productRepository->create([
                ProductDomainObjectAbstract::TITLE => $product->getTitle(),
                // ...
            ]);

            // 2. Associate taxes
            $this->taxService->associateTaxesAndFees($persistedProduct->getId());

            // 3. Create prices
            $this->priceCreateService->createPrices($persistedProduct, $prices);

            // 4. Dispatch event
            $this->eventDispatcher->dispatch(
                new ProductEvent(
                    type: DomainEventType::PRODUCT_CREATED,
                    productId: $persistedProduct->getId()
                )
            );

            return $persistedProduct;
        });
    }
}

Domain Service Guidelines

DO:

  • Encapsulate business logic
  • Focus on single responsibility
  • Compose other domain services
  • Return domain objects or specialized DTOs
  • Throw domain-specific exceptions
  • Dispatch domain events

DON'T:

  • Handle HTTP concerns
  • Know about controllers or actions
  • Deal with authentication/authorization directly
  • Format responses for API

Naming Conventions

  • Action-oriented: Create*Service, Update*Service, Delete*Service
  • Process-oriented: *ProcessingService, *CalculationService
  • Utility-oriented: *ValidationService, *ManagementService

3. Data Transfer Objects (DTOs)

Location: backend/app/Services/Application/Handlers/*/DTO/

Modern Pattern: BaseDataObject

Always use BaseDataObject (Spatie Laravel Data) for new DTOs.

class UpsertProductDTO extends BaseDataObject
{
    public function __construct(
        public readonly int $eventId,
        public readonly string $title,
        public readonly ?string $description,
        public readonly ProductType $type,
        /**
         * @var Collection<ProductPriceDTO>
         */
        public readonly Collection $prices,
        public readonly ?int $productCategoryId = null,
        public readonly ?int $maxPerOrder = null,
    ) {}
}

Key Features

  • Constructor promotion: Concise syntax
  • Readonly properties: Immutability
  • Type safety: Enums and primitives
  • Optional parameters: With defaults
  • Nested DTOs: Using Collection or #[CollectionOf]

Legacy Pattern: BaseDTO

Deprecated - Do not use for new code.

// DON'T DO THIS - BaseDTO is deprecated
class OldDTO extends BaseDTO { }

// DO THIS INSTEAD
class NewDTO extends BaseDataObject { }

DTO Best Practices

  1. Always extend BaseDataObject
class CreateWebhookDTO extends BaseDataObject { }
  1. Use readonly properties
public readonly string $url,
public readonly WebhookStatus $status,
  1. Integrate enums directly
public readonly EmailTemplateEngine $engine = EmailTemplateEngine::LIQUID,
  1. Document collections
/**
 * @var Collection<ProductDTO>
 */
public readonly Collection $products,

4. Domain Objects

Location: backend/app/DomainObjects/

What Are Domain Objects?

Auto-generated, immutable data representations that mirror the database schema.

Generation Process

php artisan generate-domain-objects

This command:

  1. Reads database schema using Doctrine DBAL
  2. Generates abstract classes in Generated/ folder
  3. Generates concrete classes (only if they don't exist)

Structure

Abstract Class (Generated/EventDomainObjectAbstract.php):

abstract class EventDomainObjectAbstract extends AbstractDomainObject
{
    // Constants for field names
    final public const ID = 'id';
    final public const TITLE = 'title';
    final public const STATUS = 'status';

    // Typed properties
    protected int $id;
    protected string $title;
    protected ?string $status = null;

    // Getters and setters
    public function setId(int $id): self
    {
        $this->id = $id;
        return $this;
    }

    public function getId(): int
    {
        return $this->id;
    }
}

Concrete Class (EventDomainObject.php):

class EventDomainObject extends EventDomainObjectAbstract
{
    private ?Collection $products = null;

    // Custom business logic
    public function isEventInPast(): bool
    {
        return $this->end_date && $this->end_date < now();
    }

    // Relationship accessors
    public function getProducts(): ?Collection
    {
        return $this->products;
    }
}

Usage Pattern

// Use constants for field names
$order = $orderRepository->create([
    OrderDomainObjectAbstract::EVENT_ID => $eventId,
    OrderDomainObjectAbstract::STATUS => OrderStatus::COMPLETED->name,
    OrderDomainObjectAbstract::TOTAL_GROSS => $total,
]);

// Use getters
$orderId = $order->getId();
$status = $order->getStatus();

Best Practices

DO:

  • Use constants for field names
  • Add custom logic to concrete classes
  • Use getters/setters for access

DON'T:

  • Edit abstract classes in Generated/ folder
  • Access properties directly (use getters)
  • Forget to regenerate after schema changes

5. Enums

Locations:

  • backend/app/DomainObjects/Status/ - Status enums
  • backend/app/DomainObjects/Enums/ - General enums

Status Enums

For entity lifecycle states:

enum OrderStatus
{
    use BaseEnum;

    case RESERVED;
    case CANCELLED;
    case COMPLETED;
    case AWAITING_OFFLINE_PAYMENT;
    case ABANDONED;

    public static function getHumanReadableStatus(string $status): string
    {
        return match ($status) {
            self::RESERVED->name => __('Reserved'),
            self::COMPLETED->name => __('Completed'),
            // ...
        };
    }
}

Examples:

  • OrderStatus
  • EventStatus (DRAFT, LIVE, ARCHIVED)
  • AttendeeStatus
  • AffiliateStatus

General Enums

For domain constants and types:

enum QuestionTypeEnum
{
    use BaseEnum;

    case ADDRESS;
    case PHONE;
    case SINGLE_LINE_TEXT;
    case CHECKBOX;
    case RADIO;
    case DROPDOWN;

    public static function getMultipleChoiceTypes(): array
    {
        return [
            self::CHECKBOX,
            self::MULTI_SELECT_DROPDOWN,
        ];
    }
}

Examples:

  • TaxType (TAX, FEE)
  • PromoCodeDiscountTypeEnum
  • ProductPriceType
  • MessageTypeEnum

BaseEnum Trait

Provides utility methods:

trait BaseEnum
{
    public function getName(): string
    {
        return $this->name;
    }

    public static function valuesArray(): array
    {
        $values = [];
        foreach (self::cases() as $enum) {
            $values[] = $enum->value ?? $enum->name;
        }
        return $values;
    }
}

Usage in Validation

'status' => [
    'required',
    Rule::in(OrderStatus::valuesArray())
]

6. DTO Flow Pattern

sequenceDiagram
    participant Action
    participant Handler
    participant Service
    participant Repository

    Action->>Handler: Pass DTO
    Note over Action,Handler: CreateOrderDTO

    Handler->>Service: Extract data, call service
    Note over Handler,Service: Pass primitives/domain objects

    Service->>Repository: Persist data
    Note over Service,Repository: Use domain object constants

    Repository-->>Service: Return Domain Object
    Service-->>Handler: Return Domain Object
    Handler-->>Action: Return Domain Object

    Action->>Action: Transform to Resource
    Note over Action: OrderResource::make($order)

Complete Example: Webhook Creation

Step 1: Action creates DTO

$dto = CreateWebhookDTO::from([
    'url' => $request->input('url'),
    'eventTypes' => $request->input('event_types'),
    'eventId' => $eventId,
    'accountId' => $this->getAuthenticatedAccountId(),
    'status' => WebhookStatus::ACTIVE,
]);

Step 2: Handler receives DTO

public function handle(CreateWebhookDTO $dto): WebhookDomainObject
{
    return $this->databaseManager->transaction(
        fn() => $this->createWebhook($dto)
    );
}

Step 3: Handler transforms DTO to Domain Object

private function createWebhook(CreateWebhookDTO $dto): WebhookDomainObject
{
    $webhookDomainObject = (new WebhookDomainObject())
        ->setUrl($dto->url)
        ->setEventTypes($dto->eventTypes)
        ->setStatus($dto->status->value);

    return $this->createWebhookService->createWebhook($webhookDomainObject);
}

Step 4: Service uses Domain Object

public function createWebhook(WebhookDomainObject $webhookDO): WebhookDomainObject
{
    $webhook = $this->webhookRepository->create([
        WebhookDomainObjectAbstract::URL => $webhookDO->getUrl(),
        WebhookDomainObjectAbstract::STATUS => $webhookDO->getStatus(),
        WebhookDomainObjectAbstract::SECRET => Str::random(32),
    ]);

    $this->logger->info('Created webhook', ['webhook' => $webhook->toArray()]);

    return $webhook;
}

7. Transaction Management

Handler-Level Transactions

Most common pattern - handlers manage transactions:

public function handle(CreateOrderDTO $dto): OrderDomainObject
{
    return $this->databaseManager->transaction(function () use ($dto) {
        $event = $this->eventRepository->findById($dto->eventId);
        $order = $this->orderService->createOrder($event);
        $items = $this->orderItemService->createItems($order, $dto->products);

        return $this->orderService->updateTotals($order, $items);
    });
}

Service-Level Transactions

For complex domain services:

public function markOrderAsPaid(int $orderId, int $eventId): OrderDomainObject
{
    return DB::transaction(function() use ($orderId, $eventId) {
        $order = $this->orderRepository->findById($orderId);

        // Multiple operations atomically
        $this->updateOrderStatus($order);
        $this->updateAttendeeStatuses($order);
        $this->updateProductQuantities($order);
        $this->createInvoice($order);

        // Events dispatched after commit
        OrderStatusChangedEvent::dispatch($order);

        return $order;
    });
}

Transaction Best Practices

  1. Dispatch events after transaction commits
DB::transaction(function() {
    // DB operations
});
OrderEvent::dispatch($order); // After commit
  1. Keep transactions focused
// DO: Single logical unit of work
DB::transaction(fn() => $this->createOrderWithItems());

// DON'T: Unrelated operations
DB::transaction(function() {
    $this->createOrder();
    $this->sendEmail(); // Side effect, should be async
});
  1. Handle failures appropriately
try {
    DB::transaction(function() {
        // Operations
    });
} catch (DomainException $e) {
    $this->logger->error('Transaction failed', ['error' => $e]);
    throw $e;
}

8. Service Composition

Services compose other services to handle complex operations:

class CompleteOrderHandler
{
    public function __construct(
        private readonly OrderRepositoryInterface $orderRepository,
        private readonly AttendeeCreationService $attendeeService,
        private readonly QuestionAnswerService $questionService,
        private readonly ProductQuantityUpdateService $quantityService,
        private readonly AffiliateTrackingService $affiliateService,
        private readonly DatabaseManager $db,
    ) {}

    public function handle(string $orderShortId, CompleteOrderDTO $dto): OrderDomainObject
    {
        return $this->db->transaction(function() use ($orderShortId, $dto) {
            $order = $this->orderRepository->findByShortId($orderShortId);

            // Compose multiple services
            $this->attendeeService->createAttendees($order, $dto->products);
            $this->questionService->saveAnswers($order, $dto->answers);
            $this->quantityService->updateQuantities($order);
            $this->affiliateService->trackSale($order);

            return $order;
        });
    }
}

9. Exception Handling

Domain Exceptions

Create custom exceptions for domain errors:

class ResourceConflictException extends Exception {}
class EmailTemplateValidationException extends Exception {
    public array $validationErrors = [];
}
class OrderValidationException extends Exception {}

Handler Exception Handling

public function handle(UpsertAffiliateDTO $dto): AffiliateDomainObject
{
    try {
        return $this->affiliateRepository->create([...]);
    } catch (ResourceConflictException $e) {
        throw ValidationException::withMessages([
            'code' => $e->getMessage(),
        ]);
    }
}

Action Exception Handling

try {
    $result = $this->handler->handle($dto);
} catch (EmailTemplateValidationException $e) {
    return $this->errorResponse(
        message: 'Validation failed',
        statusCode: ResponseCodes::HTTP_BAD_REQUEST,
        errors: $e->validationErrors,
    );
}

10. Validation Patterns

Three Levels of Validation

  1. HTTP Layer: Request validation
class CreateProductRequest extends BaseRequest
{
    public function rules(): array
    {
        return [
            'title' => 'required|string|max:255',
            'type' => ['required', Rule::in(ProductType::valuesArray())],
        ];
    }
}
  1. Handler Layer: DTO structure validation
class CreateProductDTO extends BaseDataObject
{
    public function __construct(
        public readonly string $title,  // Type validation
        public readonly ProductType $type,  // Enum validation
    ) {}
}
  1. Domain Layer: Business rule validation
class OrderValidationService
{
    public function validateOrderCanBeCompleted(OrderDomainObject $order): void
    {
        if ($order->getStatus() === OrderStatus::COMPLETED->name) {
            throw new OrderValidationException('Order already completed');
        }

        if ($order->isExpired()) {
            throw new OrderValidationException('Order has expired');
        }
    }
}

Best Practices Summary

Handlers Should

  • Orchestrate domain services
  • Manage transactions at the highest level
  • Handle logging and metrics
  • Transform between DTOs and domain objects
  • Dispatch events
  • Handle cross-cutting concerns

Domain Services Should

  • Encapsulate business logic
  • Be highly focused (single responsibility)
  • Depend on repositories via interfaces
  • Compose other domain services
  • Return domain objects or specialized DTOs
  • Throw domain-specific exceptions

DTOs Should

  • Be immutable (readonly properties)
  • Extend BaseDataObject (not BaseDTO)
  • Use constructor property promotion
  • Integrate enums for type safety
  • Document collections with PHPDoc

Domain Objects Should

  • Be auto-generated from schema
  • Provide constants for field names
  • Have custom logic in concrete classes
  • Never be edited in Generated/ folder