This is a class for holding configuration settings, particularly for multi-wiki sites. More...

Public Member Functions
	extractAllGlobals ( $wiki, $suffix=null, $params=[], $wikiTags=[])
	Retrieves the values of all settings, and places them in their corresponding global variables.

	extractGlobal ( $setting, $wiki, $suffix=null, $params=[], $wikiTags=[])
	Retrieves the value of a given setting, and places it in its corresponding global variable.

	extractGlobalSetting ( $setting, $wiki, $params)

	extractVar ( $setting, $wiki, $suffix, &$var, $params=[], $wikiTags=[])
	Retrieves the value of a given setting, and places it in a variable passed by reference.

	get ( $settingName, $wiki, $suffix=null, $params=[], $wikiTags=[])
	Retrieves a configuration setting for a given wiki.

	getAll ( $wiki, $suffix=null, $params=[], $wikiTags=[])
	Gets all settings for a wiki.

	getBool ( $setting, $wiki, $suffix=null, $wikiTags=[])
	Retrieves a configuration setting for a given wiki, forced to a boolean.

	getConfig ( $wiki, $settings)
	Get the resolved (post-setup) configuration of a potentially foreign wiki.

	getLocalDatabases ()
	Retrieves an array of local databases.

	loadFullData ()

	siteFromDB ( $wiki)
	Work out the site and language name from a database name.

Public Attributes
string array	$fullLoadCallback = null
	Optional callback to load full configuration data.

	$fullLoadDone = false
	Whether or not all data has been loaded.

	$settings = []
	The whole array of settings.

string array	$siteParamsCallback = null
	A callback function that returns an array with the following keys (all optional):

	$suffixes = []
	Array of suffixes, for self::siteFromDB()

	$wikis = []
	Array of wikis, should be the same as $wgLocalDatabases.

Protected Member Functions
	getWikiParams ( $wiki)
	Return specific settings for $wiki See the documentation of self::$siteParamsCallback for more in-depth documentation about this function.

	mergeParams ( $wiki, $suffix, array $params, array $wikiTags)
	Merge params between the ones passed to the function and the ones given by self::$siteParamsCallback for backward compatibility Values returned by self::getWikiParams() have the priority.

Protected Attributes
array	$cfgCache = []
	Configuration cache for getConfig()

Private Member Functions
	processSetting (array $thisSetting, $wiki, array $params)
	Retrieve the configuration setting for a given wiki, based on an overrides array.

Static Private Member Functions
static	arrayMerge (array $array1, array $array2)
	Merge multiple arrays together.

Detailed Description

This is a class for holding configuration settings, particularly for multi-wiki sites.

A basic synopsis:

Consider a wikifarm having three sites: two production sites, one in English and one in German, and one testing site. You can assign them easy-to-remember identifiers - ISO 639 codes 'en' and 'de' for language wikis, and 'beta' for the testing wiki.

You would thus initialize the site configuration by specifying the wiki identifiers:

$conf = new SiteConfiguration;

$conf->wikis = [ 'de', 'en', 'beta' ];

SiteConfiguration

This is a class for holding configuration settings, particularly for multi-wiki sites.

Definition SiteConfiguration.php:121

When configuring the MediaWiki global settings (the $wg variables), the identifiers will be available to specify settings on a per wiki basis.

$conf->settings = [
 'wgSomeSetting' => [
 
    # production:
    'de'     => false,
    'en'     => false,
 
    # test:
    'beta    => true,
 ],
];

With three wikis, that is easy to manage. But what about a farm with hundreds of wikis? Site configuration provides a special keyword named 'default' which is the value used when a wiki is not found. Hence the above code could be written:

$conf->settings = [
 'wgSomeSetting' => [
 
    'default' => false,
 
    # Enable feature on test
    'beta'    => true,
 ],
];

Since settings can contain arrays, site configuration provides a way to merge an array with the default. This is very useful to avoid repeating settings again and again while still maintaining specific changes on a per wiki basis.

