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 be handled by the extension. They consist of three main component declarations: store, validator and an optional form. The following example shows how to add a provider 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"
				}
			}
		}
	},

There are other mechanisms for registering a new configuration provider, through MW Configuration setting $wgCommunityConfigurationProviders or using the CommunityConfigurationProvider_initListHook hook, CommunityConfigurationProvider_initListHook.

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

PHP schemas

CommunityConfiguration is designed to work with PHP files as the source for defining json-schema compliant documents. This approach is also used in other MediaWiki software components such as MainConfigSchema. The support for PHP schemas is built ad-hoc in the extension and has limitations compared to the full json-schema specification.

Limitations

• Limited support for json-schema version draft-04
• root schema must be of "type": "object"
• additionalProperties is set to false for root properties

JSON-schema vocabulary

The following json-schema keywords are supported:

• additionalProperties
• default
• properties
• type
• items
• enum
• $ref

Extended vocabulary

• control

Versioning

Schema definitions need to change occasionally due to new product or technical requirements. CommunityConfiguration provides a way for developers to migrate between schema versions. All schemas extending the JsonSchema class have a public constVERSION = '1.0.0' that can be override for bumping the schema version, eg: public constVERSION = '1.0.1'. Learn more about migrations in the section below.

Migrations

In order for CommunityConfiguration to ease with a schema version migration a convenience maintenance script CommunityConfiguration/maintenance/migrateConfig.php is provided. Find the steps to prepare for a migration below:

Backup the current schema

In order to access older schema versions, create a copy of the current schema version in some directory in your extension. The schema backup file name should contain its version number suffixed with underscore separators and the class name should also be updated to avoid duplicating the already declared. For example:

Schemas
├── Migrations
│   └── MySchema_1_0_0.php
└── MySchema.php

Link the older schema to the new one using: public const SCHEMA_NEXT_VERSION = '2.0.0';

Bump the schema version

Once the new schema version definitions have been added, removed or changed, set a higher version number in the schema file, MySchema.php. Link the new schema version to the older one using SCHEMA_PREVIOUS_VERSION. For example:

class MySchema extends JsonSchema {

	public const VERSION = '2.0.0';
	public const SCHEMA_PREVIOUS_VERSION = '1.0.0';
	public const SCHEMA_CONVERTER = MySchemaConverter_2_0_0::class;
    
    // Add, remove or change definitions
    
    public const NewDefinition = [
        self::TYPE => self::TYPE_STRING,
		self::DEFAULT => '',
    ]
}

Create a converter

In order to be able to transform some configuration data format from one schema version to another, the extension provides conventional methods in the ISchemaConverter interface. Create a PHP class implementing such interface and suffixing the new version number on its file name, for example:

Schemas
├── Converters
│   └── MySchemaConverter_2_0_0.php
├── Migrations
│   └── MySchema_1_0_0.php
└── MySchema.php

Implement interface methods upgradeFromOlder and downgradeFromNewer, for example:

class MySchemaConverter_2_0_0 implements ISchemaConverter {

	public function upgradeFromOlder( stdClass $data ): stdClass {
		$data->NewDefinition = '';
		return $data;
	}

	public function downgradeFromNewer( stdClass $data ): stdClass {
		unset( $data->NewDefinition );
		return $data;
	}
}

Run the migration

In order to apply the migration to the existing config use migrateConfig maintenance script in the extension pointing to the provider using the target schema.

> php extensions/CommunityConfiguration/maintenance/migrateConfig.php MyProvider

Glossary

• schema: polysemic, it can refer to a full configuration specification in a PHP file, eg: MySchema.php or to the specification of a property at any level in the schema, eg: { "type": "string" }

• subschema: used to disambiguate schema, refers to the specification of a property at any level in the schema as opposed to the full schema.

• root schema: used to disambiguate schema, refers to the top level specification of a full schema. In CommunityConfiguration this is restricted to be "type": "object", see [Extension:CommunityConfiguration/Technical_documentation#tbd].

• property: refers to the schema defined under the key "properties" in any schema.

• root property: refers to the schema defined under the key "properties" in the root schema.