Builder class for constructing a Config object from a set of sources during bootstrap. More...

Public Member Functions
	__construct (string $baseDir, ExtensionRegistry $extensionRegistry, ConfigBuilder $configSink, PhpIniSink $phpIniSink, ?BagOStuff $cache=null)

	apply ()
	Apply any settings loaded so far to the runtime environment.

	assumeDirtyConfig ()
	Notify SettingsBuilder that it can no longer assume that is has full knowledge of all configuration variables that have been set.

	detectDeprecatedConfig ()
	Detect usage of deprecated settings.

	detectObsoleteConfig ()
	Detect usage of obsolete settings.

	enterReadOnlyStage ()
	Sets the SettingsBuilder read-only.

	enterRegistrationStage ()
	Prevents additional settings from being loaded, but still allows manipulation of config values.

	fileExists (string $path)
	Checks whether the given file exists relative to the settings builder's base directory.

	getConfig ()
	Returns the config loaded so far.

	getConfigBuilder ()

	getConfigSchema ()
	Return the configuration schema.

	getDefaultConfig ()
	Return a Config object with default for all settings from all schemas loaded so far.

	getDefinedConfigKeys ()
	Returns the names of all defined configuration variables.

	getWarnings ()
	Returns any warnings logged by calling warning().

	load (SettingsSource $source)
	Load settings from a `SettingsSource`.

	loadArray (array $newSettings)
	Load settings from an array.

	loadFile (string $path)
	Load settings from a file.

	overrideConfigValue (string $key, $value)
	Override the value of a config variable.

	overrideConfigValues (array $values)
	Override the value of multiple config variables.

	putConfigValue (string $key, $value)
	Puts a value into a config variable.

	putConfigValues (array $values)
	Sets the value of multiple config variables.

	registerHookHandler (string $hook, $handler)
	Register a hook handler.

	registerHookHandlers (array $handlers)
	Register hook handlers.

	validate ()
	Assert that the config loaded so far conforms the schema loaded so far.

	warning (string $msg)
	Log a settings related warning, such as a deprecated config variable.

Static Public Member Functions
static	disableAccessForUnitTests ()

static	enableAccessAfterUnitTests ()

static	getInstance ()
	Accessor for the global SettingsBuilder instance.

Detailed Description

Builder class for constructing a Config object from a set of sources during bootstrap.

The SettingsBuilder is used in Setup.php to load and combine settings files and eventually produce the Config object that will be used to configure MediaWiki.

The SettingsBuilder object keeps track of "stages" of initialization that correspond to sections of Setup.php:

The initial stage is "loading". In this stage, SettingsSources are added to the SettingsBuilder using the load* methods. This sets up the config schema and applies custom configuration values.

Once all settings sources have been loaded, the SettingsBuilder is moved to the "registration" stage by calling enterRegistrationStage(). In this stage, config values may still be altered, but no settings sources may be loaded. During the "registration" stage, dynamic defaults are applied, extension registration callbacks are executed, and maintenance scripts have an opportunity to manipulate settings.

Finally, the SettingsBuilder is moved to the "operation" stage by calling enterOperationStage(). This renders the SettingsBuilder read only: config values may no longer be changed. At this point, it becomes safe to use the Config object returned by getConfig() to initialize the service container.

Since: 1.38

Definition at line 55 of file SettingsBuilder.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\Settings\SettingsBuilder::__construct	(	string	$baseDir,
		ExtensionRegistry	$extensionRegistry,
		ConfigBuilder	$configSink,
		PhpIniSink	$phpIniSink,
		?BagOStuff	$cache = null )

Parameters

string	$baseDir
ExtensionRegistry	$extensionRegistry
ConfigBuilder	$configSink
PhpIniSink	$phpIniSink
BagOStuff \| null	$cache	BagOStuff used to cache settings loaded from each source. The caller should beware that secrets contained in any source passed to `load` or `loadFile` will be cached as well.

Definition at line 200 of file SettingsBuilder.php.

Member Function Documentation

◆ apply()

MediaWiki\Settings\SettingsBuilder::apply ( )

Apply any settings loaded so far to the runtime environment.

Note: This usually makes all configuration available in global variables. This may however not be the case in the future.

Returns: $this

Exceptions

SettingsBuilderException

Definition at line 432 of file SettingsBuilder.php.

◆ assumeDirtyConfig()

MediaWiki\Settings\SettingsBuilder::assumeDirtyConfig ( )

Notify SettingsBuilder that it can no longer assume that is has full knowledge of all configuration variables that have been set.

This would be the case when other code (such as LocalSettings.php) is manipulating global variables which represent config values.

This is used for optimization: up until this method is called, default values can be set directly for any config values that have not been set yet. This avoids the need to run merge logic for all default values during initialization.

Note: It is useful to call apply() just before this method, so any settings already queued will still benefit from assuming that globals are not dirty.

Returns: self

Definition at line 529 of file SettingsBuilder.php.

◆ detectDeprecatedConfig()

