Architecture Principles for Magento

Clean Architecture Layers

External Layer (Frameworks)
  |
  +-- Interface Adapters
  |     +-- Controllers
  |     +-- Gateways
  |     +-- Presenters
  |
  +-- Application Business Rules
  |     +-- Use Cases
  |     +-- Application Services
  |
  +-- Enterprise Business Rules
        +-- Entities
        +-- Domain Models
        +-- Value Objects

Magento Clean Architecture Example

// Entity (Domain Layer)
class Order
{
    private OrderId $id;
    private CustomerId $customerId;
    private Money $total;
    private OrderStatus $status;
    
    public function __construct(
        OrderId $id,
        CustomerId $customerId,
        Money $total,
        OrderStatus $status
    ) {
        $this->id = $id;
        $this->customerId = $customerId;
        $this->total = $total;
        $this->status = $status;
    }
    
    public function cancel(): void
    {
        if ($this->status->equals(OrderStatus::SHIPPED)) {
            throw new \DomainException('Cannot cancel shipped order');
        }
        $this->status = OrderStatus::CANCELLED;
    }
}

// Use Case (Application Layer)
class PlaceOrderUseCase
{
    private $orderRepository;
    private $paymentService;
    
    public function execute(PlaceOrderCommand $command): OrderId
    {
        $order = new Order(
            OrderId::generate(),
            $command->getCustomerId(),
            $command->getTotal(),
            OrderStatus::PENDING
        );
        
        $this->paymentService->charge($order);
        $this->orderRepository->save($order);
        
        return $order->getId();
    }
}

// Controller (Interface Adapter)
class CreateOrderController
{
    private $placeOrderUseCase;
    
    public function execute(Request $request): Response
    {
        $command = new PlaceOrderCommand(
            $request->getCustomerId(),
            $request->getItems()
        );
        
        $orderId = $this->placeOrderUseCase->execute($command);
        
        return new JsonResponse(['order_id' => $orderId->getValue()]);
    }
}

Dependency Rule

External -> Adapters -> Use Cases -> Entities

Dependencies point INWARD
Entities depend on NOTHING
Use Cases depend on Entities
Adapters depend on Use Cases

Key Takeaway

Clean architecture separates concerns into layers. Dependencies point inward. Entities contain business rules, use cases orchestrate, adapters handle external concerns.

Hexagonal (Ports and Adapters) Architecture

         +------------------+
         |   Application    |
         |                  |
    +----+----+       +----+----+
    |  Port   |       |  Port   |
    | (Input) |       | (Output)|
    +----+----+       +----+----+
         |                  |
    +----+----+       +----+----+
    | Adapter |       | Adapter |
    | (Web)   |       | (DB)    |
    +---------+       +---------+

Ports (Interfaces)

// Input Port (Use Case Interface)
interface PlaceOrderInterface
{
    public function execute(PlaceOrderCommand $command): OrderId;
}

// Output Port (Repository Interface)
interface OrderRepositoryInterface
{
    public function save(Order $order): void;
    public function findById(OrderId $id): ?Order;
}

// Output Port (Payment Gateway)
interface PaymentGatewayInterface
{
    public function charge(Order $order): PaymentResult;
}

Adapters (Implementations)

// Web Adapter (Controller)
class RestCreateOrderController
{
    private PlaceOrderInterface $placeOrder;
    
    public function __construct(PlaceOrderInterface $placeOrder)
    {
        $this->placeOrder = $placeOrder;
    }
    
    public function execute(): Response
    {
        $command = $this->buildCommand();
        $orderId = $this->placeOrder->execute($command);
        return new JsonResponse(['order_id' => $orderId->getValue()]);
    }
}

// Database Adapter (Repository)
class MysqlOrderRepository implements OrderRepositoryInterface
{
    private $resource;
    
    public function save(Order $order): void
    {
        $connection = $this->resource->getConnection();
        $connection->insert('sales_order', [
            'entity_id' => $order->getId()->getValue(),
            'customer_id' => $order->getCustomerId()->getValue(),
            'total' => $order->getTotal()->getAmount(),
            'status' => $order->getStatus()->getValue(),
        ]);
    }
}

// GraphQL Adapter
class GraphQLPlaceOrderResolver
{
    private PlaceOrderInterface $placeOrder;
    
    public function resolve($root, $args): array
    {
        $command = new PlaceOrderCommand($args['customer_id'], $args['items']);
        $orderId = $this->placeOrder->execute($command);
        return ['order_id' => $orderId->getValue()];
    }
}

Key Takeaway

Hexagonal architecture uses ports (interfaces) and adapters (implementations). The application core is independent of external concerns like web framework, database, or API.

DDD Building Blocks

Domain
  |
  +-- Entities (Order, Product, Customer)
  +-- Value Objects (Money, Address, OrderId)
  +-- Aggregates (Order + OrderItems)
  +-- Domain Events (OrderPlaced, PaymentReceived)
  +-- Repositories (OrderRepository)
  +-- Services (ShippingService)

Entities and Value Objects

// Entity - has identity
class Order
{
    private OrderId $id;  // Identity
    // ...
}

// Value Object - no identity, immutable
class Money
{
    private int $amount;
    private string $currency;
    
    public function __construct(int $amount, string $currency)
    {
        $this->amount = $amount;
        $this->currency = $currency;
    }
    
    public function add(Money $other): Money
    {
        if ($this->currency !== $other->currency) {
            throw new \DomainException('Cannot add different currencies');
        }
        return new Money($this->amount + $other->amount, $this->currency);
    }
}

Aggregates

// Aggregate Root
class Order
{
    private OrderId $id;
    private array $items = [];
    
    public function addItem(ProductId $productId, int $quantity, Money $price): void
    {
        $this->items[] = new OrderItem($productId, $quantity, $price);
    }
    
    public function removeItem(ProductId $productId): void
    {
        $this->items = array_filter(
            $this->items,
            fn($item) => !$item->getProductId()->equals($productId)
        );
    }
    
    public function getTotal(): Money
    {
        $total = new Money(0, 'USD');
        foreach ($this->items as $item) {
            $total = $total->add($item->getSubtotal());
        }
        return $total;
    }
}

Domain Events

// Event
class OrderPlaced
{
    private OrderId $orderId;
    private CustomerId $customerId;
    private Money $total;
    
    public function __construct(OrderId $orderId, CustomerId $customerId, Money $total)
    {
        $this->orderId = $orderId;
        $this->customerId = $customerId;
        $this->total = $total;
    }
}

// Event Dispatcher
class OrderPlacedHandler
{
    public function __construct(
        private SendOrderConfirmation $sendConfirmation,
        private UpdateInventory $updateInventory
    ) {}
    
    public function handle(OrderPlaced $event): void
    {
        $this->sendConfirmation->execute($event->getOrderId());
        $this->updateInventory->execute($event->getOrderId());
    }
}

Key Takeaway

DDD identifies entities, value objects, aggregates, and domain events. Aggregates maintain consistency boundaries. Domain events decouple side effects from business logic.

Module Structure

app/code/Vendor/Order/
  |
  +-- Api/
  |     +-- Data/           # Value Objects (DTOs)
  |     +-- OrderRepositoryInterface.php  # Port
  |
  +-- Domain/
  |     +-- Model/          # Entities
  |     +-- Event/          # Domain Events
  |     +-- Service/        # Domain Services
  |
  +-- Application/
  |     +-- UseCase/        # Use Cases
  |     +-- Service/        # Application Services
  |
  +-- Infrastructure/
  |     +-- Repository/     # Repository Implementations
  |     +-- Gateway/        # External Service Adapters
  |
  +-- Api/Http/             # REST Controllers (Adapters)
  +-- Api/GraphQl/          # GraphQL Resolvers (Adapters)
  +-- Observer/             # Event Handlers

Service Contracts (Ports)

// Api/Data/OrderInterface.php (Value Object)
interface OrderInterface
{
    public function getOrderId(): ?int;
    public function getCustomerId(): ?int;
    public function getStatus(): ?string;
}

// Api/OrderRepositoryInterface.php (Port)
interface OrderRepositoryInterface
{
    public function save(OrderInterface $order): OrderInterface;
    public function get(int $orderId): OrderInterface;
    public function getList(SearchCriteriaInterface $searchCriteria): SearchResultsInterface;
}

Plugin System (Adapters)

// Plugin for extending behavior
class OrderPlugin
{
    public function aroundPlace(
        Order $subject,
        callable $proceed,
        OrderInterface $order
    ): OrderInterface {
        // Before
        $this->validateOrder($order);
        
        // Execute
        $result = $proceed($order);
        
        // After
        $this->sendNotification($result);
        
        return $result;
    }
}

Repository Pattern (Adapters)

// Repository Implementation
class OrderRepository implements OrderRepositoryInterface
{
    public function save(OrderInterface $order): OrderInterface
    {
        $connection = $this->resource->getConnection();
        $data = $this->toArray($order);
        
        if ($order->getOrderId()) {
            $connection->update('sales_order', $data, ['entity_id' => $order->getOrderId()]);
        } else {
            $connection->insert('sales_order', $data);
        }
        
        return $order;
    }
}

Key Takeaway

Apply architecture principles in Magento through service contracts (ports), repository pattern (adapters), plugin system (cross-cutting concerns), and proper module structure.