| layout | group | subgroup | title | menu_title | menu_order | version | github_link | redirect_from | ||
|---|---|---|---|---|---|---|---|---|---|---|
default |
extension-dev-guide |
99_Module Development |
Plugins (Interceptors) |
Plugins (Interceptors) |
10 |
2.0 |
extension-dev-guide/plugins.md |
|
A plugin, or interceptor, is a class that modifies the behavior of public class functions by intercepting a function call and running code before, after, or around that function call. This allows you to substitute or extend the behavior of original, public methods for any class or interface.
Extensions that wish to intercept and change the behavior of a public method can create a Plugin class which are referred to as plugins.
This interception approach reduces conflicts among extensions that change the behavior of the same class or method. Your Plugin class implementation changes the behavior of a class function, but it does not change the class itself. Because they can be called sequentially according to a configured sort order, these interceptors do not conflict with one another.
Plugins cannot be used with any of the following:
- Objects that are instantiated before
Magento\Framework\Interceptionis bootstrapped - Final methods
- Final classes
- Any class that contains at least one final public method
- Non-public methods
- Class methods (such as static methods)
__construct- Virtual types
A plugin for a class object can be declared in the di.xml file in your module:
You must specify these elements:
type name. A class or interface which the plugin observes.plugin name. An arbitrary plugin name that identifies a plugin. Also used to merge the configurations for the plugin.plugin type. The name of a plugin's class or its virtual type. Use the following naming convention when you specify this element:\Vendor\Module\Plugin\<ModelName>Plugin.
The following elements are optional:
plugin sortOrder. The order in which plugins that call the same method are run.plugin disabled. To disable a plugin, set this element totrue. The default value isfalse.
A plugin is used to extend or modify a public method's behavior by applying code before, after, or around that observed method.
The first argument for the before, after, and around methods is an object that provides access to all public methods of the observed method's class.
Before methods run prior to an observed method. These methods must have the same name as the observed method with 'before' as the prefix.
You can use before methods to change the arguments of an observed method by returning a modified argument. If there are multiple arguments, the method should return an array of those arguments. Returning null will indicate that the arguments for the observed method should not be modified.
Below is an example of a before method modifying the $name argument before passing it on to the observed setName method.
{% highlight PHP %}
{% endhighlight %}
After methods run following the completion of the observed method. These methods must have the same name as the observed method with 'after' as the prefix.
These methods can be used to modify the results of an observed method and are required to have a return value.
Below is an example of an after method modifying the return value $result of an observed methods call.
{% highlight PHP %}
{% endhighlight %}
Around methods are defined such that their code is run both before and after the observed method. This allows you to completely override a method. Around methods must have the same name as the observed method with 'around' as the prefix.
Before the list of the original method's arguments, around methods receive a callable that will allow a call to the next method in the chain. When the callable is called, the next plugin or the observed function is called.
If the around method does not call the callable, it will prevent the execution of all the plugins next in the chain and the original method call.
Below is an example of an around method adding behavior before and after an observed method:
{% highlight PHP %}
doSmthBeforeProductIsSaved(); $returnValue = $proceed(); if ($returnValue) { $this->postProductToFacebook(); } return $returnValue; } } ?>{% endhighlight %}
When you wrap a method which accepts arguments, your plugin must also accept those arguments and you must forward them when you invoke the proceed callable. You must be careful to match the original signature of the method with regards to default parameters and type hints.
For example, the following code defines a parameter of type SomeType which is nullable:
{% highlight PHP %}
= null. Now, if the original method was called withnull PHP would throw a fatal error as your plugin does not accept null.
It is also worth noting that you are responsible for forwarding the arguments from the plugin to the proceed callable. If you are not using/modifying the arguments, you could use variadics and argument unpacking to achieve this simply:
{% highlight PHP %}