Extensions FAQ

How do I enable an extension?
Copy the extension PHP file to your extensions folder and add a require_once( "extensions/FILENAME" ); statement to your LocalSettings.php, with FILENAME being the filename of your extension, such as Extension.php.

How do I write my own extension?
See "Extending wiki markup".

How do I disable caching for pages using my extension?
The extension purgePage can also be used to perform the steps listed below, it works for MediaWiki 1.3 - 1.5. For MediaWiki 1.3, include the following code in your extension: global $wgOut; $wgOut->enableClientCache(false);

For MediaWiki 1.4, use this (won't necessarily work in all cases): global $wgTitle; $dbw =& wfGetDB( DB_MASTER ); $dbw->update( 'cur', array( 'cur_touched' => $dbw->timestamp( time + 120 ) ),     array( 'cur_namespace' => $wgTitle->getNamespace, 'cur_title' => $wgTitle->getDBkey ), 'nameOfYourExtension' );

Note: The above doesn't work for me in all cases. Using the same logic but with different code the following lines work much better. $ts = mktime; $now = gmdate("YmdHis", $ts + 120); $ns = $wgTitle->getNamespace; $ti = wfStrencode($wgTitle->getDBkey); $sql = "UPDATE cur SET cur_touched='$now' WHERE cur_namespace=$ns AND cur_title='$ti'"; wfQuery($sql, DB_WRITE, ""); For MediaWiki 1.4 the following also works (possibly better than the above method): global $wgTitle; wfPurgeSquidServers(array($wgTitle->getInternalURL)); $wgTitle->invalidateCache;

In MediaWiki 1.5beta5, a more reliable interface was introduced. Your parser hook function may take a parser object as a third parameter, by reference. Use the following code: function wfSomeHookFunction( $text, $params, &$parser ) { $parser->disableCache; ... } Note I am running version 1.5.8 and could not get any of the above to work. You can see the following code functioning properly |here. I had to use the following code in the second function of the extension (not the "setHook" function): global $wgTitle; $dbw =& wfGetDB( DB_MASTER ); $dbw->update( 'page', array( 'page_touched' => $dbw->timestamp( time + 120 ) ),     	array( 'page_namespace' => $wgTitle->getNamespace, 'page_title' => $wgTitle->getDBkey ), 'name of your Extension as defined in $wgExtensionFunctions[] =' 	); }

WARNING: In version 1.6 and many early versions of 1.7, it is impossible for extensions to prevent pages from being cached when edits are submitted. This is not expected behavior, see 5683. There are a number of ways to work around this issue:
 * Install the DisableCache hack. This is the most elegant solution, but has not been thoroughly tested.
 * Run action=purge after submitting edits. This is the safest choice, but may not be feasible in large wikis.
 * Disable caching site-wide. This will sharply increase the amount of work that your server will have to perform.  To disable all caching, put the following code in LocalSettings.php:


 * 1) Client-side caching:

/** Allow client-side caching of pages */ $wgCachePages      = false;

/** * Set this to current time to invalidate all prior cached pages. Affects both * client- and server-side caching. * You can get the current date on your server by using the command: *  date +%Y%m%d%H%M%S */ $wgCacheEpoch = 'date +%Y%m%d%H%M%S';

Recent versions
In MediaWiki 1.7.0 and upwards, the following should be sufficient:



where  is the reference to the parent parser that is passed as a third parameter to parser hook extensions.

Special pages
When rendering output that will not be subject to parser cache, such as on a special page

global $wgOut; $wgOut->parse( $text );

where $text is the wikitext to be parsed.

Parser hooks
Parser hook functions are passed a reference to the parser object and should use this to parse wikitext.

function efWonderfulHook( $text, $args, &$parser ) { $output = $parser->parse( $text, $parser->mTitle, $parser->mOptions, true, false ); return ' '. $output->getText. ' '; }

The fourth and fifth parameters to Parser::parse are $lineStart and $clearState; these dictate how the parser behaves. $lineStart, when true, indicates that the wikitext is to be treated as starting on a new line (use this when dealing with blocks, or handling lists, etc.). $clearState</tt>, when true, indicates that the parser should clear internal state information; in most cases, this should be false.

Note that Parser::parse returns a ParserOutput object, not raw HTML, as in the example above.

In cases where this does not work (often due to order of operations, nesting or other hook confusion), use a cloned copy of the parser object:

function efWonderfulHook( $text, $args, &$parser ) { $lparse = clone $parser; $output = $lparse->parse( $text, $parser->mTitle, $parser->mOptions, true, false ); return ' '. $output->getText. ' '; }

