Loadingaloha35

This guide will explain how to configure PhpStorm to use PHP’s Xdebug extension through Vagrant. The process is not as straightforward as it should be, and available documentation has not been clear on this usage. It will be significantly easier when PhpStorm 8 is released, due to its ability to define remote interpreters. When that is available, a new post will be written, with a link to it from this one.

Visual Studio Code, WebStorm, and Atom are probably your best bets out of the 16 options considered. 'Built-in debugging' is the primary reason people pick Visual Studio Code over the competition. This page is powered by a knowledgeable community that helps you make an informed decision. Xdebug is a PHP extension which provides debugging, profiling, code coverage, stack traces and many other capabilities. In this succinct tutorial, I will show us how to set up Xdebug that ships with XAMPP in PhpStorm. See the steps below. Open up php.ini (located at C:path-to-xamppphp) for editing.

Update Feb. 22, 2015: PhpStorm 8 was released late 2014. As indicated in the original publication, the steps to take advantage of remote interpreters will be delineated. The process only varies slightly from the original, so the steps will be included below—instead of in a new article—with a clear distinction between the original steps, which still work very well, and the new ones. Jump to the revision.

Note that as of PhpStorm 8 some of the preferences have been structured and named differently. For example, many parts of this guide mention a “Project Settings [project-name]” heading to find the “PHP” subheading; this no longer exists in PhpStorm 8. That location has been moved to “Languages & Frameworks,” and then “PHP.”

Who will benefit from reading this guide?

Anyone who has been frustrated and ultimately defeated by attempts to run a successful debugging session through Vagrant will benefit from reading this guide. It will not explain how to install Vagrant, Xdebug, or any other tool referenced. It is also assumed that the application to debug will be accessed through a browser.

How do Xdebug and PhpStorm communicate through Vagrant?

There are two communication points to be aware of when developing in Vagrant. The first (1) is the host: the host is the main operating system (OS) that Vagrant was installed on. The second (2) is the guest: the guest is the virtual OS installed by Vagrant.

Generally, the Internet works on a client-server model. Connections between Xdebug and PhpStorm are no exception. For this use case, Xdebug is the client, and PhpStorm is the server ^[1]. This means that Xdebug will connect to Phpstorm whenever the PHP application is accessed, for example, through a browser. However, in order for the client on the guest (Xdebug) to connect to the server on the host (PhpStorm), it must know where to send its request.

Vagrant acts as an intermediary between these two communication points.

A connection to PhpStorm can be established if Xdebug knows the IP address (IP) of the host, where PhpStorm resides. The IP of the host is usually known to the guest, so if Vagrant is configured mostly with defaults, the IP will be something like 10.0.2.2. Upon running vagrant ssh and authenticating into the guest OS, the date of the last login and the IP are displayed. The IP can also be discovered by running netstat -r from within the guest ^[2]; look at the Gateway value. This IP is required for the Xdebug configuration file.

Configuring the guest installation of Xdebug, and what the settings do

The location of the Xdebug configuration file depends on the guest OS. On CentOS, it is usually located at /etc/php.d/xdebug.ini if installed through PECL. Configuration settings can also be written directly in PHP’s /etc/php.ini file. However, the server may fail to start if there are duplicate entries, so be sure only one location houses them.

The Xdebug configuration settings

The configuration should, at minimum, include the settings just below. It is also important to make sure the Xdebug extension is enabled in PHP. The line for enabling it can be included directly above the configuration settings, and will look something like this: zend_extension=/usr/lib64/php/modules/xdebug.so. The path may be different, so verify where the extension is located.

The meaning and purpose of these Xdebug configuration settings

xdebug.idekey type: string

