MediaWiki REL1_32
SiteConfiguration Class Reference

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

Collaboration diagram for SiteConfiguration:

Public Member Functions

 doReplace ( $from, $to, $in)
 Type-safe string replace; won't do replacements on non-strings private?
 
 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 ( $db)
 Work out the site and language name from a database name.
 

Static Public Member Functions

static arrayMerge ( $array1)
 Merge multiple arrays together.
 

Public Attributes

string array $fullLoadCallback = null
 Optional callback to load full configuration data.
 
 $fullLoadDone = false
 Whether or not all data has been loaded.
 
 $localVHosts = []
 Array of domains that are local and can be handled by the same server.
 
 $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

 getSetting ( $settingName, $wiki, array $params)
 Really retrieves a configuration setting for a given wiki.
 
 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()
 

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' ];
This is a class for holding configuration settings, particularly for multi-wiki sites.

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 ];
const NS_HELP
Definition Defines.php:76
const NS_USER
Definition Defines.php:66
null means default in associative array with keys and values unescaped Should be merged with default with a value of false meaning to suppress the attribute in associative array with keys and values unescaped noclasses just before the function returns a value If you return true
Definition hooks.txt:2055

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' ]; localVHosts callbacks!

Definition at line 124 of file SiteConfiguration.php.

Member Function Documentation

◆ arrayMerge()

static SiteConfiguration::arrayMerge (   $array1)
static

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
Returns
array

Definition at line 587 of file SiteConfiguration.php.

References $out, $value, arrayMerge(), and as.

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

◆ doReplace()

SiteConfiguration::doReplace (   $from,
  $to,
  $in 
)

Type-safe string replace; won't do replacements on non-strings private?

Parameters
string$from
string$to
string | array$in
Returns
string|array

Definition at line 281 of file SiteConfiguration.php.

References as, and doReplace().

Referenced by doReplace(), and getSetting().

◆ extractAllGlobals()

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

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

Parameters
string$wikiWiki ID of the wiki in question.
string | null$suffixThe suffix of the wiki in question.
array$paramsList of parameters. $.'key' is replaced by $value in all returned data.
array$wikiTagsThe tags assigned to the wiki.

Definition at line 406 of file SiteConfiguration.php.

References $params, as, extractGlobalSetting(), mergeParams(), and settings.

◆ 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$settingID of the setting name to retrieve
string$wikiWiki ID of the wiki in question.
string | null$suffixThe suffix of the wiki in question.
array$paramsList of parameters. $.'key' is replaced by $value in all returned data.
array$wikiTagsThe tags assigned to the wiki.

Definition at line 371 of file SiteConfiguration.php.

References $params, extractGlobalSetting(), and mergeParams().

◆ extractGlobalSetting()

SiteConfiguration::extractGlobalSetting (   $setting,
  $wiki,
  $params 
)
Parameters
string$setting
string$wiki
array$params

Definition at line 383 of file SiteConfiguration.php.

References $GLOBALS, $params, $value, arrayMerge(), and getSetting().

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$settingID of the setting name to retrieve
string$wikiWiki ID of the wiki in question.
string$suffixThe suffix of the wiki in question.
array&$varReference The variable to insert the value into.
array$paramsList of parameters. $.'key' is replaced by $value in all returned data.
array$wikiTagsThe tags assigned to the wiki.

Definition at line 354 of file SiteConfiguration.php.

References $params, and $value.

◆ get()

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

Retrieves a configuration setting for a given wiki.

Parameters
string$settingNameID of the setting name to retrieve
string$wikiWiki ID of the wiki in question.
string | null$suffixThe suffix of the wiki in question.
array$paramsList of parameters. $.'key' is replaced by $value in all returned data.
array$wikiTagsThe tags assigned to the wiki.
Returns
mixed The value of the setting requested.

Definition at line 188 of file SiteConfiguration.php.

References $params, getSetting(), and mergeParams().

◆ getAll()

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

Gets all settings for a wiki.

Parameters
string$wikiWiki ID of the wiki in question.
string | null$suffixThe suffix of the wiki in question.
array$paramsList of parameters. $.'key' is replaced by $value in all returned data.
array$wikiTagsThe tags assigned to the wiki.
Returns
array Array of settings requested.

Definition at line 302 of file SiteConfiguration.php.

References $GLOBALS, $params, $value, arrayMerge(), as, getSetting(), mergeParams(), and settings.

◆ getBool()

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

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

Parameters
string$settingID of the setting name to retrieve
string$wikiWiki ID of the wiki in question.
string | null$suffixThe suffix of the wiki in question.
array$wikiTagsThe tags assigned to the wiki.
Returns
bool The value of the setting requested.

Definition at line 332 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$settingsA 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 525 of file SiteConfiguration.php.

References $GLOBALS, $IP, $name, $res, $settings, array(), as, unserialize(), and wfWikiID().

◆ getLocalDatabases()

& SiteConfiguration::getLocalDatabases ( )

Retrieves an array of local databases.

Returns
array

Definition at line 341 of file SiteConfiguration.php.

References $wikis.

◆ getSetting()

SiteConfiguration::getSetting (   $settingName,
  $wiki,
array  $params 
)
protected

Really retrieves a configuration setting for a given wiki.

Parameters
string$settingNameID of the setting name to retrieve.
string$wikiWiki ID of the wiki in question.
array$paramsArray of parameters.
Returns
mixed The value of the setting requested.

Definition at line 203 of file SiteConfiguration.php.

References $params, $retval, $value, arrayMerge(), as, doReplace(), and settings.

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

◆ 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 423 of file SiteConfiguration.php.

References $name, $ret, $siteParamsCallback, and as.

Referenced by mergeParams(), and siteFromDB().

◆ loadFullData()

SiteConfiguration::loadFullData ( )

Definition at line 607 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$wikiWiki ID of the wiki in question.
string$suffixThe suffix of the wiki in question.
array$paramsList of parameters. $.'key' is replaced by $value in all returned data.
array$wikiTagsThe tags assigned to the wiki.
Returns
array

Definition at line 462 of file SiteConfiguration.php.

References $params, $ret, and getWikiParams().

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

◆ siteFromDB()

SiteConfiguration::siteFromDB (   $db)

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

Parameters
string$db
Returns
array

Definition at line 490 of file SiteConfiguration.php.

References $lang, as, and getWikiParams().

Member Data Documentation

◆ $cfgCache

array SiteConfiguration::$cfgCache = []
protected

Configuration cache for getConfig()

Definition at line 177 of file SiteConfiguration.php.

◆ $fullLoadCallback

string array SiteConfiguration::$fullLoadCallback = null

Optional callback to load full configuration data.

Definition at line 152 of file SiteConfiguration.php.

Referenced by loadFullData().

◆ $fullLoadDone

SiteConfiguration::$fullLoadDone = false

Whether or not all data has been loaded.

Definition at line 155 of file SiteConfiguration.php.

◆ $localVHosts

SiteConfiguration::$localVHosts = []

Array of domains that are local and can be handled by the same server.

Deprecated:
since 1.25; use $wgLocalVirtualHosts instead.

Definition at line 146 of file SiteConfiguration.php.

◆ $settings

SiteConfiguration::$settings = []

The whole array of settings.

Definition at line 139 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 171 of file SiteConfiguration.php.

Referenced by getWikiParams().

◆ $suffixes

SiteConfiguration::$suffixes = []

Array of suffixes, for self::siteFromDB()

Definition at line 129 of file SiteConfiguration.php.

◆ $wikis

SiteConfiguration::$wikis = []

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

Definition at line 134 of file SiteConfiguration.php.

Referenced by getLocalDatabases().


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