The purpose of this article is to shed some light on the flexible yet not-so-intuitive entity attribute system offered by Magento 2.

There are plenty of resources about implementing custom and extension attributes, so here we will just focus on the main differences and some details.

Quick overview of the entity attribute system

Since the early days, Magento has offered an 

Through this system, it's straightforward to extend a Magento entity, with some limits:

 system, introduced in Magento 2, overcomes the above limits, making it easy to:

Unluckily, some Magento core entities don't implement the 

\Magento\Framework\Api\ExtensibleDataInterface

 thus they are not extensible with native extension attributes.
Anyway, let's focus on the half-full glass to explore some 

With the introduction of the extension attributes system, some new terminology comes in.

EAV attributes belong to one of the following sets:

We have already given a definition but let's refresh it: an 

First, the good news: an extension attribute allows us to 

overcome the limitations of scalar values

. With an extension attribute, we can extend 

both EAV and non-EAV with complex objects

 extension attribute added to the order (

<?php
namespace Magento\GiftMessage\Api\Data;

interface MessageInterface 
 extends \Magento\Framework\Api\ExtensibleDataInterface
{
 /**#@+
 * Constants for keys of data array. Identical to the name of the getter in snake case
 */
 const GIFT_MESSAGE_ID = 'gift_message_id';
 const CUSTOMER_ID = 'customer_id';
 const SENDER = 'sender';
 const RECIPIENT = 'recipient';
 const MESSAGE = 'message';
 /**#@-*/

 // ...
}

 for such flexibility is that extension attribute values persistency needs to be 

, whereas custom attribute values are loaded and saved automatically.

Refer to the official documentation for more details on 

how to add extension attributes to entity

 doesn't declare the methods to access extension attributes. Here is its declaration:

<?php
/**
 * Copyright © Magento, Inc. All rights reserved.
 * See COPYING.txt for license details.
 */

namespace Magento\Framework\Api;

/**
 * Interface for entities which can be extended with extension attributes.
 *
 * @api
 */
interface ExtensibleDataInterface
{
 /**
 * Key for extension attributes object
 */
 const EXTENSION_ATTRIBUTES_KEY = 'extension_attributes';
}

 but we can't give for granted that a class implementing 

 provides those methods, so my advice is to double check it.

It's worth mentioning that to prevent performance degradation while fetching extension attributes in collections, Magento provides a 

To find an example, we can look at the declaration of the 

module-newsletter/etc/extension_attributes.xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xsi:noNamespaceSchemaLocation="urn:magento:framework:Api/etc/extension_attributes.xsd">
 <extension_attributes for="Magento\Customer\Api\Data\CustomerInterface">
 <attribute code="is_subscribed" type="boolean" >
 <join reference_table="newsletter_subscriber" 
 reference_field="customer_id" 
 join_on_field="entity_id">
 <field>subscriber_status</field>
 </join>
 </attribute>
 </extension_attributes>
</config>

, it's not enough to declare the above join; we also have to pass the collection to the 

\Magento\Framework\Api\ExtensionAttribute\JoinProcessorInterface::process()

 method to have it populated with correct data. We can see an example in the 

<?php
namespace Magento\Catalog\Model;

// ...

class ProductRepository 
 implements \Magento\Catalog\Api\ProductRepositoryInterface
{
 // ...

 public function getList(\Magento\Framework\Api\SearchCriteriaInterface $searchCriteria)
 {
 /** @var \Magento\Catalog\Model\ResourceModel\Product\Collection $collection */
 $collection = $this->collectionFactory->create();
 $this->extensionAttributesJoinProcessor->process($collection);
 // ..
 }

 // ...
}

 to the values of an entity's extension attribute by declaring an ACL resource, as 

Usually, extension attributes are non-EAV attributes, meaning that we should decide where to persist their values.

If the extension attribute is a complex object, the default choice would be to use a 

But if the extension attribute is a scalar, 

.
This way, persisting values will require 

 because it avoids additional join conditions.

There isn't a golden rule, though; we need to 

 every case before making the right decision.

 are nothing new in the Magento world: just a 

 that Magento installation does not create.

With extension attributes also comes the possibility to define 

All this comes at a bit of cost: we have to carefully 

 to ensure that data is retrieved and saved the way we expect.

Magento fundamentals: what are the differences between custom and extension attributes?

Magento fundamentals: che differenza c'è tra custom ed extension attributes?

"in object-oriented programming, a helper class is used to assist in providing some functionality, which isn't the main goal of the application or class in which it is used."

Helpers used to be first-class citizens in Magento 1, which left many tracks into Magento 2 codebase.

That's the reason why, I guess, a lot of Magento developers kept on implementing their helpers, violating the new Magento 2 guidelines.

Why helpers don't respect the new Magento 2 guidelines

Since, by definition, a helper is a class with 

, it doesn't adhere to the class design principles defined in the 

"there should never be more than one reason for a class to change"

\Magento\Framework\App\Helper\AbstractHelper

In Magento 2.4.2, this class alone depends on:

This class is a perfect example of a Swiss Army knife with more than one reason to change.

Let's start with the fact that helpers don't provide data (more on this later) but 

In Magento, behaviors should be implemented as 

Note that there are many service classes in Magento that don't follow all the above rules: repositories, resource models, and many others. The most important of the rules that we should try to apply is related to the immutable state, that protects from unpredictable side effects. The adherence to the others is not always mandatory, as we will see in an example below.

If we look at our helpers, we can see that, after all, they are nothing but 

Decomposing them won't be a difficult task.

When we read that a service class doesn't provide data, it doesn't mean that it can't provide data taken from a persistence layer.

; it doesn't even have an identity and a state and doesn't persist and retrieve 

It can provide other entities' data. For example, a repository is a service class that provides data access (a.k.a. 

At this point, we are ready to decompose our helpers into different service classes.

It's just a matter of identifying the different behaviors or 

 our helper class and split them into several service classes.

💡 When doing this, we are recommended to follow the 

An example is worth more than a thousand words.

Let's say we have the following helper class (methods' implementation details don't matter at this point):

<?php declare(strict_types=1);

namespace MyCoolVendor\MyCoolModule\Helper;

class Data extends \Magento\Framework\Url\Helper\Data 
{
 public function isEnabled(): bool
 {
 // use $this->scopeConfig->isSetFlag() 
 // to retrieve the configuration value
 }

 public function getApiKey(): string
 {
 // use $this->scopeConfig->getValue() 
 // to retrieve the configuration value
 }

 public function getActionUrl(int $customerId): string
 {
 // use $this->_urlBuilder->getUrl() 
 // to build an action URL given a customer ID
 }
}

The above class exposes two main behaviors:

Thus, we will define two service contracts and their corresponding implementation:

The resulting code structure is shown below.

<?php declare(strict_types=1);

namespace MyCoolVendor\MyCoolModuleApi\Api;

interface ConfigInterface
{
 public function isEnabled(): bool;

 public function getApiKey(): string;
}

<?php declare(strict_types=1);

namespace MyCoolVendor\MyCoolModuleApi\Api;

interface GetActionUrlByCustomerInterface
{
 public function execute(): string;
}

<?php declare(strict_types=1);

namespace MyCoolVendor\MyCoolModule\Model;

use \Magento\Framework\App\Config\ScopeConfigInterface;
use \MyCoolVendor\MyCoolModuleApi\Api\ConfigInterface;

class Config implements ConfigInterface
{
 private ScopeConfigInterface $scopeConfig;

 public function __construct(ScopeConfigInterface $scopeConfig)
 {
 $this->scopeConfig = $scopeConfig;
 }

 public function isEnabled(): bool
 {
 // use $this->scopeConfig->isSetFlag() 
 // to retrieve the configuration value
 }

 public function getApiKey(): string
 {
 // use $this->scopeConfig->getValue() 
 // to retrieve the configuration value
 }
}

<?php declare(strict_types=1);

namespace MyCoolVendor\MyCoolModule\Model;

use \Magento\Framework\UrlInterface;
use \MyCoolVendor\MyCoolModuleApi\Api\GetActionUrlByCustomerInterface;

class GetActionUrlByCustomer implements GetActionUrlByCustomerInterface
{
 private UrlInterface $urlBuilder;

 public function __construct(UrlInterface $urlBuilder)
 {
 $this->urlBuilder = $urlBuilder;
 }

 public function execute(int $customerId): string
 {
 // use $this->urlBuilder->getUrl() 
 // to build an action URL given a customer ID
 }
}

<?xml version="1.0"?>

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
 <preference for="MyCoolVendor\MyCoolModuleApi\Api\ConfigInterface" 
 type="MyCoolVendor\MyCoolModule\Model\Config"/>
 <preference for="\MyCoolVendor\MyCoolModuleApi\Api\GetActionUrlByCustomerInterface" 
 type="MyCoolVendor\MyCoolModule\Model\GetActionUrlByCustomer"/>
</config>

Adhering to others' coding guidelines may be tedious because it forces us to abandon our habits and our comfort zone.

But as soon as we realize the benefits, it pays back. Everyone's code follows the same structure and rules, becomes more readable, improving stability and maintainability in the long term.

Magento fundamentals: helper decomposition

Magento fundamentals: decomporre un helper

One of the most frequent question when manipulating entities in Magento 2 is: 

"should I use a repository or a collection?"

In this article, we'll see which are the 

We won't go deep into the syntax details but rather try to understand the 

 of both and when it's better to use one or another.

A brief definition of repositories and collections

Repositories were introduced in Magento 2, while collections are a legacy of Magento 1.

We use both to deal with entity persistence but from different 

 that allows complete decoupling from the persistence layer.

"a repository mediates between the domain and data mapping layers using a collection-like interface for accessing domain objects."

introduced as a part of Domain-Driven Design in 2004

 where a query is constructed, dealing more with 

 concepts and belonging to the resource models layer.

Being a higher abstraction, in Magento 2, repositories are often resource model wrappers and exposed as API resources.

The following is a simplified representation of the relations between layers:

 of collections and repositories the same way.

This distinction is important because it tells us that collections have to be instantiated through a 

, while repositories can be instantiated through constructor-based 

Additional information about this topic can be found 

More on the state of collections and repositories

Let's see why collections store state while repositories 

 by setting, for example, the properties we want to select and the filters we want to apply to the data that will be retrieved.

 method is called, the state is used to build the query.

Let's see a code fragment taken from the 

\Magento\Eav\Model\Entity\Collection\AbstractCollection

<?php
abstract class AbstractCollection 
 extends AbstractDb 
 implements SourceProviderInterface
{
 // ...
 public function load($printQuery = false, $logQuery = false)
 {
 if ($this->isLoaded()) {
 return $this;
 }
 // ...build query and load data...
 $this->_setIsLoaded();
 // ...
 return $this;
 }
 // ...
}

 method builds up the query and fetches the results into the collection's internal state.

 method don't re-fetch data but simply return the collection, unless the state is reset by calling the 

☝ Calling the <code>load()</code> method is not necessary because it is called by the <code>getIterator()</code> method, which is automatically called as soon as we iterate the elements of the collection.

The <code>getIterator()</code> method is declared in the <code>IteratorAggregate</code> interface which every Magento collection implements.

This mechanism is called lazy data loading, and it has some advantages:

. Repositories can have a state, but since it doesn't affect the result, we can think of them as stateless objects.

 that repositories can implement for performance optimization.

 method saves product instances for subsequent retrieval, as shown below.

public function getById($productId, $editMode = false, $storeId = null, $forceReload = false)
{
    $cacheKey = $this->getCacheKey([$editMode, $storeId]);
    if (!isset($this->instancesById[$productId][$cacheKey]) || $forceReload) {
        $product = $this->productFactory->create();
        // ...
        $this->cacheProduct($cacheKey, $product);
    }
    return $this->instancesById[$productId][$cacheKey];
}

Strictly speaking, this means keeping a state; that's why I tend to say that repositories are 

Let's recap the pros and cons of collections and repositories.

Should we always implement a repository for custom entities?

This question is a pretty frequent one when developing our entities.

My answer is yes, unless the entity we are introducing is an extension attribute of the main entity.

Since the extension attributes' values are likely injected in the main entity, there is no need to develop a specific repository for the custom entity.

In the Domain-Driven Design jargon, we would say that we don't need a repository for children entities of an aggregate (the main entity) because 

"aggregates are the basic element of transfer of data storage ~ M. Fowler"

.
If you are interested in reading a bit more on the topic, you can refer to 

We've seen that there are pros and cons both in using collections and repositories. Collections are more expressive and more tight to the persistence layer; repositories are less expressive but allow us to decouple from data mapping and benefit from additional caching layers, improving performances.

Knowing the differences between the Magento framework's elements is crucial to make the proper choice when it's required.

Magento fundamentals: what are the differences between collections and repositories?

Magento fundamentals: che differenza c'è tra collection e repository?

Plugins are the brand new way of extending Magento 2 and, as often happens according to 

if all we have is a hammer, everything looks like a nail

This article will see the main differences between the good old events and plugins and when it still makes sense to use events instead of plugins to hook our customizations.

The very first difference is that events are 

Let me explain. If our observer depends on an event triggered by a module that is disabled, our functionality stops working 

Of course, since our observer is not called, something won't work as expected, but the platform doesn't throw an exception, and the storefront navigation won't be affected.

Conversely, if a plugin depends on a class that could not be found by the system, a 

 will be thrown, revealing to the world that something doesn't work as expected.

It’s important to know this difference because it can 

 in deciding whether to use an event or a plugin to hook our customizations.

Let's make a couple of examples; they are trivial, but it's just to give an idea.

 in the scope of applicability of events and plugins that are worth mentioning.

Since Magento 1, we know that we can't observe an event that is not triggered. It means that if there isn't any event fired where we could hook our customization, we can't rely on this mechanism.

There are plenty of useful events triggered by the Magento core but rest assured that we will miss one sooner or later.

☝ Classes annotated as <code>@api</code> guarantees that their public interface won't change until a major or minor update occurs. 
To learn more about it: <a href="https://devdocs.magento.com/guides/v2.4/extension-dev-guide/versioning/codebase-changes.html">https://devdocs.magento.com/guides/v2.4/extension-dev-guide/versioning/codebase-changes.html</a>

I don't want to explain plugins in more detail; the 

I want to focus on some aspects related to 

 but some kinds of plugins take more CPU time.

Let's see a benchmark that shows the differences between all of them.

☝ I used <a href="https://blackfire.io/">Blackfire</a> (highly recommended) to profile the execution of an observer and of three plugins; they just add a <code>sleep(1)</code> statement, to force Blackfire to highlight those calls as bottlenecks.

around plugins are at least an order of magnitude slower

: if we don't need to prevent the execution of the original method and subsequent plugins, around plugins don't give us more power than the other types, just less performance. In this case, better choose a 

I know that a few milliseconds (or microseconds) seem a little thing, but let’s consider that there are 

 to observers and plugins in a vanilla Magento installation, not to mention the ones added by third-party code.

The total time taken by all these executions can have a relevant impact on the overall performance, especially when they are misused.

☝ Necessary clarification: events can also affect performance negatively if we don't adopt the recommended best practices. To learn more, refer to the <a href="https://devdocs.magento.com/guides/v2.4/ext-best-practices/extension-coding/observers-bp.html">official documentation</a>.

 between events and plugins, and that plugins are not all of the same kind.

 when developing with the Magento framework can make a difference in performance.

 for Magento and let's take them into account next time we need to modify the behavior of our application.

Magento fundamentals: what are the differences between events and plugins?

Magento fundamentals: che differenza c'è tra eventi e plugin?

This article is the first of a series inspired by some 

After more than five years from the release of Magento 2.0 and plenty of available documentation, these may seem obvious topics. Still, it's not so: every day we come across third-party code that demonstrates the opposite.

The Object Manager is an object that is used by the framework to 

 and pass them as parameters to the constructor of other classes.

; that's why objects passed by the Object Manager are usually called 

The objects passed to the constructor of a class represent its 

. 
To learn more about it: https://en.wikipedia.org/wiki/Dependency_injection

 to access to system configuration, we will declare a dependency from 

<?php declare(strict_types=1);
use \Magento\Framework\App\Config\ScopeConfigInterface;

class TheMostUselessClass 
{
 protected $config;

 public function __construct(ScopeConfigInterface $config) 
 {
 $this->config = $config
 }
}

 is an interface and we know that an interface can't be instantiated.

Thus, the Object Manager should instantiate a class that implements 

; to identify the proper class, it will lookup in a map obtained by 

 files composition. Going more in-depth on how the map is built is out of the scope of this article.

) rather than on concrete classes is called 

