Skip to main content
skill CX Codex

clean-architecture · giuseppe-trisciuoglio, developer-kit-php — Claude Code skill: layers, ports and DDD in PHP

clean-architecture splits a Symfony app into Domain, Application, Adapter and Infrastructure layers, with patterns for entities, value objects and ports that stay free of framework code.

MIT ★ 372 updated 2026-09-10

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add giuseppe-trisciuoglio/developer-kit
/plugin install developer-kit-php@developer-kit
Open on GitHub

What clean-architecture does

You get a directory layout for src/Domain, src/Application, src/Adapter and src/Infrastructure, plus the dependency rule that keeps arrows pointing inward. The skill walks the layers in order, starting with immutable value objects that check themselves at construction and moving on to entities carrying business rules, repository interfaces and domain events.

Use cases come next: commands and queries as readonly DTOs, handlers coordinating domain objects, interfaces for anything external. Symfony side means controllers, request DTOs with validation attributes, Doctrine repositories, and DI bindings that connect a port to its implementation. In-memory repositories let the domain run in unit tests without a database.

It targets PHP 8.3+ and Symfony 7.x, so an older stack means rewriting the samples against your own signatures. The skill holds Read, Write, Edit, Bash, Glob and Grep permissions and edits project files rather than only describing layers.

What it helps with

  • Split a fat Symfony controller into Domain, Application and Adapter classes
  • Move business rules out of Doctrine entities into plain PHP
  • Write an immutable value object that validates on construction
  • Swap a Doctrine repository for an in-memory double in unit tests
  • Wire port interfaces to implementations in services.yaml

Example prompts for the agent

  • Refactor src/Controller/OrderController.php into the four layers and keep the logic in the entity.
  • Create a Money value object that rejects invalid amounts in its constructor.
  • Show me how to bind UserRepositoryInterface to the Doctrine implementation in services.yaml.

How to install clean-architecture

1Plugin marketplace

/plugin marketplace add giuseppe-trisciuoglio/developer-kit
/plugin install developer-kit-php@developer-kit

This installs the whole developer-kit-php plugin with all its skills

2Skills CLI (Vercel)

npx skills add giuseppe-trisciuoglio/developer-kit --skill clean-architecture -a claude-code

3Manually: put the files in place

~/.claude/skills/clean-architecture/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/clean-architecture/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about clean-architecture

How do I install clean-architecture in Claude Code?

Add the marketplace first: /plugin marketplace add giuseppe-trisciuoglio/developer-kit. Then run /plugin install developer-kit-php@developer-kit.

What does clean-architecture do?

It sets out the layer split and the inward dependency rule, then supplies patterns for entities, value objects, ports, commands and handlers in PHP 8.3+ with Symfony 7.x.

Which PHP and Symfony versions does it need?

PHP 8.3+ and Symfony 7.x. The samples rely on features from those releases, so older projects need adjustments.

Source text

SKILL.md · MIT
---
name: clean-architecture
description: Provides implementation patterns for Clean Architecture, Hexagonal Architecture (Ports & Adapters), and Domain-Driven Design in PHP 8.3+ with Symfony 7.x. Use when architecting enterprise PHP applications with entities/value objects/aggregates, refactoring legacy code to modern patterns, implementing domain-driven design with Symfony, or creating testable backends with clear separation of concerns.
allowed-tools: Read, Write, Bash, Edit, Glob, Grep
---

# Clean Architecture, Hexagonal Architecture & DDD for PHP/Symfony

## Overview

This skill provides guidance for implementing Clean Architecture, Hexagonal Architecture (Ports & Adapters), and Domain-Driven Design patterns in PHP 8.3+ applications using Symfony 7.x. It ensures clear separation of concerns, framework-independent business logic, and highly testable code through layered architecture with inward-only dependencies.

## When to Use

- Architecting new enterprise PHP applications with Symfony 7.x
- Refactoring legacy PHP code to modern, testable patterns
- Implementing Domain-Driven Design in PHP projects
- Creating maintainable applications with clear separation of concerns
- Building testable business logic independent of frameworks
- Designing modular PHP systems with swappable infrastructure

## Instructions

### 1. Understand the Architecture Layers

Clean Architecture follows the dependency rule: dependencies only point inward.

```
+-------------------------------------+
|  Infrastructure (Frameworks)        |  Symfony, Doctrine, External APIs
+-------------------------------------+
|  Adapter (Interface Adapters)       |  Controllers, Repositories, Presenters
+-------------------------------------+
|  Application (Use Cases)            |  Commands, Handlers, DTOs
+-------------------------------------+
|  Domain (Entities & Business Rules) |  Entities, Value Objects, Domain Events
+-------------------------------------+
```

