Project:DebuggingPHPinMediawiki

Most of the code in MediaWiki and its extensions is written in PHP.

For an overview, there are several possibilities including logs and debugging output on MediaWiki pages listed here: https://www.mediawiki.org/wiki/Manual:How_to_debug

XDEBUG in Docker:

This is about how to setup debugging with breakpoints etc. with xdebug.

Starting from portal-compose, adapt your docker-compose.override.yml as suggested in the Readme.md

PHPStorm setup

Setting up PHPStorm IDE with XDEBUG and Containers.

There are two major steps involved in set up (both of them can be seen in many web-documentations, e.g. in this example):

Setting up a debugging configuration from template: "PHP Remote Debug", with localhost and port 9000, IDE Key: PHPSTORM
Setting up directory mapping, this maps local code-directories to wikibase container, so they can be used as sourcecode for debugging.
- Usually it is sufficient just to map the extensions directories which are edited (in example "/extensions-dev/MathSearch" to "/var/www/html/extensions/MathSearch/"
- For setting breakpoints in the complete MediaWiki, download the corresponding source-code for MediaWiki and place it in extensions dev. The root can be linked to "/var/www/html"
- Sometimes in IDE in Settings->Server->PHP, break at first line and similar settings have to be deactivated.

To start debugging, call any page of the wiki while running the debugging configuration (the configuration has to be run explicitly by pressing green bug icon)

Then, a dialogue by IDE appears which has to be accepted.

If the directories are mapped correctly you can now set breakpoints in the code and the ide stops at these. If there is any issue during the set up, check the steps in troubleshooting section.

Debugging Scripts in CLI running in containers

Sometimes it is necessary to debug php scripts (in example maintenance scripts) which are not started by gui interactions on MediaWiki, but are started by the user in cli.

Debugging these works essentially the same like MediaWiki pages, when running the script xdebug parameters have to be specified like this:

php -dxdebug.mode=debug -dxdebug.client_host=host.docker.internal -dxdebug.client_port=9000 -dxdebug.start_with_request=yes -dxdebug.discover_client_host=1 -dxdebug.idekey=PHPSTORM -dxdebug.log=/tmp/xdebug.log /var/www/html/extensions/MathSearch/maintenance/UpdateMath.php

Also it is necessary to start the docker-composition in host-mode and to specify the hosts ip adress, because the ip (client_host) here seems not to recognize the docker.host.internal alias.

For troubleshooting debugging issues, going through these steps can be very helpful:

Common Issues:

Version for Mediawiki incremented, path mappings not correct, go to Special:Version check MediaWiki Version, download corresponding version from https://github.com/wikimedia/mediawiki/tree/wmf/1.39.0-wmf.16
dev image is not recent: pull latest mardi-wikibase image from ghcr.io, then build dev image with latest commit from repository

XDebug not installed on local Mediawiki container: https://www.garygitton.fr/setup-xdebug-php-docker/