The value can be any valid string. This is the string that will notify the browser, and thus Xdebug, that a debugging session should begin. The browser is notified by either having a cookie set (PHP COOKIE), an argument passed as a string in the URL (PHP GET), or an argument posted to the application (PHP POST); the key name is always XDEBUG_SESSION, and for this guide the IDE key (idekey) value is debugit. When a debug session is triggered, that idekey is read by Xdebug, which is listening to all incoming requests to the server hosting the application, and if it is valid, that in turn will cause Xdebug to send a request to the host server, being PhpStorm.

xdebug.remote_host type: string, default: localhost

This setting can trump people first trying to run a debug session through Vagrant. Prior to Vagrant and other virtual development environments, a default of localhost would be sufficient: the IDE, the Web server, PHP, and Xdebug, would all be running on the same machine, in the same OS. That would mean that the localhost for each tool would be the same. Vagrant changes that. The localhost for the guest OS is different from the localhost for the host OS. Their resources are virtually divorced, to put it one way. To establish that connection again, the IP of the host must be set as the value. This guide has determined that the likely IP of the host is 10.0.2.2, but be sure to verify this using the techniques described earlier.

xdebug.remote_port type: integer, default: 9000

This is the port that the server on the host OS—meaning PhpStorm—will listen to for incoming connections from Xdebug. It should be noted that the default is port 9000, but the guide uses 10000. If development takes place exclusively within the virtual machine, then it is okay to maintain that default. However, if there was no virtual layer, that port would conflict with another popular tool also listening on that port, namely, PHP-FPM, which would eliminate the likelihood of having a successful debug session.

In a typical LAMP stack setup, Apache takes care of running PHP using the mod_php extension. In more advanced setups, Apache and PHP run as separate daemons; one such setup involves a tool called PHP-FPM, which takes care of parsing and running all PHP scripts, and it listens to requests sent to it from Apache on port 9000. If the environment is hosted using Nginx, in a setup referred to as a LEMP stack, this is almost exclusively the default. This would mean that if Vagrant was not being used, the PHP-FPM daemon and PhpStorm—both running in the same OS—would each listen for connections on port 9000, resulting in a conflict.

Fortunately, Vagrant introduces that virtual divorce of resources, so it is okay to use the default remote port of 9000 for Xdebug. Though, for reasons of clarity, and if by chance the host OS has the lingering vestige of a forgotten or neglected development environment, this guide uses port 10000.

xdebug.remote_enable type: boolean, default: 0

Xdebug has a number of uses. Stepping through code in an IDE like PhpStorm is just one. This is why the default is 0; there is no need in sending off unnecessary requests, especially when nothing is waiting for them on the receiving end. Knowing this, and understanding the very purpose of this guide, the setting must be 1. Debugging in PhpStorm would be impossible otherwise.

xdebug.remote_autostart type: boolean, default: 0

Keeping the default of 0 permits finer control over when and how a debug session should be started. Setting this to 1 means Xdebug will attempt to connect with PhpStorm on every request. This is unnecessary. There are excellent browser tools available to start a debuggin session on demand.

xdebug.remote_handler type: string, default: dbgp

This setting can be excluded, but for backwards-compatibility and verboseness, it is probably best to include it. Following the release of Xdebug 2.1, dbgp is the only option. Moving forward, it is okay to ignore defining the setting, but should the version of Xdebug be unknown or old, this setting should be defined as dbgp. An explanation of the DBGp protocol is available as part of Xdebug’s documentation.

A complete list of the Xdebug configuration settings are available on the Xdebug Web site. It is beneficial to skim through the settings to become more familiar with the tool. Further settings could also be added to the configuration provided just above. A good addition would be to define xdebug.remote_log.

Configuring PhpStorm to accept connections from Xdebug, and setting up the local-to-remote file path mappings

PhpStorm requires a fairly involved setup process to listen for connections from Xdebug, and map the file paths between the remote / virtual filesystem in the guest OS and the local / internal filesystem of the host OS. In fact, this alone has probably been the reason for some developers abandoning Vagrant altogether. The process is not straightforward, and the available documentation fails to cohere the necessary steps. This is where the rest of guide diverges from most guides on configuring Xdebug—and consequently where closest attention is due.

