Setting up MediaWiki, Vagrant and VSCode

The guide describes how to setup MediaWiki for development on Vagrant while adding support for debugging on VSCode using the XDebug PHP extension.

Various documents have been linked to which contain relevant information rather than copying it here again.

Steps

Initial setup

  1. Install VirtualBox.
  2. Install Vagrant. Grab the version as per your OS.
  3. Follow instructions on the MediaWiki-Vagrant page. This Vagrant box comes with the XDebug PHP extension already installed.
  4. Turn on SSH agent forwarding. Ensure host is set to 127.0.0.1. This is useful if you wish to commit / review to / from the vagrant box.
  5. Setup git and git-review as described here. Sample .gitconfig from the Vagrant box shown below.

Configuring debugging on VSCode

The Vagrant box is already configured to support remote debugging, but to make things easier, let’s add one more setting to the php.ini . The file to be modified is inside the Vagrant box at this location –  /etc/php/7.2/apache2/php.ini.

Add the following setting: xdebug.remote_autostart = true. This ensures that we don’t have to follow section 2.5 here, that deals with the installation of an XDebug browser helper extension. You can read more about what the setting does in the XDebug documentation.

Start debugging in VSCode, and then go to 127.0.0.1:8080. Your breakpoints should trigger.

Sample .gitconfig

The configuration is added inside the Vagrant box if you plan to commit patches and review code from inside the box.

Tweaking performance

Run the command vagrant config --all inside the folder where the Vagrant box is installed. This will allow you to tweak the RAM and number of CPUs allocated to the Vagrant box, among other things.

I’ve found 2 Gigs of RAM and 4 virtual CPUs (My i7-8550U has 8 virtual CPUs) to be adequate for my development purpose.

Fixing potential problems

In case things don’t work as expected, set logging to true ("log": true) in the launch config file and then check the debug console in VSCode.

XDebug Logs from VSCode
XDebug Logs from VSCode

You can also check logs from XDebug inside the Vagrant box at this location – tail -n 100 /vagrant/logs/xdebug.log

Initially, I was able to attach breakpoints and the incoming requests triggered them but subsequent commands (Next, Step In, Continue etc) were failing to update the IDE or XDebug. Looking at the VSCode debug log revealed that VSCode was sending the requests to XDebug but was not getting a response. Checking the XDebug logs revealed that it was not receiving any of the commands.

At this point I decided to look at the pupped files for more information. If you look at the remote_debug.pp file, you’ll notice the following line,

Instead of using dev.wiki.local.wmftest.net:8080 connecting to 127.0.0.1:8080, fixed the issue with subsequent commands not working.

Happy Hacking!

Leave a Reply