User:Cneubauer/Extensions

For a list of user submitted extensions see Extension Matrix.

For documentation on enabling or configuring extensions see Help:Extensions.

Extensions:

Extensions add new features or functionality to MediaWiki. Depending on your goals you can use extensions to:

create new wiki markup like <this>, {{#this}}, OR_THIS.
create new special pages.
create new skins.
change the functionality of the wiki with a hook.

Example

Most extensions consist of three files: a small setup file which will be loaded every time MediaWiki starts, a class file with the bulk of the code, and an optional internationalization file. All of them should be placed in a subdirectory of the extensions/ directory. MediaWiki coding conventions define the three files like this:

<extension_name>.php - The setup file.
<extension_name>.body.php - The main body of the code.
<extension_name>.i18n.php - The internationalization file.

In the example below, <extension_name> is MyExtension. A working copy is available for download.

The Setup File

The setup file looks like this:

<?php
# Alert the user that this is not a valid entry point to MediaWiki if they try to access the skin file directly.
if (!defined('MEDIAWIKI')) {
        echo <<<EOT
To install my extension, put the following line in LocalSettings.php:
require_once( "$IP/extensions/MyExtension/MyExtension.php" );
EOT;
        exit( 1 );
}

$dir = dirname(__FILE__) . '/'; # store the location of the setup file.
$wgAutoloadClasses['MyExtension'] = $dir . 'MyExtension.body.php'; # Tell MediaWiki where the extension class is.
$wgExtensionFunctions[]='MyExtension::Setup'; # Do all initial setup here.
$wgExtensionMessagesFiles['MyExtension'] = $dir . 'MyExtension.i18n.php';

This file registers three important things:

The location of the MyExtension class. For more information on autoloading see #How do I autoload extension classes?
The setup function to run when the wiki is loaded. For more information on deferred setup see #How to I defer setup until its actually needed?
The location of a messages file.

More complex extensions might also:

define and/or validate any configuration variables you have defined for your extension.
determine what parts of your setup should be done immediately and what needs to be deferred until the MediaWiki core has been initialized and configured
register any special pages, custom XML tags, parser functions, and variables used by your extension.
define any additional hooks needed by your extension.

The Body File

The body file MyExtension.body.php will contain an extension class. It will be loaded automatically when the extension class is encountered. In this example, the MyExtension is called:

<?php
class MyExtension {
    public static function Setup() {
        # extension does setup stuff here.
    }

    # extension does other stuff here.
}

The technique for writing the implementation portion depends upon the part of MediaWiki system you wish to extend:

Wiki markup: Extensions that extend wiki markup will typically contain code that defines and implements custom XML tags, parser functions and variables. You can click on any of the links in the preceding sentence to get full details on how to implement these features in your extension.
Reporting and administration: Extensions that add reporting and administrative capabilities usually do so by adding special pages. For more information see Manual:Special pages.
Article automation and integrity: Extensions that improve the integration between MediaWiki and its backing database or check articles for integrity features, will typically add functions to one of the many hooks that affect the process of creating, editing, renaming, and deleting articles. For more information about these hooks and how to attach your code to them, please see Manual:Hooks.
Look and feel: Extensions that provide a new look and feel to mediaWiki are bundled into skins. For more information about how to write your own skins, see Manual:Skin and Manual:Skinning.
Security: Extensions that limit their use to certain users should integrate with MediaWiki's own permissions system. To learn more about that system, please see Manual:Preventing access. Some extensions also let MediaWiki make use of external authentication mechanisms. For more information, please see AuthPlugin. In addition, if your extension tries to limit readership of certain articles, please check out the gotchas discussed in Security issues with authorization extensions.

The Messages File

If your extension relies on messages which can be translated into other languages, they are defined in the Messages file like this:

<?php
$messages = array();
$messages['en'] = array( 
	'myextension' => 'My Extension'
	);
$messages['de'] = array(
	'myextension' => 'Meine Erweiterung'
	);

FAQ

How do I install an extension?

MediaWiki is ready to accept extensions just after installation is finished. To add an extension follow these steps:

Before you start
A few extensions require the installation of a patch. Many of them also provide instructions designed for installation using unix commands. You require shell access (SSH) to enter these commands listed on the extension help pages.
Download and install ExtensionFunctions.php.
Some extensions, especially newer ones, require a helper file called ExtensionFunctions.php. ExtensionFunctions includes a series of functions that allow extensions to be modularized away from the MediaWiki core code. The best way to install this file is to download the current version from SVN. This file is visible to the public here at all times. Once downloaded, copy the ExtensionFunctions.php file to the $IP/extensions/ subdirectory of your MediaWiki installation.
Download your extension.
Extensions are usually distributed as modular packages. They generally go in their own subdirectory of $IP/extensions/. A list of extensions documented on MediaWiki.org is available on the extension matrix, and a list of extensions stored in the Wikimedia SVN repository is located at svn:trunk/extensions. Some extensions are available as source code within this wiki. You may want to automatize copying them.

Unofficial bundles of the extensions in the Wikimedia SVN repository can be found at on the toolserver. These bundles are arbitrary snapshots, so keep in mind they might contain a broken version of the extension (just as if you load them from the developer's repository directly).

Install your extension.

Generally, at the end of the LocalSettings.php file, (but above the PHP end-of-code delimiter, "?>"), the following line should be added:

require_once "$IP/extensions/extension_name/extension_name.php";

This line forces the PHP interpreter to read the extension file, and thereby make it accessible to MediaWiki.

While this installation procedure is sufficient for most extensions, some require a different installation procedure. Check your extension's documentation for details.

Caution: While extension declaration can be placed in other places within the LocalSettings.php file, never place extensions before the require_once( "includes/DefaultSettings.php" ); line. Doing so will blank the extension setup function arrays, causing no extensions to be installed, and probably will make your wiki inaccessible until you fix it!

How do I see which extensions are installed on a wiki?

Anyone can check which extensions are active on an instance of MediaWiki by accessing the Special:Version article. For example, these extensions are active in the English Wikipedia.

How do I add my extension information to Special:Version?

You will need to add an entry to $wgExtensionCredits for each special page, custom XML tag, parser function, and variable used by your extension. The entry will look something like this:

   $wgExtensionCredits['validextensionclass'][] = array(
       'name' => 'Example',
       'author' =>'John Doe', 
       'url' => 'http://www.mediawiki.org/wiki/User:JDoe', 
       'description' => 'This Extension is an example and performs no discernable function'
   );

validextensionclass must be one of specialpage, parserhook, variable, other, as specified on Manual:$wgExtensionCredits.

How do I add my extension documentation to this site?

To autocategorize and standardize the documentation of your existing extension, please see Template:Extension. To add your new extension to this Wiki:

A developer sharing their code in the MediaWiki code repository should expect:

Feedback / Criticism / Code reviews: Review and comments by other developers on things like framework use, security, efficiency and usability.

Developer tweaking: Other developers modifying your submission to improve or clean-up your code to meet new framework classes and methods, coding conventions and translations.

Improved access for wiki sysadmins: If you do decide to put your code on the wiki, another developer may decide to move it to the MediaWiki code repository for easier maintenance. You may then create a Developer account to continue maintaining it.

Future versions by other developers: New branches of your code being created automatically as new versions of MediaWiki are released. You should backport to these branches if you want to support older versions.; Incorporation of your code into other extensions with duplicate or similar purposes — incorporating the best features from each extension.

Credit: Credit for your work being preserved in future versions — including any merged extensions.; Similarly, you should credit the developers of any extensions whose code you borrow from — especially when performing a merger.

Any developer who is uncomfortable with any of these actions occurring should not host in the code repository. You are still encouraged to create a summary page for your extension on the wiki to let people know about the extension, and where to download it.

How do I autoload extension classes?

If you choose to use classes to implement your extension, MediaWiki provides a simplified mechanism for helping php find the source file where your class is located. In most cases this should eliminate the need to write your own __autoload($classname) method.

To use MediaWiki's autoloading mechanism, you add entries to the variable $wgAutoloadClasses. The key of each entry is the class name; the value is the file that stores the definition of the class. For a simple one class extension, the class is usually given the same name as the extension, so your autoloading section might look like this (extension is named Foobar):

$wgAutoloadClasses['Foobar'] = dirname(__FILE__) . '/Foobar.body.php';

.

For complex extensions with multiple classes, your autoloading section might look like this:

$wgFoobarIncludes = dirname(__FILE__) . '/includes/';
$wgAutoloadClasses['SpecialFoobar'] 
  = $wgFoobarIncludes . 'SpecialFoobar.php'; #implements special page Foobar
$wgAutoloadClasses['FoobarTag']
  = $wgFoobarIncludes . 'FoobarTag.php';   #implements tag <foobar>

How to I defer setup until its actually needed?

LocalSettings.php runs early in the MediaWiki setup process and a lot of things are not fully configured at that point. This can cause problems for certain setup activities. To work around this problem, MediaWiki gives you a choice of when to run set up actions. You can either run them immediately by inserting the commands in your setup file -or- you can run them later, after MediaWiki has finished configuring its core software.

To defer setup actions, your setup file must contain two bits of code:

the definition of a setup function
the assignment of that function to the $wgExtensionFunctions array.

The PHP code should look something like this:

$wgExtensionFunctions[]='wfFoobarSetup';
function wfFoobarSetup() {
   #do stuff that needs to be done after setup
}