Configure the PHP Debug settings

This step is not complicated. It must be made sure that the Xdebug port defined in PhpStorm matches the one defined in the guest OS’ Xdebug configuration, and that the ports match. The steps for this are delineated below, followed by a screenshot of the UI where these steps take place.

1. Open PhpStorm’s preferences and find the “Project Settings [project-name]” heading.

2. Expand the “PHP” setting and click on “Debug.” On the right are options pertaining to this setting. The relevant section is entitled “Xdebug.” The other ones will be ignored.

3. Ensure that the “Debug port” is 10000, as already discussed in this guide.

4. Ensure that the checkbox with the text, “Can accept external connections,” is checked. The other two checkbox options are checked by default. They are good defaults, so it is good to keep them as they are.

5. Save the changes.

The screenshot lists two additional suboptions, namely, “Skipped Paths,” and “DBGp Proxy.” They can be ignored. The latter may seem like it could be needed, as it provides an “IDE key,” “Host,” and “Port” option as well—and in all likeliness appears to correspond with settings already configured—but it is not. This is for setting up a proxy on a remote server that will accept simultaneous connections from multiple developers. In order to do that, a script is installed on the remote server that listens for these connections, and delegates each debug session based on the incoming IDE key.

Add a remote server to the current project’s settings (and optionally define a remote interpreter in version 8)

In order for PhpStorm to make sense of what Vagrant is, and how connections between it and Xdebug are established, it needs to be told. In PhpStorm’s case, Vagrant should be regarded just like any other remote server. It would not matter if the server was across the globe, or operating in a virtual machine on the same computer. Vagrant is a remote server. That means it needs to be defined as such for PhpStorm to allow communications with it. The steps for this are delineated below, followed by a screenshot of the UI where these steps take place.

1. Open PhpStorm’s preferences and find the “Project Settings [project-name]” heading.

2. Expand the “PHP” setting and click on “Servers.” On the right are options pertaining to this setting.

3. Add a new server by clicking on the “+” symbol.

   Update: As of PhpStorm 8, a remote PHP interpreter can be defined. This makes the next step (4) different depending on the version of PhpStorm in use. While the original step continues to work perfectly fine with version 8, this guide will also provide the step for taking advantage of PhpStorm 8’s remote interpreters feature. The main benefit of defining a remote interpreter is that PhpStorm will not need to have paths manually mapped, which can become very cumbersome when dealing with large projects, or when PHP hits code outside of the main project.

4. Provide the server a “Name” (this is just for easy reference, so call it anything), the actual “Host” address (this will be localhost, 127.0.0.1, or any other valid host name defined in the host OS’ hosts file), the “Port” of the Web server (most likely 80, or 8080, or wherever else the guest OS’ port has been forwarded to on the host), a “Debugger” of Xdebug.

5. PhpStorm version 7.x and below: If PhpStorm 8 and above is installed, skip this step and continue reading from step 6 below. Finally—one of the most important steps in this guide—check the checkbox that states “Use path mappings (select if the server is remote or symlinks are used).” Due to Vagrant’s status as a remote server, there is no possible way for PhpStorm to actually know where files on the remote server (in the guest OS) are located in that filesystem. All that is available is an exact duplicate of the files on the local / host OS filesystem. This is why setting up file path mappings are essential to debugging through Vagrant.

   • Just below the checkbox option, in the left column, entitled, “File/Directory,” there is a list of all the files in the current project. These are the local files. Select the project to debug. Now, in the right column, entitled, “Absolute path on the server,” provide the corresponding path to the location of that directory in the guest OS; this is typically located in /vagrant/path/to/project-name. That path, to make an example, assumes the path on the host OS is something like /var/www/project-name. Note that the actual project name directory in the guest OS filesystem should exactly correspond with the project name directory in the host OS filesystem. Their contents should be an exact mirror of each other. This step provides the missing link between the remote and local filesystem.

   • Save the changes.

   Notes about the screenshot: to elucidate any possible confusion from the values defined in the screenshot, some of them will be explained.

   • The directory of the project on the host OS is /Users/dane/dev/vanilla/vhosts/vanilla and the corresponding path in the guest OS—in Vagrant—is /vanilla/vhosts/vanilla. That is because Vagrant’s Vagrantfile configuration file was configured to mount an additional directory in the guest filesystem, named, /vanilla. The /vagrant directory also exists, though. Most default setups will just use /vagrant.

   • In addition, the “Host” provided is www.vanilla.dev, but it could have also just been localhost. The host OS’ /etc/hosts file contains a custom entry, which allows custom domains like that.

