Docker Xdebug Phpstorm

Posted on  by 



July 26, 2018

To follow this tutorial, you must have the Xdebug extension installed on your container. In my example, I will use a Docker image of TheCodingMachine created by David Négrier. If you are starting a project, I recommend you to download one of our images here TheCodingMachine Docker PHP images

Pick the PHP Remote Debug template and click the +on the top left to add a new configuration (don't make the mistake of editing the template). Check 'Filter debug connection by IDE key' and set the IDE key to match the one in your XDebug config (for the above we'd use PHPSTORM). You don't need the ports exposed in Docker, or do anything with the Xdebug proxy. The telnet needs to be done from within your docker container to PhpStorm. The IP address in xdebug.remotehost, needs to be the IP address of your IDE, and not the IP address of your docker container (where HTTP/Apache listens on.

My base docker-compose.yml file looks like this:

Note: the PHP_EXTENSION_XDEBUG environment variable is specific to the thecodingmachine/php. It automatically configures Xdebug for the container.

Ports configuration

Keep in mind that PHPStorm opens port 9000 (by default) so Xdebug can connect to it. Our PHP container has Xdebug installed and Xdebug will try to connect to PHPStorm on port 9000 by default.

Out of the box, everything should be fine...

... except if port 9000 is already taken by another program on your host (your machine running PHPStorm).

Switching port

Port 9000 can be already used. In particular, if you are using PHP-FPM, the default port for PHP-FPM is 9000.This directly conflicts with the XDebug port.

If you want to use another port for Xdebug, follow the instructions below.

I recommend to use port 10000 instead.

Otherwise, just keep the default configuration port.

Registering your container server in PHPStorm

First, click on edit configurations, on the top right of PHPStorm window.

Then, follow the explanation in picture. All numbers are explained below.

(1) Click on add button

(2) Confirm it by clicking on PHP Web Page

(3) Define a name for your project

(4) Click on ... to add a debug server

(5) Once it's done, you are on debug server page. Click on '+' button to create a new one.

(6) Define a server name like docker_[your_project_name]

(7) Add your host on port 80 using Xdebug

(8) Don't forget to click on Use path mappings

(9) We need to add path mapping. Indeed, from the point of view of Xdebug, the PHP application runs in the '/var/www/html' (we are in a container!).But for PHPStorm, my project is in my host machine directory! So we need to map the root of your PHP application to the '/var/www/html' directory, as shown on the image above.

At this point, you should be able to put a breakpoint in your code, start a debugging session and get the application to stop on the breakpoint. Jump to chapter 'Run Xdebug' to see how to use Xdebug.

Xdebug CLI

All applications are not web-based. You might also want to debug a command-line application, from within your container.Let's see how to enable Xdebug for scripts (CLI)

In the docker-compose.yml, just add those environment variables

Remember that we are using our technical director's (David Négrier) images. That's why we can set PHP extensions, PHP .ini configurations into the docker-compose.yml.For more details, please look at this TheCodingMachine Docker PHP images.

(1) Enable the Xdebug extension

(2) If you are using a different Xdebug port, set your custom Xdebug port

(3) Add your Xdebug server name

(4) If you are using the default Xdebug port, please remove remote_port=[your_xdebug_port]. Otherwise, add your custom Xdebug port

Run Xdebug

Web

Place a breakpoint in your code and launch a debug session

A new windows should open and you should access to PHPStorm debug bar.

Scripts (CLI)

Click on Start Listening for PHP Debug connections

The button should appear like this :

Place a breakpoint in your code.

Now, just go into your php-apache container using docker exec -ti [container_id] bash and run your script manually.

Addentum: Installing Docker integration in PHPStorm

There is a very useful PHPStorm extension to quickly and efficiently manage your docker containers.

For example:

Docker phpstorm xdebug nginx
  • see the logs by container
  • have access to bash in a clique
  • quickly see environment variables
  • clear or restart containers

Before starting

Phpstorm Docker Xdebug Not Working

  • You should check that the 'Docker integration' is enabled on your IDE
  • Start the Docker daemon on you machine
  • Move to your favorite Docker project in PHPStorm

Configuring Docker

Now everything should be good, just go to Preferences... > Languages and Frameworks > PHP

(1) Click on ... for openning the remote PHP interpreter

Xdebug Php Docker

(2) Add a new CLI interpreter by clicking on From Docker, Vagrant, VM, Remote...

(3) Click on Docker (remember that you should start Docker daemon)

(4) Add a new server

(5) Select a server name

(6) Choose how to connect on Docker

(7) Make sure the connection is successful

(8) Select your favorite default image

(9) You need to set the path mapping for your code. By default, it's /opt/project in the container, just change it to /var/www/html

Done! Just click on the Docker button on the bottom of PHPStorm window.

About the author

Alexis is an experienced technical project manager who manages several projects including Eco-Emballages (CITEO). Graduate of EPITECH, Alexis is specialized in PHP frameworks (Symfony, Laravel, Mouf) and he masters Docker.

Related articles

Setting up a XDebug debugging environment for PHP / WAMP / Eclipse PDTJuly 8, 2010

Latest articles

Releasing GraphQLite 4: GraphQL in PHP made easyJanuary 6, 2020
Getting started with TDBM 5.1 and SymfonyAugust 6, 2019

Open-source matters

At TheCodingMachine, we are using open-source tools daily to build our projects. And since we and our clients are ripping huge benefits from these open-source products, we also try to 'give back' to the open-source community.

Freelance Developer?

