PhpStorm 2016.2 Help

Zero-Configuration Debugging

On this page:

Overview

In case of zero-configuration debugging, you do not need to create any debug configuration. Instead, you open the starting page of your PHP application in the browser manually, and then activate the debugging engine from the browser, while PhpStorm listens to incoming debugger connections.

To enable starting and stopping the debugging engine from the browser manually, you need to set a special GET/POST or COOKIE parameter. You can do it manually in the php.ini configuration file or generate the Start Debugger/Stop Debugger bookmarklets on the toolbar of your browser. These bookmarklets provide control over the debugger cookie, through them you will activate and deactivate the debugger.

For more details about setting the parameters manually, see Starting the Debugger for Xdebug and Zend Debugger GET Request Parameters for Zend Debugger.

You can also specify the scripts requests to which you want PhpStorm to ignore during debugging. This approach can be useful, when your application contains scripts that use AJAX. Suppose you have a menu-ajax-script.php that "reloads" a part of your web page. This script works properly so you do not need to debug it. However, this script is still requested during the debugging session. To have incoming connections to this script ignored, add the menu-ajax-script.php script to the skipped paths list. You can also group such scripts into folders and add these folders to the "ignore list".

Preparing the debugging engine

Before you start debugging, make sure that you have a debugging engine installed and configured properly. PhpStorm supports debugging with two most popular tools: Xdebug and Zend Debugger. These tools cannot be used simultaneously because they block each other. To avoid this problem, you need to update the corresponding sections in the php.ini file as described in Configuring Xdebug and Configuring Zend Debugger.

To open the active php.ini file in the editor:

  1. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or PhpStorm | Preferences for OS X, and click PHP under Languages&Frameworks.
  2. On the PHP page that opens, click browseButton.png next to the Interpreter field.
  3. In the Interpreters dialog box that opens, the Configuration File read-only field shows the path to the active php.ini file. Click Open in Editor.

For more information on configuring debugging engines, see Xdebug Installation Guide and Zend Debugger Installation Guide.

Setting the breakpoints

Breakpoints are source code markers used to trigger actions during a debugging session. Typically, the purpose behind setting a breakpoint is to suspend program execution to allow you to examine program data. However, PhpStorm can use breakpoints as triggers for a variety of different actions. Breakpoints can be set at any time during the debugging process. Your breakpoints don't affect your source files directly, but the breakpoints and their settings are saved with your PhpStorm project so you can reuse them across debugging sessions.

  1. Place the caret on the desired line of the source code.

    Breakpoints can be set in the PHP context inside *.php, *.html, and files of other types. Only executable lines are valid locations for line breakpoints. Comments, declarations, and empty lines are not valid locations for the

  2. Do one of the following:
    • Click the left gutter area at a line where you want to toggle a breakpoint.
    • On the main menu, choose Run | Toggle Line Breakpoint.
    • Press Ctrl+F8.

Generating the Start Debugger/Stop Debugger bookmarklets

These bookmarklets will appear on the toolbar of your browser. They provide control over the debugger cookie, through them you will activate and deactivate the debugger.

  1. Enable the Bookmarks toolbar in your browser by doing one of the following depending on the browser type:
    • In Firefox, choose View | Toolbar | Bookmarks Toolbar.
    • In Chrome, choose Bookmarks | Show bookmarks bar.
  2. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or PhpStorm | Preferences for OS X. Expand the Languages&Frameworks node, and then click Debug under PHP.
  3. On the Debug page, that opens, click the Use debugger bookmarklets to initiate debugger from your favorite browser link.
  4. On the Zend Debugger & Xdebug bookmarklets page that opens, check the debugging engine settings and click Generate. The bookmarks for listed debugging-related actions are generated.
  5. Drag the generated links to the bookmark toolbar in your browser.

