SettingsBuilder.php

Go to the documentation of this file.

<?php
 
namespace MediaWiki\Settings;
 
use MediaWiki\Config\Config;
use MediaWiki\Config\HashConfig;
use MediaWiki\Config\IterableConfig;
use MediaWiki\HookContainer\HookContainer;
use MediaWiki\MainConfigNames;
use MediaWiki\Registration\ExtensionRegistry;
use MediaWiki\Settings\Cache\CacheableSource;
use MediaWiki\Settings\Cache\CachedSource;
use MediaWiki\Settings\Config\ConfigBuilder;
use MediaWiki\Settings\Config\ConfigSchema;
use MediaWiki\Settings\Config\ConfigSchemaAggregator;
use MediaWiki\Settings\Config\GlobalConfigBuilder;
use MediaWiki\Settings\Config\PhpIniSink;
use MediaWiki\Settings\Source\ArraySource;
use MediaWiki\Settings\Source\FileSource;
use MediaWiki\Settings\Source\SettingsFileUtils;
use MediaWiki\Settings\Source\SettingsIncludeLocator;
use MediaWiki\Settings\Source\SettingsSource;
use RuntimeException;
use StatusValue;
use Wikimedia\ObjectCache\BagOStuff;
use function array_key_exists;
 
class SettingsBuilder {
 
    private const STAGE_LOADING = 1;
 
    private const STAGE_REGISTRATION = 10;
 
    private const STAGE_READ_ONLY = 100;
 
    private $baseDir;
 
    private $extensionRegistry;
 
    private $cache;
 
    private $configSink;
 
    private $obsoleteConfig;
 
    private $config;
 
    private $currentBatch;
 
    private $configSchema;
 
    private $phpIniSink;
 
    private $settingsConfig;
 
    private $stage = self::STAGE_LOADING;
 
    private $defaultsNeedMerging = false;
 
    private $warnings = [];
 
    private static bool $accessDisabledForUnitTests = false;
 
    public static function getInstance(): self {
        static $instance = null;
 
        if ( self::$accessDisabledForUnitTests ) {
            throw new RuntimeException( 'Access is disabled in unit tests' );
        }
 
        if ( !$instance ) {
            // NOTE: SettingsBuilder is used during bootstrap, before MediaWikiServices
            //       is available. It has to be, because it is used to construct the
            //       configuration that is used when constructing services. Because of
            //       this, we have to instantiate SettingsBuilder directly, we can't
            //       use service wiring.
            $instance = new SettingsBuilder(
                MW_INSTALL_PATH,
                ExtensionRegistry::getInstance(),
                new GlobalConfigBuilder( 'wg' ),
                new PhpIniSink()
            );
        }
 
        return $instance;
    }
 
    public static function disableAccessForUnitTests(): void {
        if ( !defined( 'MW_PHPUNIT_TEST' ) ) {
            throw new RuntimeException( 'Can only be called in tests' );
        }
        self::$accessDisabledForUnitTests = true;
    }
 
    public static function enableAccessAfterUnitTests(): void {
        if ( !defined( 'MW_PHPUNIT_TEST' ) ) {
            throw new RuntimeException( 'Can only be called in tests' );
        }
        self::$accessDisabledForUnitTests = false;
    }
 
    public function __construct(
        string $baseDir,
        ExtensionRegistry $extensionRegistry,
        ConfigBuilder $configSink,
        PhpIniSink $phpIniSink,
        ?BagOStuff $cache = null
    ) {
        $this->baseDir = $baseDir;
        $this->extensionRegistry = $extensionRegistry;
        $this->cache = $cache;
        $this->configSink = $configSink;
        $this->obsoleteConfig = [];
        $this->configSchema = new ConfigSchemaAggregator();
        $this->phpIniSink = $phpIniSink;
        $this->settingsConfig = [
            MainConfigNames::ExtensionDirectory => "$baseDir/extensions",
            MainConfigNames::StyleDirectory => "$baseDir/skins",
        ];
        $this->reset();
    }
 
