PhpStorm 2018.2 Help

Troubleshooting common PHP debugging issues

This section provides the list of solutions and workarounds for common problems with Debugging in PhpStorm.

Collecting debugging logs

If your issue is not addressed in this section, contact our support engineers. If asked to provide deployment logs, follow the instructions to collect them.

To collect debugging logs

  1. Select Help | Configure Debug Log in the main menu.

  2. In the Custom Debug Log Configuration dialog that opens, add the following lines depending on the issues you are experiencing:
    • Issues with PHP debugging: #com.jetbrains.php.debug

    ps collect debugging logs
  3. Click OK and reproduce the issue.

  4. Locate the log file by selecting Help | Show Log in Explorer (for Windows and Linux) or Help | Show Log in Finder (for macOS).

    If necessary, you can locate the log manually:

    Syntax
    %HOMEPATH%\.<product><version>\system\log
    Example
    C:\Users\JohnS\.PhpStorm2018.2\system\log
    Syntax
    ~/Library/Logs/<product><version>
    Example
    ~/Library/Logs/PhpStorm2018.2
    Syntax
    ~/.<product><version>/system/log
    Example
    ~/.PhpStorm2018.2/system/log

    The most recent log file is named idea.log; older files names end with a number, i.e. idea.log.1, idea.log.2, and so on. In most cases you need only the most recent one.

  5. Attach the log file(s) to the issue or forum thread.

Collecting Xdebug logs

