Manual:How to debug

This page gives a basic introduction to debugging MediaWiki software.

One of the first things you will notice is that "echo" generally does not work; this is part of the general design.

[development]

database.type      = pdo_mysql database.hostname  = localhost database.username  = sportsf2_birdsey database.password  = cabbtb02 database.database  = sportsf2_sportsfirstlook

paths.base     = ./ paths.data     = ./data paths.templates = ./templates

logging.file = ./data/logs/debug.log

[production]

database.type      = pdo_mysql database.hostname  = localhost database.username  = sportsf2_birdsey database.password  = cabbtb02 database.database  = sportsf2_sportsfirstlook

paths.base     = ./ paths.data     = ./data paths.templates = ./templates

logging.file = ./data/logs/debug.log

SQL errors
To display SQL errors in error messages instead of "(SQL query hidden)", add the following to :

You can also enable backtrace on SQL error by setting :

Zend
If you are using the Zend PHP interpreter, you can debug your code with XDebug. MediaWiki-Vagrant has [https://git.wikimedia.org/blob/mediawiki%2Fvagrant.git/c377718dea960c5e9e7b3acc79893a5e3c14da01/puppet%2Fmodules%2Fphp%2Fmanifests%2Fremote_debug.pp#L27 built in settings] for this. If you're not using MediaWiki-Vagrant, but your setup is similar, you can reuse those values. In some cases (e.g. due to a firewall), you may have to use the IDE on the same machine as the web server. In this case, you can simply set:

If you use this configuration, you may run into an issue if HHVM is also listening on the machine. Both XDebug and HHVM use port 9000 by default. However, you can change this for XDebug (and many clients). For the XDebug side, use:

Remember if you change it for XDebug, you must also change it for your IDE.

See the [http://xdebug.org/docs/remote XDebug documentation] for more information.

HHVM
If you are using the HHVM PHP runtime, you can debug your code with the built in CLI debugger and debug server.

This debugger is vaguely similar to GDB.

In order for the cli debugger to attach to web requests the hhvm.debug.enable_debugger parameter needs to be enabled.

This is enabled by default on the mediawiki-vagrant development environment.

With this enabled the process is:

$ hhvm -m debug --debug-host localhost --debug-port 8089 localhost> machine list machine list 1    vagrant's default sandbox at /vagrant/www/ 2    __builtin's default sandbox at / localhost> machine attach 2 machine attach 2 Attaching to __builtin's default sandbox at / and pre-loading, please wait... localhost> break MediaWiki::run break MediaWiki::run Breakpoint 1 set upon entering MediaWiki::run localhost> continue continue

The machine attach 2 is required.

It may not always be machine 2, but it will always be the one identified as "__builtin's default sandbox at /".

This is only true on configurations that pass a  over fastcgi to hhvm (such as  and wmf production), alternate configurations may vary.

At this point the next web request that enters MediaWiki::run (all of them) will break and put you on a command prompt:

Breakpoint 1 reached at MediaWiki::run on line 450 of /vagrant/mediawiki/includes/MediaWiki.php 449           try { 450*                  $this->checkMaxLag; 451                   try { localhost>

The HHVM CLI debugger has an excellent help system, for example try help break for details on the syntax of choosing break points.

Logging
For much greater detail, you need to profile and log errors.

Setting up a debug log file
To save errors and debugging information to a log, add   to the  file. Change the value to a text file where you want to save the debug trace output.

The MediaWiki software must have permissions from your operating system to create and write to this file, for example in a default Ubuntu install it runs as user & group :. Here's a sample setting:

This file will contain much debug information from MediaWiki core and extensions. Some subsystems write to custom logs, see to capture their output.

dbtrans>Special:MyLanguage/Database transactions|Database transaction lifecycle debugging can be enabled for some databases with .

Creating a custom log file
To create a custom log file that only holds your specific debug statements, use the  function. This function takes two arguments, the text string to log and the path to the log file:

Creating custom log groups
If you're debugging several different components, it may be useful to direct certain log groups to write to a separate file.

To set up custom log groups, use the following to LocalSettings.php:

To log to one of these groups, call  like this:

Send debug data to an HTML comment in the output
This may occasionally be useful when supporting a non-technical end-user. It's more secure than exposing the debug log file to the web, since the output only contains private data for the current user. But it's not ideal for development use since data is lost on fatal errors and redirects. Use on production sites is not recommended. Debug comments reveal information in page views which could potentially expose security risks.



Working live with MediaWiki objects
 is an interactive script to evaluate and interact with MediaWiki objects and functions in a fully initialized environment.

 $ php maintenance/eval.php > print wfMessage("Recentchanges")->plain; Recent changes

The <tvar|vagrant></> portable virtual machine integrates the interactive PHP shell.