MediaWiki  master
MediaWiki\Settings\SettingsBuilder Class Reference

Utility for loading settings files. More...

Collaboration diagram for MediaWiki\Settings\SettingsBuilder:

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. More...
 
 assumeDirtyConfig ()
 Notify SettingsBuilder that it can no longer assume that is has full knowledge of all configuration variables that have been set. More...
 
 fileExists (string $path)
 Checks whether the given file exists relative to the settings builder's base directory. More...
 
 finalize ()
 Settings can't be loaded & applied after calling this method. More...
 
 getConfig ()
 Returns the config loaded so far. More...
 
 getConfigSchema ()
 Return the configuration schema. More...
 
 getDefaultConfig ()
 Return a Config object with default for all settings from all schemas loaded so far. More...
 
 getDefinedConfigKeys ()
 Returns the names of all defined configuration variables. More...
 
 load (SettingsSource $source)
 Load settings from a SettingsSource. More...
 
 loadArray (array $newSettings)
 Load settings from an array. More...
 
 loadFile (string $path)
 Load settings from a file. More...
 
 overrideConfigValue (string $key, $value)
 Override the value of a config variable. More...
 
 overrideConfigValues (array $values)
 Override the value of multiple config variables. More...
 
 putConfigValue (string $key, $value)
 Puts a value into a config variable. More...
 
 putConfigValues (array $values)
 Sets the value of multiple config variables. More...
 
 validate ()
 Assert that the config loaded so far conforms the schema loaded so far. More...
 

Private Member Functions

 applySchemas (array $settings)
 Apply schemas from the settings array. More...
 
 applySettings (array $settings)
 Apply the settings array. More...
 
 assertNotFinished ()
 
 loadRecursive (array $batch, array $stack=[])
 Loads all sources in the current batch, recursively resolving includes. More...
 
 makeSource ( $location)
 
 reset ()
 
 updateSettingsConfig ( $config)
 Updates config settings relevant to the behavior if SettingsBuilder itself. More...
 
 wrapSource (SettingsSource $source)
 

Private Attributes

string $baseDir
 
BagOStuff $cache
 
Config null $config
 
ConfigSchemaAggregator $configSchema
 
ConfigBuilder $configSink
 
SettingsSource[] $currentBatch
 
bool $defaultsNeedMerging = false
 Whether we have to apply reverse-merging when applying defaults. More...
 
ExtensionRegistry $extensionRegistry
 
bool $finished = false
 When we're done applying all settings. More...
 
PhpIniSink $phpIniSink
 
array $settingsConfig
 Configuration that applies to SettingsBuilder itself. More...
 

Detailed Description

Utility for loading settings files.

Since
1.38

Definition at line 29 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 93 of file SettingsBuilder.php.

References MediaWiki\Settings\SettingsBuilder\$baseDir, MediaWiki\Settings\SettingsBuilder\$cache, MediaWiki\Settings\SettingsBuilder\$configSink, MediaWiki\Settings\SettingsBuilder\$extensionRegistry, MediaWiki\Settings\SettingsBuilder\$phpIniSink, MediaWiki\MainConfigNames\ExtensionDirectory, MediaWiki\Settings\SettingsBuilder\reset(), and MediaWiki\MainConfigNames\StyleDirectory.

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 245 of file SettingsBuilder.php.

◆ applySchemas()

MediaWiki\Settings\SettingsBuilder::applySchemas ( array  $settings)
private

Apply schemas from the settings array.

This returns the default values to apply, splits into two two categories: "hard" defaults, which can be applied as config overrides without merging. And "soft" defaults, which have to be reverse-merged. Defaults can be considered "hard" if no config value was yet set for them. However, we can only know that as long as we can be sure that nothing has changed config values in a way that bypasses SettingsLoader (e.g. by setting global variables in LocalSettings.php).

Parameters
array$settingsA settings structure.

Definition at line 359 of file SettingsBuilder.php.

◆ applySettings()

MediaWiki\Settings\SettingsBuilder::applySettings ( array  $settings)
private

Apply the settings array.

Parameters
array$settings

Definition at line 402 of file SettingsBuilder.php.

References $ext, and $path.

◆ assertNotFinished()

MediaWiki\Settings\SettingsBuilder::assertNotFinished ( )
private

Definition at line 548 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 342 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 156 of file SettingsBuilder.php.

◆ finalize()

MediaWiki\Settings\SettingsBuilder::finalize ( )

Settings can't be loaded & applied after calling this method.

Access: internal
Most likely called only in Setup.php.
Returns
void

Definition at line 564 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 533 of file SettingsBuilder.php.

Referenced by MediaWiki\Maintenance\MaintenanceRunner\overrideConfig().

◆ getConfigSchema()

MediaWiki\Settings\SettingsBuilder::getConfigSchema ( )

Return the configuration schema.

Note
This will implicitly call apply()
Returns
ConfigSchema

Definition at line 221 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 206 of file SettingsBuilder.php.

