Settings: add support for obsolete config

This allows config variables to be declared obsolete. Obsolete config
will be omitted from the schema, defaults, name constants, etc. The
purpose of keeping a declaration of obsolete config around is to allow
the updater to warn admins that they are using a config variable that no
longer has any effect, and provide them with a remedy.

The idea is that support for deprecated config can be removed after one
release per the stable interface policy, but the declaration of
obsolete config should be kept for as long as we support updates,
that is, at least two LTS releases.

See https://www.mediawiki.org/wiki/Topic:X4bh4nf3pe2ho5jj for
discussion.

Change-Id: Ia7a00742ea7a5311e820a6a43b11135a3f2a825f

2 files changed, 46 insertions, 2 deletions

diff --git a/includes/Settings/SettingsBuilder.php b/includes/Settings/SettingsBuilder.php
index 47e807099276..334e44c187ab 100644
--- a/includes/Settings/SettingsBuilder.php
+++ b/includes/Settings/SettingsBuilder.php
@@ -39,6 +39,9 @@ class SettingsBuilder {
 	/** @var ConfigBuilder */
 	private $configSink;
 
+	/** @var array<string,string> */
+	private $obsoleteConfig;
+
 	/** @var Config|null */
 	private $config;
 
@@ -104,6 +107,7 @@ class SettingsBuilder {
 		$this->extensionRegistry = $extensionRegistry;
 		$this->cache = $cache;
 		$this->configSink = $configSink;
+		$this->obsoleteConfig = [];
 		$this->configSchema = new ConfigSchemaAggregator();
 		$this->phpIniSink = $phpIniSink;
 		$this->settingsConfig = [
@@ -200,9 +204,13 @@ class SettingsBuilder {
 
 	/**
 	 * Detect usage of deprecated settings. A setting is counted as used if
-	 * it has a value other than the default.
+	 * 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.
+	 * @note Code that needs to call detectDeprecatedConfig() should probably also
+	 *       call detectObsoleteConfig() and getWarnings().
 	 *
 	 * @return array<string,string> an associative array mapping config keys
 	 *         to the deprecation messages from the schema.
@@ -230,6 +238,31 @@ class SettingsBuilder {
 	}
 
 	/**
+	 * 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.
+	 * @note Code that calls detectObsoleteConfig() may also want to
+	 *       call detectDeprecatedConfig() and getWarnings().
+	 *
+	 * @return array<string,string> an associative array mapping config keys
+	 *         to the deprecation messages from the schema.
+	 */
+	public function detectObsoleteConfig(): array {
+		$config = $this->getConfig();
+		$obsolete = [];
+
+		foreach ( $this->obsoleteConfig as $key => $msg ) {
+			if ( $config->has( $key ) ) {
+				$obsolete[$key] = $msg;
+			}
+		}
+
+		return $obsolete;
+	}
+
+	/**
 	 * 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.
 	 *
@@ -459,6 +492,10 @@ class SettingsBuilder {
 			$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.
diff --git a/includes/Settings/Source/ReflectionSchemaSource.php b/includes/Settings/Source/ReflectionSchemaSource.php
index ab3da5ff6921..3b4534d3e43c 100644
--- a/includes/Settings/Source/ReflectionSchemaSource.php
+++ b/includes/Settings/Source/ReflectionSchemaSource.php
@@ -63,6 +63,7 @@ class ReflectionSchemaSource implements SettingsSource {
 	 */
 	public function load(): array {
 		$schemas = [];
+		$obsolete = [];
 
 		try {
 			$class = new ReflectionClass( $this->class );
@@ -78,6 +79,11 @@ class ReflectionSchemaSource implements SettingsSource {
 					continue;
 				}
 
+				if ( isset( $schema['obsolete'] ) ) {
+					$obsolete[ $name ] = $schema['obsolete'];
+					continue;
+				}
+
 				if ( $this->includeDoc ) {
 					$doc = $const->getDocComment();
 					if ( $doc ) {
@@ -108,7 +114,8 @@ class ReflectionSchemaSource implements SettingsSource {
 		}
 
 		return [
-			'config-schema' => $schemas
+			'config-schema' => $schemas,
+			'obsolete-config' => $obsolete
 		];
 	}