PhpStorm plugin User Guide
Detect dependency on implementation details
According to the architecture principles (dependency injection as an example) on which Magento 2 & Adobe Commerce are built software solutions such as customisations and modules should use interfaces instead of the direct usage of the implementation. This helps to keep the whole application stable and reduces the time that is needed for future changes and modifications.
The “Detect dependency on implementation details” inspection
validates direct usage of implementation instead of the existing interface and provides error notification with the auto-fix suggestion. In the case of the fix, the direct usage of the implementation is changed to the corresponding interface with the required declaration in the di.xml.
There is a list of scenarios when the direct usage of the implementation is allowed and considered a corrective action from the architectural perspective:
The target class is: Magento\Sales\Model\Convert\Order
The target class is marked as @api
The target class is not inside a Magento component type module
The target class implements interfaces:
The target class extends next classes:
One aspect that should be considered is when the quick fix of the discussed functionality identifies that the current implementation does not have a preference, it recommends injecting the original class as a parameter of the current class.
There is one more case that engineers should take into account. Suppose a current class has an implementation in its __construct(), and this implementation also uses in the parent __construct() in that case, inspection notification should not be shown because the parent already uses implementation. Screenshots below illustrate the corresponding statement.
Avoid instantiating objects via the ObjectManger instance
The ObjectManager is one of the core patterns used in the Magento 2 Open Source & Adobe Commerce (the platforms). It was included in the platform's architecture to avoid boilerplate code when creating objects during their instantiation. According to the official documentation, the ObjectManger is responsible for the following
Object creation in factories and proxies
Implementing the singleton pattern by returning the same shared instance of a class when requested
Dependency management by instantiating the preferred class when a constructor requests its interface
Automatically instantiating parameters in class constructors
And the direct usage of the ObjectManager may be considered the best software engineer practice violation because of the following reasons:
Object instantiation is a responsibility that is handled by proxies and factories
Direct usage of the ObjectManager hides actual dependencies of the object that will be instantiated. This makes the whole implementation fragile and hard to maintain.
Please, take into consideration that there are some exceptions that may not be considered the best practice violation - check the official documentation.
The Avoid instantiating objects via the ObjectManger instance inspection
identifies direct usage of the ObjectManager and provides a fix that takes the class from the explicit declaration and injects it through the dependency injection. This inspection
is valuable in the following situations:
Code quality analyses
Detect the session usage without Proxy declaration
Performance is the critical point in all E-commerce applications. It is crucial to have a stable and fast application that provides the best user experience. A lot of aspects should be taken into account during the development of the E-commerce application. One of the most important parts is the architecture because proper usage of the best practices is the key to a stable and balanced application.
In the Magento 2 Open Source & Adobe Commerce, the Proxy
is used to avoid situations when one of the constructor parameters injected with the dependency injection runs heavy operations during the project initialisation. Or, for example, the initialisation of such a parameter is resource-consuming because of a long list of dependencies. Such architecture leads to performance degradation and as a result, not a beneficial user experience.
For example, the Magento\Customer\Model\Session
is the highly used class responsible for customer sessions. It has a long list of dependencies, and to avoid performance degradation, it is suitable to lazy load its instance when it is necessary to call it in the business logic. Detecting the customer session usage without Proxy declaration inspection
helps to identify the direct initialization of the Magento\Customer\Model\Session
and provides a quick fix. The fix allows choosing the area where the Proxy will be declared. In the appropriate di.xml
the fix creates all needed settings and updates the corresponding class constructor.
is beneficial for application development, refactoring and code quality analyses during the audits.
More information about the Proxy approach in the Magento 2 Open Source & Adobe Commerce is on the official website. Please, check this link
Detect the wrong Proxy declaration
As mentioned in the previous paragraph (Detect a customer session usage without Proxy declaration), Proxy is an excellent mechanism for avoiding performance degradation during object initialisation. According to the best practices of the Magento 2 Open Source & ADobe Commerce, it is more practical to declare Proxy through the dependency injection rather than directly through the class and use keyword.
The reason why this approach is more elegant and practical is that the Proxy is a framework operation. It should be declared in the corresponding di.xml to make the code generation process consistent and at the proper time.
The Detect the wrong Proxy declaration inspection
helps to identify the incorrect direct Proxy initialisation through the class and allows to fix it automatically.
is beneficial for application development, refactoring and primarily code quality analyses during the audits.
Avoid cyclical event loops in observers & plugins
One of the most tricky errors in the Magento 2 Open Source and Adobe Commerce applications is when you face cyclical event loops. It is not only difficult to identify but also results in fatal errors. This makes the error price significantly high because it may take hours to fix in case of an emergency, resulting in significant losses for the business.
The Magento 2 Open Source and Adobe Commerce have under the hood a list of strategies for business logic customisation. Still, two of them are the most popular and commonly used: observers and plugins. Observers allow us to listen to specific events such as sales order placed and customer creation after starting related business operations. Plugins allow you to plug into a particular method in the code base and change behaviour, data or else. As usual, there is a long list of plugins and observers in the E-commerce projects based on the mentioned platforms. And do not forget about the third-party extensions.
Based on the above statement, it is possible to create a cyclical loop of calls that results in a fatal error. Because business logic typically has many variations for processes, it is easy not to avoid catching cyclical errors during testing. One plugin can call the same method you try to modify, and one observer can call your observer that runs the whole process.
The avoid cyclical event loops in observers & plugins inspections
help to identify such cyclical errors based on the code base analyses. It analyzes not only the simple call of the same method in the plugin but also has sophisticated logic for error identification through the nested methods analyses. The same reasoning is for observers.
is highly profitable for project maintenance, application development and code quality analyses.
Do not include business logic in Observer classes
The Observer pattern implementation in the Magento 2 Open Source and Adobe Commerce is used for listening to the specified events such as customer creation after, sales order placed after and others. This approach allows application developers to track specific events and start other parts of the business logic.
For example, a business is required to send aggregated data from the recently placed order to the third-party system. Injecting logic into the sales order placement process is risky because this can lead to unexpected errors and the sales process performance degradation. Observing the sales order place after event looks like an excellent option to reach the goal.
In the case described above, application developers initialize a new observer and call the required business logic in the specified class. And this is a place of a possible software design error.
Placing business logic in the class declared as an observer violates fundamental principles of the OOP and good application design. Business logic in observers makes it fragile and hard to maintain. For example, if a software engineer places all send to the third-party logic into the observer, it makes it over-complicated and hard to maintain and understand. Also, it makes solutions for business logic not reusable because they belong to the observer class only.
The “Do not include business logic in Observer classes” inspection
analyses observers structure and identifies whether it contains business logic or not. It takes into consideration the complexity of the methods and the number of dependencies declared for the observer.
is exceptionally beneficial for code quality analyses, refactoring and application development.
Avoid creating helper classes
The Helper class
, or better said, the approach in software development, is the way to handle various functionality in one class to re-use them in different situations. For example, getting values from configuration, some reusable methods in the scope of one module like validation, calculation or repeated actions. From one point of view, it is a valuable thing that helps keep everything in one place, but it makes it difficult to maintain and extend the whole application. This is because the Helper class breaks the fundamental single responsibility principle
of the OOP. It is essential to follow this principle because it protects the logic of a particular implementation from modifications from different sides. If you have ClassA and a ClassAHelper with static functions that work on ClassA, you should consider refactoring those functions into ClassA.
The Magento 2 & Adobe Commerce Helper approach is considered a best practice violation because it couples functionality over the application.
The “Avoid creating helper classes” inspection
helps software engineers to prevent new helpers creation.
Preferences declared in the non-global area
From time to time there is a need to create a preference for a specific implementation. This kind of change in the scope of the Magento 2 / Adobe Commerce based projects is considered a risky one because it directly overrides implementation. In that case, it is also very important to check where the override through the preference implementation is used to define areas. Because if the author of the preference change puts its declaration, for example, to the frontend area but it also is used in the scope of the admin area it will lead to fatal errors. Just because there is no particular implementation in the specified area.
The “Preferences declared in the non-global area” inspection
validates that preference is defined in the global area to avoid situations as explained in the above paragraph. Preference should be defined in the global area to prevent unexpected crashes of the system.
Observers should be declared in the scope of the proper area
Observer by itself is used for listening to specified events such as sales order place, customer login or, for example, invoice paid. Also, it can listen to the specific area for the previously mentioned events. For example, the business needs to track successful order placement only on the storefront. In that case, the observer can be created for the frontend area only to prevent not needed execution in the scope of the web-api area or admin. Also, it should make the application bootstrapping a little bit lighter.
Global are for observers should be used only in case when the logic that the observer initiate should be executed in multiple areas.
The “Observers should be declared in the scope of the proper area” inspection
validates that the observer is created in the scope of the area that is equal to the area of the method where the observe is instantiated. Notification of this inspection
has a Weak Warning status that only helps developers to double check that they made a correct design decision.
Analyze used code consistency with the specified module dependencies
The Magento 2 & Adobe Commerce are systems that use modules under the hood as a part of their components. Each module can interact with any of the core modules, 3rd party extensions or customisations through the SAPI principle, plugins, observers, preferences etc. This makes the system flexible and easy to customize. But with this flexibility, it is essential to pay attention to the sequences between modules and, as a result, components. This is an integral part of high-quality solutions because, with the significant change of one module (or even its deactivation) that is a sequence to the list of other modules, the whole component can be broken.
According to the best practice of Magento 2 & Adobe Commerce and general principles of the software architecture, there are two files that should be maintained in the scope of the sequence setup between components: module.xml and composer.json of the module.
The “Analyze used code consistency with the specified module dependencies” inspection
helps to identify unspecified sequence declarations. Two examples below show how the corresponding functionality works for composer.json and module.xml.
Compare *.phtml templates overridden in the Magento 2 module
One of the common tasks during the project analysis or investigation of errors in templates is to compare differences between *.phtml templates. Having the ability to quickly access the difference between files saves a lot of developers' time.
The “Compare *.phtml templates overridden in the Magento 2 module” functionality benefits in the ability to show the difference between *.phtml files based on the Set the template used by a bloc
. In such cases, described functionality identifies the original file automatically and shows the difference.
Compare functionality also represents selection between parent and overwritten theme comparison.
Show template overrides in the editor context action
This feature provides the ability to show template overwrites directly from the file context menu in the PhpStorm which is possible to show with the right click on the file. This feature is valuable for quick access to the file that allows developers to avoid search for the block and then file usage.
Navigate to Factory and Proxy classes from their declaration in XML files
Better user experience of software engineers is the goal of this functionality. The factory and proxy classes navigation from the XML files leads engineers to the classes directly from the XML. This feature is enabled by default and its setting can be find by the following path Preferences > PHP > Magento 2 Support > Navigation Settings > Navigate to real class if generated(factory/proxy) class is available (only XML files are supported).
Navigate to the class source from its declaration in different XML files
With this functionality it is possible to be directly redirected to the class form XML files. For example, in the di.xml file from the plugin type declaration.
Navigate to the module from the module name in the config.php file
With this functionality developers can quickly access modules from the config.php by their names. Open the config.php file, choose the needed module and click on its name.
Navigate to the module from the sequence tag
With this functionality, engineers can navigate from the module.xml sequence tag to the corresponding module in the project tree.
Auto-detect Magento 2 / Adobe Commerce installation path
The plugin can automatically detect that the current project is Magento 2 or Adobe Commerce based and define its installation path. When the plugin detects, it shows the corresponding notification, as on the screenshot below.
Custom code and design directories support
As an application-level dependency manager, the composer provides excellent flexibility for project component structure. The prominent feature is the ability to use different types of code sources through the repository concept. Composer allows engineers to add the local directory with the repository path type.
Described functionality in the paragraph above is one of the possible way of components organisation in Magento based projects. With the "Custom code and design directories support" functionality, engineers get full functionality support for custom directories: inspections, module creation options, navigation etc.
The plugin automatically detects custom code and design directories defined in composer.json with the path type and updates the plugin's configuration settings. The following path can find the configuration setting responsible for the custom directories path keeping: Preferences > PHP > Magento 2 Support > Project Settings > Composer local paths. Automatically detected paths are represented in the grid. You can manually add, edit or remove paths.
Components elements generation
Create new Magento 2 module/theme action
The plugin provides functionality for the new Magento 2 module generation. A new module can be created on the vendor level if it already exists. Or vendor namespace can also be initiated during module generation. To run module generation on the vendor's level, choose in the navigation tree necessary vendor, call the context menu on the selected vendor folder and choose the New > Magento 2 module.
In the appeared pop-up define the module's name, and description and, if needed add dependencies. To add dependencies click on the plus symbol in the Dependencies section. In the pop-up use the search field for modules search or scroll the list. To select a module and add it as a dependency, click on it in the list of modules and be sure that it is selected in the search field. This is a required step because this is the standard behaviour of the search form in PhpStorm IDE.
When all data is set, press the OK button to create a new module. The module created with the help of the described functionality has etc/module.xml, registration.php, README.md, composer.json
The same approach is used for theme generation. The main idea is to create a basic theme skeleton. To do this select the theme folder under the design directory, call the context menu on it, and the New > Magento 2 theme click.
In the appeared pop-up the theme the basics should be configured: vendor, name and parent theme.
After pressing the OK button a new theme is going to be created with the following files: composer.json, theme.xml, registration.php
Inject copyright into the configuration files
This functionality allows engineers to automatically add copyright text into the module's configuration files such as module.xml, di.xml etc.
To define copyright for project you can do following: open PhpStorm > Preferences > Editor > Copyright > Copyright Profiles. Then define profile and select it in the Copyright section.
Magento Test Coverage Support
Add test source filter support for Magento
This functionality allows developers to quickly sort test files in the project tree. That allows to save time for project maintenance and search in case of a large number of test files.
Run configurations for the Magento CLI commands execution
The PhpStorm IDE has a beneficial functionality which is called Run/Debug Configuration
. It allows engineers to create, for example, run configuration for a specific CLI command that can be quickly executed locally or even on a remote instance. This saves time and reduces cognitive pressure if you need to run a list of commands too often during your development phase.
The plugin provides the possibility for engineers to create Run/Debug Configuration
for the Magento CLI commands. Under the standard menu that represents Run Configurations there is a new option: Magento CLI Command
The Magento 2 CLI Command run configuration helps engineers define to which domain run configuration belongs (cache, catalog, CMS, etc.) and automatically show the list of available commands. This is very helpful. For example, if the application development process requires running, reindexing and cache clean operations call often. There is no need to create custom scripts or copy-paste sequences of CLI commands. Everything can be configured in the IDE and run by click. Note that you can generate a series of run configurations and even run/define CLI commands with parameters.
There is one required precondition: the PHP interpreter should be configured. How to configure it you can find at the official PhpStorm documentation: Configure local PHP interpreters
Git related features
Analyse if a new module is added to the config.php file while committing it
This functionality's primary goal is to prevent situations when newly created modules are not added to the config.php. This situation leads to unnecessary commit and re-deployment. And as a result, time-consuming operations slow down delivery.
Described functionality is enabled by default. If it is needed to turn off, setting is located under the following path: Preferences > PHP > Magento 2 Support > VCS Settings > Check if modules are added to the config.php while commiting
The screenshots below show different situations. At the first one, the commit is organised and prepared to be delivered with the help of the PhpStorm Git functionality. The plugin identifies a new module in the project, but it was not declared in the config.php. Appropriated notification is showing.
Another level of assistance with this case is to check whether the config.php with the new module was added to the commit. It is possible that after adding a module to the config.php engineer can forget to add it to the commit. The plugin identifies this problem and reports it back to the engineer.