Debugging Laravel with Xdebug3 and Docker Compose

3 min readSep 14, 2021

Since the release of Xdebug3, setting up debugging for code inside Docker is kinda hard, However, in version 3, it’s become easier. In this tutorial, I want to share my experience configure the Xdebug3 since my current company I work for, is using Laravel with Docker & Docker Compose.

What will you need:

Development environment with Docker Installed.
One of Xdebug supported clients, I am using PHPStorm in this tutorial.
Some Laravel source code. You can get mine from here.
Some knowledge of Laravel Framework.

The Stacks:

https://anastasionico.uk/blog/containerize-your-laravel-application-docker

In this 3-tiered application, every request will come to Nginx, then will be forwarded to Laravel, and MySQL is communicating directly with Laravel App.

It’s time to initialize the new Laravel App, or if you already have an existing app, you can continue.

Docker Configuration

Usually, I create a docker folder on the root directory, to contain the configuration for the container, it’s something like this

docker
├── nginx
│   └── default.conf
└── php
    ├── Dockerfile
    └── conf.d
        ├── error_reporting.ini
        └── xdebug.ini3 directories, 4 files

My nginxconfiguration is something like this

For the php side, I usually use this Dockerfile

It’s a pretty simple Dockerfile , you can add the additional extensions you need.

And for the conf.d configuration folder of the PHP, I set it like this

Docker Compose Configuration

In my webserver container, I add the volumes mapping to

nginx configuration that we created earlier.
from the root directory on the host, into the webserver folder

In my php container, I add the

environment PHP_IDE_CONFIG , so the Xdebug3 knows where to connect.
extra_hosts , it’s just a helper, for the PHP Xdebug connecting to the host computer.
volumes , I map the 3 locations:
- from the root directory on the host into the PHP folder
- Xdebug configuration
- Additional PHP configuration to show an error.

For the mysql container, it’s pretty straightforward,

I create the volumes , to persist the data if, by accident, you run the docker-compose down command, don’t forget to set volumes on the root of the yml file too.
environment configuration to set the credentials of MySQL.

After this, all the preparations are complete, time to run the
docker-compose up -d command.

Configure Xdebug in your IDE

From Settings › PHP › Debug › Xdebug, I recommend checking the Break at the first line in PHP scripts, to check if the Xdebug is working, after then, you can disable it again.

Click on Start Listening for PHP Debug Connection, at first, the icon is red, and when active, it’s green.

And it’s time to set the breakpoint, and tried to run the debugger.

Some references that help me:

Some SO references also:

The codingmachine also have a PHP docker image, that easier to set up the Xdebug, you can check it here

Debugging Laravel with Xdebug3 and Docker Compose

Written by Ignasius