6. PhpStorm version 8.x and above: Unlike in version 7.x and under, leave the option, “Use path mappings (select if the server is remote or symlinks are used),” alone. Leave it unchecked. Version 8 can define a remote PHP interpreter.

   • Open PhpStorm’s preferences and find the “Languages & Frameworks” heading.

   • Click the “PHP” setting. On the right are options pertaining to it.

   • The “Interpreter” setting has a small ellipsis (“…”) button. Click that to open a new window of options.

   • Add a new remote PHP interpreter by clicking the “+” symbol.

   • Select “Vagrant” and provide the path to the Vagrant instance installation on the host OS; this is the directory where the VagrantFile exists, and where commands like vagrant up and vagrant ssh are run from the terminal.

   • Provide a path for the “PHP interpreter path” setting. It is typically located at /usr/bin/php, but if PhpStorm is having issues locating the binary, SSH into the guest OS (vagrant ssh from the instance directory), and run which php; copy the resulting path into the designated section in PhpStorm.

   • Save the changes.

   • By this point PhpStorm should have automatically tested the connection and reported the version of the remote PHP interpreter in the guest OS. It will have also named the remote interpreter.

   Notes about the screenshot: There are two windows layered on top of the main preferences window. The foremost one is triggered by clicking the “+” symbol in the middle layer window. That middle layer window is triggered by clicking the “…” button next to the “Interpreter” setting.

The most essential component to debugging PHP applications hosted in a Vagrant box using PhpStorm is now complete.

Create PhpStorm’s debug configuration

This is the last section to follow in order to run a successful debugging session. The Xdebug configuration settings have been defined in the guest OS; PhpStorm on the host OS has been configured to use the right port and allow external connections; the local-to-remote file path mappings have been set up so the IDE knows exactly how to step through any line of code. All that remains is setting up the “Run/Debug Configurations,” and starting the service listener so PhpStorm can actually debug code. The previous steps in this guideline must be completed prior to the next and final section.

The steps for creating the debug configuration are delineated below, followed by a screenshot of the UI where these steps take place.

1. Click on the “Run” toolbar menu option at the top of PhpStorm.

2. The dropdown of options all pertain to debugging code. Click on “Edit Configurations.” A window appears with the relevant settings.

3. The left column lists different types of run and debug configurations. They are kind of like different tool definitions that PhpStorm can implement to analyze code more effectively. Add a new configuration by clicking on the “+” symbol, and select “PHP Web Application.” An “unnamed” tool definition is created. The right column displays its configuration interface.

4. Provide the configuration a “Name.” This can be anything, but for clarity, this guide uses “Vagrant.”

5. The “Server” setting should have the name provided in Step 4 of ‘Add a remote server to the current project’s settings’ earlier in the guide. If it is not an available option in the dropdown, revisit that section of the guide; make sure it is configured properly.

6. The “Start URL” will depend on the application. Many MVC-type frameworks, though, will use the root of the URL, so a / will suffice. That essentially means that the index file of the document root will be used: index.php in most instances.

7. Choose the “Browser” where most development takes place. This is to ensure that the browser will automatically switch to PhpStorm when a breakpoint is reached. Later, the browser will be configured with an addon that simplifies debugging.

