CONVIRO
Engineering

Como instalar uma extensão Magento 2 com Composer: guia passo a passo

Um guia prático para instalar uma extensão Magento 2 com Composer: repositórios privados, auth.json, setup:upgrade, passos do modo de produção, atualizações, desinstalação e…

Conviro
19 de novembro de 20267 min de leitura
Como instalar uma extensão Magento 2 com Composer: guia passo a passo
Neste artigo

Para instalar uma extensão Magento 2 com Composer, adiciona-se o repositório do fornecedor (e as credenciais, caso seja privado), executa-se composer require, ativa-se o módulo, corre-se bin/magento setup:upgrade, compila-se e faz-se o deploy do conteúdo estático se a loja estiver em modo de produção e, por fim, limpa-se a cache. São meia dúzia de comandos, mas a ordem e o modo de deploy contam.

Este guia percorre a sequência completa com a extensão gratuita Conviro for Magento como exemplo e trata depois das atualizações, da desinstalação e dos erros que mais provavelmente vai encontrar.

Pontos-chave

  • Execute todos os comandos a partir da raiz do Magento como proprietário do sistema de ficheiros, depois de uma cópia de segurança, e primeiro em staging.
  • O modo de desenvolvimento precisa de setup:upgrade e de limpar a cache; o modo de produção precisa também de compilação e de deploy do conteúdo estático.
  • Desinstale pela ordem inversa: primeiro desligue a integração, depois desative, remova e execute o upgrade.

Antes de começar: pré-requisitos

Verifique estes pontos antes de mexer na produção:

  • Acesso SSH e Composer no servidor. Uma instalação com Composer não pode ser feita a partir do painel de administração.
  • Uma cópia de segurança recente do código e da base de dados e, idealmente, uma cópia de staging para testar.
  • O utilizador certo. Execute os comandos como proprietário do sistema de ficheiros, não como root, ou vai criar problemas de permissões.
  • O seu modo de deploy. Verifique-o com bin/magento deploy:mode:show.
  • Uma janela de manutenção para a produção: bin/magento maintenance:enable antes, bin/magento maintenance:disable depois.

No caso concreto da extensão da Conviro, precisa ainda do Magento Open Source 2.4.4 ou posterior com PHP 7.4 ou 8.1–8.4, de um URL da loja em HTTPS, do cron do Magento em execução e de HTTPS de saída para api.conviro.io. A extensão (versão 1.4.1 no momento em que escrevemos) teve a instalação testada em:

Magento PHP Tema
2.4.4-p13 8.1 Luma
2.4.7-p4 8.3 Luma
2.4.9 8.4 Luma e Hyvä 1.5.2

O Adobe Commerce assenta na mesma framework, mas ainda não foi testado, o Hyvä Checkout não foi testado e as lojas em 2.4.0–2.4.3 mantêm a extensão 1.3.5.

Como instalar uma extensão Magento 2 com Composer, passo a passo

Passo 1: adicionar o repositório Composer e as credenciais

As extensões privadas são servidas a partir do repositório Composer do próprio fornecedor. Na raiz do Magento:

composer config repositories.conviro composer https://repo.conviro.io
composer config http-basic.repo.conviro.io api <CONVIRO_API_KEY>

O primeiro comando adiciona o repositório ao composer.json. O segundo guarda as credenciais no auth.json, que fica ao lado. No caso da Conviro, o nome de utilizador é api e a palavra-passe é uma chave de API criada em Developers → API Keys no painel da Conviro. Encontra mais informação sobre a API da Conviro na página para programadores.

Mantenha o auth.json fora do controlo de versões. As suas chaves do repo.magento.com costumam estar no mesmo ficheiro.

Passo 2: executar composer require e setup:upgrade

composer require conviro/module-aichat
bin/magento module:enable Conviro_AiChat
bin/magento setup:upgrade

Estes três comandos são o núcleo de qualquer instalação de um módulo Magento 2:

  1. composer require descarrega o pacote para vendor/ e regista-o no composer.json e no composer.lock. Faça commit dos dois ficheiros para que todos os ambientes instalem a mesma versão.
  2. module:enable regista o módulo em app/etc/config.php.
  3. setup:upgrade aplica os patches de esquema e de dados do módulo à base de dados e atualiza o registo de módulos.

Passo 3: compilar, fazer o deploy e limpar a cache

Em modo de produção, o código gerado e os ficheiros estáticos não são criados a pedido, por isso execute:

bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f

Em modo de desenvolvimento, salte os dois. Em qualquer dos modos, termine com:

bin/magento cache:flush

Depois, confirme que o módulo está ativo e saia do modo de manutenção:

bin/magento module:status Conviro_AiChat
bin/magento maintenance:disable

Passo 4: ligar a extensão no admin

A maioria das extensões precisa de configuração depois da instalação. No caso da Conviro, abra Stores › Settings › Conviro Setup. Um assistente de configuração em 7 passos faz uma verificação do ambiente; depois, clica em Connect to Conviro, aprova a loja no painel da Conviro e regressa ao Magento. Nenhuma chave de API ou token é copiado para o Magento.

