CONVIRO
Engineering

Cómo instalar una extensión de Magento 2 con Composer: guía paso a paso

Guía práctica para instalar una extensión de Magento 2 con Composer: repositorios privados, auth.json, setup:upgrade, pasos en modo producción, actualizaciones, desinstalación y…

Conviro
19 de noviembre de 20267 min de lectura
Cómo instalar una extensión de Magento 2 con Composer: guía paso a paso
En este artículo

Para instalar una extensión de Magento 2 con Composer, añades el repositorio del proveedor (más las credenciales si es privado), ejecutas composer require, activas el módulo, ejecutas bin/magento setup:upgrade, compilas y despliegas el contenido estático si la tienda está en modo producción y vacías la caché. Son pocos comandos, pero el orden y el modo de despliegue importan.

Esta guía recorre la secuencia completa con la extensión gratuita Conviro for Magento como ejemplo práctico, y después explica cómo actualizar, cómo desinstalar y cómo resolver los errores con los que es más probable que te encuentres.

Puntos clave

  • Ejecuta todos los comandos desde la raíz de Magento como propietario del sistema de archivos, después de hacer una copia de seguridad y primero en staging.
  • En modo desarrollador basta con setup:upgrade y vaciar la caché; en modo producción también hay que compilar y desplegar el contenido estático.
  • Desinstala en orden inverso: primero limpia la integración y después desactiva el módulo, elimina el paquete y ejecuta setup:upgrade.

Antes de empezar: requisitos previos

Comprueba esto antes de tocar producción:

  • Acceso SSH y Composer en el servidor. Una instalación con Composer no se puede hacer desde el panel de administración.
  • Una copia de seguridad reciente del código y la base de datos y, a ser posible, una copia de staging para hacer pruebas.
  • El usuario correcto. Ejecuta los comandos como propietario del sistema de archivos, no como root, o crearás problemas de permisos.
  • Tu modo de despliegue. Compruébalo con bin/magento deploy:mode:show.
  • Una ventana de mantenimiento para producción: bin/magento maintenance:enable antes y bin/magento maintenance:disable después.

En el caso concreto de la extensión de Conviro, también necesitas Magento Open Source 2.4.4 o posterior con PHP 7.4 o 8.1–8.4, una URL de tienda con HTTPS, el cron de Magento en funcionamiento y HTTPS saliente hacia api.conviro.io. La extensión (versión 1.4.1 en el momento de escribir esto) se ha probado en instalación en:

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

Adobe Commerce se basa en el mismo framework, pero aún no se ha probado; Hyvä Checkout tampoco se ha probado, y las tiendas en 2.4.0–2.4.3 se quedan en la extensión 1.3.5.

Cómo instalar una extensión de Magento 2 con Composer, paso a paso

Paso 1: añade el repositorio de Composer y las credenciales

Las extensiones privadas se sirven desde el propio repositorio de Composer del proveedor. Desde la raíz de Magento:

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

El primer comando añade el repositorio a composer.json. El segundo guarda las credenciales en auth.json, junto a él. En el caso de Conviro, el usuario es api y la contraseña es una clave de API de Developers → API Keys en el panel de Conviro. Tienes más información sobre la API de Conviro en la página para desarrolladores.

No subas auth.json al control de versiones. Tus claves de repo.magento.com suelen estar en el mismo archivo.

Paso 2: ejecuta composer require y setup:upgrade

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

Estos tres comandos son la base de cualquier instalación de un módulo de Magento 2:

  1. composer require descarga el paquete en vendor/ y lo registra en composer.json y composer.lock. Haz commit de los dos archivos para que todos los entornos instalen la misma versión.
  2. module:enable registra el módulo en app/etc/config.php.
  3. setup:upgrade aplica a la base de datos los parches de esquema y de datos del módulo y actualiza el registro de módulos.

Paso 3: compila, despliega y vacía la caché

En modo producción, el código generado y los archivos estáticos no se crean bajo demanda, así que ejecuta:

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

En modo desarrollador, omite los dos. En cualquiera de los dos modos, termina con:

bin/magento cache:flush

Después, comprueba que el módulo está activo y sal del modo mantenimiento:

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

Paso 4: conecta la extensión en el admin

La mayoría de las extensiones necesitan configuración tras la instalación. En el caso de Conviro, abre Stores › Settings › Conviro Setup. Un asistente de 7 pasos ejecuta una comprobación del entorno; después haces clic en Connect to Conviro, apruebas la tienda en el panel de Conviro y vuelves a Magento. No se copia ninguna clave de API ni ningún token en Magento.

