magento-plugins-interceptors

Magento 2 Plugins (Interceptors)

Before writing code

Fetch live docs: Fetch https://developer.adobe.com/commerce/php/development/components/plugins/ for the official plugins guide with exact method signatures and limitations.

Conceptual Architecture

What Plugins Do

Plugins intercept public method calls on any non-final class, allowing you to modify arguments, return values, or wrap entire method execution — without modifying the original class or using inheritance.

Three Plugin Types

| Type | Method Prefix | Purpose | Receives | |------|-------------|---------|----------| | Before | before<MethodName> | Modify input arguments | Subject + original args | | After | after<MethodName> | Modify return value | Subject + result (+ original args) | | Around | around<MethodName> | Wrap entire execution | Subject + $proceed callable + original args |

Before Plugin

• Method: beforeOriginalMethod($subject, $arg1, $arg2, ...)
• Return: array of modified arguments, or null to keep originals
• Executes before the original method

After Plugin

• Method: afterOriginalMethod($subject, $result, ...$args)
• Return: modified result
• Executes after the original method
• Since 2.2: receives original arguments after $result

Around Plugin

• Method: aroundOriginalMethod($subject, callable $proceed, $arg1, $arg2, ...)
• Return: whatever the method should return
• Must call $proceed($arg1, $arg2) to invoke the original (or skip it)
• Use sparingly — most cases are better served by before + after

Plugin Declaration (di.xml)

Plugins are declared as children of a <type> element:

• name — unique plugin identifier
• type — fully qualified plugin class name
• sortOrder — execution priority (lower runs first)
• disabled — true to disable

Execution Order

1. Before plugins execute in sortOrder (ascending)
2. Around plugin's pre-$proceed code
3. Original method (via $proceed)
4. Around plugin's post-$proceed code
5. After plugins execute in sortOrder (ascending)

Limitations — Cannot Intercept

• final classes or final methods
• __construct() (constructor)
• static methods
• Non-public methods (protected, private)
• Virtual types (directly)
• Classes instantiated before the interception framework bootstraps

Plugin Class Location

Place plugin classes in the Plugin/ directory of your module:

VendorName/ModuleName/Plugin/SomePlugin.php

Best Practices

• Prefer before/after over around — around is harder to debug
• Always call $proceed in around plugins unless intentionally skipping
• Use descriptive plugin names to avoid conflicts
• Set appropriate sortOrder when multiple plugins target the same method
• Check if a before or after plugin can achieve the goal before using around
• Test with other modules' plugins to verify sortOrder interactions

Fetch the plugins documentation for exact method signatures, the latest limitations list, and any changes in recent Magento versions before implementing.