When using Xdebug, it is possible to make it log its actions.

  1. In the Settings/Preferences dialog (Ctrl+Alt+S), select PHP under Languages & Frameworks.

  2. From the PHP executable list, choose the relevant PHP interpreter and click browseButton 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, enable xdebug.remote_log by adding the following line:

    xdebug.remote_log=path_to_log/xdebug.log

    The log file contains the raw communication between PhpStorm and Xdebug as well as any warnings or errors:

    Log opened at 2018-01-08 08:14:28 I: Connecting to configured address/port: 127.0.0.1:9000. I: Connected to client. :-) -> <init xmlns="urn:debugger_protocol_v1" xmlns:xdebug="http://xdebug.org/dbgp/xdebug" fileuri="file:///C:/Projects/Samples/DebuggingTutorial/debugging.php" language="PHP" protocol_version="1.0" appid="3040" idekey="11774"><engine version="2.2.5"><![CDATA[Xdebug]]></engine><author><![CDATA[Derick Rethans]]></author><url><![CDATA[http://xdebug.org]]></url><copyright><![CDATA[Copyright (c) 2002-2018 by Derick Rethans]]></copyright></init> <- step_into -i 5 -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="http://xdebug.org/dbgp/xdebug" command="step_into" transaction_id="5" status="break" reason="ok"><xdebug:message filename="file:///C:/Projects/Samples/DebuggingTutorial/debugging.php" lineno="2"></xdebug:message></response>

Making sure Xdebug or Zend Debugger are installed and configured

To debug PHP code with PhpStorm, make sure that you have a debugging engine, either Xdebug or Zend Debugger, installed and configured properly.

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 validate the debugging engine configuration, perform the steps described in Validating the Configuration of a Debugging Engine

Startup warnings and errors preventing the debugger from working

When running PHP, it can happen that a startup warning or error is displayed. When this is the case, the debugger may fail to work. PhpStorm will also not be able to recognize the debugger being used.

To verify that no startup warnings or errors are displayed, run the following command:

php --version

This will return a message similar to the following:

<some error/warning> PHP 7.1.20 (cli) (built: Jul 20 2018 10:27:12) ( NTS ) Copyright (c) 1997-2018 The PHP Group Zend Engine v3.1.0, Copyright (c) 1998-2018 Zend Technologies with Zend OPcache v7.1.20, Copyright (c) 1999-2018, by Zend Technologies with Xdebug v2.6.0, Copyright (c) 2002-2018, by Derick Rethans

If any errors or warnings are present on the first lines, it's recommended to fix them before continuing.

The debugger cannot connect

When the debugger can not connect or refuses the connection, check the following:

  • Make sure Xdebug or Zend Debugger are configured to connect to the host and port PhpStorm is running on.

  • In the Settings/Preferences dialog (Ctrl+Alt+S), navigate to Languages & Frameworks | PHP | Debug and make sure PhpStorm and Xdebug / Zend Debugger are configured with the same port numbers.

  • In PhpStorm, enable listening to incoming debug connections by either clicking php icons debug listen off on the toolbar or selecting Run | Start Listening for PHP Debug Connections in the main menu. This will ensure PhpStorm reacts when a debugging session is started and opens the Debug tool window automatically. Before launching the script, make sure that either a breakpoint is set or the Break at first line in PHP scripts option is enabled on the Debug page of the Settings/Preferences dialog (Ctrl+Alt+S).

  • Verify no firewall, router or ISP is blocking the connection. This can be verified by running telnet host 9000 (for Xdebug) or telnet host 10137 (for Zend Debugger) from remote server (where host is an IP address of your local machine running PhpStorm) and checking a connection is established. You can use http://www.canyouseeme.org or a similar service to check for opened inbound ports.

  • Make sure that xdebug.remote_host (for Xdebug) or zend_debugger.allow_hosts (for Zend Debugger) are properly configured. The value can be a host name (e.g., localhost) or an IP address of the machine where PhpStorm is running, and it must be pingable from the server. When using Xdebug, xdebug.remote_connect_back can be used for troubleshooting.

Remote file path is not mapped to any file path in project

In some cases, the debugger can connect, but we get the error messages indicating that no mapping between the remote and project files is defined. This means that PhpStorm cannot determine which local file corresponds to the file being debugged.

ps debug no mapping

We can solve this problem by clicking Click to set up path mappings and providing the necessary path mappings.

Path mappings are used when the paths to the files processed by the server differ from the paths to the files in the PhpStorm project. This happens in the following cases:

  • The server is remote and the project files are local copies of the originals.

  • The files processed by the server and the files opened in the IDE are the same, but symlinks are used. Because the debugger resolves symlinks during a debugging session, you need to tell the IDE actual solute physical paths to the files on the server.

To configure path mappings, in the Settings/Preferences dialog (Ctrl+Alt+S), navigate to Languages & Frameworks | PHP | Debug.

ps php debug server mappings

If the files that the server processes are in the project and you are not using symlinks, clear the Use path mappings checkbox. In this case, the IDE will open files according to the paths received from the debugger.

A path mapping specified for a parent directory is automatically applied to all its subdirectories. If necessary, path mappings for any subdirectory or file can be specified.

See Configuring Synchronization with a Web Server for more details.

Breakpoints are not being hit

When breakpoints are not being hit but the debugger seems to connect, verify the following:

  • Verify the breakpoint is not disabled. Using the Run | View Breakpoints... menu command (Ctrl+Shift+F8 ), check that breakpoints are enabled. Select the checkbox next to a breakpoint to enable it.

  • Make sure that path mappings are correct .

  • On macOS X, when a file or folder is renamed using Finder and the letter case is changed, PhpStorm may not be able to find the files. If renaming is required, make sure to do it in the IDE or using a terminal and the mv command. Renaming project files or folders using Finder may result in strange behaviour. See here for more details.

  • There are some rare cases when breakpoints can't be hit due to technical limitations, e.g. caused by the way how PHP generates byte-code. See here for more details.

When using Xdebug, you can use the xdebug_break() function to force a breakpoint from within PHP. When Xdebug encounters this function during execution, it will pause at the next statement in the IDE even if no breakpoint was defined there originally.

The debugger does not work when using nginx

When using the nginx web server, debugging may fail if the $_SERVER["SERVER_NAME"] is not provided by PHP. To solve this, add a fastcgi parameter to the nginx configuration:
fastcgi_param SERVER_NAME $server_name;

or

fastcgi_param SERVER_NAME $host;
Refer to the nginx documentation and see here for additional details.

XDebug cannot connect to PhpStorm

If you see the following messages in XDebug log:

Log opened at 2017-02-21 17:52:27 I: Connecting to configured address/port: 172.19.0.1:9000. W: Creating socket for '172.19.0.1:9000', poll success, but error: Operation now in progress (29). E: Could not connect to client. :disappointed: Log closed at 2017-02-21 17:52:27

or

Log opened at 2017-02-22 13:17:13 I: Connecting to configured address/port: 10.10.10.10:9000. E: Time-out connecting to client. :-( Log closed at 2017-02-22 13:17:14

This means that XDebug tries to connect to the host and can't make the connection. To fix the issue, set xdebug.remote_connect_back=0 and make sure that xdebug.remote_host is set correctly.

Zend Debugger will not perform dropping of privileges

When using Zend Debugger on Linux, you may occasionally see the following error:

Zend Debugger: Cannot read a valid value of zend_debugger.httpd_uid or zend.httpd_uid, will not perform dropping of privileges

This error occurs when the debugger can not determine the UID of the user running the web server process. Find the UID of that user and add it to php.ini:

zend_debugger.httpd_uid=1234

After updating the setting, restart the web server.

Debugging with ionCube installed

In some PHP environments, ionCube is used to load and run the encoded PHP code. The ionCube loader extension does this by decoding the PHP code that is to be run and then making sure the PHP interpreter can execute it.

Officially, neither Xdebug nor Zend Debugger support running with ionCube enabled, however there are some workarounds to try. Note that these are not supported by JetBrains, ionCube, Xdebug or Zend Debugger.

  • Make sure the ionCube loader module is loaded first

    In php.ini, verify the ionCube loader is loaded before any debugger extension is loaded, for example:

    zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/ioncube_loader_lin_5.4.so zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so
  • Use ionCube on-demand loading

    We can disable the ionCube extension in php.ini and make use of ionCube's on-demand loading feature. When the first encoded PHP script is loaded, the PHP interpreter will check the configured extenson_dir to find the ionCube extension and run the encoded PHP script.

    Note that this method is not officially supported. It should only be used for debugging purposes and never on a production server.

Last modified: 10 October 2018