Magento 2 Plugins (Interceptors)
Before writing code
Fetch live docs: Fetch https://developer.adobe.com/commerce/php/development/components/ 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
- Before plugins execute in sortOrder (ascending)
- Around plugin's pre-
$proceed code
- Original method (via
$proceed)
- Around plugin's post-
$proceed code
- 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.
1---2name: magento-plugins-interceptors-23description: Implement Magento 2 plugins (interceptors) — before, after, and around methods for modifying class behavior without inheritance. Use when extending core or third-party module functionality.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/magento-plugins-interceptors-27---89# Magento 2 Plugins (Interceptors)1011## Before writing code1213**Fetch live docs**: Fetch `https://developer.adobe.com/commerce/php/development/components/` for the official plugins guide with exact method signatures and limitations.1415## Conceptual Architecture1617### What Plugins Do1819Plugins 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.2021### Three Plugin Types2223| Type | Method Prefix | Purpose | Receives |24|------|-------------|---------|----------|25| **Before** | `before<MethodName>` | Modify input arguments | Subject + original args |26| **After** | `after<MethodName>` | Modify return value | Subject + result (+ original args) |27| **Around** | `around<MethodName>` | Wrap entire execution | Subject + `$proceed` callable + original args |2829### Before Plugin3031- Method: `beforeOriginalMethod($subject, $arg1, $arg2, ...)`32- Return: array of modified arguments, or `null` to keep originals33- Executes before the original method3435### After Plugin3637- Method: `afterOriginalMethod($subject, $result, ...$args)`38- Return: modified result39- Executes after the original method40- Since 2.2: receives original arguments after `$result`4142### Around Plugin4344- Method: `aroundOriginalMethod($subject, callable $proceed, $arg1, $arg2, ...)`45- Return: whatever the method should return46- Must call `$proceed($arg1, $arg2)` to invoke the original (or skip it)47- **Use sparingly** — most cases are better served by before + after4849### Plugin Declaration (di.xml)5051Plugins are declared as children of a `<type>` element:52- `name` — unique plugin identifier53- `type` — fully qualified plugin class name54- `sortOrder` — execution priority (lower runs first)55- `disabled` — `true` to disable5657### Execution Order58591. Before plugins execute in sortOrder (ascending)602. Around plugin's pre-`$proceed` code613. Original method (via `$proceed`)624. Around plugin's post-`$proceed` code635. After plugins execute in sortOrder (ascending)6465### Limitations — Cannot Intercept6667- `final` classes or `final` methods68- `__construct()` (constructor)69- `static` methods70- Non-public methods (`protected`, `private`)71- Virtual types (directly)72- Classes instantiated before the interception framework bootstraps7374### Plugin Class Location7576Place plugin classes in the `Plugin/` directory of your module:77```78VendorName/ModuleName/Plugin/SomePlugin.php79```8081## Best Practices8283- Prefer before/after over around — around is harder to debug84- Always call `$proceed` in around plugins unless intentionally skipping85- Use descriptive plugin names to avoid conflicts86- Set appropriate sortOrder when multiple plugins target the same method87- Check if a before or after plugin can achieve the goal before using around88- Test with other modules' plugins to verify sortOrder interactions8990Fetch the plugins documentation for exact method signatures, the latest limitations list, and any changes in recent Magento versions before implementing.