Initiating a debugging eession and examining the suspended program

  1. Generate the bookmarklets to toggle the debugger through. These bookmarklets will appear on the toolbar of your browser. They provide control over the debugger cookie, through them you will activate and deactivate the debugger.
    1. Enable the Bookmarks toolbar in your browser by doing one of the following depending on the browser type:
      • In Firefox, choose View | Toolbar | Bookmarks Toolbar.
      • In Chrome, choose Bookmarks | Show bookmarks bar.
    2. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or PhpStorm | Preferences for OS X. Expand the Languages&Frameworks node, and then click Debug under PHP.
    3. On the Debug page, that opens, click the Use debugger bookmarklets to initiate debugger from your favorite browser link.
    4. On the Zend Debugger & Xdebug bookmarklets page that opens, check the debugging engine settings and click Generate. The bookmarks for listed debugging-related actions are generated.
    5. Drag the generated links to the bookmark toolbar in your browser.
  2. Set the breakpoints, where necessary.
  3. Toggle the Start Listen PHP Debug Connections button start_listening_php_debug_connections.png so it changes to stop_listening_php_debug_connections.png. After that PhpStorm starts listening to the port of the debugging engine used in the current project. Ports for debuggers are set at the PhpStorm level in the Debug dialog box (File | Settings | PHP | Debug for Windows and Linux or PhpStorm | Preferences | PHP | Debug for OS X).
  4. Open the starting page of your application in the browser, choose the Start debugger bookmark to activate the debugging engine from the browser, re-load the current page (the starting page of the application), and then return to PhpStorm.
  5. As soon as the debugger suspends on reaching the first breakpoint, examine the application by analyzing frames. A frame corresponds to an active method or function call and stores the local variables of the called method or function, the arguments to it, and the code context that enables expression evaluation. All currently active frames are displayed on the Frames pane of the Debug tool window. where you can switch between them and analyze the information stored therein in the Variables and Watches panes. For more details, see the section Examining Suspended Program.
  6. 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 details, see Stepping Through the Program.
    • To have the program run automatically up to the next breakpoint, resume the session by choosing Run | Resume Program or pressing F9

Troubleshooting

During a debugging session you may encounter one of the following problems:

No Path Mappings are Configured

In some cases you may get one of the following error messages: Remote file path path/to/script/on/the/server.php is not mapped to any file path in project or The script path/to/script/on/the/server.php is outside the project. This means that PhpStorm is not sure which local file corresponds to the specified remote file path because you have not specified the path mappings in the Debug server configuration.

Even if path mappings in a Debug Server configuration look very similar to path mappings in a Deployment configuration, they cannot be reused, because Deployment configurations require paths to be relative, and Debug Server configurations rely on absolute paths.

Click the link and configure path mappings in the dialog box that opens, as described in Creating a PHP Debug Server Configuration.

No Debug Server is Configured

If you initiate a debugging session without having configured a Debug server, upon establishing connection PhpStorm displays the Incoming Connection Dialog where suggests importing mappings from a server access configuration (deployment configuration). If you choose Import mappings from deployment, PhpStorm tries to detect the most suitable deployment configuration, preselects it in the Deployment drop-down list, and the Preview area shows the absolute path to the project file which corresponds to the currently executed script according to the mappings from the selected configuration.

If PhpStorm does not detect a relevant configuration:

  1. Choose the most suitable configuration from the drop-down list or click browseButton and create a new configuration in the Deployment dialog box that opens, whereupon the new configuration is added to the list.
  2. In the Deployment root text box, type the absolute path to the server root folder

You can also select the Manually choose local file or project option, in this case PhpStorm displays the project tree view where you can select a project file and map the currently executed script to it. You can also select and map the entire project.

To continue debugging with the imported or manually specified configuration settings, click Accept.

A Script Is not Suspended

Establishing a Zero-Configuration debugging session may fail, with no breakpoints hit and therefore the script not suspended. This may happen if if the path mappings are not configured or configured erroneously, or if you have not set any breakpoints. In the latter case, enabling selecting the Break at First Line in PHP Scripts check box in the External Connections area or turning the Run | Break at First Line in PHP Scripts option on the main menu may also help.

To have PhpStorm display a notification if the script is not suspended, select the Notify if debug session was finished without being stopped check box in the Advanced Settings area on the Debug page of the Settings dialog box.

Specifying the scripts to skip requests to