. 
To learn more about it: https://en.wikipedia.org/wiki/Dependency_inversion_principle

Injectable objects that the Object Manager passes should always be 

 that we use to execute some domain logic. Usually, we don't change the 

 of these objects (with a few exceptions), which are not intended to be persisted.

An example that we've already seen is the object implementing the 

, used to retrieve system configuration values.

Another widely used example of a service object is a repository, whose purpose is managing the persistence of entities on a  database.

 by the Object Manager. That means the same instance of an object is passed to those requiring it as a dependency.

Conversely, objects that need to be instantiated as new each time we need them are called 

. An instance representing an entity record stored in the database is a typical example of a newable object.

We don't need to directly use the Object Manager to get such objects, because they don't represent a dependency. To get a newable object, we instead use particular service objects called 

Being service objects, factories are instantiated by the Object Manager through the declaration of a constructor-based dependency, like shown below:

<?php declare(strict_types=1);
use \Magento\Catalog\Api\Data\ProductInterfaceFactory;

class CreateFabulousProduct
{
 protected $productFactory;

 public function __construct(
 ProductInterfaceFactory $productFactory
 ) {
 $this->productFactory = $productFactory; // injectable object
 }

 public function execute(/* ... */): ProductInterface
 {
 $product = $this->productFactory->create(); // newable object
 // ...initialize the properties of a fabulous product
 return $product;
 }
}