    public function load( SettingsSource $source ): self {
        $this->assertStillLoading( __METHOD__ );
 
        // XXX: We may want to cache the entire batch instead, see T304493.
        $this->currentBatch[] = $this->wrapSource( $source );
 
        return $this;
    }
 
    public function loadArray( array $newSettings ): self {
        return $this->load( new ArraySource( $newSettings ) );
    }
 
    private function loadArrayInternal( array $newSettings, string $func ): self {
        $this->assertNotReadOnly( $func );
 
        $source = new ArraySource( $newSettings );
        $this->currentBatch[] = $this->wrapSource( $source );
 
        return $this;
    }
 
    public function loadFile( string $path ): self {
        return $this->load( $this->makeSource( $path ) );
    }
 
    public function fileExists( string $path ): bool {
        $path = SettingsFileUtils::resolveRelativeLocation( $path, $this->baseDir );
        return file_exists( $path );
    }
 
    private function wrapSource( SettingsSource $source ): SettingsSource {
        if ( $this->cache !== null && $source instanceof CacheableSource ) {
            $source = new CachedSource( $this->cache, $source );
        }
        return $source;
    }
 
    private function makeSource( $location ): SettingsSource {
        // NOTE: Currently, files are the only kind of location, but we could add others.
        //       The set of supported source locations will be hard-coded here.
        //       Custom SettingsSource would have to be instantiated directly and passed to load().
        $path = SettingsFileUtils::resolveRelativeLocation( $location, $this->baseDir );
 
        return $this->wrapSource( new FileSource( $path ) );
    }
 
    public function validate(): StatusValue {
        $config = $this->getConfig();
        return $this->configSchema->validateConfig( $config );
    }
 
    public function detectDeprecatedConfig(): array {
        $config = $this->getConfig();
        $keys = $this->getDefinedConfigKeys();
        $deprecated = [];
 
        foreach ( $keys as $key ) {
            $sch = $this->configSchema->getSchemaFor( $key );
            if ( !isset( $sch['deprecated'] ) ) {
                continue;
            }
 
            $default = $sch['default'] ?? null;
            $value = $config->get( $key );
 
            if ( $value !== $default ) {
                $deprecated[$key] = $sch['deprecated'];
            }
        }
 
        return $deprecated;
    }
 
    public function detectObsoleteConfig(): array {
        $config = $this->getConfig();
        $obsolete = [];
 
        foreach ( $this->obsoleteConfig as $key => $msg ) {
            if ( $config->has( $key ) ) {
                $obsolete[$key] = $msg;
            }
        }
 
        return $obsolete;
    }
 
    public function getDefaultConfig(): IterableConfig {
        $this->apply();
        $defaults = $this->configSchema->getDefaults();
        $nulls = array_fill_keys( $this->configSchema->getDefinedKeys(), null );
 
        return new HashConfig( array_merge( $nulls, $defaults ) );
    }
 
    public function getConfigSchema(): ConfigSchema {
        $this->apply();
        return $this->configSchema;
    }
 
    public function getDefinedConfigKeys(): array {
        $this->apply();
        return $this->configSchema->getDefinedKeys();
    }
 
    public function apply(): self {
        if ( !$this->currentBatch ) {
            return $this;
        }
 
        $this->assertNotReadOnly( __METHOD__ );
        $this->config = null;
 
        // XXX: We may want to cache the entire batch after merging together
        //      settings from all sources, see T304493.
        $allSettings = $this->loadRecursive( $this->currentBatch );
 
        foreach ( $allSettings as $settings ) {
            $this->applySettings( $settings );
        }
        $this->reset();
        return $this;
    }
 
