Magento Technical Guidelines Eugene Shakhsuvarov Software Engineer Magento

Magento Technical Guidelines Eugene Shakhsuvarov, Software Engineer @ Magento © 2017 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/v 2. 2/coding-standards/technicalguidelines/technical-guidelines. html © 2017 Magento, Inc. Page | 2

Basic Principles © 2017 Magento, Inc. Page | 3

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 © 2017 Magento, Inc. Page | 4

Class Design © 2017 Magento, Inc. Page | 5

Object Manager • Generally Object Manager should not be used as a class dependency • Doing so decreases ability for third parties to customize your code © 2017 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 © 2017 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 © 2017 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 © 2017 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 © 2017 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 © 2017 Magento, Inc. Page | 11

Composition Example • Price Formatter may be easily replaced by injecting another dependency in the constructor • Allows precise modification of behavior © 2017 Magento, Inc. Page | 12

Inheritance Pros • Inheritance may still be applicable in specific cases, for example when class is a subtype of another class © 2017 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 © 2017 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 © 2017 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 © 2017 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 © 2017 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/ © 2017 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 © 2017 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 © 2017 Magento, Inc. Page | 20

Interception © 2017 Magento, Inc. Page | 21

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 © 2017 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 © 2017 Magento, Inc. Page | 23

Exception Handling © 2017 Magento, Inc. Page | 24

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 © 2017 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 © 2017 Magento, Inc. Page | 26

Application Layers © 2017 Magento, Inc. Page | 27

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 Result. Interface implementation • Controllers must be as lightweight as possible • Localized. Exception should only be thrown in the Presentation layer (Controllers, Blocks) © 2017 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 © 2017 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 © 2017 Magento, Inc. Page | 30

Thank you! Q&A © 2017 Magento, Inc. Page | 31