DEV Community

Lucas Teixeira dos Santos Santana
Lucas Teixeira dos Santos Santana

Posted on • Updated on

Como criar atributos de extensão no Magento 2

#php #magento2 #tutorial #braziliandevs

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

Criando o atributo de extensão

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="boolean" />
        <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>
Enter fullscreen mode Exit fullscreen mode

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.

db_schema.xml

É necessário adicionar uma coluna na tabela desejada para o campo do atributo de extensão criado no arquivo extension_attributes.xml.
Utilizarei o arquivo de db_schema.xml para adicionar a coluna na tabela, mas pode ser feito como UpgradeSchema ou SchemaPatch.

<?xml version="1.0" ?>
<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd">
    ...
    <table name="{table_name)">
        <column xsi:type="{column_type}" name="{column_name)" comment="{Column Comment}"/>
    </table>
</schema>
Enter fullscreen mode Exit fullscreen mode

Para saber mais sobre como criar e/ou atualizar campos na tabela via db_schema.xml basta acessar o post "Como criar tabelas personalizadas no banco de dados com db_schema.xml no Magento 2".
Para saber mais sobre como criar e/ou atualizar campos na tabela via SchemaPatch basta acessar o post "Como criar/atualizar tabelas e dados com DataPatch e SchemaPatch no Magento 2".
Para saber mais sobre como criar e/ou atualizar campos na tabela na forma antiga que o Magento utiliza, UpgradeSchema, basta acessar o post "Como criar/atualizar tabelas com InstallSchema e UpgradeShema no Magento 2".

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);
Enter fullscreen mode Exit fullscreen mode

Atributo de extensão na entidade

Interface

No Magento, primeiro criamos a interface do repositório no caminho \{Vendor}\{Module}\Api\Data. 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.
Para saber mais sobre como sobreescrever arquivos através no post "Como sobrescrever arquivos no Magento 2 através de preferences".

<?php

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

use Magento\Framework\Api\ExtensibleDataInterface;

interface {EntityName}Interface extends ExtensibleDataInterface
{
    public const {ATTR_NAME} = '{attribute_name}';

    public function get{MethodName}(): {type};

    public function set{MethodName}(): self;

    public function getExtensionAttributes(): \{Vendor}\{Module}\Api\Data\{EntityName}ExtensionInterface;

    public function setExtensionAttributes(\{Vendor}\{Module}\Api\Data\{EntityName}ExtensionInterface $extensionAttributes): self;
}
Enter fullscreen mode Exit fullscreen mode

di.xml

Após a criação da interface do repositório é necessário a sobrescrição através do arquivo di.xml, para que o arquivo fique devidamente implementado e possa descrever em como os métodos serão executados.

<?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="{Vendor}\{Module}\Api\Data\{EntityName}Interface" type="{Vendor}\{Module}\Model\Data\{EntityName}"/>
    ...
</config>
Enter fullscreen mode Exit fullscreen mode

Model

Criado a interface do repositório e a sobrescrição da interface através do arquivo di.xml, falta apenas implementar os métodos da interface na classe.

<?php

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

use Magento\Framework\Model\AbstractExtensibleModel;
use {Vendor}\{Module}\Api\Data\{EntityName}Interface;

class {EntityName} extends AbstractExtensibleModel implements {EntityName}Interface
{
    public function get{MethodName}(): {type}
    {
        return $this->_get({EntityName}Interface::{ATTR_NAME});
    }

    public function set{MethodName}(string $attrName): {EntityName}Interface
    {
        return $this->setData({EntityName}Interface::ATTR_NAME, $attrName);
    }

    public function getExtensionAttributes(): \{Vendor}\{Module}\Api\Data\{EntityName}ExtensionInterface
    {
        return $this->_getExtensionAttributes();
    }

    public function setExtensionAttributes(\{Vendor}\{Module}\Api\Data\{EntityName}ExtensionInterface $extensionAttributes) {
        return $this->_setExtensionAttributes($extensionAttributes);
    }
}
Enter fullscreen mode Exit fullscreen mode

Plugin para salvar/recuperar os dados do atributo de extensão

di.xml

Para saber mais sobre plugin basta acessar o post "Como criar plugins no Magento 2".

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    ...
    <type name="Magento\{Module}\Model\{Directory}\{EntityName}">
        <plugin name="{plugin_name}" type="{Vendor}\{Module}\Plugin\Model\{PluginEntityName}" disabled="false" sortOrder="10" />
    </type>
    <type name="Magento\{Module}\Model\{Directory}\{EntityName}Repository">
        <plugin name="{plugin_name}" type="{Vendor}\{Module}\Plugin\{Directory}\{PluginRepositoryName}" disabled="false" sortOrder="20" />
    </type>
    ...