This approach can be useful, when your application contains scripts that use AJAX. Suppose you have a menu-ajax-script.php that "reloads" a part of your web page. This script works properly so you do not need to debug it. However, this script is still requested during the debugging session. To have incoming connections to this script ignored, add the menu-ajax-script.php script to the skipped paths list. You can also group such scripts into folders and add these folders to the "ignore list".

  1. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or PhpStorm | Preferences for OS X. Expand the PHP node under Languages & Frameworks, and then click Skipped Paths under Debug.
  2. On the Skipped Paths page that opens, configure an "ignore list" of scripts and folders with scripts not to be invoked if PhpStorm receives incoming connections to them.
    • To add a new entry to the list, click the Add button add.png or press Alt+Insert. Then click the Browse button browseButton.png and in the dialog box that opens choose the file or folder to skip connections to.
    • To remove an entry from the list, select it and click the Remove button delete.png or press Alt+Delete. The script will be now executed upon receiving requests to it.
  3. To have PhpStorm inform you every time it receives a request to a script to be skipped, select the Notify about skipped paths check box.

Starting a debugging session from the command line

You can start debugging a PHP CLI script from the command line, having PhpStorm listen for incoming debugger connections.

  1. Set the breakpoints where necessary.
  2. On the toolbar, toggle the Start Listening for PHP Debug Connections button or choose Run | Start Listening for PHP Debug Connections on the main menu.
  3. Start the script with debugger options depending on the debugging engine you are using - Xdebug or Zend Debugger.

Starting a Script with Xdebug

Xdebug has various configuration options which can be used to let the PHP interpreter reach out to PhpStorm. These parameters have to be passed to the PHP interpreter using the -d command line switch. A more convenient is to set an environment variable you do not need to provide the -d switches all the time.

Do one of the following:

  • Launch PHP with several switches:
    php -dxdebug.remote_enable=1 -dxdebug.remote_mode=req -dxdebug.remote_port=9000 -dxdebug.remote_host=127.0.0.1 -dxdebug.remote_connect_back=0 path/to/script.php
  • Set an environment variable that configures Xdebug:
    • set XDEBUG_CONFIG="remote_enable=1 remote_mode=req remote_port=9000 remote_host=127.0.0.1 remote_connect_back=0" for Windows
    • export XDEBUG_CONFIG="remote_enable=1 remote_mode=req remote_port=9000 remote_host=127.0.0.1 remote_connect_back=0" for Linux and OS X

Starting a script with Zend Debugger

Zend Debugger has various configuration options which can be used to let the PHP interpreter reach out to PhpStorm. These parameters have to be passed to the PHP interpreter using an environment variable:

  • set QUERY_STRING="start_debug=1&debug_host=127.0.0.1&no_remote=1&debug_port=10137&debug_stop=1" for Windows
  • export QUERY_STRING="start_debug=1&debug_host=127.0.0.1&no_remote=1&debug_port=10137&debug_stop=1" for Linux and OS X

Configuring path mappings

To tell PhpStorm which path mapping configuration should be used for a connection from a certain machine, set the value of the PHP_IDE_CONFIG environment variable to serverName=SomeName, where SomeName is the name of the debug server configuration defined on the Servers page, see Creating a PHP Debug Server Configuration. Depending on the operating system you are using, set the value in one of the following formats:

  • set PHP_IDE_CONFIG="serverName=SomeName" for Windows
  • export PHP_IDE_CONFIG="serverName=SomeName" for Linux and OS X

Troubleshooting

  • The debug server configuration is not specified through the PHP_IDE_CONFIG environmanet variable. In this case, PhpStorm detects the host and port from $_SERVER['SSH_CONNECTION'] and suggests to create a new debug server configuration if it doesn't exists. This works for all connections through ssh even without a tunnel.
  • The debug server configuration is not specified through the PHP_IDE_CONFIG environment variable and $_SERVER['SSH_CONNECTION'] is not defined. In this case, a warning is displayed with a link to the instruction in specifying the debug server configuration through the PHP_IDE_CONFIG environment variable.
  • The debug server configuration is specified through the PHP_IDE_CONFIG environment variable but a wrong format is used, PhpStorm displays an error message with the instructions.
  • The PHP_IDE_CONFIG environment variable is configured properly, but the specified debug server configuration does not exist, PhpStorm displays a warning with a link to the Servers page.

See Also

Last modified: 24 November 2016