• 목록

✅ PHP에서 Hexagonal Architecture (육각형 아키텍처) 적용하기

Hexagonal Architecture (또는 Ports and Adapters)는 내부 도메인 로직을 외부로부터 완전히 격리시키는 아키텍처입니다. 이 구조를 적용하면 프레임워크, UI, DB, 외부 API 등에 의존하지 않고 비즈니스 핵심 로직만을 독립적으로 테스트하고 관리할 수 있게 됩니다.

🧱 핵심 개념

📁 디렉토리 구조 예시

src/
├── Domain/
│   ├── User.php
│   ├── RegisterUserPort.php        ← 입력 포트
│   └── UserRepository.php          ← 출력 포트
├── Application/
│   └── RegisterUserService.php     ← UseCase
├── Adapter/
│   ├── InMemory/
│   │   └── InMemoryUserRepository.php
│   └── Web/
│       └── RegisterUserController.php

🧩 1. 출력 포트: 저장소 인터페이스

[code=php]
namespace Domain;

interface UserRepository {
    public function save(User $user): void;
}
[/code]

🧠 2. 입력 포트: 유스케이스 인터페이스

[code=php]
namespace Domain;

interface RegisterUserPort {
    public function execute(string $email, string $name): void;
}
[/code]

⚙️ 3. 도메인 엔티티

[code=php]
namespace Domain;

class User {
    public function __construct(
        public string $email,
        public string $name
    ) {}
}
[/code]

🧰 4. 유스케이스 서비스

[code=php]
namespace Application;

use Domain\RegisterUserPort;
use Domain\User;
use Domain\UserRepository;

class RegisterUserService implements RegisterUserPort {
    public function __construct(private UserRepository $repo) {}

    public function execute(string $email, string $name): void {
        $user = new User($email, $name);
        $this->repo->save($user);
    }
}
[/code]

🔌 5. 어댑터: 저장소 구현

[code=php]
namespace Adapter\InMemory;

use Domain\User;
use Domain\UserRepository;

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

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

🌐 6. 어댑터: 웹 컨트롤러

[code=php]
namespace Adapter\Web;

use Domain\RegisterUserPort;

class RegisterUserController {
    public function __construct(private RegisterUserPort $useCase) {}

    public function handle(): void {
        $email = $_POST['email'];
        $name = $_POST['name'];

        $this->useCase->execute($email, $name);

        echo "등록 완료";
    }
}
[/code]

✅ 장점

⚠️ 적용 시 주의사항

• 디렉토리/네임스페이스 레벨의 분리 필수

• Service vs Controller vs Repository 역할 구분 명확히

• 초반에는 과설계처럼 느껴질 수 있음 → 점진적 적용 권장

🧠 요약

• Hexagonal Architecture는 도메인 중심 설계의 대표 모델

• 외부는 어댑터로 연결, 핵심은 포트와 유스케이스 중심

• PHP에서도 충분히 적용 가능하며, 프레임워크 독립적이고 테스트 친화적