    private function loadRecursive( array $batch, array $stack = [] ): array {
        $allSettings = [];
 
        // Depth-first traversal of settings sources.
        foreach ( $batch as $source ) {
            $sourceName = (string)$source;
 
            if ( in_array( $sourceName, $stack ) ) {
                throw new SettingsBuilderException(
                    'Recursive include chain detected: ' . implode( ', ', $stack )
                );
            }
 
            $settings = $source->load();
            $settings['source-name'] = $sourceName;
 
            $allSettings[] = $settings;
 
            $nextBatch = [];
            foreach ( $settings['includes'] ?? [] as $location ) {
                // Try to resolve the include relative to the source,
                // if the source supports that.
                if ( $source instanceof SettingsIncludeLocator ) {
                    $location = $source->locateInclude( $location );
                }
 
                $nextBatch[] = $this->makeSource( $location );
            }
 
            $nextStack = array_merge( $stack, [ $settings['source-name'] ] );
            $nextSettings = $this->loadRecursive( $nextBatch, $nextStack );
            $allSettings = array_merge( $allSettings, $nextSettings );
        }
 
        return $allSettings;
    }
 
    private function updateSettingsConfig( $config ): string {
        // No merge strategies are applied, defaults are set in the constructor.
        foreach ( $this->settingsConfig as $key => $dummy ) {
            if ( array_key_exists( $key, $config ) ) {
                $this->settingsConfig[ $key ] = $config[ $key ];
            }
        }
        // @phan-suppress-next-line PhanPossiblyUndeclaredVariable Always set
        return $key;
    }
 
    public function assumeDirtyConfig(): SettingsBuilder {
        $this->defaultsNeedMerging = true;
        return $this;
    }
 
    private function applySchemas( array $settings ) {
        $defaults = [];
 
        if ( isset( $settings['config-schema-inverse'] ) ) {
            $defaults = $settings['config-schema-inverse']['default'] ?? [];
            $this->configSchema->addDefaults(
                $defaults,
                $settings['source-name']
            );
            $this->configSchema->addMergeStrategies(
                $settings['config-schema-inverse']['mergeStrategy'] ?? [],
                $settings['source-name']
            );
            $this->configSchema->addTypes(
                $settings['config-schema-inverse']['type'] ?? [],
                $settings['source-name']
            );
            $this->configSchema->addDynamicDefaults(
                $settings['config-schema-inverse']['dynamicDefault'] ?? [],
                $settings['source-name']
            );
        }
 
        if ( isset( $settings['config-schema'] ) ) {
            foreach ( $settings['config-schema'] as $key => $schema ) {
                $this->configSchema->addSchema( $key, $schema );
 
                if ( $this->configSchema->hasDefaultFor( $key ) ) {
                    $defaults[$key] = $this->configSchema->getDefaultFor( $key );
                }
            }
        }
 
        if ( $this->defaultsNeedMerging ) {
            $mergeStrategies = $this->configSchema->getMergeStrategies();
            $this->configSink->setMultiDefault( $defaults, $mergeStrategies );
        } else {
            // Optimization: no merge strategy, just override in one go
            $this->configSink->setMulti( $defaults );
        }
    }
 
    private function applySettings( array $settings ) {
        // First extract config variables that change the behavior of SettingsBuilder.
        // No merge strategies are applied, defaults are set in the constructor.
        if ( isset( $settings['config'] ) ) {
            $this->updateSettingsConfig( $settings['config'] );
        }
        if ( isset( $settings['config-overrides'] ) ) {
            $this->updateSettingsConfig( $settings['config-overrides'] );
        }
 
        $this->applySchemas( $settings );
 
        if ( isset( $settings['config'] ) ) {
            $mergeStrategies = $this->configSchema->getMergeStrategies();
            $this->configSink->setMulti( $settings['config'], $mergeStrategies );
        }
 
        if ( isset( $settings['config-overrides'] ) ) {
            // no merge strategies, just override in one go
            $this->configSink->setMulti( $settings['config-overrides'] );
        }
 
        if ( isset( $settings['obsolete-config'] ) ) {
            $this->obsoleteConfig = array_merge( $this->obsoleteConfig, $settings['obsolete-config'] );
        }
 
        if ( isset( $settings['config'] ) || isset( $settings['config-overrides'] ) ) {
            // We have set some config variables, we can no longer assume we can blindly set defaults
            // without merging with existing config variables.
            // XXX: We could potentially track which config variables have been set, so we can still
            //      apply defaults for other config vars without merging.
            $this->defaultsNeedMerging = true;
        }
 
        foreach ( $settings['php-ini'] ?? [] as $option => $value ) {
            $this->phpIniSink->set(
                $option,
                $value
            );
        }
 
        // TODO: Closely integrate with ExtensionRegistry. Loading extension.json is basically
        //       the same as loading settings files. See T297166.
        //       That would also mean that extensions would actually be loaded here,
        //       not just queued. We can't do this right now, because we need to preserve
        //       interoperability with wfLoadExtension() being called from LocalSettings.php.
 
        if ( isset( $settings['extensions'] ) ) {
            $extDir = $this->settingsConfig[MainConfigNames::ExtensionDirectory];
            foreach ( $settings['extensions'] ?? [] as $ext ) {
                $path = "$extDir/$ext/extension.json"; // see wfLoadExtension
                $this->extensionRegistry->queue( $path );
            }
        }
 
        if ( isset( $settings['skins'] ) ) {
            $skinDir = $this->settingsConfig[MainConfigNames::StyleDirectory];
            foreach ( $settings['skins'] ?? [] as $skin ) {
                $path = "$skinDir/$skin/skin.json"; // see wfLoadSkin
                $this->extensionRegistry->queue( $path );
            }
        }
    }
 
