DEV Community


Posted on

PHPStorm + Xdebug + Alpine on Docker

First, I wanted to thank @aschmelyun for his very informative series on Docker + Laravel for development. If you haven't checked out his posts on this topic, you absolutely should!

You can also check out his git repository for this development strategy.

I've customized and integrated this method into my repos for local development and it's made starting up new projects a breeze.

BUT, I recently worked through getting PHPStorm and Xdebug working with this docker setup, and it was a bit tricky. Here's what I did to make it work:

Add Xdebug to the Webserver Dockerfile

Since this image is using alpine, it's a little different than a lot of the approaches you might find if you just google "Install Xdebug PHP." At the end of your app Dockerfile you need to manually install xdebug using pecl, so add this command at the bottom.

RUN apk add --no-cache $PHPIZE_DEPS \
    && pecl install xdebug-2.7.0 \
    && docker-php-ext-enable xdebug
Enter fullscreen mode Exit fullscreen mode

This will download and enable xdebug (change the version to the one you want to use as needed, ensuring that it's compatible with the version of PHP you're using in your dockerfile).

Modify the nginx config to expose the ports

In your docker-compose.yml modify the nginx section to include the port for xdebug:

    image: nginx:stable-alpine
    container_name: ${APP_NAME}-webserver
      - "80:80"
      # Add the port for Xdebug here
      - "9001:9001"
      - ./:/var/www/html
      # Path to custom nginx config (yours may be different)
      - ./docker-nginx.conf:/etc/nginx/conf.d/default.conf
      - app
      - db
      - laravel
Enter fullscreen mode Exit fullscreen mode

Add xdebug configuration to PHP's configuration

You'll also need to create a new .ini file to include the xdebug configuration in your PHP config.

Create a new .ini file in your project folder, wherever you want to put it. I called mine docker-xdebug.ini and placed it in the root of my project. If you wanted to organize it into a different folder to keep things organized, you're welcome to do so. Just make sure to define the path correctly when you modify your docker-compose.yml in the following steps:

# File: docker-xdebug.ini
#To activate XDEBUG remote host must be your local IP address.
#This is not Docker machine ip address, but the ones running Phpstorm
Enter fullscreen mode Exit fullscreen mode

On Windows host.docker.internal will automatically resolve to your local IP address. You might need a different workaround on Linux or Mac. You can read more about this from Jetbrains.

Now, make sure to include the new .ini file in your PHP configuration in the docker-compose.yml

      context: .
      dockerfile: Dockerfile
    container_name: ${APP_NAME}-app
    restart: unless-stopped
    tty: true
      - "9000:9000"
      - ./:/var/www/html
      # Xdebug Config for PHPStorm, check your local path to make sure it exists
      - ./docker-xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
      - laravel
Enter fullscreen mode Exit fullscreen mode

Setting up PHPStorm

At this point you should be able to boot your images using the command line docker-compose command or using PHP storm to build a run configuration. You can follow along with the Jetbrains blog post.

Make sure to modify your Xdebug listening port to 9001 in your Preferences: CTRL+ALT+S Languages & Frameworks | PHP | Debug:

PHPStorm Xdebug make sure to change your port!

In the settings you can also check "Break at first line in PHP scripts" for now just to make sure your connection is working.


If you have your application files available, you can now set a breakpoint in your code and visit http://localhost to trigger the "break on first line of PHP" degug breakpoint. Otherwise, you can create a simple HelloWorld.php file in your public directory and PHPStorm should pick up the breakpoint and display the debugging information in your IDE window.

Make sure you enable listening in PHPStorm to start the debugger:

Listen for Debugging Connections


echo "Hello World!";

Enter fullscreen mode Exit fullscreen mode

Debugging Successful!

Hopefully, this helps someone else get PHPStorm + Docker working together!

Top comments (2)

majstomphorst profile image
Maxim Stomphorst

thx for the tutorial.
I cant get it to work... do you have te compleet code somewhere?
So i can start with your working version and modify it?

sakhrihoussem profile image
Sakhri Houssem

thank you very much