featureManager: Add Requirement interface

FeatureManager::registerRequirement established the interface for a
requirement: its name and whether it's met.

However, the Feature Manager also needs to handle scenarios where a
requirement needs additional context before it can be considered met.
That context may not be available when the application is booting, e.g.
checking if the user is logged in; or the logic is complicated enough
that it should be under test.

Changes:

- Add the Requirement interface and update FeatureManager to work with
  implementations of it

- Maintain B/C by constructing an instance of a the SimpleRequirement
  DTO

Bug: T244481
Change-Id: Id95d9e5d7125492968d0e15515224aadbc3075f8

includes/FeatureManagement/FeatureManager.php

@@ -38,8 +38,8 @@ use Wikimedia\Assert\Assert;
 final class FeatureManager {
 
 	/**
-	 * A map of feature name to the array of requirements. A feature is only considered enabled when
+	 * A map of feature name to the array of requirements (referenced by name). A feature is only
-	 * all of its requirements are met.
+	 * considered enabled when all of its requirements are met.
 	 *
 	 * See FeatureManager::registerFeature for additional detail.
 	 *
@@ -48,9 +48,12 @@ final class FeatureManager {
 	private $features = [];
 
 	/**
-	 * A map of requirement name to whether the requirement is met.
+	 * A map of requirement name to the Requirement instance that represents it.
 	 *
-	 * @var Array<string,bool>
+	 * The names of requirements are assumed to be static for the lifetime of the request. Therefore
+	 * we can use them to look up Requirement instances quickly.
+	 *
+	 * @var Array<string,Requirement>
 	 */
 	private $requirements = [];
 
@@ -138,7 +141,7 @@ final class FeatureManager {
 		$requirements = $this->features[$feature];
 
 		foreach ( $requirements as $name ) {
-			if ( !$this->requirements[$name] ) {
+			if ( !$this->requirements[$name]->isMet() ) {
 				return false;
 			}
 		}
@@ -146,16 +149,38 @@ final class FeatureManager {
 		return true;
 	}
 
+	/**
+	 * Register a complex requirement.
+	 *
+	 * A complex requirement is one that depends on object that may or may not be fully loaded
+	 * while the application is booting, e.g. see `User::isSafeToLoad`.
+	 *
+	 * Such requirements are expected to be registered during a hook that is run early on in the
+	 * application lifecycle, e.g. the `BeforePerformAction` and `APIBeforeMain` hooks.
+	 *
+	 * @see FeatureManager::registerRequirement
+	 *
+	 * @param Requirement $requirement
+	 *
+	 * @throws \LogicException If the requirement has already been registered
+	 */
+	public function registerComplexRequirement( Requirement $requirement ) {
+		$name = $requirement->getName();
+
+		if ( array_key_exists( $name, $this->requirements ) ) {
+			throw new \LogicException( "The requirement \"{$name}\" is already registered." );
+		}
+
+		$this->requirements[$name] = $requirement;
+	}
+
 	/**
 	 * Register a requirement.
 	 *
 	 * A requirement is some condition of the application state that a feature requires to be true
 	 * or false.
 	 *
-	 * At the moment, these conditions can only be evaluated when the requirement is being defined,
+	 * @see FeatureManager::registerComplexRequirement
-	 * i.e. at boot time. At that time, certain objects mightn't have been fully loaded (see
-	 * User::isSafeToLoad). See TODO.md for the proposed list of steps to allow this feature
-	 * manager to handle that scenario.
 	 *
 	 * @param string $name The name of the requirement
 	 * @param bool $isMet Whether the requirement is met
@@ -163,11 +188,7 @@ final class FeatureManager {
 	 * @throws \LogicException If the requirement has already been registered
 	 */
 	public function registerRequirement( string $name, bool $isMet ) {
-		if ( array_key_exists( $name, $this->requirements ) ) {
+		$this->registerComplexRequirement( new SimpleRequirement( $name, $isMet ) );
-			throw new \LogicException( "The requirement \"{$name}\" is already registered." );
-		}
-
-		$this->requirements[$name] = $isMet;
 	}
 
 	/**
@@ -183,6 +204,6 @@ final class FeatureManager {
 			throw new \InvalidArgumentException( "Requirement \"{$name}\" isn't registered." );
 		}
 
-		return $this->requirements[$name];
+		return $this->requirements[$name]->isMet();
 	}
 }

includes/FeatureManagement/Requirement.php

@@ -0,0 +1,45 @@
+<?php
+
+/**
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * http://www.gnu.org/copyleft/gpl.html
+ *
+ * @file
+ * @since 1.35
+ */
+
+namespace Vector\FeatureManagement;
+
+/**
+ * NOTE: This API hasn't settled. It may change at any time without warning. Please don't bind to
+ * it unless you absolutely need to
+ *
+ * @unstable
+ *
+ * @package FeatureManagement
+ * @internal
+ */
+interface Requirement {
+
+	/**
+	 * Gets the name of the requirement.
+	 */
+	public function getName() : string;
+
+	/**
+	 * Gets whether the requirement is met.
+	 */
+	public function isMet() : bool;
+}

includes/FeatureManagement/SimpleRequirement.php

@@ -0,0 +1,68 @@
+<?php
+
+/**
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * http://www.gnu.org/copyleft/gpl.html
+ *
+ * @file
+ * @since 1.35
+ */
+
+namespace Vector\FeatureManagement;
+
+/**
+ * NOTE: This API hasn't settled. It may change at any time without warning. Please don't bind to
+ * it unless you absolutely need to
+ *
+ * @unstable
+ *
+ * @package FeatureManagement
+ * @internal
+ */
+class SimpleRequirement implements Requirement {
+
+	/**
+	 * @var string The name of the requirement
+	 */
+	private $name;
+
+	/**
+	 * @var bool Whether the requirement is met
+	 */
+	private $isMet;
+
+	/**
+	 * @param string $name The name of the requirement
+	 * @param bool $isMet Whether the requirement is met
+	 */
+	public function __construct( string $name, bool $isMet ) {
+		$this->name = $name;
+		$this->isMet = $isMet;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function getName() : string {
+		return $this->name;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function isMet() : bool {
+		return $this->isMet;
+	}
+}

tests/phpunit/unit/FeatureManagement/FeatureManagerTest.php

@@ -32,6 +32,7 @@ class FeatureManagerTest extends \MediaWikiUnitTestCase {
 
 	/**
 	 * @covers ::registerRequirement
+	 * @covers ::registerComplexRequirement
 	 */
 	public function testRegisterRequirementThrowsWhenRequirementIsRegisteredTwice() {
 		$this->expectException( \LogicException::class );