El asistente crea una integración de Magento con privilegios mínimos (OAuth 1.0a), te deja elegir las store views, qué sincronizar y qué acciones de IA se permiten, y lo verifica todo con un evento de prueba. Después, la tarjeta Integration Health en Stores › Configuration › Conviro › AI Chat comprueba conexión, autenticación, webhooks, catálogo, pedidos, cron, versión y entorno, con instrucciones para solucionar los fallos. La página de instalación y la documentación de instalación cubren cada paso. Para conectar necesitas un plan de Conviro con acceso a la API, Pro o superior (consulta los precios).

Cómo actualizar y desinstalar un módulo de Magento 2

Actualizar

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

Como antes, compila y despliega solo en modo producción. El admin de Magento muestra un aviso con el comando exacto cuando sale una nueva versión, y se conservan tu configuración, la clave de API y la integración.

Desinstalar

El orden importa: la desconexión se hace en el asistente de configuración, que desaparece en cuanto se elimina el módulo.

  1. Desconecta la tienda en el asistente de configuración de Conviro.
  2. Desactiva el módulo: bin/magento module:disable Conviro_AiChat
  3. Elimina el paquete: composer remove conviro/module-aichat
  4. Ejecuta bin/magento setup:upgrade.

En modo producción, vuelve a compilar, a desplegar el contenido estático y a vaciar la caché como de costumbre. Conviro elimina los datos de la tienda 30 días después de la desconexión, o de inmediato si así lo eliges. La documentación de desinstalación enumera todos los pasos.

Errores habituales y cómo solucionarlos

Síntoma Causa probable Solución
"Allowed memory size exhausted" con Composer Límite de memoria de PHP Ejecuta COMPOSER_MEMORY_LIMIT=-1 composer require ...
La compilación se queda sin memoria Límite de memoria de la CLI Ejecuta php -d memory_limit=2G bin/magento setup:di:compile
Error 401 o petición de credenciales del repositorio Clave o usuario incorrectos Vuelve a ejecutar el comando http-basic; el usuario es api
"Permission denied" en generated/, var/ o pub/static/ Comandos ejecutados como root o con el usuario equivocado Corrige la propiedad de los archivos y vuelve a ejecutarlos como propietario del sistema de archivos
"Please upgrade your database" No se ha ejecutado setup:upgrade Ejecuta bin/magento setup:upgrade
Los datos dejan de sincronizarse y la tarjeta de estado señala el cron El cron no se está ejecutando Ejecuta bin/magento cron:install y revisa crontab -l

El cron importa más de lo que parece. Conviro escribe los eventos de checkout, registro y guardado de productos en una cola local que el cron de Magento entrega en segundo plano. Además, la extensión está diseñada para que las páginas de la tienda no llamen a Conviro desde PHP y los pedidos se sigan procesando aunque Conviro no esté disponible. Prueba todo el flujo primero en staging; nuestra checklist para probar chatbots con IA te ayuda después de la instalación.

Preguntas frecuentes

¿Hay que ejecutar setup:di:compile en modo desarrollador?

No. El modo desarrollador genera el código bajo demanda, así que después de instalar un módulo basta con setup:upgrade y cache:flush. En modo producción, ejecuta también setup:di:compile y setup:static-content:deploy; si no, la tienda y el admin pueden fallar porque faltan el código generado y los archivos estáticos.

¿Dónde guarda Composer las credenciales de un repositorio privado?

composer config http-basic.<host> <user> <password> las escribe en auth.json, en la raíz del proyecto, junto a composer.json. Añade --global para guardarlas en el directorio home de Composer de tu usuario. En cualquier caso, mantén auth.json fuera del control de versiones para que no se filtren las claves.

¿Cómo compruebo si un módulo de Magento 2 está activado?

Ejecuta bin/magento module:status para ver la lista de módulos activados y desactivados, o añade el nombre del módulo, por ejemplo bin/magento module:status Conviro_AiChat. Si aparece como desactivado, ejecuta module:enable y después setup:upgrade y vacía la caché.

¿Se puede instalar una extensión de Magento sin acceso SSH?

Con Composer, no. La extensión de Conviro necesita acceso SSH o CLI y Composer en el servidor. Si tu hosting no los ofrece, pide a tu proveedor de hosting o a tu agencia que hagan la instalación. En el plan Enterprise, el equipo de Conviro instala la extensión sin coste adicional.

Próximos pasos

Haz la instalación en staging, recorre el asistente de configuración y revisa la tarjeta Integration Health antes de repetirlo en producción. Para ver todo lo que hace la extensión una vez conectada, lee nuestra presentación de la extensión de chat con IA para Magento 2. ¿Todo listo para conectar? Crea tu cuenta de Conviro.

Compartir:

Publicado por

Conviro

Comparte conocimientos sobre soporte al cliente con IA, automatización de chatbots y estrategias de crecimiento SaaS.

Desarrolla sobre Conviro

Conecta los flujos conversacionales con tu stack

Revisa los recursos para desarrolladores y los patrones de integración antes de diseñar la implementación.

Artículos relacionados

Más publicaciones