8. Save the changes.

Listen for incoming debug connections to PhpStorm from Xdebug

At the top right of PhpStorm should be a toolbar similar to the images provided. With the project open, select “Vagrant” from the dropdown. Remember that this was just defined. It is the “PHP Web Application.” A few buttons over there is a telephone receiver icon with a bug at the mouthpiece and a banned symbol at the earpiece. Click on this. The banned symbol at the earpiece should change into a sort of abstract visualization indicating that PhpStorm is listening for connections.

PhpStorm is ready to accept connections from Xdebug. All that remains is knowing how to trigger them.

Starting a debug session

Xdebug Phpstorm Cli

There are a few methods to start a debug session. PhpStorm provides bookmarklets for this, but they are not ideal. Do not even bother. The best option is one that integrates with a Web browser. Both Firefox and Chrome provide addons for this. It is unnecessary to install each if only one Web browser will be used.

Install an Xdebug addon for Firefox

Install The easiest Xdebug addon for Firefox. It provides only one option: define its “IDE key for remote debugging.” Remember that this guide defined the IDE key as debugit, so use that.

Install an Xdebug addon for Chrome

Install the Xdebug helper addon for Chrome. There are some additional options, but the relevant one for this guide is to define the IDE key. It provides different IDEs to select from—which provide the most common IDE key values for each IDE—as well as an “Other” option. Choose that and type in debugit as the IDE key.

Define a breakpoint in PhpStorm

PhpStorm is already listening for incoming connections, but if a breakpoint is not set, the code will execute to the end without pausing.

Open a file in the project, and click in the empty margin to the left of a line number. A tiny orb will indicate that a breakpoint has been set.

Trigger a debug session from a Web browser

Return to the browser and click on the the debug icon that it provides. That will set a browser cookie with the defined IDE key, which will be read by Xdebug where PHP is running code in the guest OS, as mentioned earlier. In turn, that commands Xdebug to send a request to PhpStorm, which is listening for a connection. Navigate to a page that will be affected by the breakpoint set in PhpStorm, or refresh the page if that has already been done; note that the page appears to hang. That means PhpStorm has paused execution of the PHP script at the designated breakpoint until the code has been stepped through or execution resumed. Return to PhpStorm and look for the file with the set breakpoint. The debuger tab should be visible, with all the variables and constants of the page ready to get populated with data. This is how it should appear:

Notice the $_COOKIE superglobal includes the XDEBUG_SESSION = 'debugit' cookie set by the browser.

Summary of how to configure and run PHP Xdebug in PhpStorm through Vagrant

• Xdebug in the virtual guest OS installed by Vagrant is configured for remote debugging.

• PhpStorm’s debug settings are configured. External connections are allowed through the designated port.

• A remote server is added and defined for PhpStorm. This allows it to know how to communicate with the guest OS in Vagrant. Most importantly, the local-to-remote file path mappings are defined. That allows the files in the guest filesystem to map to the files in the host filesystem, where PhpStorm will step through code.

• A new “PHP Web Application” is created. It points to the server just added.

• Set PhpStorm to start listening for incoming debug connections.

• Install a browser addon to easily trigger debug sessions.

• Set a breakpoint in PhpStorm for the given project.

• Start the debug session in the browser, refresh it, and return to PhpStorm to view the open debugger tab.

Appendix and troubleshooting

• This guide uses CentOS 6.5 as the guest OS, and Mac OSX as the host OS. The steps should not change much or at all if the OS of either is different. For example, the process for a Windows host OS should not be very different.

• The most common IDE key used in PhpStorm is PHPSTORM. The guide uses debugit. It does not matter what key is used, but it should be noted that some debugger tools, like Chrome’s “Xdebug helper” addon, does not provide a text box to define a key if PhpStorm is chosen. It automatically assumes that the key will be PHPSTORM. This is why “Other” was chosen. Another popular IDE, NetBeans, commonly defines the IDE key as netbeans-xdebug.

