PHP - Clean Architecture in PHP

Clean Architecture is a software design approach that focuses on creating systems that are easy to maintain, test, and scale. It emphasizes separation of concerns, meaning each part of the application has a clear responsibility and is independent of other parts. In PHP, applying Clean Architecture helps developers build structured and long-lasting applications.

Core Idea of Clean Architecture

The main principle of Clean Architecture is that business logic should not depend on external frameworks, databases, or user interfaces. Instead, everything depends inward toward the core logic of the application.

This ensures that the most important part of the system, the business rules, remains stable even if external technologies change.

Layers of Clean Architecture

Clean Architecture divides an application into multiple layers. Each layer has a specific role and strict dependency rules.

Entities (Core Layer)

Entities represent the core business objects and rules. These are the most stable and independent parts of the application.

Example:

class User {
    private $email;

    public function __construct($email) {
        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            throw new Exception("Invalid email");
        }
        $this->email = $email;
    }

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

This layer contains pure business logic and does not depend on anything else.

Use Cases (Application Layer)

Use cases define the application-specific business rules. They coordinate between entities and external layers.

Example:

class RegisterUser {
    private $userRepository;

    public function __construct(UserRepository $userRepository) {
        $this->userRepository = $userRepository;
    }

    public function execute($email) {
        $user = new User($email);
        $this->userRepository->save($user);
    }
}

This layer controls how the system behaves in response to user actions.

Interface Adapters (Controller Layer)

This layer acts as a bridge between the application and external systems. It converts data between formats suitable for the use cases and external interfaces.

Example:

class UserController {
    private $registerUser;

    public function __construct(RegisterUser $registerUser) {
        $this->registerUser = $registerUser;
    }

    public function handleRequest($request) {
        $email = $request['email'];
        $this->registerUser->execute($email);
    }
}

Infrastructure (Frameworks & External Layer)

This is the outermost layer, which includes:

Databases
Frameworks
APIs
File systems

Example:

class MySQLUserRepository implements UserRepository {
    public function save(User $user) {
        // Database logic here
    }
}

This layer depends on inner layers but not vice versa.

Dependency Rule

The most important rule in Clean Architecture is:

Dependencies must always point inward.

Outer layers can depend on inner layers
Inner layers must not depend on outer layers

To achieve this, interfaces are used.

Example:

interface UserRepository {
    public function save(User $user);
}

The inner layer defines the interface, and the outer layer implements it.

Benefits of Clean Architecture

Clean Architecture offers several advantages:

Independence from frameworks
Easier testing since business logic is isolated
Improved maintainability
Flexibility to change databases or UI without affecting core logic
Better organization of large codebases

Example Flow in a PHP Application

A user sends a request through an HTTP endpoint
The controller receives the request
The controller calls a use case
The use case processes business logic using entities
The use case interacts with a repository interface
The infrastructure layer implements the repository and stores data

Each layer has a clear role and minimal dependency on others.

Challenges

Initial setup can be complex
Requires discipline to maintain separation
May feel excessive for small projects

When to Use Clean Architecture

Clean Architecture is most useful when:

Building large or long-term applications
Working with teams
Expecting frequent changes in technology
Needing strong testability

Conclusion

Clean Architecture in PHP is a structured approach to designing applications where business logic remains independent of external systems. By organizing code into layers and enforcing dependency rules, it ensures that applications are maintainable, scalable, and adaptable. Although it introduces some complexity, it provides long-term benefits, especially for complex and evolving software systems.