Magento 2 Phpstorm

Xdebug is an extension for debugging your PHP. The following explains how to configure Xdebug and PhpStorm to debug in your local environment. You can use the IDE of your choice. See the vendor documentation for those applications for further configuration information.

You can configure Xdebug to run in the Magento Cloud Docker environment for local debugging without changing your Magento Commerce Cloud project configuration. See Configure Xdebug for Docker.

The step-by-step guide for setting up PhpStorm for Magento 2 development Compared to Magento 1, Magento 2 combines a lot of built-in tools and approaches designed to facilitate all development processes, and most significantly, enhance the source code quality. As a consequence, the product quality raises simultaneously. Compared to Magento 1, Magento 2 combines a lot of built-in tools and approaches designed to facilitate all development processes, and most significantly, enhance the source code quality. As a consequence, the product quality raises simultaneously. One of the most important tools for quality developments in Magento is PhpStorm.

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. To push these settings to Pro plan Staging and Production environments, you must enter a ticket.

Once configured, you can debug CLI commands, web requests, and code. Remember, all Magento Commerce Cloud environments are read-only. You need to pull code to your local development environment to perform debugging. For Pro Staging and Production environments, we include 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 Project Web Interface or your Cloud Onboarding UI.

Configure Xdebug

To configure Xdebug, you need to do the following:

Work in a branch to push file updates
Configure your IDE, like PhpStorm

For configuring on Pro plan Staging and Production, you need to enter a ticket for Staging and Production.

Get started with a branch

To add Xdebug, we recommend creating a branch to work in and add the files.

To get started with environment branches:

On your local workstation, change to your Cloud project directory.
Switch to the Magento file system owner.
Log in to your Magento project.
List your projects.
List environments in the project. Every environment includes an active Git branch that contains your code, database, environment variables, configurations, and services.
It is important to use the magento-cloud environment:list command because it displays environment hierarchies, whereas the git branch command does not.
Fetch origin branches to get the latest code.
Checkout, or switch to, a specific branch and environment.
Git commands only checkout the Git branch. The magento-cloud checkout command checks out the branch and switches to the active environment.
You can create a new environment branch using the magento-cloud environment:branch <environment-name> <parent-environment-ID> command syntax. It may take some additional time to create and activate a new environment branch.
Use the environment ID to pull any updated code to your local. This is not necessary if the environment branch is new.
(Optional) Create a snapshot of the environment as a backup.

Enable Xdebug in your environment

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

You can enable Xdebug directly to all Starter environments and Pro Integration environments. For Pro Staging and Production, you need to update this file and enter a Support ticket to have it enabled. We enable Xdebug on those environments for you.

To enable Xdebug:

In your local terminal, open the .magento.app.yaml file in a text editor.
In the runtime section, under extensions, add xdebug. For example:
Save your changes to the .magento.app.yaml file and exit the text editor.
Add, commit, and push the changes to redeploy the environment.

When deployed to Starter environments and Pro Integration environments, Xdebug is now available. You should continue configuring your IDE. For PhpStorm, see Configure PhpStorm.

Configure PhpStorm

Magento 2 Code Sniffer Phpstorm

You need to configure PhpStorm to properly work with Xdebug.

To configure PhpStorm to work with Xdebug:

In your PhpStorm project, open the settings panel.
- Mac OS X—Select PhpStorm > 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 same as the hostname. This value is used in and must match the value for PHP_IDE_CONFIG variable in Debug CLI commands.
- Host—Enter localhost.
- Port—Enter 80.
- Debugger—Select Xdebug.
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 (Edit) 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/
Change the Xdebug port to 9000 in the Languages & Frameworks > PHP > Debug > Xdebug > Debug Port panel.
Click Apply.

Set up port forwarding

You must map the XDEBUG connection from the server to your local system. To do any type of debugging, you must forward port 9000 from your Magento Commerce Cloud 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:

Open a terminal.
Use SSH to establish the connection.
Add the -v option to the SSH command to show in the terminal whenever a socket is connected to the port that is being forwarded.
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 isn’t being used, you can terminate it.

To troubleshoot the connection:

Use SSH to log in to the remote Integration, Staging, or Production environment.
Enter who to view a list of SSH sessions.
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
For a user session that is older than yours, find the pseudo-terminal (PTS) value, such as pts/0.
Kill the process ID (PID) corresponding to the PTS value.
Sample response:
To terminate the connection, enter a kill command with the process ID (PID).

