Magento Technical Guidelines

Transcription

1 Magento Technical Guidelines Eugene Shakhsuvarov, Software Magento 2018 Magento, Inc. Page 1

2 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 Magento, Inc. Page 2

3 2018 Magento, Inc. Page 3 Basic Principles

4 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

5 2018 Magento, Inc. Page 5 Class Design

6 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

7 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

8 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

9 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

10 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

11 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

12 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

13 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

14 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

15 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

16 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

17 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

18 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 Magento, Inc. Page 18

19 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

20 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

21 2018 Magento, Inc. Page 21 Interception

22 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

23 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

24 2018 Magento, Inc. Page 24 Exception Handling

25 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

26 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

27 2018 Magento, Inc. Page 27 Application Layers

28 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

29 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

30 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

31 Thank you! Q & A 2018 Magento, Inc. Page 31