Troubleshooting Common PHP Debugging Issues in PhpStorm

Debugging PHP code effectively within PhpStorm is crucial for efficient development. While PhpStorm provides robust debugging tools, encountering issues is not uncommon. This article serves as a comprehensive guide to troubleshoot and resolve common problems you might face while debugging PHP in PhpStorm.

For users to fully leverage PhpStorm’s debugging capabilities, a valid license is essential, ensuring access to all features, including seamless debugging functionality. While the focus here is on troubleshooting technical aspects, ensuring your PhpStorm is properly activated is a foundational step for a smooth development experience. For information on PhpStorm activation, refer to official JetBrains resources.

This guide will walk you through various debugging challenges, from collecting necessary logs to resolving connection problems and breakpoint issues. Whether you are new to debugging or an experienced developer, this article aims to provide practical solutions and workarounds to get your debugging sessions back on track.

Collecting PhpStorm Debugging Logs

When encountering a debugging issue that isn’t immediately clear, consulting PhpStorm’s debug logs can provide valuable insights. These logs record internal processes and can help pinpoint the source of the problem. If you need to reach out to JetBrains support, these logs are often requested to assist in diagnosing your issue.

Steps to Collect Debugging Logs:

Enable Debug Logging: Navigate to Help | Diagnostic Tools | Debug Log Settings in the PhpStorm main menu.
Specify Log Categories: In the “Custom Debug Log Configuration” dialog, add #com.jetbrains.php.debug to capture logs related to PHP debugging. You might add other categories depending on the specific issue.

Collect logs
Reproduce the Issue: Click “OK” and then replicate the debugging problem you are experiencing. This ensures the relevant events are logged.
Locate the Log File: Access the log directory by going to Help | Show Log in Explorer (Windows/Linux) or Help | Show Log in Finder (macOS).

Alternatively, you can manually find the logs in these directories:
- Windows: %USERPROFILE%AppDataLocalJetBrains<PhpStorm version>log (e.g., C:UsersJohnSAppDataLocalJetBrainsPhpStorm2024.3log)
- macOS: ~/Library/Logs/JetBrains/<PhpStorm version> (e.g., ~/Library/Logs/JetBrains/PhpStorm2024.3)
- Linux: ~/.local/share/JetBrains/<PhpStorm version> (e.g., ~/.local/share/JetBrains/PhpStorm2024.3)
The idea.log file is the most recent log. Older logs are archived as idea.log.1, idea.log.2, etc. Usually, the latest idea.log is sufficient.
Share Logs: Attach the log file(s) when reporting an issue on the JetBrains issue tracker or in their community forums.

Collecting Xdebug Logs

If you are using Xdebug for debugging, Xdebug itself can generate logs detailing its operations. These logs can be invaluable for understanding the communication between PhpStorm and Xdebug and diagnosing issues at the debugger level.

Access PHP Configuration: Open PhpStorm settings (Ctrl+Alt+S) and navigate to PHP.
Edit php.ini: Choose your configured PHP interpreter from the “PHP executable” list and click the settings icon next to it. Select “Open in Editor” next to the “Configuration file” path in the “CLI Interpreters” dialog. This will open your php.ini file in PhpStorm.
Enable Xdebug Logging: In php.ini, add the following line to enable Xdebug logging. Choose either xdebug.log or xdebug.remote_log based on your Xdebug version and logging needs:
```
xdebug.log="path_to_log/xdebug.log"
```
or
```
xdebug.remote_log="path_to_log/xdebug.log"
```
Replace "path_to_log/xdebug.log" with the actual path where you want to save the Xdebug log file (e.g., /tmp/xdebug.log, C:xdebug.log). Ensure the web server process has write permissions to this location.

The Xdebug log will contain raw communication details between PhpStorm and Xdebug, along with any warnings or errors encountered by Xdebug.
```
Log opened at 2018-01-08 08:14:28
I: Connecting to configured address/port: 127.0.0.1:9000.
I: Connected to client. :-) ->
```

Verifying Xdebug or Zend Debugger Installation and Configuration

PhpStorm relies on a debugging engine, either Xdebug or Zend Debugger, to debug PHP code. Ensure that one of these debuggers is correctly installed and configured in your PHP environment.

Important: Xdebug and Zend Debugger are incompatible and cannot be used simultaneously. You must configure your php.ini to use only one. Refer to the PhpStorm documentation on Configuring Xdebug and Configuring Zend Debugger for detailed instructions.

To check if your chosen debugging engine is properly configured, follow the validation steps outlined in Validate the configuration of a debugging engine.

