Xdebug Phpstorm Ubuntu

 admin



This post was cross posted on Dev.to

Docker has changed dramatically the way we develop applications. Thanks to it, it is really easy for everyone to run a complex application with a single command, without having to worry about the inner details like dependencies. These advantages are even greater when working on a team or enterprise context. I still remember being like the first 3 days when I joined my current company, configuring the project and all the related libraries and tools. Docker make it such much easier, faster and consistent.

PHPSTORM XDEBUG ubuntu NGINX php7.2-fpm. GitHub Gist: instantly share code, notes, and snippets. Since the use of PHPStorm IDE, Xdebug has been used for debugging, which is very efficient. I didn’t find a Xdebug configuration tutorial suitable for my development environment on the Internet, so I wrote a blog about the specific configuration, hoping to help you. Enter one of the following commands in the Ubuntu on Windows console: xon- To turn on Xdebug; xoff- To turn off Xdebug; SSH Configuration Copying your host Windows SSH keys to the development environment. The following will copy to your host Windows.ssh folder to the Ubuntu on Windows.ssh folder.

But everything comes with a price. There is an extra complexity of maintaining all the Docker stuff. Also some things that were very easy in a normal development environment running locally, like debugging your application from your IDE, now requires some extra configuration. And in case of getting Xdebug to work, its not an easy task. I couldn't find a single guide that have all the steps from start to finish. Thats why I decided to write this article. It will guide you to step by step through the process of installing and configuring Xdebug and PHPStorm with a Dockerized Symfony 4 application.

Pre-requisites

  • This was tested on an Ubuntu 18.04 machine with PHPStorm 2018.1.4 and latest versions of Docker and Docker Compose. Some things might work a little different in other Operating Systems.
  • I assume you have a basic Knowledge of Docker, PHP and XDebug.
  • You can clone this repository as base to follow this gude as it contains a basic Symfony Flex application with all the Docker stuff explained in this article included.

Step 1 - Dockerize the application

Of course, to be able to use Xdebug you must install it on your Docker container.The way to do this, will depend of your base image. I always use alpine based images. I wont enter in detail about how to Dockerize a Symfony application. You can follow along with the Dockerfile included in the demo repository.

Here is the relevant excerpt of the Dockerfile that installs Xdebug:

I dont want have to have a separate Dockerfile for development and production, so I have defined a build argument that will tell whether we want to install Xdebug or not.

Then, on my Docker-compose file I have the following definition for my application:

See for the full docker-compose file.

Nothing really fancy about this. The important bit is the 'env_file' instruction which tells Compose to load environment variables from a '.env' file, which is the standard way for Symfony 4 applications.

We will use that file to add some required environment variables for Xdebug. If you prefer in you can also add directly to the docker-compose file using the 'environment' section.

Environment Variables

We will define the following environment variables:

  • PHP_IDE_CONFIG - This variable defines the server configuration associated with the application. More on this later.
  • XDEBUG_CONFIG - This variable allows to define some Xdebug configurations. The 'remote host' is the private ip of your host machine (the one your PHPStorm is running). The 'remote_port' is the port that PHPStorm will be listening for incoming Xdebug connections. These two settings allow PHPStorm and Xdebug to communicate. It wont work without this.

We will add them to our '.env' file like this:

And thats it in terms of code.

Next lets dig into PHPStorm configurations.

PHPStorm configurations

The first thing you should do is to check your Debug settings. In PHPStorm, go to File -> Settings -> Languages and Frameworks -> PHP > Debug.

Make sure you have the some port that you have configured previously in 'XDEBUG_CONFIG' environment variable:

Next, we need to configure a server. This is how PHPStorm will map the file paths in your local system to the ones in your container.

Go to File -> Settings -> Languages and Frameworks -> PHP -> Servers

Give a name to your server. It should match the value you have defined in your 'PHP_IDE_CONFIG' environment variable. We will call it 'symfony-demo'.

The 'host' and 'port' is how will access your application. In my case is localhost:8888.

And then the 'Path mappings'.

In the 'Project files' section you have to map the root path of your application to the path inside the container. In my case its '/var/www/app'.

Click 'Apply' to save your configurations.

The last part is to configure the remote debugger of your project.

On the top right, click on 'edit configurations':

Click in the green 'plus' sign at the top left and select 'PHP Remote Debug' from the list.

