MediaWiki extension repository template

This repository template is designed to allow quickly building open-source MediaWiki extensions within the ecosystem. It comes with everything that's needed to help ensure the extension follows MediaWiki's best practices and coding conventions.

Roadmap

• Show examples of creating a special page
• Show examples of using MediaWiki hooks
• Show examples of creating a MediaWiki Action API module
• Show examples of creating a MediaWiki REST API endpoint
• Show examples of using ResourceLoader (MediaWiki's bundler system, comparable to software like Webpack, esbuild, and Rollup)
• Show examples of using PHPUnit with MediaWiki's core test infrastructure
• Integrate GitHub Actions for CI/CD

Get started

Prerequisites

First, make sure you have a local MediaWiki instance running. You can do this in a few ways:

• Installing directly on your machine [MacOS, Windows/WSL, Debian/Ubuntu, others...]
• Installing with Vagrant [GitHub repo (mirror), Gerrit repo (source)]: automatically provisions a virtual machine (via VirtualBox) with a MediaWiki instance and all of its dependencies
• Installing with MediaWiki-Docker [Docker Hub, repo]: Runs MediaWiki in a Docker container

Creating a new repository

GitHub UI

You can create a new repository based on this template by clicking the "Use this template" button in the top-right corner of this page.

Terminal

You can run the following command below with the GitHub CLI. Some notes:

• Replace placeholder with name of your extension in upper CamelCase
• Configure your repository's visibility with --public, --private, or --internal

gh repo create {{extension-uc}} --clone --template neoncitylights/mediawiki-extension-template

Cookiecutter stuff

Using your favorite text editor or IDE, find-and-replace the following placeholders:

• {{author}}: Your own username/nickname, name, or organization
• {{extension-uc}}, ExtensionUc: Name of your extension in upper CamelCase
• {{extension-lc}}: Name of your extension in lowercase

Running the extension locally

To get started, run the following commands in your terminal. This assumes you're in the root directory of your MediaWiki extension.

npm install      # Install Node.js developer dependencies
composer install # Install Composer developer dependencies

Then, in your MediaWiki's instance containing LocalSettings.php, add the following line at the bottom:

wfLoadExtension( 'BoilerPlate' ); // Replace "BoilerPlate" with the name of your extension

Confirm the extension is working

To confirm, visit Special:Version and Special:HelloWorld! E.g If you're running on port 8080, visit these links:

• http://localhost:8080/index.php?title=Special:Version
• http://localhost:8080/index.php?title=Special:HelloWorld

Setup and configure

Tool	Files	Links
MediaWiki extension configuration	extension.json	docs, schema reference
NPM configuration	package.json	docs, website, repo
Composer configuration	composer.json	docs, website, repo
Localization and translated messages	i18n/	docs
Gruntfile (JS task runner)	Gruntfile.js	docs, website, repo
ESLint (JS linter)	.eslintrc.json	docs, website, repo
Stylelint (CSS linter)	.stylelintrc.json	docs, website, repo
PHPCS (PHP linter)	phpcs.xml	repo
Phan (PHP static analysis)	.phan/config.php	mw.org docs, phan repo, mw plugin repo
PHPUnit (PHP unit testing framework)	phpunit.xml.dist	docs, website, repo
Dependabot (dependency updates)	.github/dependabot.yml	docs

Notes

Setting up your local code editor/IDE environment

Intellisense (or intelligent code completion) is supported by many code editors and IDEs. To make sure you have this enabled, you'll need to make sure you have your MediaWiki directory open, to avoid warnings like Undefined type 'SpecialPage'. There's also a few setups I recommend below, however you can use whatever works best for you. :-)

• Visual Studio Code (by Microsoft, free, open-source), with PHP Intelephense, PHP Debug extensions installed
• PHPStorm (by JetBrains, closed-source), with the MediaWiki Support plugin installed. This IDE has various pricing plans, but is free for students/teachers. MediaWiki.org also has an article about requesting a JetBrains license key by contacting one of the account administrators.

Configuring the minimum-supported PHP version

Note Please also keep in mind whether or not the minimum MediaWiki version you're running against supports that specific PHP version.

There's a few different files you'll need to change.

• composer.json: Change the require.php key. An example for supporting PHP 7.4 or greater:

  "require": {
    "php": ">=7.4"
  }

• extension.json: Change the requires.platform.php key. To support PHP 7.4 or greater:

  "requires": {
    "platform": {
      "php": ">= 7.4"
    }
  }

• .github/workflows/ci.yml: Change the php key in the matrix section.

• .phan/config.php: Change the minimum_target_php_version key.

• README.md: Change your main, user-facing documentation where the system requirements section is to reflect the minimum PHP version.

Configuring MediaWiki extension dependencies and minimum-supported MediaWiki version

extension.json

In the MediaWiki ecosystem, we use composer.json mostly for developer dependencies. However, we use extension.json overall for registering MediaWiki extensions (and skin.json for registering MediaWiki skins).

If your extension depends on other MediaWiki extensions to work (e.g BetaFeatures, Echo, etc.), you can add them to the extension.json file via the requires.extensions key.

Note Unlike other ecosystems where it's common to use semantic versioning (e.g. ^1.2.3), MediaWiki extensions use a different versioning scheme, and different extensions will vary in their compatibility policy. Some special notes:

• You can use any version syntax that Composer supports.
• A wildcard (*) means that any version of the extension is acceptable.
• You can view an extension's compatibility policy by visiting their page on MediaWiki.org.

{
	"requires": {
		"MediaWiki": ">= 1.39",
		"extensions": {
			"BetaFeatures": "*",
			"Echo": "*"
		}
	}
}

README.md

You should also update your README.md instructions on how to install your extension, e.g the instructions for editing LocalSettings.php might look like:

wfLoadExtension( 'BetaFeatures' );
wfLoadExtension( 'Echo' );
wfLoadExtension( 'BoilerPlate' );