Proxy Pattern

Definition

The Proxy pattern provides a surrogate or placeholder for another object to control access to it. The proxy has the same interface as the real object.

Types of Proxies

1. Lazy Proxy (Virtual Proxy)

Delays creation of expensive objects until they're actually used:

namespace Vendor\Catalog\Proxy;

class HeavyProductExporterProxy
{
    private ?\Vendor\Catalog\Model\ProductExporter $real = null;

    public function __construct(
        private array $config // Configuration, not the exporter
    ) {}

    public function export(array $products): string
    {
        // Create real exporter only when needed
        if ($this->real === null) {
            $this->real = new \Vendor\Catalog\Model\ProductExporter(
                $this->config['format'],
                $this->config['output_dir']
            );
        }
        return $this->real->export($products);
    }
}

2. Protection Proxy

Controls access based on permissions:

class AccessControlProxy
{
    public function __construct(
        private \Magento\Framework\Model\AbstractModel $real,
        private string $requiredRole
    ) {}

    public function save(): void
    {
        if (!$this->hasPermission()) {
            throw new \Magento\Framework\Exception\AuthorizationException(
                __('Insufficient permissions for this operation')
            );
        }
        $this->real->save();
    }

    public function __call(string $method, array $args)
    {
        return $this->real->$method(...$args);
    }

    private function hasPermission(): bool
    {
        return $this->auth->getUser()->getRole() === $this->requiredRole;
    }
}

3. Logging Proxy

Adds logging without modifying the real class:

class LoggingProxy
{
    public function __construct(
        private object $real,
        private LoggerInterface $logger
    ) {}

    public function __call(string $method, array $args)
    {
        $this->logger->info('Calling {method}', [
            'method' => get_class($this->real) . '::' . $method,
            'args' => $args,
        ]);

        $result = $this->real->$method(...$args);

        $this->logger->info('Result from {method}', [
            'method' => $method,
            'result' => $result,
        ]);

        return $result;
    }
}

They Look Similar But Differ

Both implement the same interface and wrap another object. The key difference:

The Telltale Sign

// Proxy: controls whether/how the real object is used
class CacheProxy
{
    private ?RealService $real = null;

    public function getData(string $key): mixed
    {
        // Check cache first — may never call real object
        $cached = $this->cache->get($key);
        if ($cached !== null) {
            return $cached; // Real object never created
        }

        $this->real = $this->createReal();
        $data = $this->real->getData($key);
        $this->cache->set($key, $data);
        return $data;
    }
}

// Decorator: always delegates to real object
class LoggingDecorator
{
    public function __construct(
        private RealService $real // Always provided
    ) {}

    public function getData(string $key): mixed
    {
        $this->log('Getting data');
        return $this->real->getData($key); // Always calls real
    }
}

The proxy decides whether to use the real object. The decorator always uses it and adds behavior.

How Magento Generates Proxies

Magento automatically generates proxy classes for lazy loading. When you type-hint with Proxy suffix, Magento creates a lazy-loading proxy.

// Instead of loading the product repository immediately:
namespace Vendor\Catalog\Model;

class ProductLister
{
    public function __construct(
        private \Magento\Catalog\Model\ProductRepository\Proxy $productRepo
    ) {}
    // ProductRepository is NOT loaded yet — only when first used
}

Generated Proxy (var/di/)

// Magento generates this in var/di/
class ProductRepositoryProxy
{
    private ?\Magento\Catalog\Model\ProductRepository $real = null;
    private \Magento\Framework\ObjectManager\ObjectManager $objectManager;

    public function __construct(
        \Magento\Framework\ObjectManager\ObjectManager $objectManager
    ) {
        $this->objectManager = $objectManager;
    }

    public function get($sku, $editMode = false, $storeId = null, $forceReload = false)
    {
        if ($this->real === null) {
            $this->real = $this->objectManager->create(
                \Magento\Catalog\Model\ProductRepository::class
            );
        }
        return $this->real->get($sku, $editMode, $storeId, $forceReload);
    }

    // ... other methods delegate similarly
}

Why Proxies Matter for Performance

// WITHOUT proxy: ProductRepository loads immediately
public function __construct(
    private ProductRepository $repo // ObjectManager creates this on construction
    // If ProductRepository depends on 50 other classes,
    // they ALL get created immediately
) {}

// WITH proxy: Only loads when first method is called
public function __construct(
    private ProductRepository\Proxy $repo // Lightweight proxy created
    // Nothing heavy is loaded yet
) {}

public function listProducts(): void
{
    // Only NOW does the real ProductRepository get created
    $products = $this->repo->getList($criteria);
}

This is especially valuable for CLI commands, cron jobs, and API endpoints that might not need all dependencies.