How can I avoid modification of my extension's HTML output?
This will probably require moving some code around in the parser. The current extension code assumes extensions will produce inline material and they are inserted before the final block-level rendering stages.

How can I pass XML-style parameters in my extension tag?
This is supported from MediaWiki 1.5. Accept a second parameter on your hook function, which will be an associative array of attribute => value pairs.

The value strings have already had HTML character entities decoded for you, so if you emit them back to HTML don't forget to use if (preg_match('/<div\\s+class="MyExtension"\\s+(.+?)\\s*\\/?>/', $article, $match)) { preg_match_all('/(\\w+?)="(.+?)"/', $match[1], $match, PREG_SET_ORDER);
 * In version 1.4x you can use a div element with a class name of your extension to be invisible and contain the attributes. The extension code can then match them from the article content. This example will extract and loop through all the attributes from a specified div class:

foreach ($match as $i) echo "attribute $i[1] contains $i[2]";

}
 * Nad 21:36, 21 August 2005 (UTC)


 * Addition/alternative to the 1.4x approach

As Nad's script didn't worked out for me a 100%, I developed something on me own, based on his solution. I put the div inside of the tags of my extension, so a different set of arguments can be passed to the extension on every use in one article. The var $input is the text between the extension tags, passed to the extension function.

Example:

name="Andreas" Other stuff, for the extension to process

Code: if (preg_match('/^ (.+)<\/div>/i', $input, $match)) { preg_match_all('/(\\w+?)="(.+?)"/', $match[1], $match, PREG_SET_ORDER); foreach ($match as $i) echo "attribute $i[1] contains $i[2]"; # remove the div with the arguments from the input string $input = preg_replace('@ .*? @si', '', $input); }
 * 1) try to extract attributes passed through a div

Hopefully this is of use for somebody.

Andreas Follmann | 15:34, 6. October 2005 (UTC)

I've installed an extension, but I get NaodW... output
MediaWiki 1.5(.1) has problems with some PHP versions which causes that output. You should upgrade to MediaWiki 1.5.2 or later.

Templates with extension tags
There is also similar problem when using template parameters inside extension tags (in template definition). It does occur only when an extension perform parsing of input string (between extension tags). When template is present, and such a template or extension tag appears somewhere else on the page, strange NaodW... strings are generated in result (seems as error of wiki parser).

''Note: In earlier versions of MediaWiki "NaodW..." is observed, and in later ones similar "UNIQ..." string appears.''

Additionally, if symbol of parameter is used inside extension tags (e.g.   ), it is left visible for the user as if was not parsed (seems as another parser problem).


 * A similar problem occurs in 1.5.3 (with PHP 5.0.5) when using text on a page which uses another, different custom extension tag set. The custom extension tags rendered as NaodW... strings instead of their expected output.

How can I determine in my extension, if an article is protected or not?
Use the Title class and the isProtected method, e.g.

function extensionFunction { # Assume $title is the title object if( $title->isProtected( 'edit' ) ) { # Protected from editing, do things } else { # Not protected from editing } }

What permissions do I apply to the extensions folder?
All the scripts in the /wiki structure need to be readable and executable by the user that PHP runs as. All perms are usually 755 and owner/group being that user. The LocalSettings.php file is created by the script on setup and so will be an example to set the rest by.
 * Nad 19:43, 7 March 2006 (UTC)

How do I get my extension to show up on Special:Version?
In order for your extension to be displayed on the Special:Version page in MediaWiki, you must assign extension credits within your PHP code.

To do this, add a $wgExtensionCredits variable as the first executable line of code before your hook line or function definition

An example extension credit is: <?php /** * Example.php * This Extension does ....... * written by John Doe * http://www.johndoe.com * To activate the functionality of this extension include the following in your * LocalSettings.php file: * require_once('$IP/extensions/Example.php'); */ if(! defined( 'MEDIAWIKI' ) ) { echo( "This is an extension to the MediaWiki package and cannot be run standalone.\n" ); die( -1 ); } else { $wgExtensionCredits['validextensionclass'][] = array(      'name' => 'Example',       'author' =>'John doe',        'url' => 'http://www.mediawiki.org/wiki/User:JDoe', www.JohnDoe.com',       'description' => 'This Extension is an example and performs no discernable function'

.....

function fnExample{

.....

} } ?>

Replace 'validextensionclass' with one of the following:
 * 'specialpage' -- reserved for additions to Mediawiki Special Pages;
 * 'parserhook' -- used if your extension modifies, complements, or replaces the parser functions in MediaWiki;
 * 'variable' -- extension that add multiple functionality to MediaWiki;
 * 'other' -- all other extensions.