Lo scopo di questo articolo è quello di gettare un po' di luce sul sistema di gestione degli attributi di Magento 2, flessibile ma poco intuitivo ad un primo approccio.

Ci sono molte risorse in rete che documentano come implementare custom ed extension attribute, perciò qui dedichiamo l'attenzione su alcuni 

 e non sempre ben evidenziati nella documentazione ufficiale.

Come guida di riferimento passo passo, raccomando di leggere la 

 o, ancor meglio, di seguire gli ottimi tutorial di 

Panoramica del sistema di gestione degli attributi

Sin dai primi tempi, Magento ha offerto un 

sistema flessibile per la gestione degli attributi delle entità

Attraverso questo sistema, è davvero semplice estendere una entità Magento, sebbene ci siano alcune limitazioni da tenere presente:

, introdotti in Magento 2, consentono di scavalcare i suddetti limiti, rendendo semplice:

Sfortunatamente, alcune entità core di Magento non implementano l'interfaccia 

\Magento\Framework\Api\ExtensibleDataInterface

 non consentendoci quindi di estenderle con gli extension attribute.
Tuttavia, guardando il bicchiere mezzo pieno, andiamo a vedere che 

 offre il sistema degli extension attribute.

Con l'introduzione degli extension attribute si è arricchita la terminologia, quindi è bene dare qualche definizione.

Un attributo EAV può essere di due tipi:

Abbiamo già dato una definizione ma vale la pena ripeterla: un 

Innanzi tutto le buone notizie: un extension attribute ci consente di 

superare le limitazioni relative ai valori scalari

estendere sia entità EAV sia non-EAV con oggetti complessi

Per vedere un esempio, prendiamo la dichirazione dell'extension attribute 

) dove si vede come l'attributo sia un insieme strutturato di valori:

<?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';
 /**#@-*/

 // ...
}

 per questa flessibilità è il fatto che 

la persistenza degli extension attribute è da gestire programmaticamente

, mentre i valori dei custom attribute sono caricati e salvati automaticamente.

Per i dettagli tecnici su come aggiungere un extension attribute ad una entità 

Vale la pena invece sottolineare che l'interfaccia 

 non dichiara i metodi per accedere agli extension attribute. Vediamo la sua dichiarazione:

<?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';
}

Per convenzione, i metodi generalmente sono nominati 

 ma non è scontato che una classe che implementi l'interfaccia 

 li fornisca , perciò il consiglio è di controllare sempre per sicurezza.

Un'altra caratteristica che vale la pena menzionare è che, per evitare un degrado di performance quando si recuperano gli extension attribute nelle collection, Magento mette a dispoizione 

. Attenzione però al fatto che tale funzionalità è 

limitata agli extension attribute di tipo scalare

Come esempio, possiamo fare riferimento alla dichiarazione dell'extension attribute 

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>

, non è sufficiente dichiararla come mostrato nell'esempio; dobbiamo anche assicurarci di passare la collection al metodo 

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

 che la popolerà con i dati corretti.
Possiamo vedere un esempio nel metodo 

<?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);
 // ..
 }

 // ...
}

Una ulteriore funzionalità rilevante offerta dagli extension attribute è quella di 

Dove memorizzare gli extension attribute?

Generalmente, gli extension attribute sono attributi di tipo non-EAV, quindi dobbiamo occuparci di decidere dove persisterne i valori.

Se un extension attribute è un oggetto complesso, la scelta più naturale è quella di utilizzare una 

Se, al contrario, l'extension attribute è di tipo scalare, è possibile memorizzarne i valori su una 

, a patto di utilizzare una prefisso non ambiguo che eviti collisioni con colonne native o aggiunte da altre estensioni.
Così facendo, scriveremo 

 perché eviteremo di dover utilizzare condizioni di join aggiuntive per recuperare i valori.

Tuttavia non esiste una regola assoluta: a seconda dei casi, è bene 

 non rappresentano una novità in Magento ma solo un 

nome nuovo per gli attributi delle entità EAV

, al contrario, rappresentano la vera novità che consente di 

Inoltre, gli extension attribute introducono la possibilità di definire 

, superando la limitazione dei tipi scalari.

C'è un piccolo prezzo da pagare per questa flessibilità aggiuntiva: dobbiamo 

 per assicurarci che i valori degli extension attribute siano salvati e caricati correttamente.

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

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

"nella programmazione orientata agli oggetti, una classe helper è utilizzata per fornire funzioni utili che non rappresentano lo scopo principale dell'applicazione in cui sono utilizzate."