**Hexagonal Architecture (Ports & Adapters)**:
- **Domain Core**: Business logic, framework-agnostic
- **Ports**: Interfaces (e.g., `UserRepositoryInterface`)
- **Adapters**: Concrete implementations (Doctrine, InMemory for tests)

**DDD Tactical Patterns**:
- **Entities**: Objects with identity (e.g., `User`, `Order`)
- **Value Objects**: Immutable, defined by attributes (e.g., `Email`, `Money`)
- **Aggregates**: Consistency boundaries with root entity
- **Domain Events**: Capture business occurrences
- **Repositories**: Persist/retrieve aggregates

### 2. Organize Directory Structure

Create the following directory structure to enforce layer separation:

```
src/
+-- Domain/                 # Innermost layer - no dependencies
|   +-- Entity/
|   |   +-- User.php
|   |   +-- Order.php
|   +-- ValueObject/
|   |   +-- Email.php
|   |   +-- Money.php
|   |   +-- OrderId.php
|   +-- Repository/
|   |   +-- UserRepositoryInterface.php
|   +-- Event/
|   |   +-- UserCreatedEvent.php
|   +-- Exception/
|       +-- DomainException.php
+-- Application/            # Use cases - depends on Domain
|   +-- Command/
|   |   +-- CreateUserCommand.php
|   |   +-- UpdateOrderCommand.php
|   +-- Handler/
|   |   +-- CreateUserHandler.php
|   |   +-- UpdateOrderHandler.php
|   +-- Query/
|   |   +-- GetUserQuery.php
|   +-- Dto/
|   |   +-- UserDto.php
|   +-- Service/
|       +-- NotificationServiceInterface.php
+-- Adapter/                # Interface adapters
|   +-- Http/
|   |   +-- Controller/
|   |   |   +-- UserController.php
|   |   +-- Request/
|   |       +-- CreateUserRequest.php
|   +-- Persistence/
|       +-- Doctrine/
|           +-- Repository/
|           |   +-- DoctrineUserRepository.php
|           +-- Mapping/
|               +-- User.orm.xml
+-- Infrastructure/         # Framework & external concerns
    +-- Config/
    |   +-- services.yaml
    +-- Event/
    |   +-- SymfonyEventDispatcher.php
    +-- Service/
        +-- SendgridEmailService.php
```

### 3. Implement Domain Layer

Start from the innermost layer (Domain) and work outward:

1. **Create Value Objects** with validation at construction time - they must be immutable using PHP 8.1+ `readonly`
2. **Create Entities** with domain logic and business rules - entities should encapsulate behavior, not just be data bags
3. **Define Repository Interfaces** (Ports) - keep them small and focused
4. **Define Domain Events** to decouple side effects from core business logic

### 4. Implement Application Layer

Build use cases that orchestrate domain objects:

1. **Create Commands** as readonly DTOs representing write operations
2. **Create Queries** for read operations (CQRS pattern)
3. **Implement Handlers** that receive commands/queries and coordinate domain objects
4. **Define Service Interfaces** for external dependencies (notifications, etc.)

### 5. Implement Adapter Layer

Create interface adapters that connect Application to Infrastructure:

1. **Create Controllers** that receive HTTP requests and invoke handlers
2. **Create Request DTOs** with Symfony validation attributes
3. **Implement Repository Adapters** that bridge domain interfaces to persistence layer

### 6. Configure Infrastructure

Set up framework-specific configuration:

1. **Configure Symfony DI** to bind interfaces to implementations
2. **Create test doubles** (In-Memory repositories) for unit testing without database
3. **Configure Doctrine mappings** for persistence

### 7. Test Without Framework

Ensure Domain and Application layers are testable without Symfony, Doctrine, or database. Use In-Memory repositories for fast unit tests.

## Examples

### Example 1: Value Object with Validation

```php
<?php
// src/Domain/ValueObject/Email.php

namespace App\Domain\ValueObject;

use InvalidArgumentException;

final readonly class Email
{
    public function __construct(
        private string $value
    ) {
        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidArgumentException(
                sprintf('"%s" is not a valid email address', $value)
            );
        }
    }

    public function value(): string
    {
        return $this->value;
    }

    public function equals(self $other): bool
    {
        return $this->value === $other->value;
    }

    public function domain(): string
    {
        return substr($this->value, strrpos($this->value, '@') + 1);
    }
}
```

### Example 2: Entity with Domain Logic

