MediaWiki master
MediaWiki\Settings\SettingsBuilder Class Reference

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$cacheBagOStuff 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 BackupDumper\finalSetup(), 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$keythe name of the config setting
mixed$valueThe 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$valuesAn 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$keythe name of the config setting
mixed$valueThe value to set
Returns
$this

Definition at line 670 of file SettingsBuilder.php.

Referenced by FetchText\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$valuesAn associative array mapping names to values.
Returns
$this

Definition at line 686 of file SettingsBuilder.php.

Referenced by DumpIterator\finalSetup(), and 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: