PhpStorm 2024.2 Help

Debugging with PhpStorm

Quick start

Below is a quick-start guide to using PhpStorm and Xdebug 3 for debugging PHP applications that run on a local or remote web server.

Xdebug and PhpStorm quick start

For other debugging scenarios such as debugging PHP tests or remote debugging via SSH, see Debugging scenarios.

1. Install Xdebug

The Xdebug debugging engine is an extension for PHP, so it is installed to PHP on the local or remote web server where your application runs. To install Xdebug:

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

    If you are using a preconfigured AMP (Apache, MySQL, PHP) package, the Xdebug extension may be already installed. Refer to the instructions specific for your package.

  2. Edit the relevant php.ini file to integrate Xdebug with the PHP engine:

    1. Disable the Zend Debugger and Zend Optimizer tools which block Xdebug. To do so, remove or comment out the following lines in the php.ini file:

      zend_extension=<path_to_zend_debugger> zend_extension=<path_to_zend_optimizer>
    2. Enable Xdebug. To do so, locate or create the [xdebug] section in the php.ini file and update it as follows:

      [xdebug] zend_extension=xdebug xdebug.mode=debug xdebug.client_host=localhost xdebug.client_port=9003
      • zend_extension: the setting indicating that the Xdebug debugging engine shall be used. Set to xdebug or use the full path to the xdebug.so file, such as /usr/lib/php/20190902/xdebug.so.

      • xdebug.mode: the setting controlling which Xdebug features are enabled. Set to debug for debugging.

      • xdebug.client_host: the IP address or hostname at which PhpStorm is running and listening for incoming connections from Xdebug. For example, localhost or 127.0.0.1 if Xdebug and PhpStorm run on the same machine. Xdebug only supports connecting to a single IP address, however, you can use a DBGp proxy to debug PHP applications in multiuser environments.

      • xdebug.client_port: the port to which Xdebug tries to connect on the host where PhpStorm runs. The default port is 9003.

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

    • In the command line, run the following command:

      php --version

      The output should list Xdebug among the installed extensions:

      Xdebug extension installed
    • Create a php file containing the following code:

      <?php phpinfo();

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

      Xdebug 3 support enabled
    • Use PhpStorm (Run | Web Server Debug Validation in the main menu) to validate the installation and configuration of Xdebug on your web server and get suggestions for fixing the inconsistencies if there are any. For details, see Validate the configuration of a debugging engine.

      Xdebug config check

2. Add a debugging extension to the web browser

The easiest way to instruct the web server to activate the debugger is to use a browser extension.

  1. Choose and install the browser extension suitable for your browser — for example, Xdebug helper for Chrome.

    For more options and details, see Browser debugging extensions.

  2. Open the application URL in the browser and activate the browser extension.

    Xdebug helper in Chrome

3. Configure PhpStorm to listen to incoming connections

  1. Check that the Debug port setting in Settings Ctrl+Alt+S | PHP | Debug | Xdebug corresponds to the port configured on the debbuger side. The defualt value is 9003.

    Additionally, you can customize other Xdebug settings in PhpStorm as described in define Xdebug behaviour.

  2. On the PhpStorm toolbar, toggle the Start Listening for PHP Debug Connections button to start listening for incoming PHP debug connections, or choose Run | Start Listening for PHP Debug Connections from the main menu.

    Start listening to incoming Xdebug connections

4. Start a debugging session

  1. Open the application development project in PhpStorm and set a breakpoint in code. Breakpoints can be set in the PHP context inside PHP, HTML, TWIG, BLADE, and files of other types.

    • Line breakpoints can be set by clicking the gutter at the executable line of code.

      Line breakpoint
    • Conditional breakpoints are hit only when the specified condition, such as a specific item in the loop, is met. To specify a condition, set a line breakpoint and right-click it to open the breakpoint settings dialog.

      Hitting a conditional breakpoint
    • With exception breakpoints, the debugger suspends execution of the application code when an exception or an error is thrown or when a PHP notice or warning is emitted. To set an exception breakpoint, see Debug with PHP exception breakpoints.

      Hitting an exception breakpoint

    Alternatively, select Run | Break at first line in PHP scripts to have the debugger stop as soon as connection with PhpStorm is established (instead of running automatically until the first breakpoint is reached).

  2. Back in the browser, reload the application page to start the debugging session and return to PhpStorm.

    As soon as PhpStorm detects a new incoming connection from Xdebug, it displays an Incoming Connection From Xdebug dialog.

    Incoming debugger connection Xdebug

    In the Incoming Connection From Xdebug dialog, select the path mappings so that PhpStorm can map the remote files on the web server to the local files in your project. If you have a deployment configuration defined, PhpStorm will offer configuring the mappings based on the paths you've already set in that configuration.

5. Examine the program state

  1. After reaching the breakpoint, the debugger is suspended. You can now investigate the application in PhpStorm's Debug tool window.

    Application stopped at breakpoint

    For more information about examining the program data (frames, variables, and so on), see Examine a suspended program.

  2. Continue running the program and examine its frames as soon as it is suspended again.

    • To control the program execution manually, step through the code using the commands under the Run menu or toolbar buttons: Step Into F7, Step Out Shift+F8, Step Over F8, and others. For more information, refer to Step through the program.

    • To have the program run automatically up to the next breakpoint, resume the session by choosing Run | Debugging Actions | Resume Program or pressing F9.

Debugging scenarios

The following topics will assist you in exploring debugging scenarios in PhpStorm:

Zero-configuration debugging

The debugging scenario described in this Quick start guide uses the so-called zero-configuration debugging approach, which means that you do not need to create a run/debug configuration like you would for running or testing PHP applications in PhpStorm.

If you want to run debugging sessions using run/debug configurations, see Debug with a PHP web page debug configuration.

Debugging a PHP CLI script

Besides running and debugging an entire application on the web server, you may want to debug a specific PHP script in PhpStorm, or run a PHPUnit, Behat, or other test with the debugging engine attached.

In this case, the debugging engine is set up together with the local or remote PHP interpreter configured in PhpStorm.

For more information, see Debug a PHP CLI script.

Debugging PHP framework CLI commands
Simultaneous debugging sessions

When building web applications with multiple tiers, you can have frontend PHP code calling into backend PHP code. Simultaneous debugging sessions describes several ways to step from front-end code into back-end code and debug them simultaneously.

Multiuser debugging via Xdebug proxies

Xdebug only supports connecting to a single IP address at which your PhpStorm IDE is running. To debug PHP applications in multiuser environments, see Multiuser debugging via Xdebug proxies.

Remote debugging via SSH tunnel

Remote debugging via SSH tunnel describes how to use an SSH tunnel to establish a secure connection between Xdebug and PhpStorm when they run on different machines, and direct connection between the two machines is not possible.

Troubleshooting

See Troubleshooting common PHP debugging issues for the description of some common configuration issues and learn how to troubleshoot them.

Last modified: 02 August 2024