```php
<?php
// src/Domain/Entity/User.php

namespace App\Domain\Entity;

use App\Domain\ValueObject\Email;
use App\Domain\ValueObject\UserId;
use App\Domain\Event\UserCreatedEvent;
use DateTimeImmutable;

class User
{
    private array $domainEvents = [];

    public function __construct(
        private UserId $id,
        private Email $email,
        private string $name,
        private DateTimeImmutable $createdAt,
        private bool $isActive = true
    ) {
        $this->recordEvent(new UserCreatedEvent($id->value()));
    }

    public static function create(
        UserId $id,
        Email $email,
        string $name
    ): self {
        return new self(
            $id,
            $email,
            $name,
            new DateTimeImmutable()
        );
    }

    public function deactivate(): void
    {
        $this->isActive = false;
    }

    public function canPlaceOrder(): bool
    {
        return $this->isActive;
    }

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

    public function email(): Email
    {
        return $this->email;
    }

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

    public function clearDomainEvents(): void
    {
        $this->domainEvents = [];
    }

    private function recordEvent(object $event): void
    {
        $this->domainEvents[] = $event;
    }
}
```

### Example 3: Repository Port (Interface)

```php
<?php
// src/Domain/Repository/UserRepositoryInterface.php

namespace App\Domain\Repository;

use App\Domain\Entity\User;
use App\Domain\ValueObject\Email;
use App\Domain\ValueObject\UserId;

interface UserRepositoryInterface
{
    public function findById(UserId $id): ?User;

    public function findByEmail(Email $email): ?User;

    public function save(User $user): void;

    public function delete(UserId $id): void;
}
```

### Example 4: Command and Handler

```php
<?php
// src/Application/Command/CreateUserCommand.php

namespace App\Application\Command;

final readonly class CreateUserCommand
{
    public function __construct(
        public string $id,
        public string $email,
        public string $name
    ) {
    }
}
```

```php
<?php
// src/Application/Handler/CreateUserHandler.php

namespace App\Application\Handler;

use App\Application\Command\CreateUserCommand;
use App\Domain\Entity\User;
use App\Domain\Repository\UserRepositoryInterface;
use App\Domain\ValueObject\Email;
use App\Domain\ValueObject\UserId;
use InvalidArgumentException;

readonly class CreateUserHandler
{
    public function __construct(
        private UserRepositoryInterface $userRepository
    ) {
    }

    public function __invoke(CreateUserCommand $command): void
    {
        $email = new Email($command->email);

        if ($this->userRepository->findByEmail($email) !== null) {
            throw new InvalidArgumentException(
                'User with this email already exists'
            );
        }

        $user = User::create(
            new UserId($command->id),
            $email,
            $command->name
        );

        $this->userRepository->save($user);
    }
}
```

### Example 5: Symfony Controller

```php
<?php
// src/Adapter/Http/Controller/UserController.php

namespace App\Adapter\Http\Controller;

use App\Adapter\Http\Request\CreateUserRequest;
use App\Application\Command\CreateUserCommand;
use App\Application\Handler\CreateUserHandler;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Attribute\AsController;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Uid\Uuid;

#[AsController]
class UserController
{
    public function __construct(
        private CreateUserHandler $createUserHandler
    ) {
    }

    #[Route('/api/users', methods: ['POST'])]
    public function create(CreateUserRequest $request): JsonResponse
    {
        $command = new CreateUserCommand(
            id: Uuid::v4()->toRfc4122(),
            email: $request->email,
            name: $request->name
        );

        ($this->createUserHandler)($command);

        return new JsonResponse(['id' => $command->id], 201);
    }
}
```

### Example 6: Request DTO with Validation

```php
<?php
// src/Adapter/Http/Request/CreateUserRequest.php

namespace App\Adapter\Http\Request;

use Symfony\Component\Validator\Constraints as Assert;

class CreateUserRequest
{
    #[Assert\NotBlank]
    #[Assert\Email]
    public string $email;

    #[Assert\NotBlank]
    #[Assert\Length(min: 2, max: 100)]
    public string $name;
}
```

### Example 7: Doctrine Repository Adapter

```php
<?php
// src/Adapter/Persistence/Doctrine/Repository/DoctrineUserRepository.php

namespace App\Adapter\Persistence\Doctrine\Repository;

use App\Domain\Entity\User;
use App\Domain\Repository\UserRepositoryInterface;
use App\Domain\ValueObject\Email;
use App\Domain\ValueObject\UserId;
use Doctrine\ORM\EntityManagerInterface;

readonly class DoctrineUserRepository implements UserRepositoryInterface
{
    public function __construct(
        private EntityManagerInterface $entityManager
    ) {
    }

    public function findById(UserId $id): ?User
    {
        return $this->entityManager
            ->getRepository(User::class)
            ->find($id->value());
    }

    public function findByEmail(Email $email): ?User
    {
        return $this->entityManager
            ->getRepository(User::class)
            ->findOneBy(['email.value' => $email->value()]);
    }

    public function save(User $user): void
    {
        $this->entityManager->persist($user);
        $this->entityManager->flush();
    }

    public function delete(UserId $id): void
    {
        $user = $this->findById($id);
        if ($user !== null) {
            $this->entityManager->remove($user);
            $this->entityManager->flush();
        }
    }
}
```

