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.