XAMPP Xdebug

• Introduction
• Set up the Xdebug extension
• Configure PHPStorm
  • Settings
  • Error message while testing or composer command: Xdebug: [Step Debug] Time-out
  • Check Xdebug installation
• Configure VSCode
• Code coverage

Introduction

A strong debugging tool is a must-have when developing applications.

This guide will show how to install and configure Xdebug with XAMPP on Windows and how to use it without the need for an additional browser extension or manual trigger.

Xdebug is a powerful tool for debugging PHP applications and provides a rage of features to improve the PHP development experience.

As per their website, they provide the following features:

Step Debugging
A way to step through your code in your IDE or editor while the script is executed.

Improvements to PHP's error reporting
An improved var_dump() function, stack traces for Notices, Warnings, Errors and Exceptions to highlight the code path to the error

Tracing
Writes every function call, with arguments and invocation location to disk. Optionally also includes every variable assignment and return value for each function.

Profiling
Allows you, with the help of visualization tools, to analyse the performance of your PHP application and find bottlenecks.

Code Coverage Analysis
To show which parts of your code base are executed when running unit tests with PHPUnit.

Set up the Xdebug extension

1. Go to the Xdebug download page and select the version that matches your PHP version. Choose the VS16 TS version for XAMPP.
2. Open C:\xampp\php\ext, move the downloaded .dll file to this directory and rename it to php_xdebug.dll.
3. Open C:\xampp\php\php.ini and add the following lines at the end of the file:

   [xdebug]
   zend_extension = "C:\xampp\php\ext\php_xdebug.dll"
   xdebug.mode=debug, develop
   xdebug.start_with_request=yes

   It is also possible to set xdebug.start_with_request=trigger and use a browser extension, PHPStorm bookmarklet generator or manual trigger to start the step debugging session.
4. Restart Apache.

Configure PHPStorm

Settings

Open PHPStorm settings and go to PHP then Debug.

Set the Xdebug port to 9003 and make sure that the Can accept external connections checkbox is checked.

As every request will be debugged, uncheck the settings below:

• Break at first line in PHP scripts
• Force break at first line when no path mapping specified
• Force break at the first line when a script is outside the project

If the IDE stops on its own at the beginning of an unwanted file, for example, from PHPStan or a composer command, double-check that the settings look like this:

Now you should be able to set a breakpoint in your code and start a debugging session by clicking the on the Listen for PHP Debug Connections button in the top right corner of PHPStorm.

Since debug mode is started with every request, always make sure that the Listen for PHP Debug Connections button is enabled only in one open project.
Otherwise, PHPStorm always asks which project to debug when a request is made.

Error message while testing or composer command: Xdebug: [Step Debug] Time-out

The following error might occur when running tests:

Xdebug: [Step Debug] Time-out connecting to debugging client, waited: 200 ms. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port)

The fix is fairly simple. Make sure that Listen for PHP Debug Connections is always enabled when testing.

The same applies for other CLI commands where the above error occurs.

Check Xdebug installation

Open PHPStorm settings and go to PHP then press the ... button next to the CLI Interpreter field.

The CLI Interpreters dialog opens and shows the version of the selected PHP installation and the name and version of the debugging engine associated with the selected PHP installation.
If no debugger is configured, the Debugger: Not installed message is displayed.

Configure VSCode

Please check out PHP Debug Adapter for Visual Studio Code.

Code coverage

When running the command vendor/bin/phpunit --coverage-clover=coverage.xml, there will be a warning

XDEBUG_MODE=coverage or xdebug.mode=coverage has to be set

To prevent this, the command can be run with the environment variable set like this:

php -d xdebug.mode=coverage bin/phpunit --coverage-clover='reports/coverage/coverage.xml' --coverage-html='reports/coverage'

This command can be added to the scripts section of the composer.json file like this to run it with a more concise command:

composer test:coverage