At TheCodingMachine, we are always looking for top freelance developers to work with us on our next state-of-the-art project.
Interested in developing quality projects? We love good work and we pay fairly.

We are hiring!

Living in France? We are actively looking for developers and project leaders in our Paris and Lyon office.

About us

At TheCodingMachine, we strive to develop websites , extranets, intranets and business web applications in PHP and JavaScript for a wide range of clients.
Do not hesitate to contact us!

Best practices

When writing code, we expect it to be of the best possible quality. To enforce this quality, we redacted our own 'best practices' described in a dedicated website.
We are happy to share those with you!

Packanalyst

We are the happy parents of Packanalyst, a free online service that lets you search any possible PHP class or interface referenced on Packagist.
Pretty useful for open-source developer to keep an eye on who is using what class/interface of your packages.

Xdebug is an extension for debugging your PHP code. Magento Cloud Docker provides a separate container to handle Xdebug requests in the Docker environment. Use this container to enable Xdebug and debug PHP code in your Docker environment without affecting your Magento Commerce Cloud project configuration.

The following instructions explain how to configure Xdebug and PhpStorm to debug in your local Docker environment.

If you use Microsoft Windows, take the following steps before continuing:

  1. Open your Docker settings.
  2. Select the Expose daemon on tcp://localhost:2375 without TLS checkbox.
  3. Wait for the settings to apply.

Enable Xdebug

  1. To enable Xdebug for your Docker environment, generate the Docker Compose configuration file in developer mode with the --with-xdebug option and any other required options, for example.

    For Linux systems, you must use the --set-docker-host option to add the host.docker.internal entry to the /etc/hosts file for the fpm_xdebug container.

    This command adds the Xdebug configuration to your docker-compose.yml file.

  2. Follow the steps to launch the Docker environment in Developer mode.

    The default Docker environment configuration sets the following Xdebug configuration variables:

  3. Change any Xdebug configuration using the XDEBUG_CONFIG option. For example, to change the xdebug.remote_port option:

    On Linux systems, use the following command instead:

Phpstorm Xdebug Ssh

To configure PhpStorm to work with Xdebug:

  1. In your PhpStorm project, open the settings panel.

    • Mac OS X—Select File > Preferences.
    • Windows/Linux—Select File > Settings.

  2. In the Settings panel, expand and locate the Languages & Frameworks > PHP > Servers section.

  3. Click the + to add a PHP Remote Debug server configuration. The project name is in grey at the top.

  4. Configure the following settings for the new server configuration:

    • Name—Enter the name used for the serverName option from PHP_IDE_CONFIG value.
    • Host—Enter localhost.
    • Port—Enter 80.
    • Debugger—Select Xdebug.

  5. Select Use path mappings. In the File/Directory pane, the root of the project for the serverName displays.

  6. In the Absolute path on the server column, click and add a value to the MAGENTO_ROOT option. The default value is /app

  7. Change the Xdebug port to 9001 in the Languages & Frameworks > PHP > Debug > Xdebug > Debug Port panel.

  8. Click Apply.

Use Xdebug

The following steps describe debugging web requests and CLI commands.

Phpstorm Docker Xdebug Mac

To debug web requests:

  1. In your PhpStorm project, click (Start listening) in the top navigation bar.

  2. Add breakpoints in the pub/index.php file.

  3. Install the debug extension in the browser, and then click Debug to enable.

  4. In the browser, open the https://localhost URL.

  5. When PhpStorm recognizes the Xdebug connection, you can begin debugging web requests.

You can debug any Magento command or PHP script using the following steps.

To debug CLI commands:

  1. In your PhpStorm project, open the Build, Extension, Deployment > Docker panel, and then click + to add a new Docker server and update the following settings:

    • Name—Enter a name for the server, for example Docker Cloud.
    • Connect to Docker daemon with—
      • Windows—Select TCP socket and update Engine Api Url with tcp://localhost:2375.
      • Mac OS X—Select Docker for Mac. [default]

  2. In the Languages & Frameworks > PHP > Cli Interpreter panel, click […].

  3. Click [+] to add and configure a new Cli Interpreter from your Docker image. Update the following settings:

    • Name—Enter a name for the new interpreter, such as Magento cloud docker cli.
    • Remote—Select Docker.
      • Server—Select Docker Cloud from the previous step.
      • Image name—Select magento/magento-cloud-docker-php:7.x-cli.
    • Additional > Debugger extension—
      • Windows—Enter xdebug.
      • Mac OS X/Linux—Enter xdebug.so.
    • Click Refresh to verify that the interpreter and Xdebug extension are configured properly.

  4. Click Save.

  5. Open the Run/Debug Configuration window and add a new PHP script with the following settings:

    • Name—Enter bin/magento.
    • Configuration > File—Select the path to the bin/magento file in your local environment.

  6. Add breakpoints in the bin/magento file and the debug PHP script created in the previous step.

Using Xdebug Helper

You can install and use the Xdebug Helper Chrome extension to debug your PhP code from the browser.

Docker Phpstorm Xdebug Phpunit

To use Xdebug Helper with Chrome:

Docker Phpstorm Xdebug Nginx

  1. Install the Xdebug Helper extension from the Chrome store.

  2. Enable the extension in Chrome as shown in the following figure.

  3. In Chrome, click in the Chrome toolbar.

  4. From the Xdebug helper menu, click Options.

  5. From the IDE Key list, select PhpStorm.

  6. Click Save.





Coments are closed
Free Word Document Program W Edit With Wps Office