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.

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.

Issues with XDebug 2.7.0

The MediaWiki vagrant box comes bundled with XDebug 2.7.0 which appears to be quite broken. See this Phabricator task for more information. I recommend updating it to version 2.9.x using pecl.

  1. Install php-pear extension if not installed already.
    sudo apt-get install php-pear
  2. Remove / disable the existing php-xdebug extension.
  3. Use pecl to install XDebug version 2.9.8.
    pecl install xdebug-2.9.8

Configuring debugging on VSCode

{
   "type": "php",
   "request": "launch",
   "name": "Listen for XDebug",
   "pathMappings": {
     "/vagrant/mediawiki": "${workspaceFolder}",
   },
   "port": 9000,
   "log": true,
 }

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. 

[gitreview]
	username = {{your username}}
	remote = origin
[user]
	email = {{your email}}
	name = Abijeet Patro
[credential]
	helper = cache --timeout 28800

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,

# -- In your IDE, enable "Start Listening for PHP Debug Connections"
# -- For Firefox, install
#    https://addons.mozilla.org/en-US/firefox/addon/the-easiest-xdebug
#    and click "Enable Debug" icon in the Add-on bar
# -- Set breakpoints
# -->> Navigate to 127.0.0.1:8080/...

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