Xdebug.remoteenable = 1 xdebug.remoteautostart = 1 Tip! If your PHP project runs in a Docker container, you need also to add the following line to the xdebug.ini file, where 172.17.0.1 is the IP address of the docker0 interface on your computer (on Mac OS you have to put host.docker.internal instead). To set up Xdebug, you need to configure a file in your Git repository, configure your IDE, and set up port forwarding. You can configure settings in the magento.app.yaml file. After editing, you can push the Git changes across all Starter environments and Pro Integration environments to enable Xdebug.

Xdebug Cli Config

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:

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.

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.

To use Xdebug Helper with Chrome:

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.

PHP applications are not always web applications. Various command line tools, daemons, message queue processing applications and other types of applications typically run in the PHP CLI. There are several ways to start a PHP CLI debugging session. You can start it from within PhpStorm and make it start the script and attach the debugger to it. Alternatively, you can let PhpStorm listen for incoming debugger connections and start the script outside the IDE. We'll take a look at both options.

Before you start debugging, make sure that you have a debugging engine installed and configured properly. PhpStorm supports debugging with two most popular tools: Xdebug and Zend Debugger. These tools cannot be used simultaneously because they block each other. To avoid this problem, you need to update the corresponding sections in the php.ini file as described in Configure Xdebug and Configure Zend Debugger.

Open the active php.ini file in the editor:

1. In the Settings/Preferences dialog Ctrl+Alt+S, click PHP.

2. On the PHP page that opens, click next to the CLI Interpreter field.

3. In the CLI Interpreters dialog that opens, the Configuration file read-only field shows the path to the active php.ini file. Click Open in Editor.

Start a debugging session from PhpStorm

To start debugging a PHP CLI script from within PhpStorm, perform the following steps.

Create a Run/Debug Configuration

PhpStorm uses Run/Debug configurations to execute a script from within the IDE. A configuration can define additional arguments for the PHP interpreter as well as launch other commands prior to starting our script. We will need a Run/Debug configuration to start the debugger from within PhpStorm.

1. Create a new Run/Debug configuration using the Run | Edit Configurations menu.

2. Add a new configuration of the PHP Script type and provide the required parameters, such as the script to be executed.

3. Save the created Run/Debug configuration.

• Right-click in the Project tool window, and select Debug | <script name>.php from the context menu (make sure to pick the item marked with ). Alternatively, open the script in the editor, press Alt+Shift+F9, and select the script to be debugged.

  The IDE will launch the script with the debugger enabled, and open the Debug tool window.

Launch the Debugger

Before launching the debugger, make sure that either a breakpoint is set or the Break at first line in PHP scripts option is enabled on the Debug page of the Settings/Preferences dialog Ctrl+Alt+S.

• Click on the PhpStorm toolbar.

• Press Alt+Shift+F9.

• Select Run | Debug from the main menu.

1. Press Ctrl+Shift+A and start typing Change PHP interpreter. In the suggestions list, select the Change PHP interpreter action.

   If necessary, you can assign a keyboard shortcut for this action either directly in the suggestions list by pressing Alt+Enter, or at a later point as described in Configure keyboard shortcuts.

2. In the popup menu that opens, select one of the configured local or remote PHP interpreters.

The selected interpreter will be set as the default project interpreter on the PHP page of the Settings/Preferences dialog Ctrl+Alt+S. This will also affect the run/debug configurations, test frameworks', and quality tools' configurations that are set to use the default project interpreter.

Start a debugging session from the command line

Before you start a debugging session with PhpStorm when running CLI scripts, make sure that any of the following requirements is met:

• Xdebug's remote_autostart (for Xdebug 2) or start_with_request (for Xdebug 3) option is enabled.

• XDEBUG_CONFIG environment variable exists.

Listening for incoming debugger connections

In PhpStorm, enable listening to incoming debug connections by either clicking on the toolbar or selecting Run | Start Listening for PHP Debug Connections. This will ensure PhpStorm reacts when a debugging session is started and opens the debug tool window automatically. Before launching the script, make sure that either a breakpoint is set or the Break at first line in PHP scripts option is enabled on the Debug page of the Settings/Preferences dialog Ctrl+Alt+S.

Command Line Xdebug

Start the script with debugger options

Since we'll be starting the script from the command line, we will have to make sure it is started with the required settings to enable the debugger.

Starting the script with Xdebug

Xdebug has various configuration options which we can use to let the PHP interpreter reach out to PhpStorm. These parameters have to be passed to the PHP interpreter using the -d command line parameter. Alternatively, you can set an environment variable so that you don't need to provide the -d parameters every time.

Start the script with debugging using PHP command-line switches

• Launch PHP with the following command-line options:

  php -dxdebug.remote_enable=1 -dxdebug.remote_mode=req -dxdebug.remote_port=9000 -dxdebug.remote_host=127.0.0.1 -dxdebug.remote_connect_back=0 path/to/script.php

  php -dxdebug.mode=debug -dxdebug.client_host=127.0.0.1 -dxdebug.client_port=9003 -dxdebug.start_with_request=yes path/to/script.php

Start the script with debugging using an environment variable

1. Set an environment variable that configures Xdebug:

   • For Windows:

     set XDEBUG_CONFIG=remote_enable=1 remote_mode=req remote_host=127.0.0.1 remote_port=9000 remote_connect_back=0

     set XDEBUG_CONFIG=mode=debug client_host=127.0.0.1 client_port=9003 start_with_request=yes

   • For macOS / Linux

     export XDEBUG_CONFIG='remote_enable=1 remote_mode=req remote_host=127.0.0.1 remote_port=9000 remote_connect_back=0'

     export XDEBUG_CONFIG='mode=debug client_host=127.0.0.1 client_port=9003 start_with_request=yes'

2. Start the script normally:

   Optionally, you can use Xdebug's remote_autostart (for Xdebug 2) or start_with_request (for Xdebug 3) setting to always start a debugging session for every script that is run.

Starting the script with Zend Debugger

Zend Debugger has various configuration options which we can use to let the PHP interpreter reach out to PhpStorm. These parameters have to be passed to the PHP interpreter using an environment variable.

Start the script with debugging

1. Set the QUERY_STRING environment variable:

   set QUERY_STRING=start_debug=1&debug_host=127.0.0.1&no_remote=1&debug_port=10137&debug_stop=1

   export QUERY_STRING='start_debug=1&debug_host=127.0.0.1&no_remote=1&debug_port=10137&debug_stop=1'

2. Start the script normally:

Optionally, to tell PhpStorm which path mapping configuration should be used for a connection from a certain machine, the value of the PHP_IDE_CONFIG environment variable should be set to serverName=SomeName, where SomeName is the name of the server configured on the PHP | Servers page of the Settings/Preferences dialog Ctrl+Alt+S.

Xdebug.cli Color

If this environment variable is not set, you'll be prompted to specify path mappings manually once IDE detects an incoming Xdebug connection.

Debug

Xdebug Cli Disable

Once the script is started, PhpStorm will open the Debug tool window and break at the first breakpoint that was set in the script. You can now continue debugging a PHP CLI script as described in Examining a Suspended Program.

Xdebug Cli Not Working

If the script that is being debugged is not a part of the project that's open in PhpStorm, the IDE will still open the script in the editor and pause execution at the first statement. This makes it possible to quickly debug any PHP CLI script, even if there is no PhpStorm project for it yet.