• If the project contains symlinks to other code being used from other locations, PhpStorm’s debugger tab will complain about missing file path mappings. Make sure any symlinked code is properly mapped with its guest filesystem counterpart in Vagrant.

• The assumption has not been tested, but it is very possible that the steps to configure PHPUnit to work in PhpStorm through Vagrant would be similar.

Other reference material

1. http://xdebug.org/docs/remote#communication

2. http://superuser.com/questions/310697/connect-to-the-host-machine-from-a-virtualbox-guest-os/310745#310745

3. http://confluence.jetbrains.com/display/PhpStorm/Zero-configuration+Web+Application+Debugging+with+Xdebug+and+PhpStorm

Feedback

Did you notice something wrong with this guide? Have you found related material on the Web somewhere? Let me know in the comments. Also, if you know someone who might want to read this, share it with them.

Download Xdebug

• Download the Xdebug extension compatible with your PHP version and install it as described in the installation guide.

  Xdebug 3 brings performance improvements, simplified configuration, and PHP 8 support. To learn more on upgrading to Xdebug 3, see the Upgrade guide.

  If you are using an AMP package, the Xdebug extension may be already installed. Refer to the instructions specific for your package.

Integrate Xdebug with the PHP interpreter

1. 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.

2. To disable the Zend Debugger and Zend Optimizer tools, which block Xdebug, remove or comment out the following lines in the php.ini file:

   zend_extension=<path_to_zend_debugger> zend_extension=<path_to_zend_optimizer>

3. To enable Xdebug, locate or create the [xdebug] section in the php.ini file and update it as follows:

   [xdebug] zend_extension='<path to xdebug extension>' xdebug.remote_enable=1 xdebug.remote_host=127.0.0.1 xdebug.remote_port='<the port (9000 by default) to which Xdebug connects>'

   [xdebug] zend_extension='<path to xdebug extension>' xdebug.mode=debug xdebug.client_host=127.0.0.1 xdebug.client_port='<the port (9003 by default) to which Xdebug connects>'

   In PHP 5.3 and later, you need to use only zend_extension, not zend_extension_ts, zend_extension_debug, or extension.

   To enable multi-user debugging via Xdebug proxies, locate the xdebug.idekey setting and assign it a value of your choice. This value will be used to register your IDE on Xdebug proxy servers.

4. Save and close the php.ini file.

5. Verify Xdebug installation by doing any of the following:

   • In the command line, run the following command:

     The output should list Xdebug among the installed extensions:

   • Create a php file containing the following code:

     <?php phpinfo();

     Open the file in the browser. The phpinfo output should contain the Xdebug section:

Configure Xdebug in PhpStorm

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

2. Check the Xdebug installation associated with the selected PHP interpreter:

   1. On the PHP page, choose the relevant PHP installation from the CLI Interpreter list and click next to the field. The list shows all the PHP installations available in PhpStorm, see Configure local PHP interpreters and Configure remote PHP interpreters.

   2. The CLI Interpreters dialog that opens shows the following:

      • The version of the selected PHP installation.

      • The name and version of the debugging engine associated with the selected PHP installation (Xdebug or Zend Debugger). If no debugger is configured, PhpStorm shows the corresponding message:

   Alternatively, open the Installation Wizard, paste the output of the phpinfo(), and click Analyze my phpinfo() output. Learn more about checking the Xdebug installation in Validate the Configuration of a Debugging Engine.

