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!

• Docker for Laravel Development
• Better local development for Laravel with Docker

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

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:

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

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
zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_autostart=1
;xdebug.remote_handler=dbgp
#To activate XDEBUG remote host must be your local IP address.
#This is not Docker machine ip address, but the ones running Phpstorm
xdebug.remote_host=host.docker.internal
xdebug.remote_port=9001

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

app:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: ${APP_NAME}-app
    restart: unless-stopped
    tty: true
    ports:
      - "9000:9000"
    volumes:
      - ./:/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
    networks:
      - laravel

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:

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

Debugging!

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:

<?php

echo "Hello World!";

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