Magento Technical Guidelines Eugene Shakhsuvarov, Software Engineer @ Magento

Magento 2 Technical Guidelines Document which describes the desired technical state of Magento 2 Hundreds of architect-hours invested into development of guidelines May seem too restrictive and sometimes unobvious in favor of code readability and extensibility All of the new core code must follow the rules http://devdocs.magento.com/guides/v2.2/coding-standards/technical-guidelines/technical-guidelines.html

Basic Principles

Strict types Starting with Magento 2.2 only PHP 7.0 is supported Explicit return types must be declared on functions Type hints for scalar arguments should be used Declaration of strict_types is encouraged where possible

Class Design

Object Manager Generally Object Manager should not be used as a class dependency Doing so decreases ability for third parties to customize your code

Don’t do this In this case dependency is hard coded and can not be replaced with a different one Would require more work to modify the behavior by third parties

Do this instead Now logger may be changed with a simple configuration in di.xml Behavior is changed without any additional coding

There are exceptions to this rule Object Manager may still be used in classes which create objects (Factories, Builders) May also be used in the core code to maintain backwards compatibility

Inheritance Inheritance should not be used. Composition should be used instead Magento is moving away from the inheritance as a main code reuse mechanism Inheritance enforces dependency on a specific parent class which can not be replaced in runtime Overwriting logic based on inheritance requires a lot of boilerplate code

Inheritance Example Simple task of formatting product price May be perfectly fine in conditions, where third parties do not need to modify the behavior Requires complete replacement of the default renderer, instead of customizing it

Composition Example Price Formatter may be easily replaced by injecting another dependency in the constructor Allows precise modification of behavior

Inheritance Pros Inheritance may still be applicable in specific cases, for example when class is a subtype of another class

Single Responsibility All Classes should have only Single Responsibility which is entirely incapsulated Mixing different behaviors in one class (e. g. classic Helper) greatly decreases extensibility and increases coupling in most of the cases Allows for easy replacement of any specific behavior by providing a single point for change

Constructing a Class Object must be ready for use after instantiation No additional public initialization methods are allowed Constructor should throw an exception when validation of an argument has failed

Constructor Dependency Injection All dependencies must be requested by the most generic type that is required by the client object Class constructor can have only dependency assignment operations and/or argument validation operations Proxies and interceptors must never be explicitly requested in constructors

Class members visibility All non-public properties and methods should be private Discourages use of inheritance Protected properties are much harder to remove from the class, as some client code could be already extending it

Temporal Coupling Temporal coupling must be avoided Semantic dependencies between methods is prone to errors as client code never knows the current state of the system Method chaining in class design must be avoided https://ocramius.github.io/blog/fluent-interfaces-are-evil/

Object State Service classes, ones that provide behavior but not data, should not have a state Only data objects or entities may have an observable state Getters should not change the state of an object

Principle of least knowledge Class should have limited knowledge about other classes Object should only call methods only on its “friends” Do not “talk” to strangers

Interception

Interception best practices Avoid implementing a plugin when different kind of extension point is available Plugins should not be used within own module Plugins should not be added to data objects Plugins must be stateless

“Around” Plugins Should only be used when behavior of an original method is supposed to be substituted in certain scenarios Performance penalty is increased compared to other types of plugins Generate a lot of stack frames making it harder to debug the code

Exception Handling

Exception handling Exceptions must not be handled in the same function where they are thrown Business logic (both application and domain) must not be managed with exceptions. Conditional statements should be used instead All direct communications with third-party libraries must be wrapped with a try/catch statement A separate exceptions hierarchy should be defined on each application layer. It is allowed to throw exceptions that are only defined on the same layer

Exceptions Logging It is not allowed to absorb exceptions with no logging or/and any workaround operation executed Any exception should be logged only in the catch block where it is processed, and should not be re-thrown

Application Layers

Presentation Layer Request, Response, Session, Store Manager and Cookie objects must be used only in the Presentation layer Controllers should only call appropriate services and return ResultInterface implementation Controllers must be as lightweight as possible LocalizedException should only be thrown in the Presentation layer (Controllers, Blocks)

Service Layer Service layer is a contract for every specific module Service layer Interfaces may be used both as API and SPI Service Contracts should follow CQRS principle

Persistence Layer Always separate business logic and persistence logic Entities must not contain persistence-related logic Entities may be persisted in different scopes Every persistence operation must be performed with one scope set

Thank you! Q & A