Debugging Laravel Apps with Laradock and XDebug

Before you begin, I am going to assume that you have a Laravel application in a directory called laravel and a submodule of Laradock within that directory. 

Enabling XDebug

Enabling XDebug is straight froward, simply setting the PHP_FPM_INSTALL_XDEBUG and WORKSPACE_INSTALL_XDEBUG to true in the .env file is the only "server-side" configuration that we need to do. When debugging web application code, XDebug is only required in the PHP-FPM container. Having it in both PHP-FPM and workspace container is purely for consistency.

cd laravel/laradock
sed -i -E 's/^(WORKSPACE|PHP_FPM)(_INSTALL_XDEBUG=)false/\1\2true/g' .env
sed -i '' -E 's/^(WORKSPACE|PHP_FPM)(_INSTALL_XDEBUG=)false/\1\2true/g' .env
docker-compose build --no-cache php-fpm workspace

If there is something that is running on port 9000, the port that XDebug uses to connect to the IDE, it can be changed by updating PHP_FPM_XDEBUG_PORT and WORKSPACE_XDEBUG_PORT. This setting can also be changed within the container. This isn't a permanent solution but something that will get you by without having to wait to rebuild the images.

docker exec -it $(docker ps | grep 'php-fpm' | awk '{print $1}') /bin/bash -c "sed -i -e 's/^\(xdebug.client_port\).*/\1=9003/g' /usr/local/etc/php/conf.d/xdebug.ini"
docker restart $(docker ps | grep 'php-fpm' | awk '{print $1}')

Additional configuration can be placed in the laradock/php-fpm/xdebug.ini and laradock/workspace/xdebug.ini files.

Configuring the IDE

The two main IDEs that I will cover in the configuration section are PHPStorm and VSCode as they are the most popular. Other IDEs such as Eclipse, Netbeans, and others will need the PHP extension/plugin, but the configuration for full blown IDEs will be very similar to PHPStorm. Applications along the lines of VSCode or Atom (now defunct) may differ.  

PHPStorm

Open up Settings, then under PHP -> Debug

• Within the XDebug Section
• Debug Port -- Set to whatever you have in the PHP_FPM_XDEBUG_PORT variable.
• Check Can accept incoming connections
• The rest of the options in that area can be left alone or adjusted as one sees fit.

Next, navigate to PHP -> Servers and create a new server with the following options.

• Name: Laravel
• Host: localhost
• Port: 80 or 443
• Check use path mappings
  • Find the project directory in the File/Directory column. It should be the only one under the Project files node.
  • In the Absolute path on server column, on the same row, enter /var/www.

VSCode

First, install the XDebug plugin. After it's finished installing create or edit the .vscode/launch.json file within the root of the project directory.

{
    "version": "0.2.0",
    "configurations": [
        {
            "log": true,
            "name": "XDebug listening to Laradock",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "pathMappings": {
                "/var/www": "/path/to/laravel/project",
            },
            "ignore": [
                "**/vendor/**/*.php"
            ]
        }
    ]
}