Introduction#
PhpStorm has many features, and its debugging functionality can be confusing. Here, we will document the process of configuring and using Xdebug debugging in PhpStorm.
Reference link
Preparation#
- Install the Xdebug extension for PHP (configuration differs between versions 2.x and 3.x).
- Install the Xdebug plugin for your browser (using Chrome as an example, requires a VPN) Xdebug Helper
- PhpStorm (current version 2022.1.4, but it should not have a significant impact on the process)
php.ini Xdebug Configuration#
;;;id1 Xdebug 2.x
[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>"
;;;
;;;id1 Xdebug 3.x
[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 my development environment, I use xdebug 2.x (shared folder, local directory mapped to the virtual machine) as an example.
remote_host=192.168.0.* (the local IP address of my personal PC)
remote_port=19000 (default port is 9000) You can customize the port as long as it doesn't conflict.
Additional parameter descriptions:
-
When xdebug is enabled, overload_var_dump is set to 2 by default. However, I prefer the default behavior of var_dump(), so I set it to 0.
xdebug.overload_var_dump=0 -
PhpStorm supports using Xdebug in Just-In-Time (JIT) mode. By default, xdebug.remote_mode is set to "req", which is generally not necessary to modify.
xdebug.remote_mode=jit -
For multi-user debugging using the DBGP proxy:
Official description:
Set xdebug.idekey and specify a value of your choice. This value will be used to register your IDE on the Xdebug proxy server.
Set xdebug.remote_host to dbgp_proxy_hostname_or_ip.
(I haven't tried this myself, as I don't need multi-user debugging. So, based on previous tutorials, this is generally not necessary for regular debugging.)
PhpStorm Configuration#
PhpStorm supports two popular tools for debugging: Xdebug and Zend Debugger. Here, we will focus on Xdebug.
With PhpStorm, you can start a PHP debugging session through the main menu "Run/Debug Configurations" or without using it. The latter method is known as zero-configuration debugging.
Configuring Xdebug in PhpStorm#
First, go to the main menu "File/Settings | PHP > Debug" and configure the Xdebug section.
The main configuration is the debug port in the Xdebug section, which should match the port specified in php.ini. You can also specify multiple ports separated by commas, such as 9000, 9003, 19000.
Other settings can be left as default.
Zero-Configuration Debugging#
In zero-configuration debugging, you don't need to create any debug configurations.
Instead, you manually open the starting page of your PHP application in the browser and activate the debug engine from the browser, while PhpStorm listens for incoming debugger connections.
Activating the Debug Engine in the Browser#
PhpStorm Listening for Incoming Debugger Connections#
Starting the Debug Session#
Reload the page in the browser and return to PhpStorm. A dialog box will appear, select "Accept" as shown in Figure 1.
This will automatically create a server configuration. You can view it in the main menu "File/Settings | PHP > Servers" as shown in Figure 2.
After reloading the page, if the debug mode is still not activated, check the configuration. It may be missing the mapping for the root directory. After manually adding the mapping, set breakpoints and reload the page to enter the debug session, as shown in Figure 3.
Figure 1
Figure 2
Figure 3
Creating Debug Configurations Based on Templates#
Manually Creating a Server Configuration#
As mentioned earlier, zero-configuration debugging automatically creates a server configuration. If it already exists, there is no need to create a new one. Otherwise, create it manually.
(Main menu "File/Settings | PHP > Servers")
Since my environment is in a Linux virtual machine, I need to set up mapping.
- Host: Enter the IP or domain name of the project (if using an IP, make sure to set up the mapping for testing).
- Port: Enter the port number of the project.
- Debugger: Select "Xdebug".
Debugging Using PHP Web Page Configuration (PHP web page)#
From the main menu, select "Run/Edit Configurations".
Click the "+" button in the top left corner and select the template "PHP Web Page" to start the configuration.
After configuring, click the debug button in the top right corner to automatically open the browser and start debugging.
- Select the previously configured server.
- Starting page: This depends on your project, but usually it is set to "/" by default.
- Browser: Choose according to your preference.
Debugging Using PHP Remote Debug Configuration (PHP Remote Debug)#
From the main menu, select "Run/Edit Configurations".
Click the "+" button in the top left corner and select the template "PHP Remote Debug" to start the configuration.
After configuring, click the debug button in the top right corner to start the debug session.
You need to manually open the website and set up the xdebug plugin in your browser.
Right-click the xdebug icon, expand the dropdown menu, and click "Options". Select "phpstorm" as the IDE key.
Now you can start debugging.
- Select the previously configured server.
- IDE Key (Session ID): Customize this value. Usually, "PHPSTORM" is used to match the IDE key in the xdebug plugin for the browser.
Configuration Window
Browser xdebug Plugin Options Configuration
Summary#
- Zero-Configuration Debugging
Simply enable the debug switch in the top right corner and enable the xdebug plugin in the browser.
Reload the webpage to enter the debug session (and it will automatically create a server configuration).
- PHP Web Page Debugging
Manually create a server configuration.
Click the debug button in the top right corner to automatically open the webpage.
An IDE key in the form of a number will be automatically created.
- PHP Remote Debugging
Manually create a server configuration.
Click the debug button in the top right corner and manually open the webpage.
The preset IDE key needs to match the IDE key in the xdebug plugin for the browser.