Laravel Docker Phpstorm Xdebug



  1. Phpstorm Docker Compose
  2. Phpstorm Xdebug Ssh

Created at 2020-10-10Updated at 2020-10-11Category Docker Tag Resource / Docker / PHP / PhpStorm / PhpUnit / Linux

Published parts of the Docker PHP Tutorial. Setting up PHP, PHP-FPM and NGINX for local development on Docker (2018-07-08); Setting up PhpStorm with Xdebug for local development on Docker (2018-08-06); Structuring the Docker setup for PHP Projects (2019-05-20); All code samples are publicly available in my Docker PHP Tutorial repository on github.The branch for this tutorial is part2setting. Laravel Homestead is great, it supports multiple php versions, xDebug, MySQL and allows the user to install any other required software straight into the virtual machine. It is possible to run PHP cli without a docker-compose file, I have found it is easier to set up PhpStorm using this intermediate step. PhpStorm has several preconfigured Docker containers, source: Github - JetBrains / phpstorm-docker-images; Docker hub - PhpStorm; They can be used as follows: Php 7.3 CLI and XDebug 2.7.

I have recently configured my windows 10 laptop with an additional SSD, so I could experiment with Linux. I have already installed Pop!_OS Git, PhpStorm and Docker. I haven’t installed PHP or Composer locally. Next I want to learn how to use this new environment. This is what I have found out so far.

Start with a Project

One of my favorite projects is the Gilded Rose Kata. I can clone that from github as follows:

Create docker-compose.yml

It is possible to run PHP cli without a docker-compose file, I have found it is easier to set up PhpStorm using this intermediate step.

PhpStorm has several preconfigured Docker containers, source:

They can be used as follows:

Php 7.3 CLI and XDebug 2.7

docker-compose.yml

The above will work for Linux, for Windows and MacOS the XDEBUG_CONFIG: will need the changed as follows:

Windows and MacOS

Windows and MacOS replace with XDEBUG_CONFIG:host.docker.internal, which will automatically resolve to the internal address of the host Docker is running on.

MacOS with local Homebrew php-fpm

If you use a local Homebrew php-fpm installation, port 9000 (which is the default debugging port) may become occupied. PhpStorm will remain silent on starting listening for incoming connections. If this is the case, in the Settings | Languages & Frameworks | PHP | Debug, set the Debug port to 9001, and use the following configuration line instead.

Docker

Apache, PHP 7.3, XDebug 2.7 and MySQL

For information this is the LAMP version (based on the phpstorm-workshop).

docker-compose.yml

Install dependencies using composer

To keep things simple the composer Docker container can be used to install the dependencies.

This is the script recommended on the docker hub composer page to avoid filesystem permissions problems

By default, Composer runs as root inside the container. This can lead to permission issues on your host filesystem. You can work around this by running the container with a different user:

On windows change $PWD for the full path to the project (note: forward slash / as separator), remove the line end and run the command as one line:

Alternatively, more complex projects will need specific PHP extensions to be installed, which are not included in the Composer Docker container. The following method could be used to install Composer, inside the container and install the dependencies.

  1. Access bash in the php-cli container: docker-compose run --rm php-cli /bin/bash
  2. Install Composer, by following the download instructions for Linux
  3. Still, inside the container, install dependencies: php composer.phar install
  4. Exit the container exit

Note: In Linux, using the second method Composer will create the vendor folder as root!

The permissions can be changed using chown:

Further information

There is a detailed description about running Docker containers as current host user.

The official documentation on Docker run and docker-compose cli reference.

Configure PhpStorm

Now the project has been cloned from GitHub and the dependencies have been installed. PhpStorm can be setup to use Docker. Thanks to Gary Hockin’s excellent YouTube video Running PHPUnit Tests in PhpStorm with Docker, the setup process can be easily replicated.

Laravel Docker Phpstorm Xdebug

There is a four stage process:

  1. Configure PhpStorm to use Docker
  2. Configure the remote interpreter
  3. Configure PhpUnit
  4. Create Test runner

1. Configure PhpStorm to use Docker

  • Settings (Ctrl + Alt + S)
  • Search for Docker
    • Under Build, Execution, Deployment
  • Click + to add
  • Select Unix socket
    • Confirm connection was successful

2. Configure the default CLI interpreter

  • Settings (Ctrl + Alt + S)
  • Search for CLI interpreter
    • Under Language & Frameworks > PHP
  • Click the ellipse button next to CLI Interpreter
  • Click +
  • Select From Docker, Vagrant…
  • Choose Docker Compose
  • Choose the Service from the drop down list (e.g. php-cli)
  • Select OK
  • Change the name e.g. Docker PHP
  • Apply and OK
  • Check the mapping
    • e.g. for a web project <Project root>→/var/www/html
    • e.g. for an app project <Project root>→/app

3. Configure PhpUnit

  • Settings (Ctrl + Alt + S)
  • Search for Test Frameworks
    • Under Language & Frameworks > PHP
  • Click +
  • Select PhpUnit from remote interpreter
  • Choose the interpreter created above, e.g. Docker PHP
    • Confirm the path mappings, as above <Project root>→/app
    • Input the script path based on the mapping inside the container e.g. /app/vendor/autoload.php
    • Under Test runner, tick Default configuration script, type in the path, in the docker container. e.g. /app/phpunit.xml

4. Create the test runner

  • Click Edit Configuration (next to run test button)
  • Click + to add
  • Select PHPUnit
  • Under Test Runner choose Defined in the configuration file
  • Name - e.g. Docker PHPUnit
  • Click Play to run all the tests!

What about configuring xDebug?

Thanks to this setup, xDebug has been automatically configured! It will use the default PHP Interpreter, which was configured in step 2. A breakpoint can be set in the app or tests can be run with coverage :)

Enjoy the kata!

Edit: Added details on running commands on MacOS and Windows and small tweaks.

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.

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.

Phpstorm Docker Compose

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.

Phpstorm Xdebug Ssh

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':

Phpstorm docker xdebug not working

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 ;)