Proxy Pattern

Also Known As

TL;DR

Explanation

The Proxy pattern places an intermediary in front of a real object, implementing the same interface. Types: Virtual Proxy (defers expensive object creation until needed — lazy loading), Caching Proxy (caches results of operations on the real object), Protection Proxy (enforces access control), and Remote Proxy (represents an object in a different process or server). In PHP, Doctrine ORM uses virtual proxies for lazy-loaded entities. The Proxy differs from Decorator in intent: Decorator adds behaviour, Proxy controls access. PHP's magic methods (__get, __call) enable dynamic proxy creation.

Common Misconception

Why It Matters

Common Mistakes

• Not implementing the same interface as the real subject — callers must change to use the proxy.
• Proxy that adds logic the real object should have — the proxy should be transparent infrastructure, not business logic.
• Virtual proxies that initialise the real object eagerly — defeating the lazy loading purpose.
• Confusing proxy (same interface, controlled access) with decorator (same interface, added behaviour) — they serve different purposes.

Code Examples

// Direct access — no caching, no access control:
class ReportService {
    public function getExpensiveReport(int $id): Report {
        return $this->db->runHeavyQuery($id); // Called every time
    }
}
// A CachingReportProxy would intercept and cache without changing ReportService

interface Image {
    public function render(): string;
}

class RealImage implements Image {
    public function __construct(private string $path) {
        $this->loadFromDisk(); // expensive
    }
    public function render(): string { return "<img src='{$this->path}'>"; }
}

// Lazy-loading proxy — defers expensive load until render() is first called
class LazyImage implements Image {
    private ?RealImage $real = null;
    public function __construct(private string $path) {}
    public function render(): string {
        $this->real ??= new RealImage($this->path);
        return $this->real->render();
    }
}

References

• ↗ https://refactoring.guru/design-patterns/proxy

Tags

Related Terms