$conf->settings = [
 'wgMergeSetting' = [
    # Value that will be shared among all wikis:
    'default' => [ NS_USER => true ],
 
    # Leading '+' means merging the array of value with the defaults
    '+beta' => [ NS_HELP => true ],
 ],
];
 
# Get configuration for the German site:
$conf->get( 'wgMergeSetting', 'de' );
// --> [ NS_USER => true ];
 
# Get configuration for the testing site:
$conf->get( 'wgMergeSetting', 'beta' );
// --> [ NS_USER => true, NS_HELP => true ];

Finally, to load all configuration settings, extract them in global context:

# Name / identifier of the wiki as set in $conf->wikis
$wikiID = 'beta';
$globals = $conf->getAll( $wikiID );
extract( $globals );

Note: For WikiMap to function, the configuration must define string values for $wgServer (or $wgCanonicalServer) and $wgArticlePath, even if these are the same for all wikis or can be correctly determined by the logic in Setup.php.

Todo:: Give examples for suffixes: $conf->suffixes = [ 'wiki' ];

Definition at line 121 of file SiteConfiguration.php.

Member Function Documentation

◆ arrayMerge()

static SiteConfiguration::arrayMerge	(	array	$array1,
		array	$array2
	)

staticprivate

Merge multiple arrays together.

On encountering duplicate keys, merge the two, but ONLY if they're arrays. PHP's array_merge_recursive() merges ANY duplicate values into arrays, which is not fun

Parameters

array	$array1
array	$array2

Returns: array

Definition at line 596 of file SiteConfiguration.php.

References arrayMerge().

Referenced by arrayMerge(), extractGlobalSetting(), getAll(), and processSetting().

◆ extractAllGlobals()

SiteConfiguration::extractAllGlobals	(	$wiki,
		$suffix = `null`,
		$params = `[]`,
		$wikiTags = `[]`
	)

Retrieves the values of all settings, and places them in their corresponding global variables.

Parameters

string	$wiki	Wiki ID of the wiki in question.
string \| null	$suffix	The suffix of the wiki in question.
array	$params	List of parameters. $.'key' is replaced by $value in all returned data.
array	$wikiTags	The tags assigned to the wiki.

Definition at line 398 of file SiteConfiguration.php.

References extractGlobalSetting(), and mergeParams().

◆ extractGlobal()

SiteConfiguration::extractGlobal	(	$setting,
		$wiki,
		$suffix = `null`,
		$params = `[]`,
		$wikiTags = `[]`
	)

Retrieves the value of a given setting, and places it in its corresponding global variable.

Parameters

string	$setting	ID of the setting name to retrieve
string	$wiki	Wiki ID of the wiki in question.
string \| null	$suffix	The suffix of the wiki in question.
array	$params	List of parameters. $.'key' is replaced by $value in all returned data.
array	$wikiTags	The tags assigned to the wiki.

Definition at line 362 of file SiteConfiguration.php.

References extractGlobalSetting(), and mergeParams().

◆ extractGlobalSetting()

SiteConfiguration::extractGlobalSetting	(	$setting,
		$wiki,
		$params
	)

Parameters

string	$setting
string	$wiki
array	$params

Definition at line 374 of file SiteConfiguration.php.

References arrayMerge(), and processSetting().

Referenced by extractAllGlobals(), and extractGlobal().

◆ extractVar()

SiteConfiguration::extractVar	(		$setting,
			$wiki,
			$suffix,
		&	$var,
			$params = `[]`,
			$wikiTags = `[]`
	)

Retrieves the value of a given setting, and places it in a variable passed by reference.

Parameters

string	$setting	ID of the setting name to retrieve
string	$wiki	Wiki ID of the wiki in question.
string	$suffix	The suffix of the wiki in question.
array	&$var	Reference The variable to insert the value into.
array	$params	List of parameters. $.'key' is replaced by $value in all returned data.
array	$wikiTags	The tags assigned to the wiki.

