by

Phpstorm And Xdebug



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

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

I'm having problems getting PhpStorm and the internal Xdebug in HHVM playing nicely on a vagrant box, below is my php.ini. Xdebug.enable=1 xdebug.remoteenable=1 xdebug.idekey='PHPSTORM' xdebug. PhpStorm 2020.3 EAP #6: Xdebug 3, Tailwind CSS, Git stage, and More. Roman Pronskiy November 5, 2020. This build introduces support for the upcoming Xdebug 3, Tailwind CSS, improvements for Twig, Git stage support, and the ability to generate multiple files with templates. If you prefer watching to reading, check out the Coming in PhpStorm 2020. 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. Using Xdebug with Docker Compose and PhpStorm. Add Xdebug to your PHP application container. Add following lines to your php Dockerfile: 1. RUN yes pecl install xdebug.

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

Phpstorm And Xdebug

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.

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.

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

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

1. Add Xdebug to your PHP application container

Add following lines to your php Dockerfile:

2. Add necessary environment variables

docker-compose.override.yaml

Phpstorm xdebug cli

Here we do following things:

  1. Enable the xdebug extension.
  2. Enable automatic start on every request (see note on this below).
  3. Increase default maximal function nesting level, because it is often not enough.
  4. Instruct XDebug to connect back to the IP where web request came from.
  5. Instruct XDebug to connect to host.docker.internal for command line execution or whenever “connect back” is not possible.
  6. Set PHP_IDE_CONFIG env variable to serverName=localhost. This will tell your PhpStorm which server configuration to use. See next step for details.

3. Configure server in PhpStorm

In your PhpStorm Settings go to Languages and Frameworks > PHP > Servers and add a new server:

Phpstorm Xdebug Hangs

  • Name: localhost
  • Host/Port: whatever host and port you use to open your local website, for example: ‘magento.localhost’ and ‘8080’.
  • Debugger: Xdebug
  • Use path mappings: yes

Configure the path mapping according to your source code volume mount in docker-compose.yaml.
I have the following mount: ./magento:/var/www/html, therefore my local ./magento directory is mapped to the /var/www/html path on the server.

Debugging

One important thing you need to do is to start listening for PHP debug connections with a small phone icon in your PhpStorm.

Autostart

Normally you would need a browser extension, which adds debug session start flag to your requests when you need it.
However I found it convenient to enable autostart and only control the XDebug via PhpStorm.
The case is that when XDebug tries to start the debugging session but the remote host is not listening, the XDebug does not continue.
So when I don’t need to debug, I just switch listening off. I believe this still adds a small overhead in time for all requests, but for me it is unnoticeable.

If you don’t like this approach, just disable the autostart and start the session your own way (see: Activate debugger).

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.

Phpstorm Xdebug Cli

For this you need to create a new PHP CLI interpreter configuration:

  • in your PhpStorm Settings go to Languages and Frameworks > PHP and click the ‘…’ button near the “CLI Interpreter” field.
  • in new window add a new interpreter “From Docker, Vagrant, VM, Remote…”
  • choose “Docker Compose” radiobutton,
  • select or create new Server (use Unix socket to connect to Docker daemon)
  • choose Docker Compose Configuration files; in my case I choose two in following order:
    • docker-compose.yaml
    • docker-compose.override.yaml
  • select your PHP app service
  • choose “Connect to existing container” instead of starting a new one.

Phpstorm Xdebug Cli

This should be enough, save everything and create your Run/Debug configuration using this CLI interpreter.