◆ getDefinedConfigKeys()

MediaWiki\Settings\SettingsBuilder::getDefinedConfigKeys ( )

Returns the names of all defined configuration variables.

Returns
string[]

Definition at line 231 of file SettingsBuilder.php.

◆ load()

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

Load settings from a SettingsSource.

Parameters
SettingsSource$source
Returns
$this

Definition at line 119 of file SettingsBuilder.php.

◆ loadArray()

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

Load settings from an array.

Parameters
array$newSettings
Returns
$this

Definition at line 135 of file SettingsBuilder.php.

◆ loadFile()

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

Load settings from a file.

Parameters
string$path
Returns
$this

Definition at line 145 of file SettingsBuilder.php.

◆ loadRecursive()

MediaWiki\Settings\SettingsBuilder::loadRecursive ( array  $batch,
array  $stack = [] 
)
private

Loads all sources in the current batch, recursively resolving includes.

Parameters
SettingsSource[]$batchThe batch of sources to load
string[]$stackThe current stack of includes, for cycle detection
Returns
array[] an array of settings arrays

Definition at line 272 of file SettingsBuilder.php.

References $source.

◆ makeSource()

MediaWiki\Settings\SettingsBuilder::makeSource (   $location)
private
Parameters
string$location
Returns
SettingsSource

Definition at line 177 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 507 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 522 of file SettingsBuilder.php.

Referenced by 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 475 of file SettingsBuilder.php.

Referenced by MediaWiki\Maintenance\MaintenanceRunner\overrideConfig().

◆ 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 491 of file SettingsBuilder.php.

◆ reset()

MediaWiki\Settings\SettingsBuilder::reset ( )
private

Definition at line 544 of file SettingsBuilder.php.

Referenced by MediaWiki\Settings\SettingsBuilder\__construct().

◆ updateSettingsConfig()

MediaWiki\Settings\SettingsBuilder::updateSettingsConfig (   $config)
private

Updates config settings relevant to the behavior if SettingsBuilder itself.

Parameters
array$config
Returns
string

Definition at line 316 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 193 of file SettingsBuilder.php.

◆ wrapSource()

MediaWiki\Settings\SettingsBuilder::wrapSource ( SettingsSource  $source)
private
Parameters
SettingsSource$source
Returns
SettingsSource

Definition at line 166 of file SettingsBuilder.php.

References $source.

Member Data Documentation

◆ $baseDir

string MediaWiki\Settings\SettingsBuilder::$baseDir
private

Definition at line 31 of file SettingsBuilder.php.

Referenced by MediaWiki\Settings\SettingsBuilder\__construct().

◆ $cache

BagOStuff MediaWiki\Settings\SettingsBuilder::$cache
private

Definition at line 37 of file SettingsBuilder.php.

Referenced by MediaWiki\Settings\SettingsBuilder\__construct().

◆ $config

Config null MediaWiki\Settings\SettingsBuilder::$config
private

Definition at line 43 of file SettingsBuilder.php.

◆ $configSchema

ConfigSchemaAggregator MediaWiki\Settings\SettingsBuilder::$configSchema
private

Definition at line 49 of file SettingsBuilder.php.

◆ $configSink

ConfigBuilder MediaWiki\Settings\SettingsBuilder::$configSink
private

Definition at line 40 of file SettingsBuilder.php.

Referenced by MediaWiki\Settings\SettingsBuilder\__construct().

◆ $currentBatch

SettingsSource [] MediaWiki\Settings\SettingsBuilder::$currentBatch
private

Definition at line 46 of file SettingsBuilder.php.

◆ $defaultsNeedMerging

bool MediaWiki\Settings\SettingsBuilder::$defaultsNeedMerging = false
private

Whether we have to apply reverse-merging when applying defaults.

This will initially be false, and become true once any config settings have been assigned a value.

This is used as an optimization, to avoid costly merge logic when loading initial defaults before any config variables have been set.

Definition at line 81 of file SettingsBuilder.php.

◆ $extensionRegistry

ExtensionRegistry MediaWiki\Settings\SettingsBuilder::$extensionRegistry
private

Definition at line 34 of file SettingsBuilder.php.

Referenced by MediaWiki\Settings\SettingsBuilder\__construct().

◆ $finished

bool MediaWiki\Settings\SettingsBuilder::$finished = false
private

When we're done applying all settings.

Definition at line 69 of file SettingsBuilder.php.

◆ $phpIniSink

PhpIniSink MediaWiki\Settings\SettingsBuilder::$phpIniSink
private

Definition at line 52 of file SettingsBuilder.php.

Referenced by MediaWiki\Settings\SettingsBuilder\__construct().

◆ $settingsConfig

array MediaWiki\Settings\SettingsBuilder::$settingsConfig
private

Configuration that applies to SettingsBuilder itself.

Initialized by the constructor, may be overwritten by regular config values. Merge strategies are currently not implemented but can be added if needed.

Definition at line 62 of file SettingsBuilder.php.


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