Como criar um módulo personalizado no Magento 2

Contextualizando

O que é um módulo?

Módulo é um elemento estrutural do Magento 2 que é voltado para a lógica desenvolvida no backend e o fluxo da aplicação com o fim de personalizar elementos, ou seja, o objetivo de um módulo é providenciar recursos específicos, implementando uma nova funcionalidade ou estendendo uma funcionalidade de outro(s) módulo(s).

Por que fazer um módulo personalizado?

Um módulo personalizado é necessário para adicionar, remover e/ou personalizar uma lógica existente em algum fluxo do Magento. Cada módulo é projetado para uma função independente, portanto, a inclusão ou exclusão de um módulo em específico não deve afetar a funcionalidade de outros módulos. Todo o sistema é construído sobre módulos.
O módulo é um diretório que pode conter Controllers, Models, Api, etc. E todas essas classes estarão relacionadas com o(s) recurso(s) do negócio que irá alterar.

Estrutura de um módulo personalizado

Para criar um módulo é preciso respeitar a estrutura de diretórios do Magento 2 e é mandatório que se crie os módulos na pasta \app\code\{Vendor}\{Module}.

{Vendor}: Dentro deste diretório pode ter vários módulos, que será relacionado ao distribuidor original do módulo. O nome deste diretório, normalmente, é o nome da empresa, grupo, pessoa ou fornecedor que faz as personalizações.
{Module}: Nome do módulo ou personalização que será feita. A partir deste diretório será criado os diretórios e arquivos necessários para a regra de negócio que será alterada, incluída e/ou removida.

O nome do módulo é definido pelos diretórios, porque no Magento 2, os nomes das classes devem seguir a estrutura da pasta.

Padrões no Magento

Para programação dos arquivos em PHP, o Magento requer que utilize os padrões das PSR-1 e PSR-2.

Recomendação pessoal que conheça as PSR-3, PSR-4 e PSR-12.

Os módulos seguem o padrão estrutural MVC, sendo que a camada de modelo é dividida em Model, Resource Model e Collection. A camada controladora utiliza os arquivos no diretório Controller. E a camada de visualização é dividida entro os diretórios Blocks ou View Models, layouts e templates que utilizam o padrão MVVM.

---

Código para a criação de um módulo personalizado

registration.php

Componentes no Magento 2, incluindo módulos, temas e pacote de linguagens, devem ser registrados no sistema do Magento através da classe ComponentRegistrar no arquivo registration.php. Cada módulo deve ter esse arquivo que informa ao Magento como localizar o módulo.

Os arquivos de registro do módulo são obrigatórios e devem seguir a estruturas de pastas \{Vendor}\{Module}\registration.php.

<?php

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    '{Vendor}_{Module}',
    __DIR__
);

module.xml

O module.xml é um arquivo obrigatório que irá conter informações sobre a versão do nosso módulo e também qual o nome que ele deve ser conhecido. Este arquivo também pode conter módulos dependentes, ou seja, pode-se especificar no XML quais módulos devem estar instalados e ativados. A versão atual indica quais esquemas e dados serão atualizados no banco. Esses arquivos devem seguir a estruturas de pastas \{Vendor}\{Module}\etc\module.xml.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="{Vendor}_{Module}" setup_version="{version_number}">
        <sequence>
            <module name="{Vendor}_{DependentModuleName}" />
        </sequence>
    </module>
</config>

Este arquivo é obrigatório.

composer.json

O composer.json é um arquivo para uma extensão do módulo que declara dependências externas de que ele precisa para funcionar.

Este arquivo não é obrigatório, mas recomendo a criação deste arquivo, mesmo que você não pretenda distribuí-lo. Esses arquivos devem seguir a estruturas de pastas \{Vendor}\{Módulo}\composer.json.

{
    "name": "{vendor}/module-{module-name}",
    "description": "{Description}",
    "require": {
        "php": "~8.1.0||~8.2.0",
        "{vendor}/module-{dependent-module}": "{dependent_module_version}"
    },
    "type": "magento2-module",
    "version": "{version_number}",
    "license": [
        "OSL-3.0",
        "AFL-3.0"
    ],
    "autoload": {
        "files": [
            "registration.php"
        ],
        "psr-4": {
            "{Vendor}\\{Module}\\": ""
        }
    }
}

Caso o módulo seja instalado via composer, o diretório vendor seguirá a propriedade name do arquivo composer.json.

---

Finalizando

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

Habilitando o módulo

Para registrar e habilitar o módulo é necessário rodar os dois seguintes comandos.

# Comando para habilitar o módulo no magento
php bin/magento module:enable {Vendor}_{Module}

# Comando para Ao habilitar os módulos, altere a versão dos módulos que você precisará executar
php bin/magento setup:upgrade

É possível verificar no arquivo app/code/etc/config.php e procurar na lista de módulos se o módulo personalizado foi registrado e habilitado no Magento. Você pode conferir se outros módulos estão habilitados.

Diretórios e Arquivos

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

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

Obs.: A estrutura passada aqui não altera nada visualmente no Magento 2, mas sim explica e cria a base para as personalizações que serão demonstradas no futuro.