Gli helper avevano un ruolo primario in Magento 1 e questo ha lasciato molte tracce anche nel codice di Magento 2, dove sono presenti numerose classi helper.

A mio parere, questo è il motivo per cui molti sviluppatori hanno continuato a implementare le proprie classi helper in Magento, violandone però le linee guida.

Perché gli helper non rispettano le linee guida di Magento 2?

Per definizione, una classe helper fornisce funzioni con diversa utilità e quindi ha 

, il che viola i principi di sviluppo di classi definiti nelle 

Nello specifico, un helper viola il cosiddetto 

, secondo cui una classe non dovrebbe avere più di un motivo per apportare una modifica.

Molti degli helper presenti in Magento 2estendono la classe 

\Magento\Framework\App\Helper\AbstractHelper

In Magento 2.4.2, tale classe dipende dalle seguenti:

Ecco quindi un perfetto esempio di coltellino svizzero che ha ben più di un motivo per apportare modifiche.

Partiamo dal presupposto che lo scopo di un helper non è fornire dati (in seguito approfondisco questo aspetto) ma 

Stando alle linee guida, i comportamenti si implementano con 

) che aderiscano il più possibile ai seguenti principi:

Da notare che in Magento sono presenti molte classi di servizio che non seguono del tutto i principi sopra elencati, come i repository, i resource model e molte altre. La regola più importante a cui dovremmo cercare di attenerci è quella relativa allo stato immutabile che ci mette al riparo dall'avere effetti collaterali indesiderati. Gli altri principi sono auspicabili ma non obbligatori, come vedremo nell'esempio riportato in seguito.

Se guardiamo agli helper come li abbiamo implementati sino ad oggi, ci renderemo conto che alla fin fine sono solo un insieme di comportamenti impacchettati in una sola classe.

Decomporli a questo punto non sarà difficile.

Ma non è vero che gli helper non forniscono dati!

Come promesso, eccomi a trattare questo punto. Leggere che una classe di servizio non fornisce dati non va interpretato alla lettera: tra gli scopi di questo genere di classi c'è proprio quello di fornire astrazioni sul livello di persistenza.

 si riferisce al fatto che le classi di servizio 

; non hanno una identità (una chiave primaria, per intenderci) né uno stato e non scrivono né recuperano 

Possono servire, come anticipato, per accedere ai dati di altre entità. Ad esempio i repository sono classi di servizio che forniscono metodi di accesso ai dati (noti anche come 

A questo punto dovremmo essere pronti a decomporre un helper in diverse classi di servizio.

Si tratta di identificare i diversi comportamenti, o 

, della nostra classe helper e smistarli in classi differenti.

💡 Quando scriviamo le nuove service class, è bene attenersi alle 

Credo che un esempio valga più di mille parole, quindi riporto di seguito dei frammenti di codice estratti dai moduli scritto per decomporre l'helper seguente (i dettagli di implementazione sono omessi perché non aggiungono nulla di utile):

<?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
 }
}

La classe helper sopra riportata espone due comportamenti principali:

Pertanto, definiamo due service contract e le rispettive implementazioni:

Il codice derivante da questa decomposizione è riportato di seguito.

<?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
 }
}

 per il funzionamento della dependency injection

<?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>

Capisco che adeguarsi a linee guida dettate da altri può essere noioso, perché ci obbliga ad abbandonare le nostre abitudini e la nostra 

Ma appena ci rendiamo conto dei benefici, comprendiamo anche perché ne vale la pena.
Il codice di tutti segue la stessa struttura e aderisce alle stesse regole, diventa più leggibile, a tutto vantaggio della sua stabilità e manutenibilità a lungo termine.

Magento fundamentals: decomporre un helper

Magento fundamentals: helper decomposition

Una delle domande più frequenti che capita di fare quando si gestiscono entità in Magento 2 è: 

"dovrei usare un repository o una collection?"

In questo articolo vedremo quali sono le 

 senza scendere in dettagli troppo tecnici ma analizzando soprattutto 

 per cercare di comprendere quando scegliere un approccio o l'altro.

I repository rappresentano una novità in Magento 2 mentre le collection sono una eredità di Magento 1.

Entrambi sono utilizzati per gestire la persistenza delle entità ma appartengono a 

"un repository funge da intermediario tra il dominio e i dati e utilizza una interfaccia simile a quella delle collection per accedere agli oggetti di dominio."

introdotto dal Domain-Driven Design nel 2014

