MediaWiki-Vagrant/Advanced usage

Setting up access to gerrit
The vagrant installation on your computer (the host) is mounted as /vagrant on the vagrant box. So when you make changes to its mediawiki subdirectory on your host computer, the changes will appear on the vagrant box in /vagrant/mediawiki.

This is only a potentially incomplete gross sketch, needing review. Assuming: On a terminal or command shell go to the directory, where your vagrantfile is located, and type: You should get a shell on the virtual machine. You should be prompted for your passphrase. enter it.
 * You have an account in gerrit.
 * Your public key is known to gerrit.
 * Your private key is stored in ~/.ssh/id_rsa in the virtual machine.
 * vagrant ssh
 * 
 * git remote add gerrit ssh://your-username@gerrit.wikimedia.org:29418/mediawiki/core.git
 * ssh-agent bash
 * ssh-add

MediaWiki debugging using Xdebug and an IDE in your host
The MediaWiki-Vagrant box has Xdebug, a PHP extension for debugging and profiling. Here are the steps to use it:


 * Switch from the default HHVM to ZEND with

Or, to avoid switching back and forth, you can use http://php5.local.wmftest.net:8080/. All requests to that host name will use Zend.

Once switched, XDebug is enabled and will callback your browser if requested. If you want to adjust the xdebug.ini settings further, see below.

Start and ssh to your MW-Vagrant box if you haven't done so already:

Look at the Xdebug configuration:

The following settings work pretty well on older versions of Mediawiki-vagrant, but they probably are unnecessary with newer versions (as of 4-June-2014 the built-in /etc/php5/conf.d/remote_debug.ini works). You may want to read Yurik's virtual box on Windows 7 article for more information.

zend_extension=/usr/lib/php5/[number]/xdebug.so xdebug.idekey=default xdebug.remote_autostart=1 xdebug.remote_connect_back=0 # only phone home if initiated by debugger xdebug.remote_enable=1 xdebug.remote_handler=dbgp xdebug.remote_mode=req xdebug.remote_port=9000 xdebug.remote_host=[address of the host running the IDE you want to debug in]
 * 1) xdebug.remote_connect_back=1 # always try to phone home

Next, configure your IDE.

PhpStorm
In PhpStorm, go to File > Open Directory. Choose the vagrant directory that is contained within your Mediawiki-Vagrant installation. If you are prompted to add files or about Git roots, just cancel those warnings unless you feel comfortable with those settings.

Now that you've created a PhpStorm project by adding the vagrant directory, to see the basic debug settings, go to PhpStorm > Preferences > (under Project Settings) PHP > Debug. These defaults should work well with the /etc/php5/conf.d/remote_debug.ini built-in file for MediaWiki-Vagrant or, failing that, the xdebug.ini file above.

Go to PhpStorm > Preferences > PHP (under Project Settings) > Servers. Click the plus (+) button to add a server. Set the Name field to something like vagrant local. Set the Host field to localhost, the Port field to 8080, and the leave the Debugger dropdwon at a value of Xdebug. Next, click the Use path mappings (select if the server is remote or symlinks are used) checkbox. On the lefthand side you will see your filesystem as expressed by the File/Directory header, and on the righthand side you can click to map the remote (virtual machine) absolute filesystem with your own (host) filesystem path. Here, you want to ensure that your own (host) filesystem path for the vagrant directory is mapped to the remote (virtual machine) filesystem path of /vagrant' for the Absolute path on the server''. Now, click OK.

Next, in PhpStorm, go to Run > Edit Configurations. Click the plus (+) symbol to add a PHP Web Application debug configuration. In the Name field type a descriptive name such as ff and vagrant (e.g., if you're using Firefox). In the Server section, choose the vagrant local server configuration you just defined from the dropdown list. In the Start URL field type a relative path such as /wiki/Main_Page. Choose whatever Browser you want to use from the dropdown list. Click OK.

Next, if you created the custom xdebug.ini, back in your SSH session on the virtual machine, restart Apache to make your xdebug.ini settings take effect:

You may get a warning that Apache bound itself to a port because it couldn't find additional configuration settings. Not a problem.

Now, back in PhpStorm, go to Run > Debug. When prompted. choose the PHP Web Application debug configuration you set earlier.

A browser should launch and the page should be rendered. Not that exciting!

Go back into PhpStorm, and open the file mediawiki/index.php. Add a breakpoint by clicking in the gutter at the lefthand side of the $mediawiki->run; method invocation. You should see a little red orb appear.

Now go to Run > Debug again, and choose the PHP Web Application debug configuration you set earlier. Notice how your Debugger window in PhpStorm paused execution of script and showed you some information about variables that have been set up to the point where you set the breakpoint. You can click the green Resume Program button at the lefthand side of the debugger window to let the script keep running. And if you set other breakpoints in other pieces of code within the project, script execution will pause again. You can also try using the blue Step Into button if you want to see the code execution play out call-by-call. This is a great way to learn how MediaWiki code actually works. Eventually, you'll start adding code to your own files or tweaking existing files and setting breakpoints to make sure variables are set the way you expected at actual runtime.

To learn more about PhpStorm debugging, visit the PhpStorm Debug help page.

Eclipse PDT 3.8
Then, set a breakpoint into   and debug this debug-configuration.
 * Menu File → New → PHP project from existing directory
 * Project name: Your choice.
 * Location: Path to the mediawiki folder in the vagrant installation
 * Option, Host:  , Base path:  , no library
 * Confirm
 * Right-click the project in the PHP explorer → Properties
 * PHP Debug, enable project specific settings
 * Default settings
 * PHP Debugger: XDebug (make sure it's listening to port 9000)
 * Server :
 * Tab Server: Base URL:, Local Web Root:
 * Tab Path mapping: Path on server:, Local path:
 * CLI debugging not required
 * Default base URL: Base path:
 * Menu Run → Debug configurations
 * Create a new one
 * Tab Server:
 * File:
 * URL: Auto-generate
 * Debugger: The previously created Debugger configuration for XDebug

Emacs with geben
First, checkout geben from SVN. The local directory on the right does not matter, as long as it is consistent with the code in your .emacs or .emacs.el file.

Edit your .emacs or .emacs.el file, and add the following:

There is a README in the root of the SVN checkout (the trunk README is linked from here).

Install The easiest Xdebug in Firefox.

In emacs, run. It doesn't matter what file is open, since geben will handle opening what it needs to via ssh (TODO: map local filesystem to remote as with PhpStorm above).

Click the six-legged insect in the addon bar (probably in the bottom right of your window); the tooltip says "Enable Debug with IDE key...". It will turn green.

Finally, load a MediaWiki page. It will stop automatically at the MediaWiki entry point (index.php). You may have to change to the Emacs window.

Many of the key shortcuts are listed in the README. Some important ones are:


 * g - Run
 * i - Step into
 * o - Step over
 * r - Step out
 * b - Set a breakpoint on a line
 * u - Unset the breakpoint on the current line
 * v - Inspect current variables
 * e - Evaluate a PHP expression (which can use variables from the code you're debugging) in the current context

If you want to add some of the Firebug debugger's shortcut keys as alternates, add:

You can change settings by doing. For example, you may want to disable pausing at the entry line once you have breakpoints set up.

LocalSettings.php
The settings.d directory, which is accessible from the base MediaWiki-Vagrant directory on your host, as well as "/vagrant/settings.d/" within the virtual machine's, is the best place to add files for extending LocalSettings.php. Just add one file per logical LocalSettings.php enhancement.