Definition at line 345 of file SiteConfiguration.php.

◆ get()

SiteConfiguration::get	(	$settingName,
		$wiki,
		$suffix = `null`,
		$params = `[]`,
		$wikiTags = `[]`
	)

Retrieves a configuration setting for a given wiki.

Parameters

string	$settingName	ID of the setting name to retrieve
string	$wiki	Wiki ID of the wiki in question.
string \| null	$suffix	The suffix of the wiki in question.
array	$params	List of parameters. $.'key' is replaced by $value in all returned data.
array	$wikiTags	The tags assigned to the wiki.

Returns: mixed The value of the setting requested.

Definition at line 178 of file SiteConfiguration.php.

References mergeParams(), and processSetting().

◆ getAll()

SiteConfiguration::getAll	(	$wiki,
		$suffix = `null`,
		$params = `[]`,
		$wikiTags = `[]`
	)

Gets all settings for a wiki.

Parameters

string	$wiki	Wiki ID of the wiki in question.
string \| null	$suffix	The suffix of the wiki in question.
array	$params	List of parameters. $.'key' is replaced by $value in all returned data.
array	$wikiTags	The tags assigned to the wiki.

Returns: array Array of settings requested.

Definition at line 293 of file SiteConfiguration.php.

References arrayMerge(), mergeParams(), and processSetting().

◆ getBool()

SiteConfiguration::getBool	(	$setting,
		$wiki,
		$suffix = `null`,
		$wikiTags = `[]`
	)

Retrieves a configuration setting for a given wiki, forced to a boolean.

Parameters

string	$setting	ID of the setting name to retrieve
string	$wiki	Wiki ID of the wiki in question.
string \| null	$suffix	The suffix of the wiki in question.
array	$wikiTags	The tags assigned to the wiki.

Returns: bool The value of the setting requested.

Definition at line 323 of file SiteConfiguration.php.

◆ getConfig()

SiteConfiguration::getConfig	(	$wiki,
		$settings
	)

Get the resolved (post-setup) configuration of a potentially foreign wiki.

For foreign wikis, this is expensive, and only works if maintenance scripts are setup to handle the –wiki parameter such as in wiki farms.

Parameters

string	$wiki
array \| string	$settings	A setting name or array of setting names

Returns: mixed|mixed[] Array if $settings is an array, otherwise the value

Exceptions

MWException

Since: 1.21

Definition at line 533 of file SiteConfiguration.php.

References $IP, $res, $settings, and unserialize().

◆ getLocalDatabases()

SiteConfiguration::getLocalDatabases ( )

Retrieves an array of local databases.

Returns: array

Definition at line 332 of file SiteConfiguration.php.

References $wikis.

◆ getWikiParams()

SiteConfiguration::getWikiParams ( $wiki )

protected

Return specific settings for $wiki See the documentation of self::$siteParamsCallback for more in-depth documentation about this function.

Parameters

string $wiki

Returns: array

Definition at line 415 of file SiteConfiguration.php.

References $siteParamsCallback.

Referenced by mergeParams(), and siteFromDB().

◆ loadFullData()

SiteConfiguration::loadFullData ( )

Definition at line 628 of file SiteConfiguration.php.

References $fullLoadCallback.

◆ mergeParams()

SiteConfiguration::mergeParams	(		$wiki,
			$suffix,
		array	$params,
		array	$wikiTags
	)

protected

Merge params between the ones passed to the function and the ones given by self::$siteParamsCallback for backward compatibility Values returned by self::getWikiParams() have the priority.

Parameters

string	$wiki	Wiki ID of the wiki in question.
string	$suffix	The suffix of the wiki in question.
array	$params	List of parameters. $.'key' is replaced by $value in all returned data.
array	$wikiTags	The tags assigned to the wiki.

Returns: array

Definition at line 454 of file SiteConfiguration.php.

References getWikiParams().

Referenced by extractAllGlobals(), extractGlobal(), get(), and getAll().

◆ processSetting()

