DocumentaciónCommerceGuía de Commerce en la infraestructura en la nube

Configurar Xdebug

Last update: Mon Jul 15 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Creado para:

  • Administrador
  • Desarrollador

Xdebug es una extensión para depurar su PHP. Aunque puede utilizar un IDE de su elección, a continuación se explica cómo configurar Xdebug y PhpStorm para depurar en el entorno local.

NOTE
Puede configurar Xdebug para que se ejecute en el entorno de Cloud Docker para la depuración local sin cambiar la configuración del proyecto de Adobe Commerce en la infraestructura en la nube. Consulte Configurar Xdebug para Docker.

Para habilitar Xdebug, debe configurar un archivo en el repositorio Git, configurar el IDE y configurar el reenvío de puertos. Puede establecer algunas opciones en el archivo magento.app.yaml. Después de editar, inserte los cambios de Git en todos los entornos de Starter y de integración de Pro para habilitar Xdebug. Xdebug ya está disponible en los entornos de ensayo y producción de Pro.

Una vez configurados, puede depurar los comandos de CLI, las solicitudes web y el código. Recuerde que todos los entornos de infraestructura en la nube son de solo lectura. Clone el código en el entorno de desarrollo local para realizar la depuración. Para los entornos de ensayo y producción Pro, consulte instrucciones adicionales para Xdebug.

Requisitos

Para ejecutar y utilizar Xdebug, necesita la URL SSH para el entorno. Puede encontrar la información a través de Cloud Console o de su Cloud Onboarding UI.

Configurar Xdebug

Para configurar Xdebug, siga estos pasos:

Introducción a una rama

Para agregar Xdebug, el Adobe recomienda trabajar en una rama de desarrollo.

Habilitar Xdebug en su entorno

Puede habilitar Xdebug directamente en todos los entornos de Starter y de integración de Pro. Este paso de configuración no es necesario para los entornos de ensayo y producción de Pro. Consulte Depurar para ensayo y producción profesional.

Para habilitar Xdebug en su proyecto, agregue xdebug a la sección runtime:extensions del archivo .magento.app.yaml.

Para habilitar Xdebug:

  1. En el terminal local, abra el archivo .magento.app.yaml en un editor de texto.

  2. En la sección runtime, en extensions, agregue xdebug. Por ejemplo:

    code language-yaml 
    runtime:
    extensions:
        - redis
        - xsl
        - newrelic
        - sodium
        - xdebug

  3. Guarde los cambios en el archivo .magento.app.yaml y salga del editor de texto.

  4. Agregue, confirme e inserte los cambios para volver a implementar el entorno.

    code language-bash 
    git add -A
    code language-bash 
    git commit -m "Add xdebug"
    code language-bash 
    git push origin <environment-ID>

Cuando se implementa en entornos Starter y entornos de integración Pro, Xdebug ya está disponible. Continúe configurando el IDE. Para PhpStorm, consulte Configurar PhpStorm.

Configurar PhpStorm

El IDE PhpStorm debe estar configurado para funcionar correctamente con Xdebug.

Para configurar PhpStorm para que funcione con Xdebug:

  1. En su proyecto PhpStorm, abra el panel Configuración.

    • macOS—Seleccione PhpStorm > Preferencias.
    • Windows/Linux—Seleccione Archivo > Configuración.

  2. En el panel Configuración, expanda y busque la sección Idiomas y marcos > PHP > Servidores.

  3. Haga clic en + para agregar una configuración de servidor. El nombre del proyecto aparece en gris en la parte superior.

  4. [Opcional] Configure las siguientes opciones para la nueva configuración del servidor. Consulte No se ha configurado ningún servidor de depuración en la documentación de PHPStorm.

    • Nombre: escriba el mismo nombre que el nombre de host. Este valor debe coincidir con el valor de la variable PHP_IDE_CONFIG en Depurar comandos CLI para usar CLI para la depuración.
    • Host: escriba el nombre de host.
    • Puerto—Escriba 443.
    • Debugger: seleccione Xdebug.

  5. Seleccionar Usar asignaciones de ruta. En el panel Archivo/Directorio, se muestra la raíz del proyecto para serverName.

  6. En la columna Ruta absoluta en el servidor, haga clic en el icono Editar y agregue una configuración basada en el entorno.

    • La ruta remota es /app para todos los entornos de Starter y de Pro Integration.

    • Para entornos de ensayo y producción Pro:

      • Producción: /app/<project_code>/
      • Ensayo: /app/<project_code>_stg/

  7. Cambie el puerto Xdebug a 9000 en el panel Idiomas y marcos de trabajo > PHP > Depurar > Xdebug > Puerto de depuración.

  8. Haga clic en Aplicar.