MediaWiki\Settings\SettingsBuilder::detectDeprecatedConfig ( )

Detect usage of deprecated settings.

A setting is counted as used if it has a value other than the default. Note that deprecated settings are expected to be supported. Settings that have become non-functional should be marked as obsolete instead.

Note: this is slow, so you probably don't want to do this on every request.; Code that needs to call detectDeprecatedConfig() should probably also call detectObsoleteConfig() and getWarnings().

Returns: array<string,string> an associative array mapping config keys to the deprecation messages from the schema.

Definition at line 338 of file SettingsBuilder.php.

◆ detectObsoleteConfig()

MediaWiki\Settings\SettingsBuilder::detectObsoleteConfig ( )

Detect usage of obsolete settings.

A setting is counted as used if it is defined in any way. Note that obsolete settings are non-functional, while deprecated settings are still supported.

Note: this is slow, so you probably don't want to do this on every request.; Code that calls detectObsoleteConfig() may also want to call detectDeprecatedConfig() and getWarnings().

Returns: array<string,string> an associative array mapping config keys to the deprecation messages from the schema.

Definition at line 372 of file SettingsBuilder.php.

◆ disableAccessForUnitTests()

static MediaWiki\Settings\SettingsBuilder::disableAccessForUnitTests ( )

static

Access: internal

Definition at line 173 of file SettingsBuilder.php.

◆ enableAccessAfterUnitTests()

static MediaWiki\Settings\SettingsBuilder::enableAccessAfterUnitTests ( )

static

Access: internal

Definition at line 183 of file SettingsBuilder.php.

◆ enterReadOnlyStage()

MediaWiki\Settings\SettingsBuilder::enterReadOnlyStage ( )

Sets the SettingsBuilder read-only.

Call this before using the configuration returned by getConfig() to construct services objects or initialize the service container.

Access: internal: For use in Setup.php.

Definition at line 804 of file SettingsBuilder.php.

◆ enterRegistrationStage()

MediaWiki\Settings\SettingsBuilder::enterRegistrationStage ( )

Prevents additional settings from being loaded, but still allows manipulation of config values.

Call this before applying dynamic defaults and executing extension registration callbacks.

Access: internal: For use in Setup.php.

Definition at line 816 of file SettingsBuilder.php.

◆ fileExists()

MediaWiki\Settings\SettingsBuilder::fileExists ( string $path )

Checks whether the given file exists relative to the settings builder's base directory.

Parameters

string $path

Returns: bool

Definition at line 283 of file SettingsBuilder.php.

◆ getConfig()

MediaWiki\Settings\SettingsBuilder::getConfig ( )

Returns the config loaded so far.

Implicitly triggers apply() when needed.

Note: This will implicitly call apply()

Returns: Config

Definition at line 761 of file SettingsBuilder.php.

Referenced by MediaWiki\Maintenance\BackupDumper\finalSetup(), MediaWiki\Maintenance\Maintenance\finalSetup(), and RebuildFileCache\finalSetup().

◆ getConfigBuilder()

MediaWiki\Settings\SettingsBuilder::getConfigBuilder ( )

Access: internal: For use in Setup.php, pending a better solution.

Returns: ConfigBuilder

Definition at line 825 of file SettingsBuilder.php.

◆ getConfigSchema()

MediaWiki\Settings\SettingsBuilder::getConfigSchema ( )

Return the configuration schema.

Note: This will implicitly call apply()

Returns: ConfigSchema

Definition at line 408 of file SettingsBuilder.php.

◆ getDefaultConfig()

MediaWiki\Settings\SettingsBuilder::getDefaultConfig ( )

Return a Config object with default for all settings from all schemas loaded so far.

If the schema for a setting doesn't specify a default, null is assumed.

Note: This will implicitly call apply()

Returns: IterableConfig

Definition at line 393 of file SettingsBuilder.php.

◆ getDefinedConfigKeys()

MediaWiki\Settings\SettingsBuilder::getDefinedConfigKeys ( )

Returns the names of all defined configuration variables.

Returns: string[]

Definition at line 418 of file SettingsBuilder.php.

◆ getInstance()

static MediaWiki\Settings\SettingsBuilder::getInstance ( )

static

Accessor for the global SettingsBuilder instance.

Note: It is always preferable to have a SettingsBuilder injected! But as long as we can't to this everywhere, this is the preferred way of getting the global instance of SettingsBuilder.

Returns: SettingsBuilder

Definition at line 146 of file SettingsBuilder.php.

◆ getWarnings()

MediaWiki\Settings\SettingsBuilder::getWarnings ( )

Returns any warnings logged by calling warning().

Access: internal

Returns: string[]

Definition at line 852 of file SettingsBuilder.php.

◆ load()

MediaWiki\Settings\SettingsBuilder::load ( SettingsSource $source )

Load settings from a SettingsSource.

Only allowed during the "loading" stage.

Parameters

SettingsSource $source

Returns: $this

Definition at line 228 of file SettingsBuilder.php.

◆ loadArray()

