Project:DebuggingPHPinMediawiki: Difference between revisions

Latest revision as of 14:56, 10 March 2023

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/

@@ Line 5: / Line 5: @@
 === XDEBUG in Docker: ===
-This is about to setup debugging with breakpoints etc. with xdebug.
+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
@@ Line 12: / Line 12: @@
 Setting up PHPStorm IDE with XDEBUG and Containers.
-There are two major steps involved in set up:
+There are two major steps involved in set up (both of them can be seen in many web-documentations, e.g. in [https://hackernoon.com/how-to-debug-php-container-with-xdebug-and-phpstorm-1b2k3yjo this example]):
-* Setting up a debugging configuration with localhost and port 9000
+* 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.
-* Both steps are can be seen in many web-documentations, [https://hackernoon.com/how-to-debug-php-container-with-xdebug-and-phpstorm-1b2k3yjo example is this] from step 4  (only port has to be changed from 80 to 9000)
+** 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 [[mediawikiwiki:Download|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. 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.
+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: ====
 * https://medium.com/advanced-xdebug-connection-issues-troubleshooting/debug-your-xdebug-advanced-troubleshooting-part-1-network-issues-25da412d0a11
 * https://medium.com/advanced-xdebug-connection-issues-troubleshooting/debug-your-xdebug-advanced-troubleshooting-part-2-xdebug-settings-ef91d05dc526
+==== 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/