, in cui la query viene costruita utilizzando concetti molto vicini al dominio dei 

Poiché i repository appartengono ad un livello di astrazione più alto, in Magento 2 sono spesso implementati come 

 e i loro metodi sono esposti attraverso le API pubbliche.

Ecco un semplice diagramma che riassume le relazioni tra i diversi livelli:

Collection e repository non si istanziano allo stesso modo perché sono due 

Tale distinzione è importante perché ci dice che le collection devono essere istanziate attraverso un 

 mentre i repository possono essere istanziati attraverso 

 dichiarandone una dipendenza nei costruttori.

Per approfondire l'argomento, si può fare riferimento a 

Approfondiamo lo stato di collection e repository

Vediamo in che senso le collection mantengono uno stato mentre i repository 

Le collection possono essere considerate oggetti di tipo 

 e servono a costruire query, anche se non aderiscono strettamente al 

Per costruire una query, una collection viene 

 impostando, ad esempio, i campi dell'entità e i filtri che vogliamo applicare al set di dati.

 è invocato, lo stato della collection è utilizzato per costruire la query.

Vediamo un frammento di codice tratto dal metodo 

\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;
 }
 // ...
}

 costruisce la query e recupera il risultato della sua esecuzione, 

 non ripeteranno il passaggio precedente ma si limiteranno a tornare il dato precedentemente memorizzato, a meno di invocare prima il metodo 

☝ Invocare il metodo <code>load()</code> non è necessario perché è invocato dal metodo <code>getIterator()</code>, a sua volta invocato appena si prova a iterare gli elementi della collection.

Il metodo <code>getIterator()</code> è dichiarato nella interfaccia <code>IteratorAggregate</code> implementata da ogni collection di Magento.

Questo meccanismo prende il nome di lazy data loading, e ha diversi vantaggi:

oggetti di servizio generalmente privi di stato

In realtà i repository possono avere uno stato ma poiché, a differenza delle collection, questo non ha un effetto sul risultato, possiamo considerarli oggetti privi di stato.

Lo stato a cui mi riferisco è rappresentato dall'uso della 

 che un repository può implementare per ottimizzare le prestazioni.

 salva le istanze di prodotto per le chiamate successive, come mostrato di seguito.

<?php
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];
}

Tecnicamente, questo significa mantenere uno stato; per questo motivo aggiungo sempre "generalmente" quando dico che i repository non mantengono uno stato.

Ricapitoliamo i pro e i contro nell'utilizzo di collection e repository.

Dovremmo sempre implementare un repository per le entità custom?

Questa domanda ricorre tutte le volte che sviluppiamo una entità custom.

La mia risposta è sì, a meno che l'entità che stiamo sviluppando rappresenti una estensione (

Poiché i valori degli extension attribute in genere sono iniettati nell'entità principale, non è necessario implementare un repository specifico per la nostra entità custom.

