How to Transform Legacy PHP Code into a Clean, Testable Architecture

In today's fast‑moving tech environment, many companies still rely on PHP codebases written years ago. These traditional, procedural‑style codes lack clear architecture, making maintenance, extension, and testing extremely difficult. This article explores how to gradually refactor such legacy PHP systems into modern, clean, and testable architectures.

Common Problems in Traditional PHP Code

Spaghetti code: logic scattered across many files with tangled function and procedure calls.

Abuse of global state: over‑reliance on global and super‑global variables (GET, POST, etc.).

Mixed layers: business logic, data access, and presentation are intertwined.

Lack of tests: high coupling makes unit testing nearly impossible.

Duplicate code: similar code fragments appear in multiple places.

Refactoring Strategies

1. Establish a Testing Safety Net

Before refactoring, add high‑level tests (functional or acceptance tests) for critical business logic to ensure existing functionality is not broken during the process.

<code>// Example functional test
class OrderProcessingTest extends PHPUnit\Framework\TestCase
{
    public function testOrderTotalCalculation()
    {
        $order = new Order();
        $order->addItem(new Item('Product A', 100));
        $order->addItem(new Item('Product B', 200));
        $this->assertEquals(300, $order->calculateTotal());
    }
}
</code>

2. Introduce Dependency Injection Incrementally

Replace global dependencies with explicit dependency injection to achieve loose coupling.

Before refactoring:

<code>function processOrder()
{
    global $db;
    // use $db
}
</code>

After refactoring:

<code>class OrderProcessor
{
    private $db;
    public function __construct(Database $db)
    {
        $this->db = $db;
    }
    public function process(Order $order)
    {
        // use $this->db
    }
}
</code>

3. Separate Concerns

Adopt MVC or layered architecture to split code into distinct responsibility layers:

Presentation layer: handles HTTP requests and responses.

Business logic layer: contains core business rules.

Data access layer: interacts with the database.

4. Apply Domain‑Driven Design (DDD)

For complex business systems, introduce DDD concepts to better organize code.

<code>class Order
{
    private $items;
    private $status;

    public function addItem(Item $item)
    {
        $this->items[] = $item;
    }

    public function calculateTotal()
    {
        return array_reduce($this->items, fn($sum, $item) => $sum + $item->getPrice(), 0);
    }

    public function markAsPaid()
    {
        $this->status = 'paid';
    }
}
</code>

5. Replace Direct SQL Calls with Repository Pattern

Before refactoring:

<code>function getUsers()
{
    global $db;
    return $db->query("SELECT * FROM users");
}
</code>

After refactoring:

<code>interface UserRepository
{
    public function findAll(): array;
}

class DatabaseUserRepository implements UserRepository
{
    private $db;
    public function __construct(Database $db)
    {
        $this->db = $db;
    }
    public function findAll(): array
    {
        return $this->db->query("SELECT * FROM users");
    }
}
</code>

Modern Tools and Techniques

Composer: dependency management tool.

PSR standards: follow PHP Standard Recommendations (e.g., PSR‑4 autoloading).

Static analysis tools: PHPStan or Psalm to discover potential issues.

Framework components: use Symfony or Laravel components individually instead of a full‑stack framework.

Incremental Refactoring Approach

Identify pain points: start with the most problematic areas.

Take small steps: make tiny, controlled changes each time.

Continuous integration: ensure all tests pass after each change.

Gradual replacement: use strategy or adapter patterns to replace old code gradually.

Conclusion

Refactoring legacy PHP code into a modern architecture requires patience and strategy. By gradually introducing design patterns, dependency injection, and layered architecture, you can significantly improve maintainability, testability, and scalability. Remember, the goal is not to rewrite the entire system but to continuously improve code quality through safe, incremental steps while keeping the system operational.

A well‑structured PHP application becomes easier to maintain and extend, enabling development teams to work more efficiently and deliver greater business value.