Módulo com o nome da agência no vendor: o que custa trocar depois e o que combinar antes

Vendor_Module: quem escolhe o nome e por que ele importa

Pela convenção da Adobe, todo módulo se chama Vendor_ComponentName, nome declarado no etc/module.xml e no registration.php. O vendor vira também o começo do namespace PHP (Vendor\Modulo\...) e do nome do pacote Composer, que pela regra do Composer é minúsculo, como vendor/module-nome.

Quem escolhe, na prática, é o dev, e ele costuma usar o nome da própria empresa. Isso não é abuso. Quando o módulo é um produto do fornecedor, usado em várias lojas, o vendor dele é o nome certo. O problema é outro: módulo feito só para a sua loja, com o nome de quem fez. No dia em que você troca de fornecedor, esse nome fica no seu código ou precisa ser migrado. E o nome no código não prova autoria nem define quem é dono: isso é assunto do contrato.

Onde o nome do módulo fica gravado numa loja Magento

Conferi os nomes de tabela e coluna no código do Magento 2.4.9. Numa troca de Agencia_Brinde para Loja_Brinde, tudo isto carrega o nome antigo:

No tema, a falha é silenciosa. A estrutura de tema documentada pela Adobe guarda os overrides de cada módulo numa pasta com o nome Vendor_Module. Renomeou o módulo e esqueceu a pasta, o Magento volta a usar o template original, sem erro nenhum na tela.

SQL para medir o tamanho da troca antes de pedir orçamento

Estas consultas só leem e dão uma ideia do tamanho da migração. O filtro com o nome entre porcentagens pode contar a mais, por exemplo quando a palavra aparece num texto de página; quem faz a troca revisa linha por linha depois.

-- Troque Agencia pelo vendor atual. Com prefixo de tabela, acrescente o prefixo.
-- Só leitura. Rode numa cópia do banco, nunca direto na produção.
SELECT module, schema_version, data_version FROM setup_module WHERE module LIKE 'Agencia%';
SELECT COUNT(*) AS patches FROM patch_list WHERE patch_name LIKE '%Agencia%';
SELECT COUNT(*) AS permissoes FROM authorization_rule WHERE resource_id LIKE '%Agencia%';
SELECT COUNT(*) AS atributos FROM eav_attribute
  WHERE source_model LIKE '%Agencia%' OR backend_model LIKE '%Agencia%' OR frontend_model LIKE '%Agencia%';
SELECT COUNT(*) AS widgets FROM widget_instance WHERE instance_type LIKE '%Agencia%';
SELECT COUNT(*) AS paginas FROM cms_page WHERE content LIKE '%Agencia%';
SELECT COUNT(*) AS blocos FROM cms_block WHERE content LIKE '%Agencia%';

No código, a conta é esta, rodada na raiz da loja:

grep -rl "Agencia" app/code app/design --include=*.php --include=*.xml --include=*.phtml --include=*.js | wc -l
composer show | grep -i agencia

Com os números na mão, a conversa com o dev deixa de ser “quanto custa renomear” e passa a ser “são tantos patches, tantas permissões e tantos templates no tema”. É isso que permite comparar orçamentos.

Renomear módulo Magento depois de instalado: os dois efeitos que pegam de surpresa

Patch de dados rodando de novo

O Magento decide se um patch já rodou procurando o nome da classe na patch_list. Com o namespace novo, o nome não está lá, e o patch roda outra vez. Patch que cria bloco de CMS ou insere registros pode duplicar dados ou sobrescrever o que a equipe alterou no admin. A saída prevista pela própria Adobe é o método getAliases() do patch renomeado devolver o nome antigo; no PatchApplier do 2.4.9, quando um alias consta como aplicado, o nome novo é registrado e o patch não roda:

public function getAliases()
{
    return ['Agencia\Brinde\Setup\Patch\Data\CriarBlocoAvisoBrinde'];
}

Permissões do admin que somem

Os papéis de usuário guardam os recursos liberados pelo nome, em authorization_rule. Depois da troca, o recurso Loja_Brinde::faixas não está liberado em nenhum papel restrito, e quem usa esses papéis perde acesso às telas do módulo. O papel Administrators não sente, porque recebe o recurso Magento_Backend::all. Resultado: quem testa como administrador aprova, e a equipe que usa o papel restrito descobre o problema depois do deploy.

Além desses dois, a linha antiga da setup_module fica para trás: no código do Magento, quem apaga esse registro é o module:uninstall. Por tudo isso, renomear módulo é trabalho para o staging, com backup do banco e teste logado com um usuário de papel restrito, nunca direto na produção.

Qual nome de vendor usar e o texto para a especificação

O critério que eu uso é simples. Módulo feito exclusivamente para a loja leva o nome da loja ou da empresa contratante, curto e sem acento. Módulo que é produto do fornecedor mantém o vendor dele, com a licença de uso por escrito. Texto pronto para colocar na especificação do módulo:

Módulos desenvolvidos exclusivamente para a loja usarão o vendor LojaExemplo: namespace PHP LojaExemplo, nome de módulo LojaExemplo_Funcionalidade e pacote Composer lojaexemplo/module-funcionalidade. Componentes reaproveitados do catálogo do fornecedor mantêm o vendor do fornecedor e serão listados à parte na entrega, com a licença de uso de cada um.

Se você já tem módulos com o nome de um fornecedor antigo e quer saber o tamanho da troca, me chama com o resultado das consultas acima.