1. Magento Technical Guidelines Eugene Shakhsuvarov, Software Engineer @ Magento

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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)

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

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

31. Thank you! Q & A