There are a number of things XDEBUG can be used for. So long as it's enabled, you will be given the "nice" XDEBUG error messages without any additional work, however for more advanced use please see the instructions below
Depending on the version of PHP you are using you will get different versions of XDEBUG please refer to the PHP Component for specific version information
Debugging
XDEBUG has a step debugging feature, which allows you to step through your code as it runs.
To allow this functionality, it requires a connection to your machine. Even though the instance is not running on your machine it is still possible in MDOQ.
You can either debug in vscode or debug on your computer. The later requires some additional setup, but may be more comfortable for you to use a familiar IDE.
Debug in VSCode
Prerequisites
- Have Debug Location set to "VSCode"
(If you have changed this setting after creating the instance, you will need to synchronize the PHP-FPM components)
Instructions
- Open VSCode and hit "F5" this will open the debugging gui.
No configuration needed you can head to Activating the debugger
Debug locally
Prerequisites
Before you can begin using the step debugger functionality you must:
- Have SSH access set up to your instance.
(you can find a guide on this here) - Have the repository and the same branch as your instance checked out locally on your computer and ran a composer install to populate the vendor directory
(One alternate/easy way to do this is to setup sftp to your instance.) - Have an IDE that support XDebug Step debugging
- Have Debug Location set to "On My Computer"
(If you have changed this setting after creating the instance, you will need to synchronize the PHP-FPM components)
Instructions
- To allow php-fpm to talk your IDE we need to set up an SSH tunnel that forwards request from a remote server to your computer.
The command takes the format:ssh -R 9001:localhost:9000 magento@SSH_HOST -p SSH_PORT
For example if the SSH credentials for your instance were:
SSH host:mysite-0000.00.mdoq.io
SSH port:11111
Your tunnel command would be:ssh -R 9001:localhost:9000 magento@mysite-0000.00.mdoq.io -p 11111
Running this command will just look like you have SSH'd into the instance there is no obvious confirmation that it is working.
- Configure your IDE to listen on port 9000
If you haven't configured any break points in your code you may also which to select "Break at first line"
In PHPStorm these options can be found easily by searching for "xdebug" in the settings dialog. - You must then tell your IDE to listen for remote connections.
In PHPStorm this means clicking this icon:
So that it looks like this:
This is now all set up and configured you can head to Activating the debugger
VSCode Specifics
If you are debugging locally using VSCode in addition to the requirements already documented above:
- You will need the "php-debug" extension installed
- You will need to create a ".vscode/launch.json" if it doesn't already exist with the content
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for XDebug",
"type": "php",
"request": "launch",
"port": 9000,
"pathMappings": {
"/home/magento/htdocs": "${workspaceRoot}"
},
"stopOnEntry": true
}
]
}
Activating the debugger
Web requests
To activate the debugger for a specific request simply append the query variable:XDEBUG_SESSION_START=something
Here "something" can be anything you want.
For example if you were debugging the home page and the base url was:https://mysite-0000.00.mdoq.io/
You could change this to:https://mysite-0000.00.mdoq.io/?XDEBUG_SESSION_START=name
Your IDE should then notify you of an incoming connection from XDEBUG.
Complex Web Requests (Eg forms, Ajax calls)
There are circumstances where it would be unrealistic to append the query string onto URLs which might be stored/initiated from Javascript, so you might wish to enable XDEBUG on all requests. This can be done by inserting this into the beginning of pub/index.php ensuring you do NOT commit this to source control
CLI commands
To activate the debugger for a cli command you need to set a XDEBUG_CONFIG
environment variable with an idekey
value:
export XDEBUG_CONFIG="idekey=something"
Here "something" can be anything you want.
You can then run your command.
Your IDE should then notify you of an incoming connection from XDEBUG.
When you are done debugging simply unset the variable:unset XDEBUG_CONFIG
PHP 8.2+
If you are using PHP 8.2+ you need to make some small adjustments due to the new version of XDebug.
In your PHP configuration (which can be managed via /mdoq/php-fpm/configure) you can add the following, ensuring you can implement this only on non production instances.
CONFIG_FILE="/etc/php/${PHP_VERSION}/cli/php.ini"
INSTANCEID="$(echo $HOSTNAME | cut -d'-' -f1)"
echo "xdebug.start_with_request=trigger" >> ${CONFIG_FILE}
echo "xdebug.client_host=$INSTANCEID-vs-code-editor" >> ${CONFIG_FILE}
echo "xdebug.client_port=9000" >> ${CONFIG_FILE}
echo "Config updated, restarting PHP-FPM"
supervisorctl restart php-fpm
supervisorctl status php-fpm
Once you have done this the only other directive you need to replace is the XDEBUG_SESSION_START with XDEBUG_TRIGGER which can be done any manner of ways explained above.