Configuración del reenvío de puertos

Asigne la conexión XDEBUG del servidor al sistema local. Para realizar cualquier tipo de depuración, debe reenviar el puerto 9000 desde el servidor de Adobe Commerce en la nube a su equipo local. Consulte una de las siguientes secciones:

Reenvío de puertos en Mac o UNIX®

Para configurar el reenvío de puertos en un entorno Mac o UNIX®:

  1. Abra un terminal.

  2. Utilice SSH para establecer la conexión.

    code language-bash 
    ssh -R 9000:localhost:9000 <ssh url>

    Utilice la opción -v (detallada) para que cuando un socket esté conectado al puerto que se está reenviando, se muestre en el terminal.

    Si se muestra el error "no se puede conectar" o "no se pudo escuchar el puerto en remoto", podría haber otra sesión SSH activa en el servidor que está ocupando el puerto 9000. Si esa conexión no se está utilizando, puede terminarla.

Para solucionar problemas de conexión:

  1. Utilice SSH para iniciar sesión en el entorno de integración, ensayo o producción remoto.

  2. Ver una lista de sesiones SSH: who

  3. Ver sesiones SSH existentes por usuario. ¡Tenga cuidado de no afectar a un usuario que no sea usted!

    • integración: los nombres de usuario son similares a dd2q5ct7mhgus
    • Ensayo: los nombres de usuario son similares a dd2q5ct7mhgus_stg
    • Producción: los nombres de usuario son similares a dd2q5ct7mhgus

  4. Para una sesión de usuario anterior a la suya, busque el valor de pseudoterminal (PTS), como pts/0.

  5. Elimine el ID de proceso (PID) correspondiente al valor PTS.

    code language-bash 
    ps aux | grep ssh
kill <PID>

    Respuesta de ejemplo:

    code language-terminal 
    dd2q5ct7mhgus        5504  0.0  0.0  82612  3664 ?      S    18:45   0:00 sshd: dd2q5ct7mhgus@pts/0

    Para finalizar la conexión, introduzca un comando kill con el ID de proceso (PID).

    code language-bash 
    kill 3664

Reenvío de puertos en Windows

Para configurar el reenvío de puertos (túnel SSH) en Windows, debe configurar la aplicación de terminal de Windows. En este ejemplo se explica cómo crear un túnel SSH con Putty. Puede utilizar otras aplicaciones como Cygwin. Para obtener más información sobre otras aplicaciones, consulte la documentación del proveedor proporcionada con esas aplicaciones.

Para configurar un túnel SSH en Windows usando Putty:

  1. Si aún no lo ha hecho, descargue Putty.

  2. Iniciar Masilla.

  3. En el panel Categoría, haga clic en Sesión.

  4. Introduzca la siguiente información:

    • Campo Nombre de host (o dirección IP): Escriba la URL SSH para su servidor en la nube
    • Campo de puerto: escriba 22

    Configurar Masilla

  5. En el panel Categoría, haga clic en Conexión > SSH > Túneles.

  6. Introduzca la siguiente información:

    • Campo de puerto Source: escriba 9000
    • Campo Destino: escriba 127.0.0.1:9000
    • Haga clic en Remoto

  7. Haga clic en Agregar.

    Crear un túnel SSH en Putty

  8. En el panel Categoría, haga clic en Sesión.

  9. En el campo Sesiones guardadas, escriba un nombre para este túnel SSH.

  10. Haga clic en Guardar.

    Guarde su túnel SSH

  11. Para probar el túnel SSH, haz clic en Cargar y luego haz clic en Abrir.

    Si aparece el error "no se puede conectar", compruebe lo siguiente:

    • Todos los ajustes de Masilla son correctos
    • Está ejecutando Putty en el equipo en el que se encuentran las claves SSH de su Adobe Commerce privado en la infraestructura de la nube

