Decomposition of Magento Controllers

📋 Archival Copy: This is an archival copy of a blog post originally published on Adobe Magento DevBlog. The original publication date has been preserved.

Magento 2.4 became a perfect opportunity to proceed with backward-incompatible changes that were waiting for years. One such change was the decomposition of Controllers using composition instead of inheritance. When I spoke at Magento conferences about replacing inheritance with composition, I didn’t realize I would be part of making this change a reality.

The work began with this Pull Request and its followup introduced by Vinai Kopp. Although this change was very expected, these PRs were not merged initially.

At the beginning of 2020, Vinai encouraged me to continue the work on Controllers decomposition using his contribution. With his continuous support and tremendous work of Lena Orobei—together we finally delivered one of the biggest architectural changes towards decomposition of Controllers.

Solution

As a module developer, to implement a new Controller Action you only need to implement the \Magento\Framework\App\ActionInterface.

The authentication mechanisms for Customers are also migrated!

Benefits

The decomposition of Controllers brings several key benefits that improve both developer experience and application performance:

No need to extend

Module developers don’t have to extend from any class to create a fully functional action controller.

Example controller GET Action

use Magento\Framework\App\Action\HttpGetActionInterface;
use Magento\Framework\View\Result\PageFactory;

class MyController implements HttpGetActionInterface
{
    /** @var PageFactory */
    protected $resultPageFactory;

    public function __construct(PageFactory $resultPageFactory)
    {
        $this->resultPageFactory = $resultPageFactory;
    }
    
    public function execute()
    {
        return $this->resultPageFactory->create();
    }
}

You may have noticed that we use \Magento\Framework\App\Action\HttpGetActionInterface. It is a method-specific Interface extending ActionInterface. If you want to explicitly define what methods are going to be handled by the Controller, the most common interfaces are:

• \Magento\Framework\App\Action\HttpDeleteActionInterface
• \Magento\Framework\App\Action\HttpGetActionInterface
• \Magento\Framework\App\Action\HttpPostActionInterface
• \Magento\Framework\App\Action\HttpPutActionInterface

Please be aware that the HEAD method is handled the same way that GET is.

Performance

Previously, \Magento\Framework\App\Action\Context was injected into Actions with a set of classes:

/**
 * @param \Magento\Framework\App\RequestInterface $request
 * @param \Magento\Framework\App\ResponseInterface $response
 * @param \Magento\Framework\ObjectManagerInterface $objectManager
 * @param \Magento\Framework\Event\ManagerInterface $eventManager
 * @param \Magento\Framework\UrlInterface $url
 * @param \Magento\Framework\App\Response\RedirectInterface $redirect
 * @param \Magento\Framework\App\ActionFlag $actionFlag
 * @param \Magento\Framework\App\ViewInterface $view
 * @param \Magento\Framework\Message\ManagerInterface $messageManager
 * @param \Magento\Framework\Controller\Result\RedirectFactory $resultRedirectFactory
 * @param \Magento\Framework\Controller\ResultFactory $resultFactory
 */

There’s no doubt that the new way of creating Controllers is much cleaner. The performance overhead caused by instantiating unused classes is significantly reduced.

Differences

• Simple controllers like customer/account/logoutSuccess experience a 5% decrease in CPU time on generation.

• Complex controllers like customer/section/load experience a > 30% decrease in CPU time on generation.

• Common ones like catalog/category/view experience a 10% decrease in CPU time on generation.

Performance measurements were performed using BlackFire.io, in an isolated Docker environment with cURL requests, not being affected by Browser/Network overhead. Thanks to Christophe Dujarric for BlackFire’s support.

These performance improvements demonstrate the tangible benefits of the composition approach, with CPU time reductions ranging from 5% for simple controllers to over 30% for complex ones.

Testing

Controllers are easier to test due to their reduced amount of dependencies.

Inheriting from AbstractAction forces you to use at least the same dependencies as the parent class. Unit Test for Category View has more than 70 lines of mocking dependencies, mocking Context methods to return mocked dependencies.

With the composition approach, you can inject dependencies directly into your class and inject only the ones you need (for example, only the ones you are going to use with your Unit Tests). This significantly reduces the complexity and verbosity of unit tests.

Caution

⚠️ Important Considerations:

• Keep in mind that some Modules have their own AbstractAction. For example \Magento\Customer\Controller\AccountInterface additionally handles Customer Authentication.
• Controller “Supertypes” are deprecated (\Magento\Backend\App\AbstractAction, \Magento\Framework\App\Action\Action, \Magento\Framework\App\Action\AbstractAction, Magento\Framework\App\Action\Action\AbstractAccount) and you should not use them anymore.
• It is recommended to avoid code migration till 2.5.0 since third-party observers may be subscribed to your controllers. Methods like getRequest, getResponse, getActionFlag are eliminated with the inheritance and it will lead to errors when accessing them through controller object from event.
• It is recommended to use the new approach for new code only starting with the 2.4.0 release.
• Existing Magento controllers will not be migrated until 2.5.0 to keep backward compatibility.