Hacer debug en Magento remoto con X-Debug

por David Abad
Magento-Debug-Remoto

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:

PHPStorm: Remote debug config

  • 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:

PHP Storm: X-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:

Esta extensión nos permitirá indicar, desde el propio navegador, cuando queremos comenzar con el proceso de debug:
 

Xdebug helper

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.

Déjanos tu email para recibir contenido interesante en tu bandeja de entrada, cada mes.

¡No hacemos spam!

Otros artículos