Debuguear con LANDO + WSL2 + PHPSTORM

Bueno pues quiero comenzar una serie de posts dedicados a la configuración y uso de Lando en un entorno Windows 10 u 11 con WSL2 instalado. En esta serie pretenderé plasmar todas las situaciones y dificultades que me iré encontrando en este proceso de on-boarding con este nuevo ‘stack’ técnico para mi.

¿Qué es Lando?

Según definen en la propia documentación de Lando:

Es una herramienta DevOps y un entorno de desarrollo local multiplataforma, de código abierto y gratuito construido en Docker tecnología de contenedores y desarrollada por Tandem. Diseñado para trabajar con la mayoría de lenguajes, frameworks y servicios. Lando proporciona una manera fácil para que los desarrolladores de todos los niveles de habilidad especifiquen requisitos simples o complejos para sus proyectos y luego se pongan a trabajar rápidamente en ellos.

Sobre todo es una herramienta que nos facilita sobremanera el poder montar nuestros entornos de desarrollo con Docker y no morir en el intento. Agilizando el proceso en el cual podemos empezar a trabajar, digamos que sería una especie de ‘plug&play’ ejecutar un comando y empezar a trabajar. Al estilo que lo puede realizar mi queridísimo DDEV.

¿WSL2?

Con Windows 10, Microsoft decidió abrazar Linux, implementando WSL o ‘Windows Subsystem Linux’ dentro de su sistema operativo. Pudiendo así ejecutar un Linux real sin necesidad de instalar ninguna máquina virtual.

Las razones de este movimiento lo desconozco, pero quiero pensar que lo hizo porque puede, porque es Microsoft. Y porque sus desarrolladores estarían hartos de tener que instalar máquinas virtuales en sus equipos corporativos para poder usa Linux. XD Pero bueno dejemos esto para otro día y centrémonos en lo importante.

Al turrón

Pues lo que necesitamos para comenzar, lo primero obviamente, es un equipo con Windows 10 u 11. Y dentro de nuestro equipo tener instalado.

• WSL2
• Lando
• Docker Desktop

El propósito de este post no es explicar la instalación de este stack, si no creo que se alargaría en demasía el mismo. Por lo que dejo un enlace del blog drupaladicto el cual nos lo explica paso a paso y con videos de cómo es el proceso.

Creación del proyecto

Para comenzar nuestro proyecto utilizaremos el sistema de archivos creado por el subsistema de Linux en lugar del de Windows. Siguiendo los consejos tanto de Docker como de Windows, para, según se comenta, optimizar el rendimiento.

Para ello crearemos nuestra carpeta e iniciaremos un proyecto con lando dentro de ella. En el cual especificaremos que queremos crear un proyecto de Drupal 9 en nuestro directorio actual, especificando nuestro webroot como web.

$ mkdir lando-debug
$ cd lando-debug
$ lando init
$ ls -la

Una vez iniciado si listamos los archivos en nuestro actual directorio encontramos con que lando ha creado un archivo de configuración llamado .lando.yml con la siguiente estructura:

name: lando-debug
recipe: drupal9
config:
  webroot: web

Como podemos ver se ha creado un proyecto con nombre lando-debug para drupal 9 indicando que la carpeta donde tenemos nuestro index es ‘web’.

Una vez iniciado nuestro proyecto con lando, vamos a descargarnos nuestro Drupal con composer. Por desgracia con lando este proceso, al contario que con ddev, implica unos pasos de más que explicaré a continuación. Primero crearemos el proyecto con el comando lando composer. No lo podemos descargar en el actual directorio ya que la carpeta actual ya tiene nuestro primer archivo de configuración .lando.yml, por lo que tenemos que especificar una carpeta donde descargarlo. Después moveremos todo el contenido del proyecto creado a nuestra carpeta raiz, para luego instalar drush e iniciar el site. Bien pues nuestro proceso quedaría así:

