1	<?php
2
3	namespace MediaWiki\Hook;
4
5	use MediaWiki\MediaWikiServices;
6
7	/**
8	* This is a hook handler interface, see docs/Hooks.md.
9	* Use the hook name "MediaWikiServices" to register handlers implementing this interface.
10	*
11	* @warning Implementations of this interface must not have services injected into
12	* their constructor! This is because this hook runs while the service container is
13	* still being initialized, so any services it asks for might get instantiated based on
14	* incomplete configuration and wiring.
15	*
16	* @stable to implement
17	* @ingroup Hooks
18	*/
19	interface MediaWikiServicesHook {
20	/**
21	* This hook is called when a global MediaWikiServices instance is initialized.
22	* Extensions may use this to define, replace, or wrap services. However, the
23	* preferred way to define a new service is the $wgServiceWiringFiles array.
24	*
25	* @warning Implementations must not immediately access services instances from the
26	* service container $services, since the service container is not fully initialized
27	* at the time when the hook is called. However, callbacks that are used as service
28	* instantiators or service manipulators may access service instances.
29	*
30	* Example:
31	* @code
32	* function onMediaWikiServices( $services ) {
33	*     // The service wiring and configuration in $services may be incomplete at this time,
34	*     // do not access services yet!
35	*     // At this point, we can only manipulate the wiring, not use it!
36	*
37	*     $services->defineService(
38	*        'MyCoolService',
39	*         function( MediaWikiServices $container ) {
40	*             // It's ok to access services inside this callback, since the
41	*             // service container will be fully initialized when it is called!
42	*             return new MyCoolService( $container->getPageLookup() );
43	*         }
44	*     );
45	*
46	*     $services->addServiceManipulator(
47	*         'SlotRoleRegistry',
48	*         function ( SlotRoleRegistry $service, MediaWikiServices $container ) {
49	*             // ...
50	*         }
51	*     );
52	*
53	*     $services->redefineService(
54	*         'StatsdDataFactory',
55	*         function ( MediaWikiServices $container ) {
56	*             // ...
57	*         }
58	*     );
59	* }
60	* @endcode
61	*
62	* @since 1.35
63	*
64	* @param MediaWikiServices $services
65	* @return bool|void True or no return value to continue or false to abort
66	*/
67	public function onMediaWikiServices( $services );
68	}