Managing Legacy PHP: From Technical Debt to Modern Architecture

The Reality of Legacy PHP

Most legacy PHP systems share common characteristics:

• Mixed responsibilities: Database queries embedded in templates, business logic scattered throughout presentation layers
• Global state pollution: Heavy reliance on global variables, superglobals, and shared mutable state
• Inconsistent coding standards: Multiple developers over many years, each with different approaches
• Outdated dependencies: Old PHP versions, unmaintained libraries, security vulnerabilities
• No automated testing: Manual testing processes that slow down changes and increase risk

The temptation is always to start fresh, but that's rarely the right answer. These systems work, they generate revenue, and they embody years of business logic that would be expensive to rebuild.

The Modernization Strategy

1. Establish a Safety Net

Before making any changes, you need confidence that you won't break production. This means:

• Comprehensive monitoring: Error logging, performance monitoring, user behavior tracking
• Automated backups: Both database and file system, with tested restore procedures
• Staging environments: Production-like environments for testing changes
• Feature flags: Ability to roll back changes without deploying new code

2. Identify High-Value Targets

Not all legacy code is created equal. Focus on areas that will give you the biggest impact:

• Performance bottlenecks: Slow queries, inefficient algorithms, resource-intensive operations
• Security vulnerabilities: SQL injection, XSS vulnerabilities, authentication issues
• Frequently changed code: Areas where developers spend the most time
• Business-critical functions: Core revenue-generating features

3. Implement the Strangler Fig Pattern

This pattern allows you to gradually replace old code with new code by routing requests through a facade:

<?php
declare(strict_types=1);
namespace AppServicesUser;
use AppContractsUserServiceInterface;
use AppValueObjectsUserId;
use AppEntitiesUser;
use AppExceptionsUserNotFoundException;
final readonly class StranglerFigUserService implements UserServiceInterface
{
public function __construct(
private UserServiceInterface $legacyService,
private UserServiceInterface $modernService,
private FeatureToggleService $featureToggle,
) {}
public function getUser(UserId $id): User
{
return match ($this->featureToggle->isEnabled('modern_user_service', $id)) {
true => $this->modernService->getUser($id),
false => $this->legacyService->getUser($id),
};
}
private function shouldUseModernImplementation(UserId $id): bool
{
// Canary release: 10% of users
return $id->value % 10 === 0;
}
}

Practical Modernization Techniques

Dependency Injection

Replace global state with explicit dependencies:

<?php
declare(strict_types=1);
// Before: Global database connection
function getUser(int $id): array|false
{
global $db;
return $db->query("SELECT * FROM users WHERE id = {$id}")->fetch();
}
// After: Modern dependency injection with proper typing
final readonly class UserRepository implements UserRepositoryInterface
{
public function __construct(
private PDO $connection,
private UserHydrator $hydrator,
) {}
public function findById(UserId $id): ?User
{
$stmt = $this->connection->prepare(<<< 'SQL'
SELECT id, email, name, created_at, updated_at
FROM users
WHERE id = :id AND deleted_at IS NULL
SQL);
$stmt->execute(['id' => $id->value]);
$userData = $stmt->fetch();
return $userData ? $this->hydrator->hydrate($userData) : null;
}
}

Extract Service Classes

Move business logic out of controllers and into dedicated service classes:

<?php
declare(strict_types=1);
namespace AppServicesOrder;
use AppValueObjects{OrderId, Money, CustomerId};
use AppEntitiesOrder;
use AppEventsOrderPlaced;
use AppExceptions{OrderValidationException, PaymentFailedException};
final readonly class OrderService
{
public function __construct(
private OrderValidator $validator,
private PriceCalculator $calculator,
private PaymentGateway $paymentGateway,
private OrderRepository $repository,
private EventDispatcher $eventDispatcher,
) {}
public function processOrder(OrderData $orderData): Order
{
$this->validator->validate($orderData);
$order = Order::create(
OrderId::generate(),
$orderData->customerId,
$orderData->items,
$this->calculator->calculate($orderData->items)
);
$paymentResult = $this->paymentGateway->charge(
$order->total,
$orderData->paymentMethod
);
if (!$paymentResult->isSuccessful()) {
throw new PaymentFailedException($paymentResult->errorMessage);
}
$order->markAsPaid($paymentResult->transactionId);
$this->repository->save($order);
$this->eventDispatcher->dispatch(
new OrderPlaced($order->id, $order->customerId)
);
return $order;
}
}

Implement Automated Testing

Start with integration tests for critical paths, then add unit tests as you refactor:

<?php
declare(strict_types=1);
namespace TestsUnitServicesOrder;
use AppServicesOrderOrderService;
use AppTesting{OrderDataBuilder, PaymentResultBuilder};
use AppExceptionsPaymentFailedException;
use PHPUnitFrameworkTestCase;
use PHPUnitFrameworkAttributes{Test, TestDox};
final class OrderServiceTest extends TestCase
{
#[Test]
#[TestDox('Successfully processes valid order with payment')]
public function processOrder_WithValidData_CreatesOrderAndProcessesPayment(): void
{
// Arrange
$orderData = OrderDataBuilder::new()
->withCustomer(CustomerId::fromString('cust_123'))
->withItems([
OrderItemBuilder::new()->withProduct('prod_456')->build(),
])
->build();
$paymentResult = PaymentResultBuilder::successful()
->withTransactionId('txn_789')
->build();
$this->paymentGateway->shouldReceive('charge')
->once()
->with(Money::fromCents(1000), $orderData->paymentMethod)
->andReturn($paymentResult);
// Act
$order = $this->orderService->processOrder($orderData);
// Assert
$this->assertInstanceOf(Order::class, $order);
$this->assertTrue($order->isPaid());
$this->assertEquals('txn_789', $order->transactionId->value);
$this->repository->shouldHaveReceived('save')
->once()
->with($order);
$this->eventDispatcher->shouldHaveReceived('dispatch')
->once()
->with(Mockery::type(OrderPlaced::class));
}
}

Managing the Transition

Team Buy-in

Modernization efforts fail without team support. Make sure everyone understands:

• The business case for modernization
• How changes will improve their daily work
• The incremental approach that minimizes risk
• Success metrics and how progress will be measured

Documentation and Knowledge Transfer

Legacy systems often have tribal knowledge. Document:

• Business rules embedded in code
• Integration points and data flows
• Deployment procedures and environment setup
• Common troubleshooting scenarios

Common Pitfalls to Avoid

• Big bang rewrites: They rarely work and often fail spectacularly
• Perfectionism: Don't let perfect be the enemy of good
• Ignoring performance: Modern doesn't always mean faster
• Over-engineering: Solve today's problems, not imaginary future ones
• Neglecting deployment: Modernize your deployment process alongside your code

Measuring Success

Track metrics that matter to both developers and business stakeholders:

• Code quality: Test coverage, code complexity, technical debt ratio
• Performance: Page load times, database query performance, memory usage
• Developer productivity: Time to implement features, deployment frequency
• Business impact: Bug reports, customer satisfaction, revenue impact

The Long Game

Legacy PHP modernization is a marathon, not a sprint. Success comes from:

• Consistent, incremental improvements
• Clear communication with stakeholders
• Balancing technical debt with feature delivery
• Building team capabilities alongside system improvements

Remember: the goal isn't to have the most modern technology stack. It's to have a system that serves your business needs reliably, can be maintained efficiently, and can evolve with your requirements.

Every legacy system got that way by being successful. Respect that success while building for the future.