Resolving Startup Warnings and Errors

PHP startup warnings or errors can disrupt the debugger’s functionality, preventing PhpStorm from recognizing the active debugger.

To check for startup issues, execute the following command in your terminal:

php --version

Examine the output. A clean output should resemble:

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 warnings or errors appear before the PHP version information, address them before proceeding with debugging. Common causes include incorrect extension paths or conflicts in your php.ini configuration.

Debugger Connection Problems

If the debugger fails to connect or refuses connections, consider these common scenarios:

“No Debug Server is Configured” Message

When initiating a Zero-configuration debugging session for the first time, and no Debug server is set up in PhpStorm, the “Incoming Connection” dialog will appear. This dialog prompts you to import mappings from a server access configuration (deployment configuration).

Import Mappings: Choosing “Import mappings from deployment” instructs PhpStorm to find a suitable deployment configuration. If found, it will be preselected in the “Deployment” list, and the “Preview” area will show the server path corresponding to the executed script based on the configuration’s mappings.
No Configuration Detected: If PhpStorm cannot find a relevant deployment configuration:
1. Select or Create Configuration: Choose the most appropriate existing configuration from the list or click “…” to open the “Deployment” dialog and create a new one. The new configuration will be added to the list.
2. Specify Deployment Root: In the “Deployment root” field, enter the absolute path to the server’s root directory.
Alternatively, you can select “Manually choose local file or project.” This option displays your project tree, allowing you to manually map the executed script or the entire project to a local file or project directory.

Click “Accept” to proceed with debugging using the chosen configuration.

“Remote file path is not mapped to any file path in project” Error

This error indicates that the debugger connected, but PhpStorm cannot associate the remote file being debugged with a local file in your project.

No folder mapping is specified

Solution: Click the “Click to set up path mappings” link in the error message. This will open the PHP Servers settings where you can define path mappings.

When are Path Mappings Necessary?

Path mappings are essential when the file paths on your server differ from those in your PhpStorm project. This typically occurs in these situations:

Remote Server Debugging: Your server is remote, and your project files are local copies.
Symlinks: Files on the server and in your IDE are the same, but symlinks are used. Debuggers resolve symlinks, so you need to provide the actual physical paths on the server to PhpStorm.

Configuring Path Mappings:

Go to PHP | Servers in PhpStorm settings (Ctrl+Alt+S). Configure your server and specify the necessary path mappings.

If the server files are directly within your project and you are not using symlinks, you can clear the “Use path mappings” checkbox. In this case, PhpStorm will use the paths received directly from the debugger.

Path mappings defined for a parent directory are automatically applied to subdirectories. You can specify more specific mappings for individual subdirectories or files if needed.

Refer to Connect to a web server for more detailed information on server configurations and path mappings.

Breakpoint Issues

Breakpoints are Not Being Hit

If breakpoints are not being triggered despite the debugger connecting, verify the following:

Breakpoint Placement: Ensure breakpoints are set on executable lines of code. Blank lines, comments, or class/function declarations are not executable lines.
Correct Script Execution: Confirm that the code with breakpoints is actually being executed during your debugging session.
Conditional Breakpoints: If using conditional breakpoints, double-check that the condition is being met.
Xdebug xdebug_break(): For Xdebug, you can insert the xdebug_break() function directly into your PHP code to force a breakpoint at that line, regardless of whether a breakpoint was set in PhpStorm.

Xdebug Ignores Breakpoint and Stops at a Different Line

This behavior can occur due to Xdebug’s breakpoint resolving mechanism. Xdebug determines if a line of code can generate executable bytecode. If a breakpoint is set on a non-executable line, Xdebug will search for the nearest subsequent line with executable code (within a limit of 5 lines), stop there, and update the breakpoint location.

Disabling Breakpoint Resolving:

If you prefer PhpStorm not to automatically adjust breakpoint positions, you can disable this feature in PHP | Debug settings (Ctrl+Alt+S).

In the “Xdebug” area:

Disable Resolving: Uncheck “Resolve breakpoint if it’s not available on the current line (Xdebug 2.8+)” to completely disable breakpoint resolving. Breakpoints on non-executable lines will then be ignored.
Disable Moving: Uncheck “Move breakpoint to resolved position if it’s different from the source” to prevent automatic breakpoint position adjustment. Breakpoint resolving will still occur, but the breakpoint in PhpStorm will remain on the original line, even if Xdebug stops at a different resolved line.
Disable Notifications: Uncheck “Notify if breakpoint was resolved to a different line (Xdebug 2.8+)” to suppress PhpStorm notifications about breakpoint resolution.

