Como criar um módulo personalizado no Magento 2
Tags: php, magento2, tutorial, braziliandevs
Published: 2021-10-01 20:48:10

# 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
<?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
<?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`.

```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.

```bash
# 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.