### Example 8: Symfony DI Configuration

```yaml
# config/services.yaml
services:
    _defaults:
        autowire: true
        autoconfigure: true

    App\:
        resource: '../src/'
        exclude:
            - '../src/Domain/Entity/'
            - '../src/Kernel.php'

    # Repository binding - Port to Adapter
    App\Domain\Repository\UserRepositoryInterface:
        class: App\Adapter\Persistence\Doctrine\Repository\DoctrineUserRepository

    # In-memory repository for tests
    App\Domain\Repository\UserRepositoryInterface $inMemoryUserRepository:
        class: App\Tests\Infrastructure\Repository\InMemoryUserRepository
```

### Example 9: In-Memory Repository for Testing

```php
<?php
// tests/Infrastructure/Repository/InMemoryUserRepository.php

namespace App\Tests\Infrastructure\Repository;

use App\Domain\Entity\User;
use App\Domain\Repository\UserRepositoryInterface;
use App\Domain\ValueObject\Email;
use App\Domain\ValueObject\UserId;

class InMemoryUserRepository implements UserRepositoryInterface
{
    private array $users = [];

    public function findById(UserId $id): ?User
    {
        return $this->users[$id->value()] ?? null;
    }

    public function findByEmail(Email $email): ?User
    {
        foreach ($this->users as $user) {
            if ($user->email()->equals($email)) {
                return $user;
            }
        }
        return null;
    }

    public function save(User $user): void
    {
        $this->users[$user->id()->value()] = $user;
    }

    public function delete(UserId $id): void
    {
        unset($this->users[$id->value()]);
    }
}
```

## Best Practices

1. **Dependency Rule**: Dependencies only point inward - domain knows nothing of application or infrastructure
2. **Immutability**: Value Objects MUST be immutable using `readonly` in PHP 8.1+ - never allow mutable state
3. **Rich Domain Models**: Put business logic in entities with factory methods like `create()` - avoid anemic models
4. **Interface Segregation**: Keep repository interfaces small and focused - do not create god interfaces
5. **Framework Independence**: Domain and application layers MUST be testable without Symfony or Doctrine
6. **Validation at Construction**: Validate in Value Objects at construction time - never allow invalid state
7. **Symfony Attributes**: Use PHP 8 attributes for routing (`#[Route]`), validation (`#[Assert\]`), and DI
8. **Test Doubles**: Always provide In-Memory implementations for repositories to enable fast unit tests
9. **Domain Events**: Dispatch domain events to decouple side effects - do not call external services from entities
10. **XML/YAML Mappings**: Use XML or YAML for Doctrine mappings instead of annotations in domain entities

## Constraints and Warnings

### Architecture Constraints

- **Dependency Rule**: Dependencies only point inward. Domain knows nothing of Application, Application knows nothing of Infrastructure. Violating this breaks the architecture.
- **No Anemic Domain**: Entities should encapsulate behavior, not just be data bags. Avoid getters/setters without business logic.
- **Interface Segregation**: Keep repository interfaces small and focused. Do not create god interfaces.

### PHP Implementation Constraints

- **Immutability**: Value Objects MUST be immutable using `readonly` in PHP 8.1+. Never allow mutable state in Value Objects.
- **Validation**: Validate in Value Objects at construction time. Never allow invalid state to exist.
- **Symfony Attributes**: Use PHP 8 attributes for routing, validation, and DI (`#[Route]`, `#[Assert\Email]`, `#[Autowire]`).

### Testing Constraints

- **Framework Independence**: Domain and Application layers MUST be testable without Symfony, Doctrine, or database.
- **Test Doubles**: Always provide In-Memory implementations for repository interfaces to enable fast unit tests.

### Warnings

- **Avoid Rich Domain Models in Controllers**: Controllers should only coordinate, not contain business logic.
- **Beware of Leaky Abstractions**: Infrastructure concerns (like Doctrine annotations) should not leak into Domain entities. Use XML/YAML mappings instead.
- **Command Bus Consideration**: For complex applications, use Symfony Messenger for async processing. Do not inline complex orchestrations in handlers.
- **Domain Events**: Dispatch domain events to decouple side effects from core business logic. Do not call external services directly from entities.

