PhpStorm plugin User Guide

Coding Standards

• 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:‍
  • Magento\Framework\Session\SessionManagerInterface
  • Psr\Log\LoggerInterface
  • Magento\Framework\View\Element\Block\ArgumentInterface
  • Magento\Framework\ObjectManager\ContextInterface
  • Magento\Framework\Data\OptionSourceInterface
  • Magento\Framework\Event\ObserverInterface
  • Magento\Framework\Indexer\ActionInterface
    
  • Magento\Framework\Mview\ActionInterface
  The target class extends next classes:‍
  • Magento\Framework\Model\ResourceModel\AbstractResource
  • Magento\Framework\Model\AbstractModel
  • Magento\Framework\Model\ResourceModel\Db\Collection\AbstractCollection
  • Magento\Framework\App\Helper\AbstractHelper
  • Magento\Framework\View\Element\AbstractBlock
    
  • Magento\Sales\Model\Order\Pdf\AbstractPdf
  
  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:
  • Application development
  • Refactoring
  • 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.
  This inspection 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.
  

• Add circular dependencies inspection

  In software engineering, a circular dependency is a relation between two or more modules which either directly or indirectly depend on each other to function properly. Such modules are also known as mutually recursive. Circular dependencies are natural in many domain models where particular objects of the same domain depend on each other.
  
  However, circular dependencies between larger software modules in software design are considered an anti-pattern because of their adverse effects. Despite this, such circular (or cyclic) dependencies are widespread among the source files of real-world software.This inspection depends on analysing used code consistency with the specified module dependencies inspection.
  

• 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.
  This inspection 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.
  This inspection 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.
  This inspection 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.
  

ChatGPT

ChatGPT widget integration

Code refactoring with ChatGPT

Controllers

Search controller by path action

Add a new controller

Add controller path above controller class

Project Structure

Analyze used code consistency with the specified module dependencies

Files-Comparison

Compare Preference With Original Class

Compare *.phtml templates overridden in the Magento 2 module

Navigation

Navigation support for phtml templates inside layout files and blocks

Show template overrides in the editor context action

Navigate to Factory and Proxy classes from their declaration in XML files

Navigate to the class source from its declaration in different XML files

Navigate to the module from the module name in the config.php file

Show & navigate to layouts where corresponding template is used

Navigate from controller to layout and vice versa

Navigate to the module from the sequence tag

Auto-detect Magento 2 / Adobe Commerce installation path

Custom code and design directories support

Components elements generation

Create new Magento 2 module/theme action

Inject copyright into the configuration files

Magento Test Coverage Support

Add test source filter support for Magento

CLI

Run configurations for the Magento CLI commands execution

Git related features

Analyse if a new module is added to the config.php file while committing it