Script Not Suspended

If a Zero-Configuration debugging session starts, but no breakpoints are hit, and the script does not pause, possible reasons include:

Incorrect Path Mappings: As discussed earlier, incorrect or missing path mappings can prevent breakpoints from working.
No Breakpoints Set: If no breakpoints are set, the script will run to completion without pausing.

Solutions:

Set Breakpoints: Click in the editor gutter next to executable lines of code to set breakpoints as needed.
“Break at first line in PHP scripts” Option: Enable “Break at first line in PHP scripts” either in PHP | Debug settings (“External Connections” area) or via the main menu Run | Break at first line in PHP scripts. This will force the debugger to stop at the very first executable line of any PHP script execution.

To receive a notification if a debug session completes without pausing (meaning no breakpoints were hit), enable “Notify if debug session was finished without being paused” in the “Advanced Settings” area of PHP | Debug settings.

Debugging Issues with Nginx

When using the nginx web server, debugging might fail if the $_SERVER["SERVER_NAME"] variable is not correctly provided to PHP.

Solution: Add the following fastcgi_param directive to your nginx configuration within the PHP block:

fastcgi_param SERVER_NAME $server_name;

fastcgi_param SERVER_NAME $host;

Refer to the nginx documentation and this community post for more details.

Xdebug Cannot Connect to PhpStorm

If you encounter these messages in your 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

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 indicates that Xdebug is unable to establish a connection to PhpStorm at the configured host and port.

Solution:

Set remote_connect_back=0 (or discover_client_host=false for Xdebug 3): In your php.ini, set xdebug.remote_connect_back=0 or xdebug.discover_client_host=false.
Correct remote_host (or client_host for Xdebug 3): Ensure that xdebug.remote_host (or xdebug.client_host for Xdebug 3) is set to the IP address of the machine running PhpStorm. If debugging locally, this is usually 127.0.0.1 or localhost. In Docker environments or remote debugging scenarios, it might be a different IP address.

Debugging Framework CLI Commands

When attempting to debug CLI commands of frameworks like Symfony Console or Laravel Artisan, you might encounter PHP errors such as “Fatal error: Class ‘…Command’ not found.”

Cause: Directly debugging the command file or class is often the problem. Framework CLI commands require the framework’s bootstrapping process to be executed correctly.

Solution: Use a “PHP Script” run configuration in PhpStorm instead of directly debugging the command file.

Create PHP Script Configuration: Create a new run/debug configuration of type “PHP Script.”
Specify CLI Tool Path: In the “File” field, provide the path to your framework’s command-line tool (e.g., artisan for Laravel, bin/console for Symfony).
Provide Command Arguments: In the “Arguments” field, enter the specific command you want to debug (e.g., list, migrate, your:command).

PHP Script run/debug configuration for Artisan

This approach ensures that the framework’s environment is correctly initialized before the command is executed, allowing for normal debugging. Refer to framework-specific documentation for detailed guides.

Zend Debugger Privilege Issues on Linux

When using Zend Debugger on Linux, you might see the 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 Zend Debugger cannot determine the User ID (UID) of the web server process.

Solution:

Find Web Server UID: Identify the UID of the user running your web server (e.g., apache, www-data, nginx).
Set zend_debugger.httpd_uid: Add the following line to your php.ini, replacing 1234 with the actual UID:
```
zend_debugger.httpd_uid=1234
```
Restart Web Server: Restart your web server after modifying php.ini.

Debugging with ionCube Loader

If your PHP environment uses ionCube to load encoded PHP code, debugging with Xdebug or Zend Debugger can be challenging as they are officially not supported to run with ionCube enabled. However, some workarounds might be possible, though they are not officially supported by JetBrains, ionCube, Xdebug, or Zend Debugger.

Potential Workarounds (Use with Caution):

Load Order in php.ini: Ensure the ionCube loader module is loaded before any debugger extension in your php.ini. 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

ionCube On-Demand Loading: Try disabling the ionCube extension in php.ini and relying on ionCube’s on-demand loading feature. When an encoded PHP script is encountered, PHP will search extension_dir for the ionCube extension and load it.

Warning: This on-demand method is not officially supported and is recommended for debugging purposes only, never for production servers.

By systematically working through these troubleshooting steps, you should be able to resolve most common PHP debugging issues in PhpStorm and restore a smooth and efficient debugging workflow. Remember to consult official documentation and support resources for more specific or complex problems.

Last modified: October 27, 2024

Step through the program Testing