Circular Dependencies

A circular dependency occurs when class A depends on class B, and class B depends on class A (directly or through a chain).

Direct circular dependency:

ClassA → ClassB → ClassA

Indirect circular dependency:

ClassA → ClassB → ClassC → ClassA

Why they're problematic:

• ObjectManager cannot determine instantiation order
• PHP cannot resolve the dependency graph
• Causes fatal errors during compilation or runtime
• Indicates architectural design issues

Example:

// ClassA.php
class ClassA
{
    public function __construct(
        private ClassB $classB  // Depends on ClassB
    ) {}
}

// ClassB.php
class ClassB
{
    public function __construct(
        private ClassA $classA  // Depends on ClassA — CIRCULAR!
    ) {}
}

Magento error message:

Circular dependency detected: ClassA -> ClassB -> ClassA

Or during compilation:

[ERROR] Circular dependency: Vendor\Module\ClassA -> Vendor\Module\ClassB -> Vendor\Module\ClassA

Circular dependencies in Magento typically arise from several architectural patterns.

1. Bidirectional relationships:

// Order references OrderItem
class Order { private OrderItem $item; }
// OrderItem references Order
class OrderItem { private Order $order; }

2. Shared service dependencies:

// LoggerService needs ConfigService
class LoggerService { private ConfigService $config; }
// ConfigService needs LoggerService
class ConfigService { private LoggerService $logger; }

3. Factory depending on repository:

// Repository needs factory to create objects
class ProductRepository { private ProductFactory $factory; }
// Factory needs repository to load base product
class ProductFactory { private ProductRepository $repo; }

4. Plugin circular chain:

// Plugin A modifies ProductRepository
// Plugin B modifies ProductRepository
// Plugin A depends on a service that depends on Plugin B

5. Observer depending on dispatcher:

// Observer listens to events
class MyObserver { private EventDispatcher $dispatcher; }
// Dispatcher depends on observer manager
class EventDispatcher { private ObserverManager $manager; }
// ObserverManager depends on observers

6. Template/Block circular references:

// Block A renders Block B
class BlockA { private BlockB $block; }
// Block B renders Block A
class BlockB { private BlockA $block; }

Several methods help identify circular dependencies.

Method 1: Compilation error:

php bin/magento setup:di:compile
# Output will show the circular chain

Method 2: Magento logger:

grep -i "circular" var/log/exception.log
# Example output:
# [2024-01-15 10:30:00] main.CRITICAL: Circular dependency: Vendor_A_Model_ClassA -> Vendor_B_Model_ClassB -> Vendor_A_Model_ClassA

Method 3: Static analysis:

# Using phpstan (if installed)
vendor/bin/phpstan analyse --level=8 app/code/Vendor/Module/

# Look for circular reference warnings

Method 4: Manual tracing:

// Add debugging to ObjectManager
$objectManager = \Magento\Framework\App\ObjectManager::getInstance();

// Check the dependency graph
$reflectionClass = new \ReflectionClass(ClassA::class);
$constructor = $reflectionClass->getConstructor();

if ($constructor) {
    foreach ($constructor->getParameters() as $param) {
        echo "ClassA depends on: " . $param->getType() . "\n";
    }
}

Method 5: Dependency graph visualization:

# Generate dependency graph (requires tools)
# Use PHP_CodeSniffer or custom scripts

Quick check:

# Check for circular dependencies in a module
php bin/magento module:status --dependencies | grep -i circular

Breaking circular dependencies requires architectural changes.

Solution 1: Introduce an interface/contract:

// Before (circular)
class Logger { private Config $config; }
class Config { private Logger $logger; }

// After (broken)
interface LoggerInterface {}
interface ConfigInterface {}

class Logger implements LoggerInterface { /* no Config dependency */ }
class Config implements ConfigInterface { /* no Logger dependency */ }

// Shared configuration class
class ConfigProvider { private ConfigInterface $config; }
class LoggerWithConfig implements LoggerInterface {
    public function __construct(private ConfigProvider $configProvider) {}
}

Solution 2: Use events/observer pattern:

// Instead of direct dependency, dispatch event
class OrderService
{
    public function save(Order $order)
    {
        // Instead of calling InventoryService directly
        $this->eventManager->dispatch('order_saved_after', ['order' => $order]);
    }
}

// Observer handles the response
class InventoryObserver
{
    public function execute(EventObserver $observer)
    {
        $order = $observer->getEvent()->getOrder();
        $this->inventoryService->updateStock($order);
    }
}

Solution 3: Use proxies for lazy loading:

// Break the chain with a proxy
class Order
{
    public function __construct(
        private OrderItem\Proxy $itemProxy  // Lazy load
    ) {}
}

Solution 4: Extract shared logic to third class:

// Extract to a new class
class SharedService
{
    public function __construct(
        private Logger $logger,
        private Config $config
    ) {}
}

class OrderService
{
    public function __construct(private SharedService $shared) {}
}

Prevention tips:

• Design unidirectional dependencies
• Use dependency inversion (depend on interfaces)
• Keep dependency graphs shallow
• Regularly run static analysis