Debuguear en VS Code con Laravel y Sail en MacOS

En Laravel podemos encontrar varios ambientes de trabajo: Homestead, Laravel Valet pero hoy en día es muy conveniente utilizar Laravel Sail pues permite utilizar las ventajas de trabajar con Docker. Entre ellas, se puede utilizar en cualquier sistema operativo.

Crear proyecto con Laravel Sail

Para crear un proyecto con Laravel Sail solo debe ejecutar el siguiente comando.

curl -s https://laravel.build/debug-laravel-sail | bash

Este comando ejecuta una serie de instrucciones. Debe esperar a que termine.

El siguiente paso es entrar al directorio que se creo con la instalación de Laravel.

cd ./debug-laravel-sail

Levantar el proyecto con Laravel Sail y publicar las versiones de PHP

Dentro del proyecto ejecute el comando siguiente dentro de la consola.

./vendor/bin/sail up -d

Publique la configuración los ficheros de configuración de Laravel Sail.

./vendor/bin/sail artisan sail:publish

Nota: Si no desea escribir el camino completo(./vendor/bin/sail) para ejecutar cada comando de Laravel puede ejecutar el comando: alias sail=’[ -f sail ] && sh sail || sh vendor/bin/sail’ y despues lo ejecuta así: sail artisan sail:publish

Dentro de su proyecto se va publicar una carpeta con el nombre: docker y dentro verá las versiones que puede configurar de php, Ejemplos: 8.0, 8.1, 8.2.

Nota: La carpeta docker puede agregarla al fichero .gitignore para no subirla al repositorio pues solo es para trabajo local.

Preparar el fichero docker-compose.yml para que docker.

services:
    laravel.test:
        build:
            # Sustituya el valor ./vendor/laravel/sail/runtimes/8.2 por ./docker/8.2
            context: ./docker/8.2
            dockerfile: Dockerfile
            args:
                WWWGROUP: '${WWWGROUP}'
                # Adicionar estas 2 lineas
                XDEBUG: '${APP_DEBUG:-false}'
                XDEBUG_PORT: '${SAIL_XDEBUG_PORT:-9003}'
ports:
    - '${APP_PORT:-80}:80'
# Adicionar esta linea para exponer el puerto 9003
expose:
    - "9003"
# Adicionar XDEBUG_CONFIG, PHP_XDEBUG_ENABLED y XDEBUG_MODE con los valores
environment:
    WWWUSER: '${WWWUSER}'
    LARAVEL_SAIL: 1
    XDEBUG_CONFIG: ${SAIL_XDEBUG_CONFIG:-client_host=172.120.19.9}
    PHP_XDEBUG_ENABLED: 1
    XDEBUG_MODE: '${SAIL_XDEBUG_MODE:-off}'

# Buscar la configuración de networks
networks:
    sail:
        driver: bridge
        # Adicionar la siguientes 4 lineas
        ipam:
            driver: default
            config:
                - subnet: 172.120.19.0/24

Nota: Para saber la subnet ejecute el comando: ipconfig getifaddr en0 y obtendrá el ip: 172.120.19.40, en mi caso sustituí el 40 por el 0 y me quedo así: 172.120.19.0/24.

Dentro del fichero: docker-composer.yml busque el valor del key: context, en nuestro caso el valor que tiene es: ./docker/8.2 por lo que debe ir a la carpeta docker que publicamos anteriormente y dentro de la carpeta 8.2, modificar el fichero: php.ini. Adicionale el siguiente código:

[XDebug]
zend_extension = xdebug.so
xdebug.start_with_request = yes
xdebug.mode = debug
xdebug.idekey = VSC
xdebug.discover_client_host = true
xdebug.client_host = host.docker.internal
xdebug.client_port = 9003

Luego agregue la siguientes lineas al fichero: .env.

SAIL_XDEBUG_MODE=develop,debug
SAIL_XDEBUG_CONFIG="client_host=localhost"

Por último reconstruya con el comando de Laravel Sail de nuevo el proyecto para que cargue las nuevas configuraciones.

./vendor/bin/sail up --build -d

Configure VSCode para poder utilizarlo con Laravel Sail.

En la opción de las extensiones de VSCode instale las extensiones PHP Debug, Docker y Remote Explorer.

Aquí estan los links de las extensiones respectivamente:

PHP Debug - Visual Studio Marketplace

Docker - Visual Studio Marketplace

Dev Containers - Visual Studio Marketplace

Puede leer la siguientes seciones para profundizar mas en el tema en el sitio de Laravel:

Laravel - The PHP Framework For Web Artisans

Laravel - The PHP Framework For Web Artisans

Luego debe configurar el VSCode para debuguear, para lo cual debe crear el fichero de configuración como se muestra en la siguiente imagen:

Se crear una carpeta .vscode con el fichero launch.json y dentro del mismo remplace la configuración que se genera automaticamente por la siguiente:

{
  "version": "0.2.0",
  "configurations": [
      {
          "name": "Listen for Xdebug",
          "type": "php",
          "request": "launch",
          "port": 9003,
          "pathMappings": {
              "/var/www/html": "${workspaceFolder}"
          }
      }
  ]
}

Luego ejecute el mismo boton con el que le salio la configuración y verá que VSCode cambia para modo debug.

Ponga un punto de ruptura en cualquier fichero de su aplicacion en Laravel y haga una petición utilizando Postman y vera que podra debuguear.

Espero les haya funcionado, cualquier duda escribame y le respondere con gusto.