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 loads Xdebug, a PHP extension for debugging and profiling. Here are the steps to use it:

MediaWiki-Vagrant is automatically configured with xdebug support. However, if you want to adjust the xdebug.ini settings, 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 (see Yurik's virtual box on Windows 7 article for more information):

zend_extension=/usr/lib/php5/20090626/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
 * 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 mediawiki 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 mediawiki directory, to see the basic debug settings, go to PhpStorm > Preferences > (under Project Settings) PHP > Debug. These defaults should work well with the xdebug.ini file above. But more configuration is necessary to make everything work.

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 mediawiki directory is mapped to the remote (virtual machine) filesystem path of /vagrant/mediawiki 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 (or if you are a mobile developer and have enabled the MobileFrontend extension, /wiki/Main_Page?useformat=mobile). Choose whatever Browser you want to use from the dropdown list. Click OK.

Next, 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.

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.

All 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

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 directory, which is accessible from the base MediaWiki-Vagrant directory on your host, as well as /vagrant/settings/ within the virtual machine's file system, is the best place to add files for extending LocalSettings.php. Just add one file per logical LocalSettings.php enhancement.