Port forwarding on Windows

To set up port forwarding (SSH tunneling) on Windows, you must configure your Windows terminal application. For this example, we walk 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:

If you have not already done so, download Putty.
Start Putty.
In the Category pane, click Session.
Enter the following information:
- Hostname (or IP address) field: Enter the SSH URL for your Cloud server
- Port field: Enter 22
In the Category pane, click Connection > SSH > Tunnels.
Enter the following information:
- Source port field: Enter 9000
- Destination field: Enter 127.0.0.1:9000
- Click Remote
Click Add.
In the Category pane, click Session.
In the Saved Sessions field, enter a name for this SSH tunnel.
Click Save.
To test the SSH tunnel, click Load, then click Open.
If an “unable to connect” error displays, verify all of the following:
- All Putty settings are correct
- You are running Putty on the machine on which your private Magento Commerce Cloud SSH keys are located

Configure Pro Staging and Production

To complete configuration for Pro plan Staging and Production environments, you must enter a Support ticket to have Xdebug enabled and configured in Staging and Production environments.

We enable Xdebug in the environment. Be aware that this is a configuration change that requires us to redeploy your Staging and Production environments.

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 Project Web Interface 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:

To use Xdebug, SSH to the environment as follows:

For example,

Debug for Pro Staging and Production

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 Project Web Interface or your Cloud Onboarding UI.
The xdebug_key value we set when configuring the Staging and Pro environments

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

Open a terminal.
Clean up all SSH sessions.
Set up the SSH tunnel for Xdebug.

To start debugging using the environment URL:

To enable remote debugging, visit the site in the browser with the following added to the URL where KEY is value for xdebug_key:
This sets the cookie that sends browser requests to trigger Xdebug.
Complete your debugging with Xdebug.
When you are ready to end the session, you can use the following command to remove the cookie and end debugging through the browser where KEY is value for xdebug_key:
The XDEBUG_SESSION_START passed by POST requests are not supported at this time.

Debug CLI commands

This section walks through debugging CLI commands.

To debug CLI commands:

SSH into the server you want to debug using CLI commands.
Create the following environment variables:
These variables are removed when the SSH session ends.
Begin debugging
On Starter environments and Pro Integration environments, run the CLI command to debug.You may add runtime options, for example:
On Pro Staging and Production environments, you must specify the path to the Xdebug php configuration file when debugging CLI commands, for example:

For debugging web requests

The following steps help you debug web requests.

On the Extension menu, click Debug to enable.
Right click, select the options menu, and set the IDE key to PHPSTORM.
Install the Xdebug client on the browser. Configure and enable it.

Example set up on Chrome

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:

Create an SSH tunnel to the Cloud server.
Install the Xdebug Helper extension from the Chrome store.
Enable the extension in Chrome as shown in the following figure.
In Chrome, right-click in the Chrome toolbar.
From the pop-up menu, click Options.
From the IDE Key list, click PhpStorm.
Click Save.
Open your PhpStorm project.
In the top navigation bar, click (Start listening).
If the navigation bar isn’t displayed, click View > Navigation Bar.
In the PhpStorm navigation pane, double-click the PHP file to test.

Debug code locally

Due to the read-only environments, you need to pull code locally 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 Magento 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 Magento and third-party code is in the vendor directory, this method is likely to result in good testing although you will not be testing the entire codebase.

To compress files and copy them to your local machine:

Use SSH to login to the remote environment.
Compress the files.
For example, to compress the vendor directory only, enter
On your local environment, use PhpStorm to compress the files.

Magento Tutorials

In this tutorial, I will demonstrate how to debug remote REST API calls that are implemented with PHP. That is, I will show you how to run the debugger through the code that is called by the REST API.

In this specific tutorial, the demonstration will be done on Magento 2. However, it is applicable to any other platform that uses PHP to call and to implement the REST API calls.

Magento 2 Phpstorm Templates

In this tutorial, I am using Ubuntu 16.04, PHP 7.0.33, Xdebug 2.4.o and Phpstorm 6.0.3.

Magento 2 Phpstorm Urn

Step 1: Configuring Xdebug

In this tutorial, I assume that you’ve installed Xdebug on your server.

