This section outlines solutions to common problems you may encounter during a debugging session:
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 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 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.
Choose the most suitable configuration from the list or click and create a new configuration in the Deployment dialog that opens, whereupon the new configuration is added to the list.
In the Deployment root field, 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.
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 checkbox in the External Connections area or turning the option from 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 checkbox in the Advanced Settings area on the Debug page of the Settings dialog.