XDebug Installation for Windows

Prerequisites

This guide assumes you have:

• Windows operating system
• PHP installed
• VS Code or similar text editor
• Administrator access to modify system files

Installation Process

Generate PHP Information

In a terminal window:

php -i > phpinfo.txt

Use the XDebug Installation Wizard

1. In VS Code, open the phpinfo.txt file, (vscode: ctrl + p then type phpinfo.txt)
2. Select all text (Ctrl + A) and copy it (Ctrl + C)
3. Visit the XDebug Wizard
4. Paste the text into the input field (Ctrl + V)
5. Click "Analyse my phpinfo() output" at the bottom of the page

Follow the Installation Steps

You will receive a summary with installation instructions:

1. Download the DLL file by clicking on the provided link
2. Move the downloaded file to the PHP extensions directory (commonly C:\Program Files\php\ext)
3. Rename it to php_xdebug.dll

Configure PHP.ini

1. In Windows Search, type "Notepad"
2. Right-click on Notepad and select "Run as administrator"
3. In Notepad, press Ctrl + O and navigate to C:\Program Files\php
4. Open the php.ini file
5. Press Ctrl + F to search for memory_limit
6. Check if the value is at least 512M (e.g., memory_limit = 512M)
   • If it's lower (like 128M), change it to memory_limit = 512M
   • This ensures enough memory for PHP when running tests with coverage
7. At the end of the file, add the following lines:

[XDebug]
zend_extension = xdebug
xdebug.mode = off

8. Make sure to delete the phpinfo.txt file, as it is no longer necessary.

Why off and not coverage,develop,debug: having Xdebug loaded with any active mode adds overhead to every function call/return in the Zend engine, even when nothing is actively recording. Left on permanently, this measurably slows down everyday PHP work — artisan commands, db:seed, and the test:unit/test:arch gates in .githooks/pre-push all pay the tax on every run, not just the coverage runs that actually need it. xdebug.mode is overridden per-invocation by the XDEBUG_MODE environment variable (Windows included), so coverage stays one env var away without paying for it the rest of the time.

Run All Integration Tests with Coverage

Open a terminal and navigate to your backend directory:

cd backend
XDEBUG_MODE=coverage ./vendor/bin/pest --testsuite=Integration --stop-on-failure --coverage --coverage-text

This will generate a coverage report based on the files specified in the <source> section of your phpunit.xml configuration file.

Running One Specific Test File

To run tests on a specific file instead of the entire test suite. Use the path to the specific test file. For example:

cd backend
XDEBUG_MODE=coverage ./vendor/bin/pest tests/Integration/app/Actions/Model/CareType/UpdateCareTypeActionTest.php --stop-on-failure --coverage --coverage-text

Step-Debugging

To use Xdebug as a step debugger (e.g. VS Code breakpoints) instead of for coverage, set the mode to debug for that invocation instead:

XDEBUG_MODE=debug php artisan tinker

Troubleshooting

Coverage Issues

No Coverage Report Generated If tests run but no coverage information appears:

Check that XDebug is properly installed and loaded. Run in a terminal:

php -v

You should see "with Xdebug" in the output

ERROR

If you encounter this error: Unable to get coverage using Xdebug. Did you set Xdebug's coverage mode?

This means that XDebug is installed but not being told to run in coverage mode. Check that:

1. You're running the command with XDEBUG_MODE=coverage set (see above) — or, if you'd rather not set it per-command, that xdebug.mode in your php.ini includes coverage
2. If set in php.ini, the line is not commented out (doesn't have ; at the beginning)