Merge "Add warning to MediaWikiServicesHook interface."

RELEASE-NOTES-1.37

@@ -274,6 +274,9 @@ because of Phabricator reports.
 * The PatchFileLocation trait was removed without deprecation.
 * ActorMigrationBase::getExistingActorId and ::getNewActorId, hard deprecated
   since 1.36, were removed.
+* Hook handlers implementing MediaWikiServicesHook are prohibited from having
+  services injected. This is because by definition, this hook runs before the
+  service container is fully initialized.
 * The protected property LocalFile::$metadata was removed without deprecation.
 * WatchedItem::getUser, hard deprecated since 1.36, has been removed.
 * AuthManager::singleton, hard deprecated since 1.36, has been removed.

includes/Hook/MediaWikiServicesHook.php

@@ -8,6 +8,11 @@ use MediaWiki\MediaWikiServices;
  * This is a hook handler interface, see docs/Hooks.md.
  * Use the hook name "MediaWikiServices" to register handlers implementing this interface.
  *
+ * @warning Implementations of this interface must not have services injected into
+ * their constructor! This is because this hook runs while the service container is
+ * still being initialized, so any services it asks for might get instantiated based on
+ * incomplete configuration and wiring.
+ *
  * @stable to implement
  * @ingroup Hooks
  */
@@ -17,6 +22,43 @@ interface MediaWikiServicesHook {
 	 * Extensions may use this to define, replace, or wrap services. However, the
 	 * preferred way to define a new service is the $wgServiceWiringFiles array.
 	 *
+	 * @warning Implementations must not immediately access services instances from the
+	 * service container $services, since the service container is not fully initialized
+	 * at the time when the hook is called. However, callbacks that are used as service
+	 * instantiators or service manipulators may access service instances.
+	 *
+	 * Example:
+	 * @code
+	 * function onMediaWikiServices( $services ) {
+	 *     // The service wiring and configuration in $services may be incomplete at this time,
+	 *     // do not access services yet!
+	 *     // At this point, we can only manipulate the wiring, not use it!
+	 *
+	 *     $services->defineService(
+	 *        'MyCoolService',
+	 *         function( MediaWikiServices $container ) {
+	 *             // It's ok to access services inside this callback, since the
+	 *             // service container will be fully initialized when it is called!
+	 *             return new MyCoolService( $container->getPageLookup() );
+	 *         }
+	 *     );
+	 *
+	 *     $services->addServiceManipulator(
+	 *         'SlotRoleRegistry',
+	 *         function ( SlotRoleRegistry $service, MediaWikiServices $container ) {
+	 *             // ...
+	 *         }
+	 *     );
+	 *
+	 *     $services->redefineService(
+	 *         'StatsdDataFactory',
+	 *         function ( MediaWikiServices $container ) {
+	 *             // ...
+	 *         }
+	 *     );
+	 * }
+	 * @endcode
+	 *
 	 * @since 1.35
 	 *
 	 * @param MediaWikiServices $services

includes/HookContainer/HookRunner.php

@@ -2529,7 +2529,8 @@ class HookRunner implements
 	public function onMediaWikiServices( $services ) {
 		return $this->container->run(
 			'MediaWikiServices',
-			[ $services ]
+			[ $services ],
+			[ 'noServices' => true ]
 		);
 	}