To check if your Xdebug is installed, run php -v in your SSH, and check that the output has the xdebug string in it. For example, this is what I get when I run php -v:

PHP 7.0.33-0ubuntu0.16.04.2 (cli) ( NTS )
Copyright (c) 1997-2017 The PHP Group
Zend Engine v3.0.0, Copyright (c) 1998-2017 Zend Technologies
with Zend OPcache v7.0.33-0ubuntu0.16.04.2, Copyright (c) 1999-2017, by Zend Technologies
with Xdebug v2.4.0, Copyright (c) 2002-2016, by Derick Rethans

If you don’t get the Xdebug in the output message, you either haven't installed it or haven't enabled it. I won’t cover here how to install Xdebug, but there are tons of great tutorials about that over the internet.

Assuming that your Xdebug is installed and enabled, open the xdebug apache configuration file. On my server (Ubuntu 16.04 with PHP 7.0.33) it is located at /etc/php/7.0/apache2/conf.d/20-xdebug.ini

Make sure that it has the following content:

zend_extension=/usr/lib/php/20151012/xdebug.so
xdebug.remote_enable=1
xdebug.remote_port=9001
xdebug.remote_host=192.168.1.12

Where 192.168.1.12 is the local IP address of the computer where the Phpstorm is running. If your Phpstorm is running on Windows, you can check your IP address by running ipconfig in the Windows shell.

I’ve set 9001 as a remote_port, because the standard port 9000 is often being used by other applications.

After saving the configuration files, restart apache. If you are on Ubuntu, it can be done by running service apache2 restart

Step 2: Setting a XDEBUG_SESSION cookie to your REST client

In order for the Xdebug to pick up your session, you need to set the XDEBUG_SESSION cookie in the client that you use to make your API calls. I use Zend Http client. So my code looks something like that:

$client = new Client();
$client->setEncType(Client::ENC_FORMDATA);
$options = [
'adapter' => 'ZendHttpClientAdapterCurl',
'curloptions' => [
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_SSL_VERIFYPEER => false,
CURLOPT_SSL_VERIFYHOST => false
],
'maxredirects' => 0,
'timeout' => 30
];
$client->setOptions($options);
$client->setCookies(['XDEBUG_SESSION' => '16045']);
$response = $client->send($request);
$body = $response->getBody();

(The number 16045 is arbitrary.)

Step 3: Uploading the PHP file where you are making the API call to the root Magento directory

Upload the file where you are making the API calls to the Magento root directory. In my example, it is the file apiUpdateInventory.php.

Here is my Project structure in Phpstorm:

Step 4: Setting the debugging port in Phpstorm

In my example, I use the port 9001 in the server configuration, so I need to set it as the debugging port in Phpstorm. To do that, go to Phpstorm → Settings → PHP → Debug, and under xdebug, set the Debug port to 9001 (or any other port that you’ve set in the xdebug configuration file in Step 1).

Step 5: Turning on the Debug Connection Listener in Phpstorm

In Phpstorm, click on the phone icon next to the debugging section on the top, and make sure that it is green, like in the following screenshot:

Also, don’t forget to set some breakpoints (in the file that makes the API call, as well as in the file that implements the API call), or to click on “Run → Break at first line in PHP scripts” in Phpstorm.

Step 5: Running the PHP script that calls the API

To run the script, in your favorite browser, surf to <your_website_url>/<the_PHP_file_that_makes_the_API_call>?XDEBUG_SESSION_START=16045

In my example it is https://www.magento-ee-22-6.local/apiUpdateInventory.php?XDEBUG_SESSION_START=16045

Step 6: Debugging the API!

This is where the magic happens - in the second you run your script (in Step 5), the debugging of the PHP script that makes the API call should trigger automatically in your Phpstorm. When the debugger reaches the line that makes the actual API call, it should get stuck, while the status should be “Connected”. Then you should click on the red square to stop the debugging, and then the debugger will popup in the code that implements the API! Yaaay!

Here is a screen recording where I do exactly what I just described - I run the debugger, stop it in the line that calls the API , and it proceeds to the file that implements the API call (in my case it is the UpdateInventory::save() function) -

Summing up

After reading this tutorial, you should be able to debug your API calls with Phpstorm and Xdebug. If you have any questions - please write me in comments!