How to become a MediaWiki hacker

This article is written to help novice developers learn the skills needed to contribute to MediaWiki development.

If you are an experienced developer, visit the developer hub instead.

Overview

The MediaWiki software is written in PHP and uses the MySQL database. Both have been ported to a variety of operating systems, including, but not limited to, most Unix variants (Linux, Mac OS X, etc.) and Microsoft Windows. It is possible to install and use MediaWiki on Linux, Mac OS X and Windows. Note: if you do use Windows, certain features involving external utilities will be unavailable, or only available with special downloads and configuration. Operating system dependent bugs are occasionally observed, it is best to have some knowledge of the difference between the various platforms regardless of which operating system you develop on.

The PHP programming language

If you have no knowledge of PHP (PHP stands for "PHP: Hypertext Preprocessor") but know how to program in other object-oriented programming languages, have no fear, PHP will be easy for you to learn.

If you have no knowledge of PHP or other object-oriented programming languages, you should familiarize yourself with concepts such as classes, objects, methods, events and inheritance.

If you have no knowledge of any programming language, PHP is a good language to start with, as it is reasonably similar to other modern languages, although it is specific in the way it is executed.

PHP scripts can run from the command line, or a window manager is enough to call the interpreter. e.g. (Linux/UNIX)

/usr/bin/php -q < phpshell.php

The script maintenance/eval.php in MediaWiki provides a basic php interpreter with MediaWikiobjects and classes loaded.

Usually, for websites a PHP script is executed when you request a file with the ".php" extension (among others) from a webserver. As you do that, the web server, in our case Apache, calls the PHP interpreter (which may be built into the webserver), interprets the PHP file and returns the result to your browser. The PHP file can contain both regular HTML and PHP code, which makes it relatively simple to add dynamic functionality to a static webpage.

Related links

• PHP tutorial (available in many different languages)
• The PHP manual (available in many different languages)
• PHP at Wikibooks

Database

MediaWiki currently uses MySQL as the primary database backend. It also supports other DBMSes, such as PostgreSQL and SQLite. However, almost all developers use MySQL and don't test other DBs, which consequently break on a regular basis. You're therefore advised to use MySQL when testing patches, unless you're specifically trying to improve support for another DB. In the latter case, make sure you're careful not to break MySQL (or write queries that are horribly inefficient in it), since that's what everybody else uses.

Although the WMF has now moved on from MySQL 4.0, it's important to not intentionally break MySQL 4.0 support. MySQL 4.0 is missing a lot of features of later MySQL versions (never mind other DBMSes): if you aren't sure, double-check in the manual first! The most commonly used feature missing from MySQL 4.0 is subqueries; don't use those outside of code specific to a non-MySQL DBMS.

Installing MediaWiki

Get the latest sources from SVN before creating patches. See Download from SVN for how to get the sources from SVN

Follow the instructions in the INSTALL file in the source. You could also read the installation guide.

It's not necessary to download Wikipedia database dumps in order to develop MediaWiki features. In fact, in many cases it's easier to use a near-empty database with a few specially-crafted test pages. However, if for some reason you want to have a copy of Wikipedia, you can get a dump from meta:data dumps.

You may also find that you get an error complaining that access was denied to the wiki database. Make sure that you have created a file AdminSettings.php in your top-level MediaWiki install directory (the same place as LocalSettings.php is found). An AdminSettings.sample file is provided for you to customise - make sure your MySQL administration username and password is set correctly. See Manual:Upgrading for more details.

Rebuilding the link tables may take a long time, particularly if you've installed the English Wikipedia database, which is quite big. (Note also that you can skip the old table if you wish.) See Manual:Database layout on what rebuildall.php is good for.

Note that if you want to create a public mirror of Wikipedia, this probably isn't the best way to go about it. If you do set up a mirror this way, please tweak the code to note that you're looking at a mirror and include links back to the main site. See Forks and Mirrors for more info.

The MediaWiki codebase

The MediaWiki codebase is large and ugly. Don't be overwhelmed by it. When you're first starting off, aim to write features or fix bugs which are constrained to a small region of code.

Browse through the list of important files at Manual:Code. For more detailed information, browse the generated documentation (warning: huge page will be loaded).

Your first feature

Here are some ideas:

• Code something that interests you;
• Fix an annoying little bug that nobody else could be bothered with;
• Write a special page to provide some handy information;
• Write a parser hook;
• Write a simple extension.

For more specific suggestions, please come and talk to the developers on #mediawiki. If you already have an idea for a feature you want to implement, it's also a good idea to talk to a senior developer before you start, especially if you're not sure how your feature will affect other parts of the code.

Make your changes against the trunk in Subversion, not a branch.

When you have a feature ready to go, post a patch in Bugzilla and ping the Bugmeister to have it reviewed and committed — this can be a slower process than just committing it yourself, but by doing it once or twice you demonstrate your good faith, and your ability to write reasonably stable code. In this regard, before you commit your feature, make sure it can be disabled easily.

When you are ready to write a new MediaWiki extension and you'd like to get it deployed on Wikimedia project servers, read Writing an extension for deployment.

Testing

Use E_STRICT in your php.ini to have unnecessary warnings and notices reported early.

When adding features, it's vital to verify you didn't break existing functionality. The usual tool for this is automated testing frameworks. MediaWiki's test suite is still relatively sparse. We have three kinds of tests:

• Parser tests (see tests/parserTests.php), which only test the parser. Try running php tests/parserTests.php --quick --quiet to see how those work. Everything should pass, in theory. You can add new tests or fix existing ones by editing tests/parserTests.txt.
• PHPUnit-based unit tests in the tests/phpunit directory. They are typically run through the phpunit.php script invoked from the aforementioned directory. These tests also include ordinary parser tests, though parserTests.php probably works faster. See Manual:PHP unit testing for PHPUnit setup instructions and further details.
• Selenium tests are in directory tests/selenium.

Anyway, if you can't write an automatic test, do manual testing. If you cause breakage too often, people will get annoyed at you, especially if it isn't caught until it goes live on Wikipedia. Revocation of commit access has been threatened in the past occasionally. At the very least, expect serious indignation if you check in syntax errors – try at least loading your wiki, or

php maintenance/checkSyntax.php --modified.

Turning display_startup_errors on

display_startup_errors is off by default on the toolserver. Turning it on within the program under test is too late! So create the following stub and execute that instead.

    error_reporting(0x7FFF ^ (E_NOTICE | E_STRICT));
    ini_set('display_startup_errors',1);
    ini_set("display_errors",1);
    include("program_currently_under_test.php");

Posting a patch

If you have created and tested a patch (for example to fix an annoying little bug), get a diff of the modified file by using:

svn diff path/to/modified_file.php > my.patch

Then post the patch as an attachment to the appropriate bug report.

See also

• "Learn how to hack MediaWiki" workshop
• Developer hub – When you've thoroughly read the information in this article, it's time to move on to the information in the developer hub.