3. Define the Xdebug behaviour. Click Debug under the PHP node. On the Debug page that opens, specify the following settings in the Xdebug area:

   • In the Debug port field, appoint the port through which the tool will communicate with PhpStorm.

     This must be the same port number as specified in the php.ini file:

     xdebug.remote_port='<the port (9000 by default) to which Xdebug connects>'

     xdebug.client_port='<the port (9003 by default) to which Xdebug connects>'

     By default, Xdebug 2 listens on port 9000. For Xdebug 3, the default port has changed from 9000 to 9003. You can specify several ports by separating them with a comma. By default, the Debug port value is set to 9001,9003 to have PhpStorm listen on both ports simultaneously.

   • To have PhpStorm accept any incoming connections from Xdebug engine through the port specified in the Debug port field, select the Can accept external connections checkbox.

   • Select the Force break at first line when no path mapping specified checkbox to have the debugger stop as soon as it reaches and opens a file that is not mapped to any file in the project on the Servers page. The debugger stops at the first line of this file and Examine/update variables shows the following error message: Cannot find a local copy of the file on server <path to the file on the server> and a link Click to set up mappings. Click the link to open the Resolve Path Mappings Problem dialog and map the problem file to its local copy.

     When this checkbox cleared, the debugger does not stop upon reaching and opening an unmapped file, the file is just processed, and no error messages are displayed.

   • Select the Force break at first line when a script is outside the project checkbox to have the debugger stop at the first line as soon as it reaches and opens a file outside the current project. With this checkbox cleared, the debugger continues upon opening a file outside the current project.

4. In the External connections area, specify how you want PhpStorm to treat connections received from hosts and through ports that are not registered as deployment server configurations.

   • Ignore external connections through unregistered server configurations: Select this checkbox to have PhpStorm ignore connections received from hosts and through ports that are not registered as deployment server configurations. When this checkbox is selected, PhpStorm does not attempt to create a deployment server configuration automatically.

   • Break at first line in PHP scripts: Select this checkbox to have the debugger stop as soon as connection between it and PhpStorm is established (instead of running automatically until the first breakpoint is reached). Alternatively turn on the Run | Break at first line in PHP scripts option from the main menu.

   • Max. simultaneous connections Use this spin box to limit the number of external connections that can be processed simultaneously.

By default, PhpStorm only listens for incoming IPv4 connections. To enable IPv6 support, you need to make adjustments in PhpStorm JVM options:

1. Select Help | Edit Custom VM Options from the main menu.

2. In the .vmoptions file that opens, delete the -Djava.net.preferIPv4Stack=true line.

3. Restart PhpStorm.

Configure Xdebug for using in the On-Demand mode

PhpStorm supports the On-Demand mode, where you can disable Xdebug for your global PHP installation and have it enabled automatically on demand only when you are debugging your command-line scripts or when you need code coverage reports. This lets your command line scripts (including Composer and unit tests) run much faster.

1. Disable Xdebug for command-line scripts:

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

   2. From the PHP executable list, choose the relevant PHP interpreter and click next to it. In the CLI Interpreters dialog that opens, click the Open in Editor link next to the Configuration file: <path to php.ini> file. Close all the dialogs and switch to the tab where the php.ini file is opened.

   3. In the php.ini file, find the [xdebug] section and comment the following line in it by adding ; in preposition:

      ;[xdebug] ;zend_extension = '<path to xdebug extension>'

   4. Open the CLI Interpreters dialog and click next to the PHP executable field. PhpStorm informs you that debugger is not installed:

2. To enable PhpStorm to activate Xdebug when it is necessary, specify the path to it in the Debugger extension field, in the Additional area. Type the path manually or click and select the location in the dialog that opens.

Configure Xdebug for using in the Just-In-Time mode

PhpStorm supports the use of Xdebug in the Just-In-Time (JIT) mode so it is not attached to your code all the time but connects to PhpStorm only when an error occurs or an exception is thrown. Depending on the Xdebug version used, this operation mode is toggled through the following settings:

• Xdebug 2 uses the xdebug .remote_mode setting, which has to be set to jit.

• Xdebug 3 uses the xdebug.start_upon_error setting, which has to be set to yes.

The mode is available both for debugging command-line scripts and for web server debugging.