$ lando composer create-project drupal/recommended-project drupal
$ mv drupal/* .
$ mv drupal/.* .
$ rm -rf drupal
$ lando rebuild -y
$ lando composer require drush/drush
$ lando info
$ lando drush si demo_umami --site-name="Debug demo" --account-name=admin --account-pass=admin --account-mail=mail@example.com

Como podemos observar hemos dejado el comando ‘drush si’ para poder interactuar con él y especificar los datos de acceso a la base de datos proporcionados por el comando ‘lando info’. También podríamos haberlos especificado dentro del comando drush.

Bien pues ya tenemos nuestro Drupal corriendo con Lando en el dominio https://lando-debug.lndo.site/

Configuraciones en Windows

Bueno pues ya tenemos la primera parte de nuestro proceso, ahora tenemos que continuar con la configuración en windows.

Lo primero de todo, Windows por defecto no muestra el sistema de archivos montado por nuestro subsistema Linux en el explorador de archivos, por lo que hay que montarlo. Para ello abriremos nuestro explorador de archivos y clicamos con el botón derecho sobre ‘Este equipo’ -> ‘Conectar a unidad de red’

Esto nos abrirá un cuadro de diálogo para configurar nuestra unidad de Linux. Aquí tendremos que especificar la ubicación de nuestra carpeta de red \\wsl$\Nombre Instalación Linux. En mi caso mi ‘linux’ se llama ‘Ubuntu’ por lo que quedaría \\wsl$\Ubuntu. Si no recuerdas el nombre de tu instalación de Linux, puedes abrir un terminal en Windows y ejecutar el comando wsl -l -v.

Pulsamos sobre finalizar y ahora debería aparecer nuestro sistema de archivos de Linux en nuestro explorador de archivos de Windows. Y ya podemos abrir nuestro proyecto con nuestro IDE favorito.

Conectar Docker Desktop con WSL2

Si hemos seguido las instrucciones para la instalación de drupaladicto, ya tendríamos que tener conectado nuestro docker dektop con nuestro WSL2. Por si acaso podemos seguir las instrucciones que se detallan en Docker Desktop WSL 2 backend, para configurarlo.

1. Instalar el ejecutable de Docker Desktop.

2. Iniciar Docker Desktop desde el menú Inicio de Windows.

3. En el menú de Docker, seleccionar Configuración > General .

   

4. Seleccionar la casilla de verificación Usar motor basado en WSL 2 .

   Si ha instalado Docker Desktop en un sistema que admita WSL 2, esta opción estará habilitada de forma predeterminada.

5. Hacer clic en Aplicar y reiniciar .

6. Asegurarse de que la distribución se ejecuta en modo WSL 2. WSL puede ejecutar distribuciones en modo v1 o v2.

   Para verificar el modo WSL, ejecutar:

   wsl.exe -l -v

   Para actualizar su distribución de Linux existente a v2, ejecutar:

   wsl.exe --set-version (distro name) 2

   Para configurar v2 como la versión predeterminada para futuras instalaciones, ejecutar:

   wsl.exe --set-default-version 2

7. Cuando se reinicie Docker Desktop, vaya a Configuración > Recursos > Integración WSL y seleccionar las distribuciones en las que le gustaría habilitar la integración Docker-WSL.

   

8. Hacer clic en Aplicar y reiniciar .

Ping a nuestra máquina host

Este paso debe ser nuestra obsesión. Ya que si nuestro sistema linux no es capaz de conectarse a nuestro host, nunca llegaremos a debuguear. Para ello comprobamos primero si podemos realizar ping a nuestro host desde nuestro terminal linux, para ello podemos ejecutar lo siguiente:

$cat /etc/resolv.conf
# This file was automatically generated by WSL. To stop automatic generation of this file, add the following entry to /etc/wsl.conf:
# [network]
# generateResolvConf = false
nameserver 172.25.0.1
$ping 172.25.0.1

Si obtenemos una respuesta favorable en la cual se han podido transmitir los paquetes, ¡Enhorabuena! puedes continuar con el próximo punto. Si no es así continua conmigo en este tortuoso camino.

Si no conecta es porque el firewall de Windows está bloqueando la conexión. Para desbloquear tendremos que abrir el firewal de windows y clickar en ‘Configuración avanzada’. Una vez pulsado nos abre un cuadro de diálogo en el que podemos ver las reglas de entrada del firewal. Seleccionamos todas las reglas llamadas ‘Supervision de máquina virtual’ y las habilitamos desde el menú de la derecha.

En este punto volvemos sobre nuestro terminal linux y volvemos a realizar ping sobre nuestro host, debería de darnos ¡éxito!. Si no es así comprobad que no hay otro firewall o antivirus bloqueándolo. En mi caso estaba realizando las pruebas sobre un equipo que hacía tiempo que no lo cogía, y se me olvidó que tenía otro firewall activo que andaba bloqueando el servicio.

Configuraciones en Lando

Nuestro camino tortuoso ya está viendo el fin. Ahora solo nos falta activar nuestro xdebug en Lando y configurar el remote_host de nuestro XDebug. Para ello nos dirigimos a nuestro archivo .lando.yml de la raíz de nuestro proyecto y añadimos las siguiente lineas:

name: lando-debug
recipe: drupal9
config:
  webroot: web
services:
  appserver:
    xdebug: true
    overrides:
      environment:
        XDEBUG_CONFIG: "mode=debug client_host=host.docker.internal client_port=9000"

Como vemos hemos activado XDebug por defecto, por lo que cada vez que iniciemos Lando este siempre estará activo. Si deseamos poder activar y desactivar XDebug a placer deberíamos configurar nuestro archivo .lando.yml con la herramienta ‘tooling’ que nos proporciona Lando para crear comandos. Dependiendo del servidor que escojamos, los comandos introducidos en el tooling pueden ser unos u otros. Aquí podemos encontrar la configuración a realizar para poder activar y desactivar XDebug a través de comandos.

También podemos observar que está configurado para que el puerto de escucha de XDebug sea el 9000. En mi caso lo configuré así ya que tenía el puerto 9003 ocupado, este es el puerto activado por defecto en XDebug 3.

Debemos de tener en cuenta que Lando por defecto instala para drupal 9 una versión de PHP 7.4 con XDebug 3. Por lo que si nuestra configuración de Lando ejecuta una versión anterior de PHP y de XDebug, los nombres de las variables de configuración cambiarían a los de esa versión. Por ejemplo a una versión 2.1 de XDebug sería remote_host y remote_enable correspondientes a las variables client_host y mode de la versión 3.

Una vez modificado nuestro archivo .lando.yml ejecutamos el comando lando rebuild -y.

¡A debuguear!

¡Ya estamos listos para empezar a debuguear! Tan solo tendremos que incluir unos puntos de ruptura en nuestro código. Podemos ponerlo en nuestro index.php si queremos simplemente ver si funciona y activar la escucha de xdebug en nuestro PHPStorm.

Ahora recargamos la página de nuestro site y automáticamente debe saltarnos en nuestro PHPStorm la configuración para mapear las carpetas del servidor con nuestro proyecto. En este caso el index.php del servidor con el de nuestro proyecto

Felicidades ya hemos empezado a debuguear!

Bonus

Gracias a los comentarios de Jheyner David Ibagon, voy a incluir la configuración que he creado para VScode para conectar este IDE con XDebug.

Con la misma receta de lando creada en este post, arrancamos el proyecto y configuramos VScode para debuguear. Para ello debemos tener instalado en el IDE la extensión Php Debug. Una vez instalada si pulsamos sobre el botón de debugueo que aparece en la izquierda del editor, nos aparecerá para crear un archivo launch.json con las configuraciones. Pulsamos para crear el archivo.

Dentro de este archivo incluimos la siguiente configuración:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for XDebug",
      "type": "php",
      "request": "launch",
      "port": 9000,
      "pathMappings": {
        "/app": "${workspaceRoot}"
      },
      "log": true,
      "stopOnEntry": true,
      "hostname": "0.0.0.0"
    }
  ]
}

A tener en cuenta en la configuración:

• port: El numero de puerto de escucha de XDebug. En nuestro caso especificamos el puerto de escucha 9000 en la configuración de XDebug en lando.
• pathMappings: Este es el mapeo para conectar el servidor con nuestro proyecto en local. Lando suele desplegar en la carpeta /app del contendor del proyecto. Para comprobarlo se puede ejecutar lando ssh, el cual se conecta al contenedor por defecto ‘appserver’, y luego ejecutar pwd. Este comando nos muestra la ruta de carpeta actual. Si listasemos los archivos de esta ruta veremos que coinciden con el arból de carpeta de nuestro proyecto.
• stopOnEntry: Con esta configuración especificamos, si deseamos que la ejecución del debug pare en la primera línea que se ejecuta del proyecto. Está especificado a ‘true’ ya que no hemos especificado ningún punto de ruptura y deseamos que entre en la primera línea a ejcutar.
• hostname: Aquí especificamos el host de entrada de la aplicación, en este caso ‘0.0.0.0’

Ahora si lanzamos el debug en VScode y recargamos nuestra página el debug se parará en la primera linea a ejecutar del index.php:

Conclusión

Este es un pequeño tutorial de las particularidades que me he llegado a encontrar para conectar XDebug con mi instalación de WSL2 y Lando. En principio no he me encontrado con más, pero si alguien encuentra alguna más que no dude en comentarlo.

¡Hasta la próxima!