X

Understanding Clean Architecture in PHP with Real Examples

As PHP applications grow, maintaining clean, scalable, and testable code becomes challenging. This is where Clean Architecture, introduced by Robert C. Martin (Uncle Bob), helps. It provides a way to structure your PHP application so that business logic stays independent of frameworks, databases, or external tools.

In this article, we break down Clean Architecture for PHP developers and provide simple, real-world examples.

What Is Clean Architecture?

Clean Architecture is a way of designing software systems with clear separation of concerns. The idea is simple:

👉 Your business logic should not depend on anything external.
Frameworks, databases, and UI should be replaceable without changing core logic.

The Core Principles:

  • Independent of frameworks

  • Independent of UI (web, API, CLI)

  • Independent of database

  • Easy to test

  • Separation of concerns

Clean Architecture Layers

Clean Architecture is usually visualized as concentric circles:

1. Entities (Core Domain)

Business rules and enterprise-wide logic.

2. Use Cases (Application Logic)

Application-specific processes (e.g., "Register User", "Place Order").

3. Interface Adapters

Converts data between internal and external formats.
Examples: Controllers, Repositories, Presenters.

4. Infrastructure Layer

External systems like DB, frameworks (Laravel, Symfony), logging, email, etc.

Real Example in PHP — User Registration Flow

Let’s create a simple example:

1️⃣ Entities Layer (Pure PHP Classes)

class User {
    public $name;
    public $email;

    public function __construct($name, $email) {
        $this->name  = $name;
        $this->email = $email;
    }
}

This class has zero dependency on database, framework, or external library.

2️⃣ Use Case Layer

Business rule: Register a user.

class RegisterUser {
    private $userRepository;

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

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

The use case depends only on an interface, not on MySQL, Laravel, or files.

3️⃣ Interface Adapter Layer

Define repository interface:

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

4️⃣ Infrastructure Layer (Database Implementation)

Actual MySQL implementation:

class MySQLUserRepository implements UserRepository {
    public function save(User $user) {
        // Insert into DB
        // This can be PDO, Laravel ORM, Symfony DBAL — anything.
        return "User saved: " . $user->email;
    }
}

Notice the core code does NOT depend on MySQL.
We can change MySQL to MongoDB or JSON without touching business logic.

Controller Example (Using the Use Case)

$repo = new MySQLUserRepository();
$useCase = new RegisterUser($repo);

echo $useCase->execute("Aman", "aman@example.com");

The system is clean, testable, and maintainable.

Why Use Clean Architecture in PHP (2025 Benefits)

✔ Better Testability

You can test use cases without databases or frameworks.

✔ Scalability

Add new features without breaking old code.

✔ Framework Independence

Switch between Laravel, Symfony, Slim, or custom PHP — without changing core logic.

✔ Maintainable Codebase

Everything stays organized and easy to understand.

✔ Easy to onboard new developers

Clear boundaries = faster understanding.

Common Mistakes Developers Make

❌ Putting business logic inside controllers
❌ Mixing database code with models
❌ Making core logic dependent on frameworks
❌ Overusing service containers
❌ No separation between input/output and domain logic

Clean Architecture helps avoid all of these.

Conclusion

Clean Architecture in PHP allows you to build strong, scalable, and framework-independent applications. By separating entities, use cases, adapters, and infrastructure, your code becomes clean, testable, and future-proof.

Whether you're building a small project or a complete enterprise system, Clean Architecture is a powerful pattern to follow.

Tags
PHP