MediaWiki\Settings\SettingsBuilder::loadArray ( array $newSettings )

Load settings from an array.

Parameters

array $newSettings

Returns: $this

Definition at line 244 of file SettingsBuilder.php.

◆ loadFile()

MediaWiki\Settings\SettingsBuilder::loadFile ( string $path )

Load settings from a file.

Parameters

string $path

Returns: $this

Definition at line 272 of file SettingsBuilder.php.

◆ overrideConfigValue()

MediaWiki\Settings\SettingsBuilder::overrideConfigValue	(	string	$key,
			$value )

Override the value of a config variable.

This ignores any merge strategies and discards any previous value. This is a shorthand for overrideConfigValues( [ $key => $value ] ).

See also: putConfigValue

Parameters

string	$key	the name of the config setting
mixed	$value	The value to set

Returns: $this

Definition at line 702 of file SettingsBuilder.php.

◆ overrideConfigValues()

MediaWiki\Settings\SettingsBuilder::overrideConfigValues ( array $values )

Override the value of multiple config variables.

This ignores any merge strategies and discards any previous value. This is a shorthand for loadArray( [ 'config-overrides' => $values ] ).

See also: putConfigValues

Parameters

array $values An associative array mapping names to values.

Returns: $this

Definition at line 717 of file SettingsBuilder.php.

Referenced by MediaWiki\Maintenance\MaintenanceRunner\emulateConfig(), and MediaWiki\Installer\Installer\overrideConfig().

◆ putConfigValue()

MediaWiki\Settings\SettingsBuilder::putConfigValue	(	string	$key,
			$value )

Puts a value into a config variable.

Depending on the variable's specification, the new value may be merged with the previous value, or may replace it. This is a shorthand for putConfigValues( [ $key => $value ] ).

See also: overrideConfigValue

Parameters

string	$key	the name of the config setting
mixed	$value	The value to set

Returns: $this

Definition at line 670 of file SettingsBuilder.php.

Referenced by FetchText\finalSetup(), InstallPreConfigured\finalSetup(), MergeMessageFileList\finalSetup(), RebuildFileCache\finalSetup(), and RebuildLocalisationCache\finalSetup().

◆ putConfigValues()

MediaWiki\Settings\SettingsBuilder::putConfigValues ( array $values )

Sets the value of multiple config variables.

Depending on the variables' specification, the new values may be merged with the previous values, or they may replace them. This is a shorthand for loadArray( [ 'config' => $values ] ).

See also: overrideConfigValues

Parameters

array $values An associative array mapping names to values.

Returns: $this

Definition at line 686 of file SettingsBuilder.php.

Referenced by DumpIterator\finalSetup(), and MediaWiki\Maintenance\Maintenance\finalSetup().

◆ registerHookHandler()

MediaWiki\Settings\SettingsBuilder::registerHookHandler	(	string	$hook,
			$handler )

Register a hook handler.

Parameters

string	$hook
mixed	$handler

Returns: $this

See also: HookContainer::register()

Definition at line 747 of file SettingsBuilder.php.

◆ registerHookHandlers()

MediaWiki\Settings\SettingsBuilder::registerHookHandlers ( array $handlers )

Register hook handlers.

Parameters

array<string,mixed> $handlers An associative array using the same structure as the Hooks config setting: Each value is a list of handler callbacks for the hook.

Returns: $this

See also: HookContainer::register()

Definition at line 731 of file SettingsBuilder.php.

◆ validate()

MediaWiki\Settings\SettingsBuilder::validate ( )

Assert that the config loaded so far conforms the schema loaded so far.

Note: this is slow, so you probably don't want to do this on every request.

Returns: StatusValue

Definition at line 320 of file SettingsBuilder.php.

◆ warning()

MediaWiki\Settings\SettingsBuilder::warning ( string $msg )

Log a settings related warning, such as a deprecated config variable.

This can be used during bootstrapping, when the regular logger is not yet available. The warnings will be passed to a regular logger after bootstrapping is complete. In addition, the updater will fail if it finds any warnings. This allows us to warn about deprecated settings, and make sure they are replaced before the update proceeds.

Parameters

string $msg

Definition at line 841 of file SettingsBuilder.php.

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

includes/Settings/SettingsBuilder.php

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ apply()

◆ assumeDirtyConfig()

◆ detectDeprecatedConfig()

◆ detectObsoleteConfig()

◆ disableAccessForUnitTests()

◆ enableAccessAfterUnitTests()

◆ enterReadOnlyStage()

◆ enterRegistrationStage()

◆ fileExists()

◆ getConfig()

◆ getConfigBuilder()

◆ getConfigSchema()

◆ getDefaultConfig()

◆ getDefinedConfigKeys()

◆ getInstance()

◆ getWarnings()

◆ load()

◆ loadArray()

◆ loadFile()

◆ overrideConfigValue()

◆ overrideConfigValues()

◆ putConfigValue()

◆ putConfigValues()

◆ registerHookHandler()

◆ registerHookHandlers()

◆ validate()

◆ warning()