La detección de errores en proyectos Magento que únicamente se replican en entornos remotos puede ser compleja. Para agilizar el análisis y detección de estos problemas, es posible hacer debug remoto del proyecto utilizando X-Debug a través de un tunel SSH.
Paso 0. Clonar el proyecto
En caso de no tener clonado el proyecto en nuestra máquina local, será necesario clonarlo desde el repositorio GIT correspondiente. Si ya tenemos clonado el proyecto, no será necesario volver a realizar esta operación.
Paso 1. Activar X-Debug en el entorno remoto
El primer paso para la activación de X-Debug es acceder al servidor remoto por SSH e instalar la extensión:
sudo apt-get install php-xdebug
Una vez instalada, deberá modificarse el fichero .ini correspondiente para definir su configuración:
xdebug.remote_enable=1 xdebug.remote_connect_back=0 xdebug.remote_host=localhost xdebug.remote_port=9000
xdebug.idekey=PHPSTORM
En caso de no saber donde se encuentran los ficheros .ini de configuración de PHP en nuestro sistema, podemos utilizar el comando: php –ini.
Paso 2. Configurar tunel SSH
Para poder hacer debug en el servidor remoto como si se tratase de nuestro entorno local, tendremos que abrir un tunel SSH que mapee el tráfico del puerto 9000 del servidor remoto a nuestro puerto 9000 local:
ssh -R 9000:localhost:9000 <usuario>@<host>
Asegúrate de no cerrar el terminal desde el que hemos lanzado este tunel, ya que al cerrarlo se perderá la conexión.
Paso 3. Configurar debugger en IDE
Como siguiente paso, tendremos que configurar nuestro IDE. En este caso, he utilizado PHP Storm para definir la siguiente configuración:
Desde Settings > PHP > Debug > Xdebug > Debug Port, debemos definir el puerto 9000.
Desde Settings > PHP > Servers, configuraremos un nuevo servidor:
- Name: localhost
- Host: localhost
- Port: 80
- Debugger: Xdebug
En la sección de path mappings debemos definir la ruta absoluta del servidor remoto en el directorio raíz de nuestro proyecto.
Por otro lado, en el apartado Run > Edit configurations, debemos añadir una configuración del tipo PHP Remote Debug:
- Name: localhost
- Server: localhost
- IDE key: PHPSTORM
Paso 4. Instalar la extensión Xdebug helper en tu navegador
Para el proceso de debug, necesitaremos instalar la extensión Xdebug helper en nuestro navegador:
Es importante acceder a las opciones de la extensión y seleccionar el IDE Key correspondiente (PHPSTORM).
Paso 5. Comienza a debuggear
Una vez realizados los pasos anteriores, ya podemos comenzar a debuggear el proyecto remoto.
Asegúrate de los siguientes puntos:
- El tunel SSH permanece abierto.
- El modo debug se encuentra activado en la extensión de nuestro navegador.
- El modo debug se encuentra activado en PHP Storm (icono del teléfono).
[EXTRA] Magento Cloud
En el caso de proyectos alojados en Magento Cloud, el proceso es el mismo que se ha explicado. Sin embargo, para la activación de X-Debug en el servidor será necesario modificar y subir el fichero .magento.app.yaml, incluyendo la extensión “xdebug”:
# Enable extensions required by Magento 2
runtime:
extensions:
- xsl
- newrelic
- sodium
- xdebug
Por otro lado, la IDE KEY a utilizar durante el proceso de debug no será “PHPSTORM”. Para consultar la clave a utilizar, debemos lanzar el siguiente comando en el entorno correspondiente:
cat /etc/platform/*/nginx.conf | grep xdebug.sock | head -n1
Por último, lanzaremos el túnel SSH (Se recomienda eliminar el fichero xdebug.sock remoto antes de abrir el túnel. Consulta la ruta exacta del fichero antes de lanzar las siguientes lineas):
ssh <usuario>@<host> 'rm /run/platform/<id proyecto>/xdebug.sock' ssh -R /run/platform/<id proyecto>/xdebug.sock:localhost:9000 -N <usuario>@<host>
En caso de entornos cloud formados por varios servidores (p.ej. los entornos production/staging de Magento Cloud Pro), se deberá lanzar un tunel por cada nodo de forma simultanea.