Acceso SSH a entornos Xdebug

Para iniciar la depuración, realizar la configuración y mucho más, necesita los comandos SSH para acceder a los entornos. Puede obtener esta información a través de Cloud Console y la hoja de cálculo del proyecto.

Para entornos Starter y entornos de integración Pro, puede utilizar el siguiente comando CLI magento-cloud para SSH en esos entornos:

magento-cloud environment:ssh --pipe -e <environment-ID>

Para usar Xdebug, SSH debe conectarse al entorno de la siguiente manera:

ssh -R <xdebug listen port>:<host>:<xdebug listen port> <SSH-URL>

Por ejemplo,

ssh -R 9000:localhost:9000 pwga8A0bhuk7o-mybranch@ssh.us.magentosite.cloud

Depurar para ensayo y producción profesionales

NOTE
En entornos de ensayo y producción Pro, Xdebug siempre está disponible, ya que estos entornos tienen una configuración especial para Xdebug. Todas las solicitudes web normales se dirigen a un proceso PHP dedicado que no tiene Xdebug. Por lo tanto, estas solicitudes se procesan normalmente y no están sujetas a la degradación del rendimiento cuando se carga Xdebug. Cuando se envía una solicitud web que tiene la clave Xdebug, se enruta a un proceso PHP independiente que tiene Xdebug cargado.

Para usar Xdebug específicamente en el entorno de ensayo y producción de plan Pro, cree un túnel SSH y una sesión web independientes a los que solo tenga acceso. Este uso difiere del acceso habitual, ya que solo proporciona acceso a usted y no a todos los usuarios.

