Unfortunately there really isn't good documentation on creating extensions for MediaWiki. And a lot of the existing documentation is badly out of date. (This is kind of the reason why we still see a lot of use of the SpecialPage::addPage method when it has been depreciated).
Actually, JaeSharp once poked me to help start on creating a good source of help. I've got SMW and a good setup, cept I need to get God to watch PHP to keep it alive. I could create a developer help wiki for MediaWiki.
^_^ As for the boilerplate code... Honestly, JaeSharp was planning on creating a kind of generator code... Like how rails has generators to create scaffolding (models, views, and controllers which already work out of the box). That way extension developers could simply run a script with the name of their extension, and a bit of input on what kind of things they are using... Do they want it to not output i18n files, any special pages to create, any parserfunctions that need a i18n.magic, or extension class. And create relevant files from that.
~Daniel Friesen(Dantman) of: -The Gaiapedia (http://gaia.wikia.com) -Wikia ACG on Wikia.com (http://wikia.com/wiki/Wikia_ACG) -and Wiki-Tools.com (http://wiki-tools.com)
Sergey Chernyshev wrote:
Dan, thanks for this long overview, is there a wiki page on MediaWiki.org that describes all this? If not, I'll just refactor your email to a page if you don't mind.
It probably also makes sense to maintain some boilerplate code as well so new developers can have an easy start.
SergeyOn Fri, May 9, 2008 at 11:49 AM, DanTMan dan_the_man@telus.net wrote:
Magic Words also normally go in a: ExtensionName.i18n.magic.php
And for special pages: Special/SpecialPageName/.php and the class name should be the exact same as the filename without the .php
For the i18n files you also use $messages and $words for the magic word ones.
There are also some semi-enforced conventions in coding... What I kind of refer to as 'Standards' when I offer to help fix up an extension.
For the most part those are things like:
- Use $wgSpecialPages, not SpecialPage::addPage because the former is
less weight and the latter is depreciated.
- Use wfLoadMessage and a i18n file rather than using the
ExtensionFunction to load all the messages in. This improves performance as well.
- The standard of ExtensionName(.setup).php, and such is mildly enforced
to... I've seen Tim take a number of old extensions and change them to reflect the standard among extensions.
- Comment your files with a license or add a LICENSE or COPYING file.
Only Free-License stuff goes into SVN so it should be marked as such.
- It's not written or really enforced or anything, but it's common and
good to see people using @author, @license, etc... to mark files.
- Add your extension into $wgExtensionCredits to mark that it's
installed. And it's good to give it a url linking to a page where it's documented.
- Check if the 'MEDIAWIKI' is not defined! It's a security issue if
that's not there and you're running php code, so it's bad to see files without that. I developed the habit of putting the line into i18n files to, though don't know if other people do.
- Use $wgAutoloadClasses rather than loading php files directly.
- Use dirname(__FILE__) to determine the path to use for including
files. Don't rely on the include path, it can be a potential security issue, but mainly, it adds more stat calls. One of Wikia's techs was complaining that MediaWiki makes around 3000 stat calls trying to find php files on each load and it slows things down.
- This is a new one, but if you have maintenance scripts in your
extension, they should make use of the MW_INCLUDE_PATH environment variable if set when including things in the maintenance directory, and dirname(__FILE__) when including other files inside the extension. See CheckUser < http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/CheckUser/install...
.
- Don't do what SMW did with it's setup script
< http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/SemanticMediaWiki...
,
making the user specify database user and password instead of using AdminSettings.php is a major security flaw which is completely avoidable. And the same goes for implying that the wiki's database user should have administrative permissions like CREATE, DROP, and ALTER.
- Another one I drilled SMW on was temporary tables. When you are using
temporary tables, never use 'DROP' alone, you always use 'DROP TEMPORARY', not only is it a safety to ensure you don't remove a real table, if you don't use TEMPORARY then the wiki's database user is required to have DROP permissions which is not secure. And there isn't even any backwards compatibility issues. MySQL 4.0 ignores the TEMPORARY so you won't break it.
Just a few off ones which are good to follow:
- If your ParserFunctions do conditional things, use the dom frames in
the new parser. Take a look at ParserFunctions < http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/ParserFunctions/P...
to see how to.
The tricky thing about the conventions/standards is that they evolve, so you don't always know if part of your own convention is being outdated by something new in core.
There is one nice handy feature of core that I really wish extension would actually make use of. I see SMW, CheckUser, and piles of other extensions which require new SQL and some setup. Some give you a SQL file to run raw (Actually, they say to run it raw... But MediaWiki has a patchSql.php maintenance script which you should actually run because it handles your variables and such on it's own), and some others make an installation script for the extension to handle SQL. However, there is a very nice hook inside of MediaWiki I wish people would use more.
For quite some time updaters.inc has had a LoadExtensionSchemaUpdates hook. And the globals $wgExtNewTables, $wgExtNewFields, $wgExtPGNewFields, and $wgExtNewIndexes all for extensions. And while I don't know if it's something which is discouraged or not, but $wgMysqlUpdates could be appended to if you need a function called back to do schema stuff. Though, I expect that it's best if we tweaked updaters.inc to support a $wgExtMysqlUpdates and $wgExtPGUpdates for those. I honestly don't see people using them. But they would be great things to use. They're hooks and they're included into the updaters.inc file. All you'd have to do is hook into it and populate a few fields, and magically anyone wanting to install your extension would only need to include it into LocalSettings.php then run update.php.
~Daniel Friesen(Dantman) of: -The Gaiapedia (http://gaia.wikia.com) -Wikia ACG on Wikia.com (http://wikia.com/wiki/Wikia_ACG) -and Wiki-Tools.com (http://wiki-tools.com)
Roan Kattouw wrote:
Sergey Chernyshev schreef:
I really prefer to have my extensions in MW repository - so the next question then is what are the guidelines for SVN usage for Extension developers (especially tagging so developers of code-rich extensions
like
Semantic Forms and Semantic MediaWiki can use it),
The idea is that you put your extension in /mediawiki/trunk/extensions/ExtensionName/ . How you organize that directory is more or less up to you, although there is a convention to call the setup file (the one that's included in LocalSettings.php) ExtensionName.setup.php or ExtensionName.php , the file with the interface messages and their translations ExtensionName.i18n.php and the file with the actual code ExtensionName.body.php . Larger extensions will probably want to put classes in their own files, and put the 'main' code flow in the .body.php file.
and how does one get commit access to the repository ;)
Ask Brion Vibber. To quote him, commit access is granted to everyone who asks for it and has shown they're not a baboon. In practice, that means either having submitted a few patches to BugZilla or maintaining an extension.
Also, can you guys import a project from another repository, e.g. Google code hosting (first two in line will be "Header Tabs" and "Widgets" extensions)?
Importing the files in their current state is pretty easy. Importing the files with history is probably gonna be tricky.
Roan Kattouw (Catrope)
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l