Now configure it like this:

Make sure you associate it with the previously created 'server' definition. Use 'PHPSTORM' as idekey.

Your IDE should be now correctly configured. Lets test.

Testing

  • Open 'src/Controllers/HelloController.php' and place a breakpoint in the 'hello' method.

  • Start your Docker container with docker-compose up

  • Then click on 'Start Listening for PHP Debug connections' icon on top right corner of PHPStorm.

  • Open http://localhost:8888?XDEBUG_SESSION_START=PHPSTORM

If everything went well you should see the execution stop at your breakpoint.

And thats it. You should now have a fully configured development environment with Docker and Xdebug integrated with PHPStorm IDE.

If you have any issues or questions feel free to comment bellow or in the GitHub Repository.

Thank you and good debugging ;)

How the Vagrant box is configured

To be able to step through code using the IDE of our choice, we need to install Xdebug onto our Vagrant Box.

Good instructions here: http://ubuntuforums.org/showthread.php?t=525257

Updates to the Provisioning Script:

Install php5-dev php-pear using apt-get, install xdebug using pecl, creating a properly owned folder in /var/log to store the xdebug log file.

Added to apt-get packages list:

Also added:

Needed to add the following to the php.ini to configure it for xdebug:

Configure Xdebug Phpstorm

How to configure your IDE

Your IDE needs to listen for connections on port 9000.

Your IDE needs to know the host IP as well as the path the files reside in on the server.

Your IDE (or you, via a url) need to start and stop xdebug.

Configuring PHPStorm

Create Project

First, create a new project. If you’re using SVN, configure PhpStorm to use SVN and check out the project into a new folder.

Add Remote Server

File -> Settings

Under Project Settings [project-name] on the left, browse to PHP -> Servers

Xdebug

Click the green +

Name: 192.168.50.4

Host: 192.168.50.4

Port: 80

Debugger: Xdebug

Check “Use path mappings (select if the server is remote or symlinks are used)”

Under File/Directory on the left, Browse to Project Files -> checkoutdirwwwproject-name

Next to the www directory, on the right under Absolute path on the server, enter: /data/www (or wherever your files are stored on the vagrant box)

Click OK

Add Debug Config

Under the Run dropdown menu, click Edit Configurations…

Click PHP Web Application, then click the green +

Name: vagrant

Server: 192.168.50.4 should be in the dropdown

Start URL: /

Browser: Chrome

Start Listening for Debug Connections

There’s a telephone icon in the icon bar, with a very small green bug and a red circle with a line through it.
Hovering over it, it will say Start Listen PHP Debug Connections
Clicking that will start the listener.

OR

Click Run -> Start Listen PHP Debug Connections

Start Debugger

Make sure vagrant is selected in the drop-down next to the green play arrow icon in the header.

Click the green bug icon in the header (hover text is Debug ‘vagrant’ Shift+F9)

OR

Click Run -> Debug vagrant

A new browser window will open with a url something like: “http://192.168.50.4/?XDEBUG_SESSION_START=15172”

If you have a breakpoint defined, the browser will appear to ‘hang’ or ‘spin’ or ‘load’ forever. It’s waiting for the IDE to give it the go signal. Press F9 OR click Run -> Resume Program to finish loading the page.

Debugging / Stepping through the program execution

First off, you need to have a breakpoint set, or you will not stop program execution, and so will not have the opportunity to utilize the debugger.

Set a breakpoint by clicking in the left margin right next to the code to put a red dot there.

Now click a link on the application in the browser, and the server will execute all the code up to the red dot, and stop, waiting for a command.

Pressing F7 for Step into will make sure to execute every single line of code

Pressing F8 for Step over will go to the next line but basically never leave the current file: it will not dive down into function calls. This is useful for skipping stuff you know you don’t care about.

Stopping the Debugger

Ctrl+F2,

Run -> Stop, or

Clicking the red square in the debug window all stop the PhpStorm debugger.

Phpstorm Xdebug Vagrant

However, if you click a link on the browser it will start right back up again. It needs to send a header to the xdebug server and… it doesn’t appear to. We can send that ourselves.

Xdebug Phpstorm Ubuntu Update

1) Click Stop

Xdebug Phpstorm Ubuntu Nginx

2) Follow this link: http://192.168.50.4/?XDEBUG_SESSION_STOP