Extension:CommunityConfiguration/Technical documentation

Getting started

Registering a new provider

Community configuration providers are a formal description of how a set of configuration options should handled by the extension. They consist of three main component declarations: store, validator and an optional form. See more in "docs/tbd". The following example shows the minimal definitions to get a provider up and working.

There are two mechanisms of registering a new configuration provider, through MW Configuration setting $wgCommunityConfigurationProviders or using the attributes property in extension.json

Using wgCommunityConfigurationProviders

$wgCommunityConfigurationProviders['MyProvider'] = [
	'store' => [
		'type' => 'wikipage',
		'args' => [
			'MediaWiki:ExampleConfig.json'
		]
	],
	'validator' => [
		'type' => 'jsonschema',
		'args' => [
			\CommunityConfigurationExample\Schemas\ExampleSchema::class
		]
	],
	'type' => 'mw-config'
];

Using extension.json attributes

"attributes": {
		"CommunityConfiguration": {
			"Providers": {
				"MyProvider": {
					"store": {
						"type": "wikipage",
						"args": [
							"MediaWiki:ExampleConfig.json"
						]
					},
					"validator": {
						"type": "jsonschema",
						"args": [
							"CommunityConfigurationExample\\Schemas\\ExampleSchema"
						]
					},
					"type": "mw-config"
				}
			}
		}
	},

Creating a JSON schema with PHP

The extensions provides a JsonSchema interface to facilitate creating JSON schema document representations with a PHP class. This also restricts the JSON schema features available to those Community Configuration can handle. Below a minimal example of an schema class:

<?php

namespace CommunityConfigurationExample\Schemas;

use MediaWiki\Extension\CommunityConfiguration\Schema\JsonSchema;

class ExampleSchema implements JsonSchema {
	public const ExampleConfigOption = [
		self::TYPE => self::TYPE_STRING
	];
}

Public class properties are collected as top level keys of an object. At this stage, Community Configuration can only work with type object for the top level data structure. Hence there's no support for top level type array. The ExampleSchema class would be expanded to the following JSON schema in json format:

{
	"$schema": "https://json-schema.org/draft-04/schema#"
	"$id": "CommunityConfigurationExample/Schemas/ExampleSchema/1.0.0",
	"type": "object",
	"properties": {
		"ExampleConfigOption": {
			"type": "string"
		}
	},
	"additionalProperties": false
}

Creating a new config page

The configuration data for a given set of options under a provider is stored as wiki json pages in the MediaWiki namespace. Whenever you create a new provider using the "type": "wikipage" for its store, you'll need to create the page on your target wiki and add a valid configuration for the first time. This action requires some privileged rights, currently, any of 'administrator', 'interface administrator' (see more in docs/CC-user-rights-tbd).

This process is tedious and not ideal, further improvements are being discussed in task T351517