    public function putConfigValue( string $key, $value ): self {
        return $this->putConfigValues( [ $key => $value ] );
    }
 
    public function putConfigValues( array $values ): self {
        return $this->loadArrayInternal( [ 'config' => $values ], __METHOD__ );
    }
 
    public function overrideConfigValue( string $key, $value ): self {
        return $this->overrideConfigValues( [ $key => $value ] );
    }
 
    public function overrideConfigValues( array $values ): self {
        return $this->loadArrayInternal( [ 'config-overrides' => $values ], __METHOD__ );
    }
 
    public function registerHookHandlers( array $handlers ): self {
        // NOTE: Rely on the merge strategy for the Hooks setting.
        // TODO: Make hook handlers a separate structure in settings files,
        //       like they are in extension.json.
        return $this->loadArrayInternal( [ 'config' => [ 'Hooks' => $handlers ] ], __METHOD__ );
    }
 
    public function registerHookHandler( string $hook, $handler ): self {
        // NOTE: Rely on the merge strategy for the Hooks setting.
        // TODO: Make hook handlers a separate structure in settings files,
        //       like they are in extension.json.
        return $this->loadArray( [ 'config' => [ 'Hooks' => [ $hook => [ $handler ] ] ] ] );
    }
 
    public function getConfig(): Config {
        // XXX: Would be nice if we could forbid using this method
        //   before enterRegistrationStage() is called. But we need
        //   access to some configuration earlier, e.g. WikiFarmSettingsDirectory.
 
        if ( $this->config && !$this->currentBatch ) {
            return $this->config;
        }
 
        $this->apply();
        $this->config = $this->configSink->build();
 
        return $this->config;
    }
 
    private function reset() {
        $this->currentBatch = [];
    }
 
    private function assertNotReadOnly( string $func ): void {
        if ( $this->stage === self::STAGE_READ_ONLY ) {
            throw new SettingsBuilderException(
                "$func not supported in operation stage."
            );
        }
    }
 
    private function assertStillLoading( string $func ): void {
        if ( $this->stage !== self::STAGE_LOADING ) {
            throw new SettingsBuilderException(
                "$func only supported while still in the loading stage."
            );
        }
    }
 
    public function enterReadOnlyStage(): void {
        $this->apply();
        $this->stage = self::STAGE_READ_ONLY;
    }
 
    public function enterRegistrationStage(): void {
        $this->apply();
        $this->stage = self::STAGE_REGISTRATION;
    }
 
    public function getConfigBuilder(): ConfigBuilder {
        $this->apply();
        return $this->configSink;
    }
 
    public function warning( string $msg ) {
        $this->assertNotReadOnly( __METHOD__ );
        $this->warnings[] = trim( $msg );
    }
 
    public function getWarnings(): array {
        return $this->warnings;
    }
 
}