DocumentationCommerceCommerce on Cloud Infrastructure Guide

Configure Xdebug

Last update: Wed Feb 14 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Admin
  • Developer

Xdebug is an extension for debugging your PHP. Although you can use an IDE of your choice, the following explains how to configure Xdebug and PhpStorm to debug in your local environment.

NOTE
You can configure Xdebug to run in the Cloud Docker environment for local debugging without changing your Adobe Commerce on cloud infrastructure project configuration. See Configure Xdebug for Docker.

To enable Xdebug, you must configure a file in your Git repository, configure your IDE, and set up port forwarding. You can configure some settings in the magento.app.yaml file. After editing, push the Git changes across all Starter environments and Pro integration environments to enable Xdebug. Xdebug is already available in Pro Staging & Production environments.

Once configured, you can debug CLI commands, web requests, and code. Remember that all cloud infrastructure environments are read-only. Clone the code to your local development environment to perform debugging. For Pro Staging and Production environments, see additional instructions for Xdebug.

Requirements

To run and use Xdebug, you need the SSH URL for the environment. You can locate the information through the Cloud Console or your Cloud Onboarding UI.

Configure Xdebug

To configure Xdebug, follow these steps:

Get started with a branch

To add Xdebug, Adobe recommends working in a development branch.

Enable Xdebug in your environment

You can enable Xdebug directly to all Starter environments and Pro integration environments. This configuration step is not required for Pro Production & Staging environments. See Debug for Pro Staging and Production.

To enable Xdebug for your project, add xdebug to the runtime:extensions section of the .magento.app.yaml file.

To enable Xdebug:

  1. In your local terminal, open the .magento.app.yaml file in a text editor.

  2. In the runtime section, under extensions, add xdebug. For example:

    code language-yaml 
    runtime:
    extensions:
        - redis
        - xsl
        - newrelic
        - sodium
        - xdebug

  3. Save your changes to the .magento.app.yaml file and exit the text editor.

  4. Add, commit, and push the changes to redeploy the environment.

    code language-bash 
    git add -A
    code language-bash 
    git commit -m "Add xdebug"
    code language-bash 
    git push origin <environment-ID>

When deployed to Starter environments and Pro integration environments, Xdebug is now available. Continue configuring your IDE. For PhpStorm, see Configure PhpStorm.

Configure PhpStorm

The PhpStorm IDE must be configured to properly work with Xdebug.

To configure PhpStorm to work with Xdebug:

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

    • macOS—Select PhpStorm > 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 server configuration. The project name is in gray at the top.

  4. [Optional] Configure the following settings for the new server configuration. See No debug server configured in the PHPStorm documentation.

    • Name—Enter the same as the hostname. This value must match the value for the PHP_IDE_CONFIG variable in Debug CLI commands to use CLI for debugging.
    • Host—Enter the hostname.
    • Port—Enter 443.
    • 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 the Edit icon and add a setting based on the environment.

    • For all Starter environments and Pro integration environments, the remote path is /app.

    • For Pro Staging and Production environments:

      • Production: /app/<project_code>/
      • Staging: /app/<project_code>_stg/

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

  8. Click Apply.

Set up port forwarding

Map the XDEBUG connection from the server to your local system. To do any type of debugging, you must forward port 9000 from your Adobe Commerce on cloud infrastructure server to your local machine. See one of the following sections:

Port forwarding on Mac or UNIX®

To set up port forwarding on a Mac or in a UNIX® environment:

  1. Open a terminal.

  2. Use SSH to establish the connection.

    code language-bash 
    ssh -R 9000:localhost:9000 <ssh url>

    Use the -v (verbose) option so that whenever a socket is connected to the port that is being forwarded it shows in the terminal.

    If an “unable to connect” or “could not listen to port on remote” error is displayed, there could be another active SSH session persisting on the server that is occupying port 9000. If that connection is not being used, you can terminate it.

