Como criar atributos de extensão no Magento 2

Contextualizando

O que é um atributo de extensão?

Os atributos no Magento 2 são propriedades das entidades que auxiliam na variedade de opções. Os módulos personalizados não podem alterar as interfaces das entidades nativas, entretanto, a maioria das interfaces das entidades possuem um funcionalidade chamada atributos de extensão. Para saber se a interface da entidade possui atributos de extensão, basta observar se a mesma estende da interface \Magento\Framework\Api\ExtensibleDataInterface e possui os métodos getExtensionAttributes() e setExtensionAttributes().

Código para criar um atributo

extension_attributes.xml

Para criar os atributos de extensão é necessário criar um arquivo chamado extension_attributes.xml que deve seguir a estrutura de pasta \{Vendor}\{Module}\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="{Vendor}\{Module}\Api\Data\{EntityName}Interface">
        <attribute code="{attr_name_object}" type="{Vendor}\{Module}\{Directory}\{Class}" />
        <attribute code="{attr_name_string}" type="string" />
        <attribute code="{attr_name_boolean}" type="bool" />
        <attribute code="{attr_name_integer}" type="int" />
        <attribute code="{attr_name_float}" type="float" />
        <attribute code="{attr_name_array}" type="{type}[]" />
        <attribute code="{attr_name_array}" type="{Vendor}\{Module}\Api\Data\{EntityName}Interface[]">
            <resources>
                <resource ref="{Vendor}_{Module}::{acl_path}" />
            </resources>
            <join reference_table="{table_name}" reference_field="{column_name}" join_on_field="{interface_field}">
                <field>{field_name}</field>
            </join>
        </attribute>
    </extension_attributes>
</config>

O nó <extension_attributes> só possui um atributo, o for, que indicará qual a entidade que receberá os novos atributos de extensão e que será implementada a interface \Magento\Framework\Api\ExtensibleDataInterface e possuir os métodos getExtensionAttributes() e setExtensionAttributes().

O nó <attribute> é filho do nó <extension_attributes> e é obrigatório, este possui o atributo code, que será o nome do atributo (deverá ser escrito em snake case) e o atributo type, que indicará o tipo do atributo.

O nó <resources> é filho do nó <attribute> é opcional e não possui atributos, apenas pode ter o nó filho <resource>, já este possui o atributo ref, que referencia a seção a um recurso ACL para fornecer permissões das configurações.

O nó <join> é filho do nó <attribute> é opcional e possui o atributo reference_table, que faz uma operação de join com a tabela referenciada neste atributo, com o valor da coluna referenciada no atributo reference_field e join_on_field é a coluna da tabela associada a interface.

O nó <field> é filho do nó <join> e é obrigatório quando este for inserido. Este nó não possui atributos e nem outros nós filhos, apenas valor, que especifica a propriedade da tabela referenciada que irá unir a interface definida.

Acessando os atributos de extensão

Assim que criar o arquivo extension_attributes.xml já fica disponível para acessar e definir valores dos atributos via métodos mágicos, apenas adicionando o prefixo get e set nos nomes definidos dos atributos.

$extAttributes = $entityName->getExtensionAttributes();
$extAttributes->getAttrNameObject();
$extAttributes->getAttrNameString();
$extAttributes->getAttrNameBoolean();
$extAttributes->getAttrNameInteger();
$extAttributes->getAttrNameFloat();
$extAttributes->getAttrNameArray();

$extAttributes->setAttrNameObject($objectValue);
$extAttributes->setAttrNameString($stringValue);
$extAttributes->setAttrNameBoolean($booleanValue);
$extAttributes->setAttrNameInteger($integerValue);
$extAttributes->setAttrNameFloat($floatValue);
$extAttributes->setAttrNameArray($arrayValue);

Interface da entidade

Caso a interface que queira adicionar os atributos de extensão não pertença ao código fonte do Magento 2, basta herdar a interface \Magento\Framework\Api\ExtensibleDataInterface.

<?php

namespace {Vendor}\{Module}\Api\Data;

use Magento\Framework\Api\ExtensibleDataInterface;

interface {EntityName}Interface extends ExtensibleDataInterface
{
}

Finalizando

Valores entre chaves ({test}) devem ser alterados na implementação do código.

Habilitando as alterações

Apague os arquivos que são gerados na compilação do Magento e execute o comando PHP para gerar a configuração das injeções de dependência e todas as classes ausentes que precisam ser geradas (proxys, interceptors, etc) e para limpar todos os caches de armazenamento em cache do processos.

rm -rf var/generation/
rm -rf generated/
php bin/magento setup:di:compile
php bin/magento cache:clean
php bin/magento flush

Diretórios e Arquivos

Segue a a lista de diretórios e arquivos que devem ser criados.

- app/
  - code/
    - {Vendor}/
        - {Module}/
          - etc/
            - module.xml
            - extension_attributes.xml
          - registration.php
          - composer.json