Validate the configuration of a debugging engine

PhpStorm can validate the configuration of Xdebug on a local or remote web server, detect the settings that are missing or inconsistent with others, explain inconsistencies and suggest fixes. The Run | Web Server Debug Validation dialog provides several options depending on how and where validation is done:

Output phpinfo(). PhpStorm parses the output which you copy and paste manually from the php -i CLI command or a web page rendered from phpinfo().
Local Web Server or Shared Folder. PhpStorm checks the debugger associated with a local web server. To do so, it creates a temporary validation script (_intellij_phpdebug_validator.php), deploys it to the target environment, runs it there, and then fetches and displays the output.
Remote Web Server. PhpStorm checks the debugger associated with a remote server. To do so, it creates a temporary validation script (_intellij_phpdebug_validator.php), deploys it to the target remote environment, runs it there, and then fetches and displays the output.
Debug Validation Script. PhpStorm generates a CLI command for the validation script (phpstorm_index.php). You can copy and manually execute this command on a running server, and have PhpStorm fetch and display the output.

Go to Run | Web Server Debug Validation.

In the Validate Debugger Configuration on Web Server dialog that opens, choose the debugger validation method and specify the required parameters for it.

Output phpinfo()
Output phpinfo():
In this field, copy and paste the output from the php -i CLI command or the rendered or source HTML output from phpinfo().

Local Web Server or Shared Folder

Path to create validation script

In this field, specify the absolute path to the folder under the server document root where the validation script will be created. For web servers of the Inplace type, the folder is under the project root.

The folder must be accessible through HTTP.

URL to validation script

In this field, type the URL address of the folder where the validation script will be created. If the project root is mapped to a folder accessible through HTTP, you can specify the project root or any other folder under it.

Remote Web Server

Path to create validation script

In this field, specify the absolute path to the folder under the server document root where the validation script will be created. The folder must be accessible through HTTP.

Deployment server

In this field, specify the server access configuration of the type Local Server or Remote Server to access the target environment. For more information, refer to Connect to a web server.

Choose a configuration from the list or click Browse in the Deployment dialog.

Debug Validation Script

Download script command	Copy the CLI command to clipboard () and execute it on the server to download and unpack the script there.
URL to validation script	In this field, type the URL address of the folder where the validation script is deployed to. If the project root is mapped to a folder accessible through HTTP, you can specify the project root or any other folder under it.

Click Validate. PhpStorm displays the list of the debugger configuration checks with their status and description and suggests fixes for inconsistent settings where available.
With the Debug Validation Script option, you can also open the phpstorm_index.php file from the downloaded script package in the browser.

Troubleshoot validation results

Connection refused

There has been a problem connecting to your web server. Make sure that the URL (and port) are correct; these are provided to your web server either in the URL to validation script option or within your deployment.

Check that web path to validation script is correctly configured for

The Path to create validation script within the local project does not map to the URL to validation script or Deployment URL option. If you are using a framework or the PHP built-in web server, this is likely due to the framework sending a 404 response instead of sending the actual file in that directory.

A quick way to test this is to create a test.php file in the directory you have set as the Path to create validation script, and then check that file is callable from the URL to validation script or deployment url with test.php appended.

For example, if the Path to create validation script is set to /var/www/public, create a test.php file with the following contents in that folder:

<?php echo 'test works';

If your URL to validation script or Deployment URL is http://192.168.100.100:8080, then you should be able to call that script by visiting http://192.168.100.100:8080/test.php and see the "test works" output. If you are seeing a 404 generated by your framework, then your URL rewriting is wrongly configured, and you should consult your framework's documentation to ensure that the URL rewriting configuration will return real files if they exist before sending any other requests to your framework dispatcher.

If you're seeing a 404 and you are using PHP built-in web server, it's likely because you cannot configure this web server to serve files on the file system if they exist. You'll need to add the following code to the file you are sending all requests to (typically index.php) in order to send file system files if they exist:

                if (PHP_SAPI == 'cli-server') {
                    // To help the built-in PHP dev server, check if the request was actually for
                    // something which should probably be served as a static file
                    $file = __DIR__ . $_SERVER['REQUEST_URI'];
                    if (is_file($file)) {
                        return false;
                    }
                }
            

Remote host is configured as 'localhost' despite server host is probably not local

The URL to validation script contains something different from localhost, but the xdebug.remote_host value is not set, and is therefore using the default value of localhost, or is set to localhost or 127.0.0.1.

Specified URL is not reachable, caused by: 'Request failed with status code 404'

The issue can happen in situations when the server document root is different from the project root, and deployment path mappings are not configured correspondingly.

Consider the following example:

The project is stored in the /MyProject folder.
The server document root is set to its public subfolder, that is /MyProject/public.
The URL to access the application is http://MyApp.test.

If the entire project root folder is mapped to the server document root, PhpStorm will attempt to access the validation script via the http://MyApp.test/public/_intellij_phpdebug_validator.php URL, which will result in a 404 error. To solve this, you need to set the explicit mapping between the public subfolder and the server document root.

In the Settings dialog (Ctrl+Alt+S) , go to Build, Execution, Deployment | Deployment.
Select your deployment server, and on the Mappings tab, click the Add New Mapping button.
Add an additional entry that maps the /MyProject/public folder to the server document root /.

As a result, the URL to access the validation script becomes the correct http://MyApp.test/_intellij_phpdebug_validator.php.

Last modified: 10 December 2024