Configure Xdebug for Docker
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:
- Open your Docker settings.
- Select the Expose daemon on tcp://localhost:2375 without TLS checkbox.
- Wait for the settings to apply.
Enable Xdebug
-
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.1
vendor/bin/ece-docker build:compose --mode --sync-engine="mutagen" developer --with-xdebug
This command adds the Xdebug configuration to your
docker-compose.yml
file.1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
fpm_xdebug: hostname: fpm_xdebug.magento2.docker image: 'magento/magento-cloud-docker-php:7.3-fpm-1.1' extends: generic ports: - '9001:9001' volumes: - 'mymagento-magento-sync:/app:nocopy' environment: - 'PHP_EXTENSIONS=bcmath bz2 calendar exif gd gettext intl mysqli pcntl pdo_mysql soap socketssysvmsg sysvsem sysvshm opcache zip redis xsl sodium' networks: magento: aliases: - fpm_xdebug.magento2.docker depends_on: db: condition: service_started
-
Follow the steps to launch the Docker environment in Developer mode.
The default Docker environment configuration sets the following Xdebug configuration variables:
1 2
PHP_IDE_CONFIG=serverName=magento_cloud_docker XDEBUG_CONFIG=remote_host=host.docker.internal
-
Change any Xdebug configuration using the
XDEBUG_CONFIG
option. For example, to change the xdebug.remote_port option:1
XDEBUG_CONFIG='remote_host=host.docker.internal remote_port=9002'
To configure PhpStorm to work with Xdebug:
-
In your PhpStorm project, open the settings panel.
- Mac OS X—Select File > Preferences.
- Windows/Linux—Select File > Settings.
-
In the Settings panel, expand and locate the Languages & Frameworks > PHP > Servers section.
-
Click the + to add a server configuration. The project name is in grey at the top.
-
Configure the following settings for the new server configuration:
- Name—Enter the name used for the
serverName
option fromPHP_IDE_CONFIG
value. - Host—Enter
localhost
. - Port—Enter
80
. - Debugger—Select
Xdebug
.
- Name—Enter the name used for the
-
Select Use path mappings. In the File/Directory pane, the root of the project for the
serverName
displays. -
In the Absolute path on the server column, click and add a value to the
MAGENTO_ROOT
option. The default value is/app
-
Change the Xdebug port to 9001 in the Languages & Frameworks > PHP > Debug > Xdebug > Debug Port panel.
-
Click Apply.
Use Xdebug
The following steps describe debugging web requests and CLI commands.
To debug web requests:
-
In your PhpStorm project, click (Start listening) in the top navigation bar.
-
Add breakpoints in the
pub/index.php
file. -
Install the debug extension in the browser, and then click Debug to enable.
-
In the browser, open the
https://localhost
URL. -
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:
-
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]
- Windows—Select TCP socket and update Engine Api Url with
- Name—Enter a name for the server, for example
-
In the Languages & Frameworks > PHP > Cli Interpreter panel, click […].
-
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
.
- Server—Select
- Additional > Debugger extension—
- Windows—Enter
xdebug
. - Mac OS X/Linux—Enter
xdebug.so
.
- Windows—Enter
- Click Refresh to verify that the interpreter and Xdebug extension are configured properly.
- Name—Enter a name for the new interpreter, such as
-
Click Save.
-
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.
- Name—Enter
-
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.
To use Xdebug Helper with Chrome:
-
Install the Xdebug Helper extension from the Chrome store.
-
Enable the extension in Chrome as shown in the following figure.
-
In Chrome, click in the Chrome toolbar.
-
From the Xdebug helper menu, click Options.
-
From the IDE Key list, select PhpStorm.
-
Click Save.