SiteConfiguration::processSetting	(	array	$thisSetting,
			$wiki,
		array	$params
	)

private

Retrieve the configuration setting for a given wiki, based on an overrides array.

General order of precedence:

Wiki ID, an override specific to the given wiki.
Tag, an override specific to a group of wikis (e.g. wiki family, or db shard). It is unsupported for the same setting to be set for multiple tags of which the wiki groups overlap. In that case, whichever is iterated and matched first wins, where the tag iteration order is NOT guaranteed.
Default, the default value for all wikis in this wiki farm.

If the "+" operator is used, with any of these, then the merges will follow the following order (earlier entries have precedence on clashing sub keys):

"+wiki"
"tag" Only one may match here. And upon match, the merge cascade stops.
"+tag" These are only considered if there was no "tag" match. Multiple matches are allowed here, although the array values from multiple tags that contain the same wiki must not overlap, as it is undocumented how key conflicts among them would be handled.
"default"

Parameters

array	$thisSetting	An array of overrides for a given setting.
string	$wiki	Wiki ID of the wiki in question.
array	$params	Array of parameters.

Returns: mixed The value of the setting requested.

Definition at line 217 of file SiteConfiguration.php.

References arrayMerge().

Referenced by extractGlobalSetting(), get(), and getAll().

◆ siteFromDB()

SiteConfiguration::siteFromDB ( $wiki )

Work out the site and language name from a database name.

Parameters

string $wiki Wiki ID

Returns: array

Definition at line 495 of file SiteConfiguration.php.

References $lang, and getWikiParams().

Member Data Documentation

◆ $cfgCache

array SiteConfiguration::$cfgCache = []

protected

Configuration cache for getConfig()

Definition at line 167 of file SiteConfiguration.php.

◆ $fullLoadCallback

string array SiteConfiguration::$fullLoadCallback = null

Optional callback to load full configuration data.

Definition at line 142 of file SiteConfiguration.php.

Referenced by loadFullData().

◆ $fullLoadDone

SiteConfiguration::$fullLoadDone = false

Whether or not all data has been loaded.

Definition at line 145 of file SiteConfiguration.php.

◆ $settings

SiteConfiguration::$settings = []

The whole array of settings.

Definition at line 136 of file SiteConfiguration.php.

Referenced by getConfig().

◆ $siteParamsCallback

string array SiteConfiguration::$siteParamsCallback = null

A callback function that returns an array with the following keys (all optional):

suffix: site's suffix
lang: site's lang
tags: array of wiki tags
params: array of parameters to be replaced The function will receive the SiteConfiguration instance in the first argument and the wiki in the second one. if suffix and lang are passed they will be used for the return value of self::siteFromDB() and self::$suffixes will be ignored

Definition at line 161 of file SiteConfiguration.php.

Referenced by getWikiParams().

◆ $suffixes

SiteConfiguration::$suffixes = []

Array of suffixes, for self::siteFromDB()

Definition at line 126 of file SiteConfiguration.php.

◆ $wikis

SiteConfiguration::$wikis = []

Array of wikis, should be the same as $wgLocalDatabases.

Definition at line 131 of file SiteConfiguration.php.

Referenced by getLocalDatabases().

The documentation for this class was generated from the following file:

includes/SiteConfiguration.php

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Private Member Functions

Static Private Member Functions

Detailed Description

Member Function Documentation

◆ arrayMerge()

◆ extractAllGlobals()

◆ extractGlobal()

◆ extractGlobalSetting()

◆ extractVar()

◆ get()

◆ getAll()

◆ getBool()

◆ getConfig()

◆ getLocalDatabases()

◆ getWikiParams()

◆ loadFullData()

◆ mergeParams()

◆ processSetting()

◆ siteFromDB()

Member Data Documentation

◆ $cfgCache

◆ $fullLoadCallback

◆ $fullLoadDone

◆ $settings

◆ $siteParamsCallback

◆ $suffixes

◆ $wikis