Nel gergo del Domain-Driven Design, si direbbe che non ci serve un repository per le entità figlie di un 

 (l'entità principale) poiché, citando Martin Fowler, 

"gli aggregati rappresentano una unità transazionale"

Abbiamo visto che ci sono pro e contro nell'utilizzo sia dei repository sia delle collection.

Le collection ci offrono più espressività poiché sono più vicine al livello di persistenza; i repository sono meno espressivi ma ci consentono di disaccoppiare maggiormente il codice che li utilizza dal livello di persistenza; ci consentono, inoltre, di implementare meccanismi per migliorare le performance, come la cache.

Conoscere le differenze tra i diversi elementi offerti dal framework Magento è essenziale per fare scelte consapevoli e ottenere il miglior risultato possibile.

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

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

I plugin sono una novità introdotta da Magento 2 e rappresentano un nuovo modo di estenderne le funzionalità.

quando in mano abbiamo un martello, tutto il mondo ci sembra un chiodo

. In altre parole, spesso si ricorre ai plugin anche quando non ce ne sarebbe bisogno.

In questo articolo approfondiremo le differenze tra i plugin e i cari vecchi eventi e cercheremo di capire quando ha senso usare gli uni o gli altri per personalizzare la piattaforma.

La differenza tra dipendenze deboli e forti

Una importante differenza tra eventi e plugin è costituita dal fatto che i primi costituistono 

, rispettivamente indicate in inglese come 

Cerchiamo di capire in cosa consiste tale differenza.

Se un observer dipende da un evento che per qualche motivo (intenzionale o meno) non è più dispacciato, l'observer non si attiva e in apparenza tutto continua a funzionare. Naturalmente qualcosa non sta funzionando ma senza compromettere la navigabilità del sito.

In questo caso si dice che la dipendenza (dall'evento) è di tipo 

I plugin si comportano in maniera diversa: se un plugin dipende da una classe che per qualche motivo non è presente a sistema, viene generato un 

In questo caso si dice che la dipendenza (dal plugin) è di tipo 

Conoscere questa differenza è importante perché può 

 nella scelta dell'uno o dell'altro meccanismo quando dobbiamo applicare le nostre personalizzazioni.

Facciamo un paio di esempi; sono estremamente semplici giusto per rendere l'idea.

 nell'ambito di applicazione di eventi e plugin che occorre conoscere.

Sin dai tempi di Magento 1, sappiamo che se nel punto in cui vogliamo applicare le nostre modifiche non viene dispacciato un evento, non possiamo contare su questo meccanismo.

Ci sono moltissimi eventi utili dispacciati da Magento, ma prima o poi ci imbatteremo in un punto di codice dove manca il 

 di qualsiasi classe, preferibilmente annotata con 

☝ Le classi annotate con <code>@api</code> garantiscono che le loro interfacce pubbliche non cambieranno a meno di un major o minor update. 
Per approfondire: : <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>

Una spiegazione più dettagliata dei plugin esula dagli obiettivi di questo articolo e per approfondire vi rimando alla 

Mi interessa invece soffermarmi su alcuni aspetti legati alle 

L'esecuzione dei plugin e degli eventi ha un 

 ma l'esecuzione di alcuni tipi di plugin è decisamente più onerosa.

Di seguito riporto una misurazione di tale impatto.

☝ Ho utilizzato <a href="https://blackfire.io/">Blackfire</a> (uno strumento che consiglio caldamente) per profilare il tempo di esecuzione di un observer e di tre plugin; questi non fanno altro che aggiungere uno statement <code>sleep(1)</code>, per forzare Blackfire a segnalarli come potenziali colli di bottiglia.

around plugin sono più lenti di almeno un ordine di grandezza

: se non abbiamo bisogno di impedire l'esecuzione del metodo originale o quella dei plugin successivi, gli around plugin non ci danno niente di più, aggiungono inutilmente del tempo di calcolo in più. 
In questo caso è raccomandato scegliere un tipo di plugin

Sebbene una singola chiamata di pochi microsecondi o millisecondi non influisca più di tanto sulle prestazioni, è bene considerare che in una installazione di default di Magento ci sono 

 dovute a observer e plugin, senza contare quelle aggiunte da moduli e personalizzazioni di terze parti.

Il tempo di esecuzione totale di tali chiamate può avere quindi un impatto non indifferente sulle prestazioni, soprattutto quando i plugin sono utilizzati impropriamente.

☝ Doverosa precisazione: anche gli eventi possono impattare negativamente sulle prestazioni se non si adottano le necessarie linee guida. Per approfondire, fare riferimento alla <a href="https://devdocs.magento.com/guides/v2.4/ext-best-practices/extension-coding/observers-bp.html">documentazione ufficiale</a>.

 tra eventi e plugin e che non tutti i plugin sono dello stesso tipo.

 può fare la differenza in termini di prestazioni.

eventi costituiscono ancora una valida scelta

, perciò teniamoli in considerazione la prossima volta che dovremo applicare le nostre personalizzazioni.

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

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

Questo articolo inaugura una serie ispirata ad alcune 

Potrebbero sembrare argomenti scontati dopo più di cinque anni dal rilascio della versione 2.0 e tanta documentazione disponibile ma purtroppo ci imbattiamo quotidianamente in codice di terze parti che dimostra che in realtà argomenti come questi sono tutt'altro che assodati.

, aspettatevi domande tratte da questa serie di articoli durante il colloquio.

L'Object Manager è un oggetto utilizzato internamente dal framework Magento per 

 e passarli al costruttore di altre classi.

 e per questo motivo gli oggetti passati dall'Object Manager sono detti 

Gli oggetti passati ad un altro oggetto attraverso il suo costruttore costituiscono le cosiddette 

. 
Per approfondire: https://it.wikipedia.org/wiki/Dependency_injection

Bitbull

Alessandro Ronchi

Articoli scritti da Alessandro Ronchi

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

Magento fundamentals: decomporre un helper

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

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

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

Magento Imagine 2019

Mage Titans Italy 2018: gli spunti che ho portato a casa

Msi Module Enables Drop Shipping Magento 2

#NoEstimates non significa “Non stimare”