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:

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.

On a terminal or command shell go to the directory, where your vagrantfile is located, and type:

vagrant ssh

You should get a shell on the virtual machine.

git remote add gerrit ssh://your-username@gerrit.wikimedia.org:29418/mediawiki/core.git
ssh-agent bash
ssh-add

You should be prompted for your passphrase. enter it.

MediaWiki debugging using Xdebug and an IDE in your host

The MediaWiki-Vagrant box has Xdebug, a PHP extension for debugging and profiling. The PHP extension is loaded by default for MediaWiki-Vagrant VMs running Debian Stretch or newer. For older MediaWiki-Vagrant VMs, you will need to enable the Zend role: vagrant roles enable zend; vagrant provision.

Note: as of 2021-06-30, the MediaWiki-Vagrant VM pulled from https://gerrit.wikimedia.org/r/admin/repos/mediawiki/vagrant has a broken version of XDebug (see task T220406). Better results have been observed by installing XDebug 2.9.8.

Ensure that port 9000 is open on your IDE host, because xdebug needs to use it in order to debug. On Fedora Workstation, you can add your Vagrant network interface to the firewall configuration (which should have port 9000 open by default) with

sudo firewall-cmd --add-interface=virbr0

(replace virbr0 with the interface name on your computer; you can usually find it by using ifconfig).

Next, configure your IDE.

PhpStorm

