Magento Technical Guidelines Eugene Shakhsuvarov, Software Engineer @ Magento 2018 Magento, Inc. Page 1
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/technicalguidelines/technical-guidelines.html 2018 Magento, Inc. Page 2
2018 Magento, Inc. Page 3 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 2018 Magento, Inc. Page 4
2018 Magento, Inc. Page 5 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 2018 Magento, Inc. Page 6
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 2018 Magento, Inc. Page 7
Do this instead Now logger may be changed with a simple configuration in di.xml Behavior is changed without any additional coding 2018 Magento, Inc. Page 8
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 2018 Magento, Inc. Page 9
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 2018 Magento, Inc. Page 10
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 2018 Magento, Inc. Page 11
Composition Example Price Formatter may be easily replaced by injecting another dependency in the constructor Allows precise modification of behavior 2018 Magento, Inc. Page 12
Inheritance Pros Inheritance may still be applicable in specific cases, for example when class is a subtype of another class 2018 Magento, Inc. Page 13
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 2018 Magento, Inc. Page 14
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 2018 Magento, Inc. Page 15
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 2018 Magento, Inc. Page 16
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 2018 Magento, Inc. Page 17
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/ 2018 Magento, Inc. Page 18
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 2018 Magento, Inc. Page 19
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 2018 Magento, Inc. Page 20
2018 Magento, Inc. Page 21 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 2018 Magento, Inc. Page 22
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 2018 Magento, Inc. Page 23
2018 Magento, Inc. Page 24 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 2018 Magento, Inc. Page 25
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 2018 Magento, Inc. Page 26
2018 Magento, Inc. Page 27 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) 2018 Magento, Inc. Page 28
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 2018 Magento, Inc. Page 29
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 2018 Magento, Inc. Page 30
Thank you! Q & A 2018 Magento, Inc. Page 31