Factory classes are peculiar: it's not necessary to implement them because they are auto-generated by the framework (automatically if we work in 

 circumstances under which we are allowed to use the Object Manager:

We've seen that directly using the Object Manager is rarely required because:

Since the circumstances in which we need to use the Object Manager are very few: we can now analyze our legacy code and apply the principles seen here to clean it up!

Magento fundamentals: why we shouldn't (almost never) use the Object Manager

Magento fundamentals: perché non serve usare (quasi mai) l'Object Manager

Per il terzo anno consecutivo ho avuto l'onore e l'onere di partecipare al
Magento Imagine, edizione 2019.

Onore perché è l'evento principale di Magento a cui, come dico sempre, almeno
una volta nella vita vale la pena partecipare.

Onere perché, diciamolo, tra ore di viaggio e ritmi sostenuti, non è proprio una
passeggiata.

Bitbull

Alessandro Ronchi

Posts written by Alessandro Ronchi

Magento fundamentals: what are the differences between custom and extension attributes?

Magento fundamentals: helper decomposition

Magento fundamentals: what are the differences between collections and repositories?

Magento fundamentals: what are the differences between events and plugins?

Magento fundamentals: why we shouldn't (almost never) use the Object Manager

Magento Imagine 2019

Mage Titans Italy 2018: my takeaways

Msi Module Enables Drop Shipping Magento 2

#NoEstimates non significa “Non stimare”