see also Manual:How to debug/with MediaWiki-Vagrant and 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 (Mac) or File > Settings (Windows/Linux) > (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 (Mac) or File > Settings (Windows/Linux) > Languages & Frameworks > 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 (or php5.local.wmftest.net as mentioned above), the Port field to 8080, and the leave the Debugger dropdown 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. You also want to map your host filesystem path of vagrant/srv/docroot/w to /var/www/w 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.

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

$ sudo apachectl restart

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. Note that you may need to wait a few seconds, then in the lower lefthand part of the screen click the green "play" arrow once it becomes activated.

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.

Executing and debugging command-line scripts

Follow step 1 from the JetBrains Running PHPUnit tests over SSH on a remote server with PhpStorm . After you have set up your remote PHP interpreter, create a new run/debug configuration (similar to step 2 from the same article), but choose "PHP Script" instead of "PHPUnit". For "file" input "/path/to/vagrant/mediawiki/tests/phpunit/phpunit.php" where "/path/to/vagrant" is on your host machine, not the Vagrant VM. Then for "arguments" add, for example, "--wiki wiki /vagrant/mediawiki/extensions/PageTriage/tests/phpunit". You can now run or debug unit tests for an extension.

Eclipse PDT 3.8

Tracked in Phabricator
Task T88149

This is how the result should be like

Menu File → New → PHP project from existing directory
- Project name: Your choice.
- Location: Path to the mediawiki folder in the vagrant installation
- Option Launch URL, Host: http://localhost:8080, Base path: /w/, 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 (PHP Servers):
    - Tab Server: Base URL: http://localhost:8080, Local Web Root: vagrant installation folder
    - Tab Path mapping: Path on server: /w, Local path: /mediawiki
  - CLI debugging not required
- Default base URL: Base path: /w
Menu Run → Debug configurations
- Create a new one
  - Tab Server:
    - File: /mediawiki/index.php
    - URL: Auto-generate
  - Debugger: The previously created Debugger configuration for XDebug

Then vagrant up, set a breakpoint into index.php and debug this debug-configuration.

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.

svn checkout http://geben-on-emacs.googlecode.com/svn/trunk/ ~/.emacs.d/geben

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

; Tell Emacs where to look for Geben.  Should match path above
(add-to-list 'load-path "~/.emacs.d/geben")

; Load geben when you run the geben command
(autoload 'geben "geben" "PHP Debugger on Emacs" t)

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 M-x geben. 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:

(eval-after-load 'geben
  '(progn
    (define-key geben-mode-map (kbd "<f8>") 'geben-run)
    (define-key geben-mode-map (kbd "<f10>") 'geben-step-over)
    (define-key geben-mode-map (kbd "<f11>") 'geben-step-into)
    (define-key geben-mode-map (kbd "S-<f11>") 'geben-step-out)))

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

Netbeans IDE 8.2

(This Tutorial was tested on Ubuntu x64 16.04.3 and aims to configure netbeans to be able to debug on a local server)

Optional if you don't have a running version of mediawiki on your local machine, follow the installation instruction in Manual:Running MediaWiki on Debian or Ubuntu or download it via git.

Download Netbeans IDE for php and install it.

Detailed installation explanation

On Ubuntu you end up with a netbeans*.sh file. In order to use it you have to make it executable. In Terminal:

chmod +x netbeans*

run the netbeans*.sh

./netbeans*.sh

Setup Netbeans Project

File >> New Project

Choose Project: (Categories:PHP | Projects: PHP Project with Existing Sources)
Name and Location: Browse for the mediawiki root folder (if you followed the instructions from the Manual:Running MediaWiki on Debian or Ubuntu it is located in /var/www/html/mediawiki) This will prompt you with the error that the directory is not writable. In order to continue with have to change the permissions with the following command in terminal chmod go+rwx /var/www/html/mediawiki Reselect the root folder and rename the project if you want to PHP Version: leave PHP 5.6
Run Configuration: Local Web Site (running on local web server)

Setup xdebugger

In order to be able to debug a webpage, we have to setup xdebug. Download it via the package-manager with <sudo apt-get install php-xdebug>.

After installing we have to modify the xdebug.ini file

sudoedit /etc/php/7.0/mods-available/xdebug.ini if you can't find it there look where the link of /etc/php/7.0/apache2/conf.d/20-xdebug.ini points (could be another number than 20)

zend_extension=/pathto/xdebug.so
xdebug.idekey=default
xdebug.remote_autostart=1
xdebug.remote_connect_back=0 # only phone home if initiated by debugger
# xdebug.remote_connect_back=1 # always try to phone home
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_port=9000
xdebug.remote_host=127.0.0.1

the pathto for zend_extension can be found with dpkg -L php-xdebug | grep xdebug.so

and you should be good to go for debugging.

(Hint disable in Tools > Options > PHP > Debugging > Stop at First line // otherwise the debugger will stop in every file it encounters)

Problems

If you encounter Problems with the debugger you probably screwed something up with the run configuration. Best solution is to delete the Netbean's project (not the files on the system) and to create a new project from existing source

VS Code

First, install the PHP Debug extension in VS Code.

You can set this up either in the vagrant directory or the mediawiki core subdirectory. Open whichever directory you prefer in VS Code. Go to the Run tab (play button with a little bug), click the "create a launch.json file" link, and select PHP as the environment. (If you already have a launch.json file, select "add configuration" from the dropdown.) The launch.json file should look something like this:

{
	// Use IntelliSense to learn about possible attributes.
	// Hover to view descriptions of existing attributes.
	// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
	"version": "0.2.0",
	"configurations": [
		{
			"name": "Listen for XDebug",
			"type": "php",
			"request": "launch",
			"port": 9000,
			"pathMappings": {
			     // If you're working out of the mediawiki subdirectory, the
			     // property value here should just be "${workspaceFolder}"
			     "/vagrant/mediawiki": "${workspaceFolder}/mediawiki"
			}
		},
		{
			"name": "Launch currently open script",
			"type": "php",
			"request": "launch",
			"program": "${file}",
			"cwd": "${fileDirname}",
			"port": 9000
		}
	]
}

The important things are 1) the "pathMappings" configuration is defined and 2) the port number corresponds to the value of xdebug.remote_port in your php.ini file (9000 by default).

Set your Xdebug browser extension of choice to listen for the debugger. In the vagrant codebase, place a breakpoint in the PHP code you'd like to step through. Visit your local site in the browser and, if the breakpoint is placed on a line of code that's run, the debugger will pause on that line and allow you to step through the code.

Notes:

If the debugger stops on errors or exceptions unexpectedly, in VS Code, uncheck "Everything" in the Breakpoints window within the Run tab.
This won't work for extension codebases opened in VS Code; you must run the debugger from the vagrant or vagrant/mediawiki codebase (but you can place breakpoints in extension code there).

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.

Vagrant LXC

Please see support/README-lxc.md for detailed notes on using LXC with MediaWiki Vagrant.