Depending on whether you are going to debug command-line scripts or use a Web server, use one of the scenarios below.

Command-line scripts

For debugging command-line scripts, specify the custom -dxdebug.remote_mode=jit (for Xdebug 2) or -dxdebug.start_upon_error=yes (for Xdebug 3) directive as an additional configuration option:

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

2. From the PHP executable list, choose the relevant PHP interpreter and click next to it.

3. In the CLI Interpreters dialog that opens, click next to the Configuration options field in the Additional area.

4. In the Configuration Options dialog that opens, click to add a new entry.

   • For Xdebug 2, type xdebug.remote_mode in the Configuration directive field and jit in the Value field.

   • For Xdebug 3, type xdebug.start_upon_error in the Configuration directive field and yes in the Value field.

   When you click OK, you return to the CLI Interpreters dialog where the Configuration options field shows -dxdebug.remote_mode=jit (for Xdebug 2) or -dxdebug.start_upon_error=yes (for Xdebug 3).

Web server debugging

1. From the main menu, choose Run | Web Server Debug Validation.

2. In the Validate Remote Environment that opens, choose the Web server to validate the debugger on.

   • Choose Local Web Server or Shared Folder to check a debugger associated with a local Web server.

     • Path to Create Validation Script: In this field, specify the absolute path to the folder under the server document root where the validation script will be created. For Web servers of the type Inplace, the folder is under the project root.

       The folder must be accessible through http.

     • URL to Validation Script: In this field, type the URL address of the folder where the validation script will be created. If the project root is mapped to a folder accessible through http, you can specify the project root or any other folder under it.

   • Choose Remote Web Server to check a debugger associated with a remote server.

     • Path to Create Validation Script: In this field, specify the absolute path to the folder under the server document root where the validation script will be created. The folder must be accessible through http.

     • Deployment Server: In this field, specify the server access configuration of the type Local Server or Remote Server to access the target environment. For details, see Configure synchronization with a Web server.

       Choose a configuration from the list or click Browse in the Deployment dialog.

3. Click Validate to have PhpStorm create a validation script, deploy it to the target remote environment, and run it there.

4. Open the php.ini file which is reported as loaded and associated with Xdebug.

5. In the php.ini file, find the [xdebug] section.

   Change the value of the xdebug.remote_mode from the default req to jit.

   Change the value of the xdebug.start_upon_error from the default default to yes.

See also Just-In-Time debugging and PHP Exception Breakpoints with PhpStorm and Xdebug

Configure Xdebug running in a Docker container

To configure Xdebug running in a Docker container, provide the Xdebug-specific parameters in the Dockerfile, for example:

In this example, we're modifying /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini providing the remote_enable and remote_host Xdebug parameters.

Note that the xdebug.remote_host value should be replaced with the IP address of the machine where PhpStorm is running, which is accessible from the Docker container. If you are using Docker for Windows or Docker for Mac, you can set xdebug.remote_host to host.docker.internal, which automatically resolves to the internal address of the host, letting you easily connect to it from the container.

In this example, we're modifying /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini providing the mode and client_host Xdebug parameters.

Note that the xdebug.client_host value should be replaced with the IP address of the machine where PhpStorm is running, which is accessible from the Docker container. If you are using Docker for Windows or Docker for Mac, you can set xdebug.client_host to host.docker.internal, which automatically resolves to the internal address of the host, letting you easily connect to it from the container.

Configure Xdebug running on a Vagrant instance

To configure Xdebug running on a Vagrant instance, connect to the Vagrant machine and provide the Xdebug-specific parameters in the php.ini file:

Phpstorm Xdebug Ssh

Note that the xdebug.remote_host value is 10.0.2.2. This is the gateway used in the default Vagrant setup, which allows connecting from the instance to host where PhpStorm is running.

Note that the xdebug.client_host value is 10.0.2.2. This is the gateway used in the default Vagrant setup, which allows connecting from the instance to host where PhpStorm is running.