Skip to end of metadataGo to start of metadata

Creating Run/Debug configurations in PhpStorm Sometimes it is useful to create and store some specific configuration so you can run it over and over. I will not describe the whole Run/Debug configurations topic here but only one Docker-specific aspect: you need to teach your PhpStorm to run PHP interpreter inside your container. An IDE in your machine (I use PHPStorm) An issue you need to debug (d’oh!) SSH to the remote server and install Xdebug sudo apt-get install php5-xdebug (Debian based servers) Configure Xdebug. The Xdebug configuration goes in the php.ini file (or in a specific.conf file inside your conf.d folder, it depends on the server’s OS).

Redirection Notice

PHPSTORM + XDEBUG (2/3) + WSL2 + DOCKER. Small example project to show how to configure xdebug (2 or 3) with WSL2 and Docker. This solution works only if you use PhpStorm on WSL2 with X server! WSL2 change Linux IP every reboot time, so you should, add global variable (WSLIP) in your Linux system.

Docker is an open platform for building, shipping and running distributed applications. It gives programmers, development teams and operations engineers the common toolbox they need to take advantage of the distributed and networked nature of modern applications.

Shutdown shortcut for mac. This tutorial describes Docker support in PhpStorm, which includes debugging PHP web applications (running in the Docker container), inspecting, managing containers and viewing running processes.You can also search through logs, start and stop containers, and perform basic container management.

• Prerequisites
• PhpStorm & Docker Integration Configuration
• Working with Docker in PhpStorm

Docker installation

First of all, you'll need to install Docker and related tools so that you can take advantage of the Docker integration in PhpStorm. Please refer to the Docker documentation to get more information about the installation process:

• Installing Docker engine on Windows;
• Installing Docker engine on Mac OS X;
• Installing Docker engine on Linux (Ubuntu, other distributions-related instructions are available as well);
• You can also install Docker on various cloud platforms (e.g. read tutorials on installing Docker on Amazon EC2, Google Cloud Platform, and Microsoft Azure).

Docker plugin is bundled in PhpStorm since 2016.3.

Prerequisites for Mac for PhpStorm 2016.3 and below.

1. Use the standard MacOSX terminal to execute asocat TCP-LISTEN:2375,reuseaddr,fork,bind=localhost UNIX-CONNECT:/var/run/docker.sockcommand to allow older versions of PhpStorm to connect to Docker;

   1. install socat as described at http://macappstore.org/socat/
   2. run socat TCP-LISTEN:2375,reuseaddr,fork,bind=localhost UNIX-CONNECT:/var/run/docker.sock
   3. enter tcp://localhost:2375 as an API URL in IDE
   4. (note: you may use any other port instead of 2375)

   
   Note: Since PhpStorm 2017.1 you can connect via Unix socket directly.
   

Configuring PhpStorm to work with Docker

1. Open Settings / Preferences | Build, Execution, Deployment | Docker and create Docker configuration with a + button.
   

2. You should provide the configuration name (Docker in our case), API URL (tcp://localhost:2375for Windows and for Mac OS X if using PhpStorm older than 2017.1, unix:///var/run/docker.sock for Mac OS X and Linux).
   

3. Apply the configuration and close the Settings / Preferences dialog.
4. Create a new Docker DeploymentRun/Debug Configuration invoking the dialog from the Run | Edit configurations.. menu:
   Then, create a Docker Deployment configuration with a + button:
   

5. Provide all the necessary parameters on the Deployment tab. In our case we've provided Run/Debug Configuration Name (Start Docker in our case), selected the server (Docker), selected the Deployment method to be Dockerfile, provided Image tag (mysite) and Container name (Docker_Xdebug):
   

6. Provide all the necessary parameters and configurations on the Container tab. At this point we are interested in exposing port 80 of the container to be available from our local machine, so we should configure a port binding for that (Container port: 80, Protocol: tcp, Host IP: empty, Host port: 8080):
   In addition, we can configure links, volume bindings, environment variables, and much more.

7. Apply the Run/Debug Configuration and close the dialog.

At this step it's important to note that that there are many ways to create/configure Docker containers and VM images, and we'd recommend to always refer to the Docker documentation on the official web site.

For the purposes of this tutorial we're using Dockerfile and Apache configuration file. We've also created an index.php file with phpinfo(); to be deployed to the Docker container. We're making some significant configuration in those Dockerfile and Apache configuration file, so you're recommended to have a look at them. You can download entire project used in this demo or separate config files (apache-config.conf, Dockerfile) which then need to be placed in the project root folder.

Running the Docker from PhpStorm

As all the tools are installed, and the integration is configured, the recently created Start Docker Run/Debug Configuration can be launched:

The Application Servers tool window will be opened updating you on the provisioning status and current state of all your Docker containers:

As soon as the process is completed, and our Docker_Xdebug container status turns green, we can check how it works in the browser. You should be able to open it by the URL http://localhost:8080/. If you can't see the index.php execution results in the browser (containing phpinfo(); in our case), please check that you have specified the correct port bindings on the previous steps.

In our example, everything is running fine on the port we've expected the web app to be:

Managing Docker containers and other Docker-related actions in PhpStorm

From the Application Servers tool window, it’s easy to inspect containers and view running processes. You can also search through logs, start and stop containers, and perform basic container management like creating and deleting containers. Each deployment in Docker is assigned a unique container ID - these are initially temporary containers, although they can be committed and saved for further distribution. On the Docker Hub registry, there are many such images available for you to try.

Images in Docker are read-only - once committed, any changes to a container’s state will become part of a new image. When you have a stable build on one instance of Docker (on your development machine, staging server, or a cloud), reproducing the exact same build is as simple as (1) committing the Docker container, (2) pushing it to a registry (public or private), then (3) pulling the same image to another instance of Docker, running - wherever.

Debugging the PHP web application running in the Docker container

Assuming that you already run the Docker container now (and everything worked well on the previous steps), you should now able to open your PHP web application in the browser by http://host:port URL (http://localhost:8080/ in our case). The major difficulty in getting Xdebug (or Zend Debugger) working with PhpStorm and Docker integration is the correct configuration of the Docker container.

Download apple app for mac. In our case we're using a Dockerfile (we've already shown this config earlier and provided links to download it) to configure the container, including Xdebug-specific parameters, such as:

In the example above we're modifying /etc/php/7.0/apache2/php.ini providing a path to Xdebug extension, and some other Xdebug parameters (remote_enable and remote_host). Please note that xdebug.remote_host value should be replaced with your local machine IP address which is visible from the Docker container (where PhpStorm is running, 192.168.2.117 in our case).

Configuration for Zend Debugger is similar, please see a full tutorial on installing Xdebug and installing Zend Debugger (there's much more information on required parameters and options).

Don't forget to re-run Start Docker Run/Debug Configuration so that all the changes are applied.

As soon as all the configs are in place, the debugging process can be triggered following this tutorial from step 2 (start Listening for PHP Debug Connections, set a breakpoint in the source code, start a debug session in the browser, reload the current page, debug) to get the debugger up and running in a few moments:

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.

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.

Docker Xdebug Phpstorm Linux

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:

Gamepad for mac os. 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.

Docker Phpstorm Xdebug

• 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.

Docker Xdebug Phpstorm Ubuntu

Thank you and good debugging ;)