## References

- [PHP Clean Architecture Patterns](references/php-clean-architecture.md)
- [Symfony Implementation Guide](references/symfony-implementation.md)

© Giuseppe Trisciuoglio · MIT · giuseppe-trisciuoglio/developer-kit

Similar skills

All skills for Backend and APIs →

clean-architecture by other authors comes first.

clean-architecture wondelai clean-architecture — a skill that keeps business rules independent of framework and database by enforcing one rule: source code dependencies point inward. CX Codex +1 8,000installs clean-architecture codewithmukesh clean-architecture — a skill that lays out .NET code across four projects, keeps dependencies pointing inward, and shows where use case handlers belong. CX Codex +1 4,200installs clean-architecture ciembor This Claude Code skill applies clean architecture principles to decisions about separating business policy from implementation details. It activates for work on dependency direction, use cases, and application boundaries. CX Codex +1 645installs clean-architecture giuseppe-trisciuoglio Skill for designing layered Java 21+ and Spring Boot 3.5+ applications. Separates business logic from the framework by uniting Clean Architecture, Hexagonal Architecture, and Domain-Driven Design into one system. CX Codex +1 4,200installs clean-architecture pproenca clean-architecture — a skill with 42 rules from Robert C. Martin's book: it tells the agent which way dependencies should point and where layer boundaries belong. CX Codex +1 2,100installs architecture-advisor codewithmukesh architecture-advisor runs a questionnaire on domain, team and system lifetime, then recommends an architecture for your .NET project. Useful before you lay out folders. CX Codex +1 4,000installs ports-and-adapters dev-toolings ports-and-adapters guides Claude Code in setting up Hexagonal Architecture in Symfony, isolating domain models from Doctrine, HTTP, and vendor SDKs. CX Codex +1 ★ 234repo stars go-backend-clean-architecture rebyteai-template go-backend-clean-architecture scaffolds a Go backend in the current folder: Gin, MongoDB, JWT auth and Clean Architecture layers, from clone to first run. CX Codex +1 105installs android-clean-architecture affaan-m android-clean-architecture tells the agent how to split an Android or KMP project into layers: modules, dependency rules, UseCases, repositories, plus Room, SQLDelight and Ktor patterns. CX Codex +1 7,200installs architecture-patterns Seth Hobson architecture-patterns guides backend architecture with Clean Architecture, Hexagonal Architecture, and DDD. Use it when designing a service, untangling a monolith, or tracing dependency cycles. CX Codex +1 24,144installs architecture-review decebals architecture-review — a skill that reviews a Java project at the macro level: package layout, module boundaries, dependency direction and layering. Useful once a codebase grows past the point where you can hold its structure in your head. CX Codex +1 394installs

From the same set191

The whole set →
java-software-architect-review The java-software-architect-review subagent reviews Java architecture through Clean Architecture, DDD, and Spring Boot patterns. Use it when shaping a design or checking an existing codebase. CX Codex ★ 372repo stars java-documentation-specialist java-documentation-specialist reads a Spring Boot codebase and writes it up: endpoints, database schema, architecture notes. Handy when the project has to be explained to somebody else. CX Codex ★ 372repo stars devkit.github.review-pr devkit.github.review-pr inspects GitHub pull requests before merging by reviewing diffs, scanning for leaked secrets, and evaluating architecture or security risks. CX Codex +1 ★ 372repo stars java-refactor-expert java-refactor-expert is a Claude Code subagent that restructures Java and Spring Boot code while keeping its behavior intact. It can run after feature work or on a code-quality request. CX Codex ★ 372repo stars speckit.optimize speckit.optimize analyzes tasks.md to uncover blocking dependencies and generate a parallel subagent execution strategy. CX Codex +1 ★ 372repo stars aws-cloudformation-devops-expert The aws-cloudformation-devops-expert subagent for Claude Code creates and reviews CloudFormation templates, links stacks, and prepares AWS deployment automation for Infrastructure as Code and CI/CD tasks. CX Codex ★ 372repo stars react-software-architect-review react-software-architect-review audits React architecture: how components compose, where state lives, how data flows, what costs render time. Useful once a React 19 or Next.js codebase has grown past its first structure. CX Codex ★ 372repo stars devkit.fix-debugging The devkit.fix-debugging command for Claude Code systematically investigates bug root causes and coordinates specialized sub-agents to prepare minimal fixes. CX Codex +1 ★ 372repo stars

Project sponsors

Companies that keep this analytics open