To troubleshoot the connection:

  1. Use SSH to log in to the remote integration, Staging, or Production environment.

  2. View a list of SSH sessions: who

  3. View existing SSH sessions by user. Be careful to not affect a user other than yourself!

    • integration: usernames are similar to dd2q5ct7mhgus
    • Staging: usernames are similar to dd2q5ct7mhgus_stg
    • Production: usernames are similar to dd2q5ct7mhgus

  4. For a user session that is older than yours, find the pseudo-terminal (PTS) value, such as pts/0.

  5. Kill the process ID (PID) corresponding to the PTS value.

    code language-bash 
    ps aux | grep ssh
kill <PID>

    Sample response:

    code language-terminal 
    dd2q5ct7mhgus        5504  0.0  0.0  82612  3664 ?      S    18:45   0:00 sshd: dd2q5ct7mhgus@pts/0

    To terminate the connection, enter a kill command with the process ID (PID).

    code language-bash 
    kill 3664

Port forwarding on Windows

To set up port forwarding (SSH tunneling) on Windows, you must configure your Windows terminal application. This example steps through creating an SSH tunnel using Putty. You can use other applications such as Cygwin. For more information on other applications, see the vendor documentation provided with those applications.

To set up an SSH tunnel on Windows using Putty:

  1. If you have not already done so, download Putty.

  2. Start Putty.

  3. In the Category pane, click Session.

  4. Enter the following information:

    • Hostname (or IP address) field: Enter the SSH URL for your Cloud server
    • Port field: Enter 22

    Set up Putty

  5. In the Category pane, click Connection > SSH > Tunnels.

  6. Enter the following information:

    • Source port field: Enter 9000
    • Destination field: Enter 127.0.0.1:9000
    • Click Remote

  7. Click Add.

    Create an SSH tunnel in Putty

  8. In the Category pane, click Session.

  9. In the Saved Sessions field, enter a name for this SSH tunnel.

  10. Click Save.

    Save your SSH tunnel

  11. To test the SSH tunnel, click Load, then click Open.

    If an “unable to connect” error displays, verify the following:

    • All Putty settings are correct
    • You are running Putty on the machine on which your private Adobe Commerce on cloud infrastructure SSH keys are located

SSH access to Xdebug environments

For initiating debugging, performing setup, and more, you need the SSH commands for accessing the environments. You can get this information through the Cloud Console and your project spreadsheet.

For Starter environments and Pro integration environments, you can use the following magento-cloud CLI command to SSH into those environments:

magento-cloud environment:ssh --pipe -e <environment-ID>

To use Xdebug, SSH to the environment as follows:

ssh -R <xdebug listen port>:<host>:<xdebug listen port> <SSH-URL>

For example,

ssh -R 9000:localhost:9000 pwga8A0bhuk7o-mybranch@ssh.us.magentosite.cloud

Debug for Pro Staging and Production

NOTE
On Pro Staging & Production environments, Xdebug is always available as these environments have a special setup for Xdebug. All normal web requests are routed to a dedicated PHP process that does not have Xdebug. Therefore, these requests are processed normally and are not subject to the performance degradation when Xdebug is loaded. When a web request is sent that has the Xdebug key, it is routed to a separate PHP process that has Xdebug loaded.

To use Xdebug specifically on Pro plan Staging and Production environment, you create a separate SSH tunnel and web session only you have access to. This usage differs from typical access, only providing access to you and not to all users.

