README

ContentProvisioner for MediaWiki

Provides a mechanism which allows to import some arbitrary information during "maintenance/update.php".

This code is meant to be executed within the MediaWiki application context. No standalone usage is intended.

Usage in MediaWiki extension

MediaWiki 1.35

Add "mwstake/mediawiki-component-contentprovisioner": "~1" to the require section of your composer.json file.

MediaWiki 1.39

Add "mwstake/mediawiki-component-contentprovisioner": "~2" to the require section of your composer.json file.

Explicit initialization is required. This can be achieved by

either adding "callback": "mwsInitComponents" to your extension.json/skin.json
or calling mwsInitComponents(); within you extensions/skins custom callback method

Register content to provision

Initially, content provisioner needs "manifest" file to get data to import from. JSON file with such structure is needed:

{
	"Some_page": {
		"lang": "de",
		"target_title": "Some_page",
		"content_path": "/pages/Main/Some_page.wiki",
		"sha1": "<hash_of_the_content>",
		"old_sha1": []
	},
	"Template:Some_template": {
		"lang": "en",
		"target_title": "Template:Some_template",
		"content_path": "/pages/Template/Some_template.wiki",
		"sha1": "<hash_of_the_content>",
		"old_sha1": []
	}
}

Here, "old_sha1" key contains hashes for previous content versions. It is needed for cases with already existing wiki pages, to identify if they are just outdated or were added/changed by user.

Such files should be registered in "extension.json" of particular extension that way:

{
	"attributes": {
		"MWStakeContentProvisioner": {
			"ContentManifests": {
				"DefaultContentProvisioner": [
					"extensions/SomeExtension/path/to/manifest.json"
				]
			}
		}
	}
}

Manifests added to "DefaultContentProvisioner" key will be processed by default content provisioner. That content provisioner just imports corresponding wiki pages which are provided by manifest.

All registered files will be processed during next update with "maintenance/update.php".

Custom content provisioners

Extensions may implement their own import logic within their own content provisioners. To do so, it is needed to have a class, implementing "\MWStake\MediaWiki\Component\ContentProvisioner\IContentProvisioner" interface.

Register custom content provisioner

To be executed during "update.php", custom content provisioner must be registered in such way (ObjectFactory specification):

{
	"attributes": {
		"MWStakeContentProvisioner": {
			"ContentProvisioners": {
				"ArbitraryContentProvisionerKey": {
					"class": "\\MediaWiki\\Path\\To\\ArbitraryProvisioner",
					"args": [
						"ManifestsKey"
					],
					"services": [
						"ArbitraryService",
						"SomeOtherService"
					]
				}
			}
		}
	}
}

Here "ArbitraryContentProvisionerKey" is a key, which is used just to identify content provisioner. It is used mostly for logging. "ManifestsKey" is a key which will help to recognize manifests which should be processed by this specific content provisioner.

Register custom content to import

By default, custom manifest file, which will be processed by custom content provisioner, must be registered such way:

{
	"attributes": {
		"MWStakeContentProvisioner": {
			"ContentManifests": {
				"ManifestsKey": [
					"extensions/SomeExtension/path1/to/manifest1.json",
					"extensions/SomeExtension/path2/to/manifest2.json"
				]
			}
		}
	}
}

Here "ManifestsKey" must be the same value which was passed to that content provisioner as first argument.

Skip content provisioners

If some of content provisioners needs to be disabled, it can be done with $mwsgContentProvisionerSkip global. Let's assume that there is some custom content provisioner which is registered that way:

{
	"attributes": {
		"MWStakeContentProvisioner": {
			"ContentProvisioners": {
				"ArbitraryContentProvisionerKey": {
					"class": "\\MediaWiki\\Path\\To\\ArbitraryProvisioner",
					"args": [
						"ManifestsKey"
					],
					"services": [
						"ArbitraryService",
						"SomeOtherService"
					]
				}
			}
		}
	}
}

Then it can be disabled in that way:

$mwsgContentProvisionerSkip[] = 'ArbitraryContentProvisionerKey';

If there is a need to disable default content provisioner, it looks similar:

$mwsgContentProvisionerSkip[] = 'DefaultContentProvisioner';

mwstake / mediawiki-component-contentprovisioner

Maintainers

Details