Necesita lo siguiente:

  • Comandos SSH para acceder a los entornos. Puede obtener esta información a través de Cloud Console o de su Cloud Onboarding UI.

  • El valor xdebug_key establecido al configurar los entornos Staging y Pro.

    xdebug_key se puede encontrar utilizando SSH para iniciar sesión en el nodo principal y ejecutar:

    code language-bash 
    cat /etc/platform/*/nginx.conf | grep xdebug.sock | head -n1

Para configurar un túnel SSH en un entorno de ensayo o producción:

  1. Abra un terminal.

  2. Limpie todas las sesiones SSH de cada nodo web del clúster.

    code language-bash 
    ssh USERNAME@CLUSTER.ent.magento.cloud 'rm /run/platform/USERNAME/xdebug.sock'

  3. Configure el túnel SSH para Xdebug para cada nodo web del clúster.

    code language-bash 
    ssh -R /run/platform/USERNAME/xdebug.sock:localhost:9000 -N USERNAME@CLUSTER.ent.magento.cloud

Para iniciar la depuración con la URL del entorno:

  1. Habilite la depuración remota; visite el sitio en el explorador y agregue lo siguiente a la dirección URL donde KEY es el valor de xdebug_key.

    code language-http 
    ?XDEBUG_SESSION_START=KEY

    Este paso establece la cookie que envía las solicitudes del explorador al déclencheur Xdebug.

  2. Complete la depuración con Xdebug.

  3. Cuando esté listo para finalizar la sesión, utilice el siguiente comando para quitar la cookie y finalizar la depuración a través del explorador donde KEY es el valor de xdebug_key.

    code language-http 
    ?XDEBUG_SESSION_STOP=KEY
    note note
    NOTE
    No se admiten las XDEBUG_SESSION_START pasadas por POST solicitudes.

Depurar comandos CLI

En esta sección se explican los comandos de CLI de depuración.

Para depurar comandos CLI:

  1. SSH en el servidor que desea depurar mediante comandos CLI.

  2. Cree las siguientes variables de entorno:

    code language-bash 
    export XDEBUG_CONFIG='PHPSTORM'
    code language-bash 
    export PHP_IDE_CONFIG="serverName=<name of the server that is configured in PHPSTORM>"

    Estas variables se eliminan cuando finaliza la sesión SSH.

  3. Comenzar depuración

    En entornos Starter y entornos de integración Pro, ejecute el comando CLI para depurar.
    Puede añadir opciones de tiempo de ejecución, por ejemplo:

    code language-bash 
    php -d xdebug.profiler_enable=On -d xdebug.max_nesting_level=9999 bin/magento cache:clean

    En entornos de ensayo y producción Pro, debe especificar la ruta al archivo de configuración PHP Xdebug al depurar comandos CLI, por ejemplo:

    code language-bash 
    php -c /etc/platform/USERNAME/php.xdebug.ini bin/magento cache:clean

Depuración de solicitudes web

Los siguientes pasos le ayudan a depurar solicitudes web.

  1. En el menú Extensión, haga clic en Depurar para habilitar.

  2. Haga clic con el botón derecho, seleccione el menú de opciones y establezca la clave IDE en PHPSTORM.

  3. Instale el cliente Xdebug en el explorador. Configúrelo y actívelo.

Ejemplo: configuración de Chrome

En esta sección se explica cómo usar Xdebug en Chrome con la extensión Xdebug Helper. Para obtener información acerca de las herramientas de Xdebug para otros exploradores, consulte la documentación del explorador.

Para usar el Asistente de Xdebug con Chrome:

  1. Cree un túnel SSH al servidor en la nube.

  2. Instale la extensión Xdebug Helper desde el almacén de Chrome.

  3. Habilite la extensión en Chrome como se muestra en la siguiente figura.

    Habilitar la extensión Xdebug en Chrome

  4. En Chrome, haga clic con el botón derecho en el icono verde de ayuda en la barra de herramientas de Chrome.

  5. En el menú emergente, haga clic en Opciones.

  6. En la lista Clave IDE, haga clic en PhpStorm.

  7. Haga clic en Guardar.

    Opciones de ayuda de Xdebug

  8. Abra el proyecto PhpStorm.

  9. En la barra de navegación superior, haga clic en el icono Comenzar a escuchar.

    Si no se muestra la barra de navegación, haga clic en Ver > Barra de navegación.

  10. En el panel de navegación de PhpStorm, haga doble clic en el archivo PHP que desea probar.

Depuración del código local

Debido a los entornos de solo lectura, debe extraer el código de la estación de trabajo local desde un entorno o rama Git específica para realizar la depuración.

El método que elija depende de usted. Tiene las siguientes opciones:

  • Compruebe el código de Git y ejecute composer install

    Este método funciona a menos que composer.json haga referencia a paquetes en repositorios privados a los que no tiene acceso. Este método resulta en obtener toda la base de código de Adobe Commerce.

  • Copie los directorios vendor, app, pub, lib y setup

    Este método hace que tenga todo el código que pueda probar. Según el número de recursos estáticos que tenga, podría resultar en una transferencia larga con un gran volumen de archivos.

  • Copiar solo el directorio vendor

    Debido a que la mayor parte del código se encuentra en el directorio vendor, es probable que este método genere buenas pruebas, aunque no se esté probando toda la base de código.

Para comprimir archivos y copiarlos en el equipo local:

  1. Utilice SSH para iniciar sesión en el entorno remoto.

  2. Comprima los archivos.

    code language-bash 
    tar -czf /tmp/<file-name>.tgz <directory list>

    Por ejemplo, para comprimir solo el directorio vendor:

    code language-bash 
    tar -czf /tmp/vendor.tgz vendor

  3. En su entorno local, utilice PhpStorm para comprimir los archivos.

    code language-bash 
    cd <phpstorm project root dir>
    code language-bash 
    rsync <SSH-URL>:/tmp/<file-name>.tgz .
    code language-bash 
    tar xzf <file-name>.tgz
recommendation-more-help
05f2f56e-ac5d-4931-8cdb-764e60e16f26