Magento Technical guidelines

© 2018 Magento, Inc. Page | 1
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.3 only PHP 7.1+ 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

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

Magento Technical guidelines

Recommended

Recommended

More Related Content

Similar to Magento Technical guidelines

Similar to Magento Technical guidelines (20)

More from Elogic Magento Development

More from Elogic Magento Development (15)

Recently uploaded

Recently uploaded (20)

Magento Technical guidelines