You need the following:

  • SSH commands for accessing the environments. You can get this information through the Cloud Console or your Cloud Onboarding UI.

  • The xdebug_key value set when configuring the Staging and Pro environments.

    The xdebug_key can be found by using SSH to log in to the primary node and executing:

    code language-bash 
    cat /etc/platform/*/nginx.conf | grep xdebug.sock | head -n1

To set up an SSH tunnel to a Staging or Production environment:

  1. Open a terminal.

  2. Clean up all SSH sessions for each web node of the cluster.

    code language-bash 
    ssh USERNAME@CLUSTER.ent.magento.cloud 'rm /run/platform/USERNAME/xdebug.sock'

  3. Set up the SSH tunnel for Xdebug for each web node of the cluster.

    code language-bash 
    ssh -R /run/platform/USERNAME/xdebug.sock:localhost:9000 -N USERNAME@CLUSTER.ent.magento.cloud

To start debugging using the environment URL:

  1. Enable remote debugging; visit the site in the browser and append the following to the URL where KEY is value for xdebug_key.

    code language-http 
    ?XDEBUG_SESSION_START=KEY

    This step sets the cookie that sends browser requests to trigger Xdebug.

  2. Complete your debugging with Xdebug.

  3. When you are ready to end the session, use the following command to remove the cookie and end debugging through the browser where KEY is value for xdebug_key.

    code language-http 
    ?XDEBUG_SESSION_STOP=KEY
    note note
    NOTE
    The XDEBUG_SESSION_START passed by POST requests are not supported.

Debug CLI commands

This section walks through debugging CLI commands.

To debug CLI commands:

  1. SSH into the server you want to debug using CLI commands.

  2. Create the following environment variables:

    code language-bash 
    export XDEBUG_CONFIG='PHPSTORM'
    code language-bash 
    export PHP_IDE_CONFIG="serverName=<name of the server that is configured in PHPSTORM>"

    These variables are removed when the SSH session ends.

  3. Begin debugging

    On Starter environments and Pro integration environments, run the CLI command to debug.
    You may add runtime options, for example:

    code language-bash 
    php -d xdebug.profiler_enable=On -d xdebug.max_nesting_level=9999 bin/magento cache:clean

    On Pro Staging and Production environments, you must specify the path to the Xdebug PHP configuration file when debugging CLI commands, for example:

    code language-bash 
    php -c /etc/platform/USERNAME/php.xdebug.ini bin/magento cache:clean

Debug web requests

The following steps help you debug web requests.

  1. On the Extension menu, click Debug to enable.

  2. Right click, select the options menu, and set the IDE key to PHPSTORM.

  3. Install the Xdebug client on the browser. Configure and enable it.

Example: Chrome setup

This section discusses how to use Xdebug in Chrome using the Xdebug Helper extension. For information about Xdebug tools for other browsers, consult the browser documentation.

To use Xdebug Helper with Chrome:

  1. Create an SSH tunnel to the Cloud server.

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

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

    Enable the Xdebug extension in Chrome

  4. In Chrome, right-click the green helper icon in the Chrome toolbar.

  5. From the pop-up menu, click Options.

  6. From the IDE Key list, click PhpStorm.

  7. Click Save.

    Xdebug Helper options

  8. Open your PhpStorm project.

  9. In the top navigation bar, click the Start listening icon.

    If the navigation bar is not displayed, click View > Navigation Bar.

  10. In the PhpStorm navigation pane, double-click the PHP file to test.

Debug local code

Because of the read-only environments, you must pull code to the local workstation from an environment or specific Git branch to perform debugging.

The method you choose is up to you. You have the following options:

  • Check out code from Git and run composer install

    This method works unless composer.json references packages in private repositories to which you do not have access. This method results in getting the entire Adobe Commerce codebase.

  • Copy the vendor, app, pub, lib, and setup directories

    This method results in your having all code you can possibly test. Depending on how many static assets you have, it could result in a long transfer with a large volume of files.

  • Copy the vendor directory only

    Because most of the code is in the vendor directory, this method is likely to result in good testing, although are not testing the entire codebase.

To compress files and copy them to your local machine:

  1. Use SSH to log in to the remote environment.

  2. Compress the files.

    code language-bash 
    tar -czf /tmp/<file-name>.tgz <directory list>

    For example, to compress the vendor directory only:

    code language-bash 
    tar -czf /tmp/vendor.tgz vendor

  3. On your local environment, use PhpStorm to compress the files.

    code language-bash 
    cd <phpstorm project root dir>
    code language-bash 
    rsync <SSH-URL>:/tmp/<file-name>.tgz .
    code language-bash 
    tar xzf <file-name>.tgz
05f2f56e-ac5d-4931-8cdb-764e60e16f26