</config>
Enter fullscreen mode Exit fullscreen mode

Plugins

Será necessário criar o método afterLoad() para adicionar os atributos de extensão no retorno do objeto quando forem recuperado do banco via a classe da entidade.
Será necessário criar o método beforeSave() para adicionar valores no atributo de extensão antes de salvar o objeto no banco de dados através da entidade.

<?php

namespace {Vendor}\{Module}\Plugin\{Directory};

use Magento\{Module}\Api\Data\{EntityName}ExtensionFactory;
use Magento\{Module}\Api\Data\{EntityName}Interface as Magento{EntityName}Interface;
use {Vendor}\{Module}\Api\Data\{EntityName}Interface;

class {PluginEntityName}
{
    public function __construct(
        private {EntityName}ExtensionFactory $extensionAttributeFactory
    ) {
    }

    public function afterLoad(Magento{EntityName}Interface $subject): Magento{EntityName}Interface {
        $extensionAttributes = $subject->getExtensionAttributes() ?: $this->extensionAttributeFactory->create();

        $extensionAttributes->set{MethodName}($subject->getData({EntityName}Interface::ATTR_NAME));

        $subject->setExtensionAttributes($extensionAttributes);

        return $subject;
    }

    public function beforeSave(Magento{EntityName}Interface $subject): array 
    {
        $extensionAttributes = $subject->getExtensionAttributes() ?: $this->extensionAttributeFactory->create();

        if ($extensionAttributes !== null && $extensionAttributes->set{MethodName}() !== null) {
            $subject->set{MethodName}($extensionAttributes->get{MethodName}());
        }

        return [$subject];
    }
}
Enter fullscreen mode Exit fullscreen mode

Será necessário criar os métodos afterGetById() e afterGetList() para adicionar os atributos de extensão no retorno do(s) objeto(s) quando forem recuperado do banco via o repositório.
Será necessário criar o método beforeSave() para adicionar valores no atributo de extensão antes de salvar o objeto no banco de dados através do repositório.

<?php

namespace {Vendor}\{Module}\Plugin\{Directory};

use Magento\{Module}\Api\Data\{EntityName}ExtensionFactory;
use Magento\{Module}\Api\{EntityName}RepositoryInterface;
use {Vendor}\{Module}\Api\Data\{EntityName}Interface;
use Magento\{Module}\Api\Data\{EntityName}Interface as Magento{EntityName}Interface;
use Magento\{Module}\Api\Data\{EntityName}SearchResultsInterface;

class {PluginRepositoryName}
{
    public function __construct(
        private {EntityName}ExtensionFactory $extensionAttributeFactory
    ) {
    }

    public function afterGetById(
        {EntityName}RepositoryInterface $subject,
        Magento{EntityName}Interface $entity
    ): Magento{EntityName}Interface {
        $extensionAttributes = $entity->getExtensionAttributes() ?: $this->extensionAttributeFactory->create();

        $extensionAttributes->set{MethodName}($entity->getData({EntityName}Interface::ATTR_NAME));

        $entity->setExtensionAttributes($extensionAttributes);

        return $entity;
    }

    public function afterGetList(
        {EntityName}RepositoryInterface $subject,
        {EntityName}SearchResultsInterface $resultCart
    ) {
        /** @var Magento{EntityName}Interface $entity */
        foreach ($resultCart->getItems() as $entity) {
            $this->afterGetById($subject, $entity);
        }

        return $resultCart;
    }

    public function beforeSave(
        {EntityName}RepositoryInterface $subject,
        Magento{EntityName}Interface $entity
    ): array {
        $extensionAttributes = $entity->getExtensionAttributes() ?: $this->extensionAttributeFactory->create();

        if ($extensionAttributes !== null && $extensionAttributes->set{MethodName}() !== null) {
            $entity->set{MethodName}($extensionAttributes->get{MethodName}());
        }

        return [$entity];
    }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Top comments (0)

Read next

jancizmar profile image

I have localized the best short-linking platform in the world

Jan Cizmar -

nasrulhazim profile image

Kong Admin API for PHP: A Framework-Agnostic Client for Seamless Kong Gateway Management

Nasrul Hazim Bin Mohamad -

lithephp profile image

Lithe Crypt: Simplifying Encryption in PHP Applications

Lithe -

lithephp profile image

Improving the Performance of Your PHP Application with Lithe Cache

Lithe -