Xdebug for Local Magento 2 Development

Add Xdebug to your Docker + Magento 2 developer flow

This tutorial is a direct add-on to our previous blog post: Docker for Magento 2 Development. You will need to follow that tut before you are able to use Xdebug in your local Magento 2 development environment.

Docker + Xdebug + Magento 2 = Awesome

Ok, here’s an analogy for you. Xdebug is to the PHP developer as Robin is to Batman. In this Magento 2 developer tut, we teach you how to add Xdebug to your development flow. In my opinion, this is the most important part of your development environment. Without it, the process of writing code is slower and visibility into the way the code works is limited. In fact, I can easily say that Xdebug is largely responsible for my career success and general Magento skill level. Why? Xdebug allows me to walk through every step of code execution which makes it much easier to understand the Magento architecture. In short, I absolutely love Xdebug.

Before we get started, I should clarify that the scope of this tutorial involves activating and preparing Xdebug to run. However, we do not provide instructions on how to configure your specific IDE to accept Xdebug connections. When I make the follow up video to accompany this written tutorial, I will also walk you through configuring PHPStorm to work with Xdebug and do a full demo.

What is Xdebug?

Xdebug is a low-level PHP debugger that can provide a wealth of real-time information during code execution. It can be used from the command line during script execution and from the browser during page load. With Xdebug, a developer can pause code execution, evaluate different scenarios, see real-time data stored inside of variables, and much, much more.

Install Xdebug In Your Virtual Machine

Adding Xdebug to your local Magento 2 development environment is going to be a piece of cake. It’s actually already included in the Docker image for the web service. We only need to configure it and then create a network loopback. I’ll explain that down the page a little.

Setup Steps:

Add Configuration To docker-compose.yml

In this first step, we simply add some environment variables to our docker-compose.yml file. A short explanation/clarification here. You might notice that my php.xdebug.idekey setting is set to PHPSTORM. You do not need PHPStorm for this to work, although, I strongly recommend it. You can make the IDE key setting anything you would like and just make sure that the software of your choice is aware of your IDE key. Additionally, port 9000 is the default port for Xdebug. However, you can change it to use any port you’d like. Again, just make sure your IDE is listening on that port.

  1. Copy the highlighted lines below into your docker-compose.yml file.
    version: '3'
            image: webdevops/php-apache-dev:ubuntu-16.04
            container_name: web
            restart: always
            user: application
              - WEB_ALIAS_DOMAIN=local.domain.com
              - WEB_DOCUMENT_ROOT=/app/pub
              - PHP_DATE_TIMEZONE=EST
              - PHP_DISPLAY_ERRORS=1
              - PHP_MEMORY_LIMIT=2048M
              - PHP_MAX_EXECUTION_TIME=300
              - PHP_POST_MAX_SIZE=500M
              - PHP_UPLOAD_MAX_FILESIZE=1024M
              - PHP_DEBUGGER=xdebug
              - XDEBUG_REMOTE_HOST=
              - XDEBUG_REMOTE_PORT=9000
              - php.xdebug.remote_enable=1
              - php.xdebug.idekey=PHPSTORM
              - "/path/to/magento:/app:cached"
              - "80:80"
              - "443:443"
              - "32823:22"
              - mysql
            image: mariadb:10
            container_name: mysql
            restart: always
              - "3306:3306"
              - MYSQL_ROOT_PASSWORD=root
              - MYSQL_DATABASE=magento
              - db-data:/var/lib/mysql
            container_name: phpmyadmin
            restart: always
            image: phpmyadmin/phpmyadmin:latest
              - MYSQL_ROOT_PASSWORD=root
              - PMA_USER=root
              - PMA_PASSWORD=root
              - "8080:80"
              - mysql:db
              - mysql
            external: false
  2. After adding your configuration values to the docker-compose.yml file, you’ll need to tear it all down and spin it back up.
    docker-compose down && docker-compose up -d --build
  3. These two steps are all it takes to get properly configured and activated.

Create a Network Loopback

What does that even mean? When Xdebug runs, it will try to make a connection to either a specified remote host or connect back to the original IP address that the request came from. Since we are running our VM on our local computer, the original page request comes from localhost or As expected, it attempts to connect back to but fails. This is because, in the eyes of Xdebug, refers back to the server and not your local computer. So basically the request never makes it out of the Docker container.

The solution to this problem is to create a network loopback that will route a specific IP address back to your local machine. The IP address that we’ve chosen and that you see in the docker-compose.yml file is It will be routed back to your local host machine listening on port 9000.

  1. Create the network loopback by running this command on your local machine.
    sudo ifconfig lo0 alias
  2. Optional, but recommended. Store the loopback creation command as an alias on your bash profile so that you can run it simply by typing init-loopback into your terminal. The reason we do this is because when you restart or shut down your computer, the loopback connection goes away. In this case, you’ll need to run the command to create the loopback again.
    echo 'alias init-loopback="sudo ifconfig lo0 alias"' >> ~/.bash_profile
  3. Done! Now you are truly ready to run Xdebug listening on remote host and port 9000.

For demos on how you can use X-debug, watch our YouTube videos. However, you can skip the first video in the playlist. The instructions in this tutorial negate the need for any manual installation.

1 Reply to “Xdebug for Local Magento 2 Development”

  1. This is a great idea and thanks for sharing “Magento 2 + Docker”.

    Whilst I have “Magento 2 + Docker” working… the script is proving a little tricky on macOS Catralina 10.15

    For those that see this error… bash: ./magento2-install: /bin/bash: bad interpreter: Operation not permitted

    You need to add “bash” to System Preference > Security & Privacy > “Full Disk Access”

    In Finder… Menu: Go > Go To Folder… Type “/bin”
    Drag “bash” icon into the open and unlocked Security & Privacy > Full Disk Access window

    Thanks for your blog posts, very helpful!

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.