O assistente de configuração cria uma integração Magento com privilégios mínimos (OAuth 1.0a), permite escolher as vistas de loja (store views), o que sincronizar e que ações de IA são permitidas, e verifica tudo com um evento de teste. Depois disso, o cartão Integration Health em Stores › Configuration › Conviro › AI Chat verifica ligação, autenticação, webhooks, catálogo, encomendas, cron, versão e ambiente, com instruções de correção. A página de instalação e a documentação de instalação explicam cada passo. Ligar a loja exige um plano Conviro com acesso à API, Pro ou superior (veja os preços).

Atualizar e desinstalar um módulo Magento 2

Atualizar

composer update conviro/module-aichat
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Tal como antes, compile e faça o deploy apenas em modo de produção. O admin do Magento mostra um aviso com o comando exato quando sai uma nova versão, e a configuração, a chave de API e a integração são preservadas.

Desinstalar

A ordem importa: a loja desliga-se no assistente de configuração, que deixa de existir depois de o módulo ser removido.

  1. Desligue a loja no assistente de configuração da Conviro.
  2. Desative o módulo: bin/magento module:disable Conviro_AiChat
  3. Remova o pacote: composer remove conviro/module-aichat
  4. Execute bin/magento setup:upgrade.

Em modo de produção, volte a compilar, faça de novo o deploy do conteúdo estático e limpe a cache, como habitualmente. A Conviro apaga os dados da loja 30 dias depois de a desligar, ou de imediato, se o preferir. A documentação de desinstalação lista todos os passos.

Erros comuns e como os corrigir

Sintoma Causa provável Solução
"Allowed memory size exhausted" durante o Composer Limite de memória do PHP Execute COMPOSER_MEMORY_LIMIT=-1 composer require ...
A compilação fica sem memória Limite de memória do CLI Execute php -d memory_limit=2G bin/magento setup:di:compile
Erro 401 ou pedido de credenciais do repositório Chave ou nome de utilizador errados Volte a executar o comando http-basic; o nome de utilizador é api
"Permission denied" em generated/, var/ ou pub/static/ Comandos executados como root ou com o utilizador errado Corrija o proprietário dos ficheiros e volte a executar como proprietário do sistema de ficheiros
"Please upgrade your database" setup:upgrade não executado Execute bin/magento setup:upgrade
Os dados deixam de sincronizar e o cartão de saúde assinala o cron O cron não está a correr Execute bin/magento cron:install e verifique crontab -l

O cron importa mais do que parece. A Conviro escreve os eventos de checkout, de registo de clientes e de gravação de produtos numa fila local que o cron do Magento entrega em segundo plano. A extensão foi também concebida para que as páginas da loja não chamem a Conviro a partir de PHP e para que as encomendas continuem a ser processadas mesmo que a Conviro esteja inacessível. Teste primeiro todo o fluxo em staging; a nossa checklist de testes para chatbots de IA ajuda depois da instalação.

Perguntas frequentes

Preciso de executar setup:di:compile em modo de desenvolvimento?

Não. O modo de desenvolvimento gera código a pedido, por isso setup:upgrade e cache:flush chegam depois de instalar um módulo. Em modo de produção, execute também setup:di:compile e setup:static-content:deploy; caso contrário, a loja e o admin podem deixar de funcionar por faltarem o código gerado e os ficheiros estáticos.

Onde é que o Composer guarda as credenciais de um repositório privado?

composer config http-basic.<host> <user> <password> escreve-as no auth.json na raiz do projeto, ao lado do composer.json. Acrescente --global para as guardar antes na pasta Composer home do seu utilizador. Em qualquer dos casos, mantenha o auth.json fora do controlo de versões para que as chaves não sejam expostas.

Como verifico se um módulo Magento 2 está ativo?

Execute bin/magento module:status para listar os módulos ativos e inativos, ou acrescente o nome do módulo, por exemplo bin/magento module:status Conviro_AiChat. Se aparecer como inativo, execute module:enable, depois setup:upgrade e limpe a cache.

Posso instalar uma extensão Magento sem acesso SSH?

Não com Composer. A extensão da Conviro precisa de acesso SSH ou CLI e de Composer no servidor. Se o seu alojamento não os disponibiliza, peça ao fornecedor de alojamento ou à sua agência que façam a instalação. No plano Enterprise, a equipa da Conviro instala a extensão sem custo adicional.

Próximos passos

Faça a instalação em staging, percorra o assistente de configuração e verifique o cartão Integration Health antes de repetir o processo em produção. Para conhecer tudo o que a extensão faz depois de ligada, leia a nossa apresentação da extensão de chat com IA para Magento 2. Pronto para ligar a loja? Crie a sua conta Conviro.

Partilhar:

Publicado por

Conviro

Partilha insights sobre suporte ao cliente com IA, automação de chatbots e estratégias de crescimento SaaS.

Construa sobre o Conviro

Ligue fluxos conversacionais aos seus sistemas

Consulte os recursos para programadores e os padrões de integração antes de desenhar a implementação.

Artigos relacionados

Mais publicações