Plugins & Observers Reference

Plugins Overview

The Magento_Sales module implements 16 plugins to intercept and modify behavior at critical execution points in the order management lifecycle.

Plugin Execution Priority

Frontend Plugins

These plugins are registered in etc/frontend/di.xml and only apply to customer-facing storefront requests.

Order Controller Authentication Plugins (1-10)

Purpose: Validates customer has permission to view their orders, invoices, shipments, and credit memos.

These 10 plugins all use the same class but intercept different controllers:

Plugin Class

Class: Magento\Sales\Controller\Order\Plugin\Authentication
Sort Order: 10 (default)

Behavior

1. Extract order ID from request parameters
2. Load order from repository
3. Check if current customer owns the order
4. If mismatch: redirect to 404 (prevent information disclosure)
5. If match: allow request to proceed

Code Example

public function beforeExecute(\Magento\Framework\App\ActionInterface $subject)
{
    $orderId = (int) $subject->getRequest()->getParam('order_id');

    if (!$orderId) {
        throw new NotFoundException(__('Page not found.'));
    }

    $customer = $this->customerRepository->get($orderId);
    $customerId = $this->customerSession->getCustomerId();

    if ($order->getCustomerId() != $customerId) {
        // Return 404 to prevent order ID enumeration
        throw new NotFoundException(__('Page not found.'));
    }

    return null; // Proceed with action
}

Security Impact

Critical: Without these plugins, any customer could view any order by guessing order IDs.

# Without plugin:
GET /sales/order/view/order_id/123  → Shows order details
GET /sales/order/view/order_id/124  → Shows different customer's order ❌

# With plugin:
GET /sales/order/view/order_id/123  → Shows order details (if owned)
GET /sales/order/view/order_id/124  → 404 Not Found ✓

Global Plugins

These plugins are registered in etc/di.xml and apply across all areas (frontend, admin, API).

{
  "entity_id": 12345,
  "increment_id": "000000123",
  "extension_attributes": {
    "shipping_label": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXB..."
  }
}

Observers Overview

The Magento_Sales module implements 25 observers that react to events dispatched during sales operations.

Grid Synchronization Observers

These 8 observers maintain the sales grid tables (denormalized copies of order/invoice/shipment/creditmemo data for fast admin grid display).

Grid Insert Observers (2-5) - Synchronous

Performance Comparison

Quote Integration Observers

Observer Best Practices

// BAD - blocks order save
public function execute(Observer $observer): void
{
    $order = $observer->getEvent()->getOrder();
    $this->externalApi->notifyOrderPlaced($order); // 2s timeout!
}

// GOOD - async processing
public function execute(Observer $observer): void
{
    $order = $observer->getEvent()->getOrder();
    $this->publisher->publish('sales.order.placed', $order->getId());
}

public function execute(Observer $observer): void
{
    $order = $observer->getEvent()->getOrder();

    // Check if status changed
    if (!$order->dataHasChangedFor('status')) {
        return; // No change, skip processing
    }

    // Expensive status change logic
}

public function execute(Observer $observer): void
{
    try {
        // Risky operation
        $this->externalService->notify($data);
    } catch (\Exception $e) {
        // Log error but don't fail order save
        $this->logger->error('Notification failed: ' . $e->getMessage());
        // Don't rethrow - allow order save to succeed
    }
}

# Enable async grid indexing
bin/magento config:set dev/grid/async_indexing 1

# Enable async email sending
bin/magento config:set sales_email/general/async_sending 1