2 namespace MediaWiki\Services
;
4 use InvalidArgumentException
;
6 use Wikimedia\Assert\Assert
;
9 * Generic service container.
11 * This program is free software; you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by
13 * the Free Software Foundation; either version 2 of the License, or
14 * (at your option) any later version.
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU General Public License for more details.
21 * You should have received a copy of the GNU General Public License along
22 * with this program; if not, write to the Free Software Foundation, Inc.,
23 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
24 * http://www.gnu.org/copyleft/gpl.html
32 * ServiceContainer provides a generic service to manage named services using
33 * lazy instantiation based on instantiator callback functions.
35 * Services managed by an instance of ServiceContainer may or may not implement
38 * @note When using ServiceContainer to manage a set of services, consider
39 * creating a wrapper or a subclass that provides access to the services via
40 * getter methods with more meaningful names and more specific return type
43 * @see docs/injection.txt for an overview of using dependency injection in the
44 * MediaWiki code base.
46 class ServiceContainer
implements DestructibleService
{
51 private $services = [];
56 private $serviceInstantiators = [];
61 private $serviceManipulators = [];
64 * @var bool[] disabled status, per service name
66 private $disabled = [];
71 private $extraInstantiationParams;
76 private $destroyed = false;
79 * @param array $extraInstantiationParams Any additional parameters to be passed to the
80 * instantiator function when creating a service. This is typically used to provide
81 * access to additional ServiceContainers or Config objects.
83 public function __construct( array $extraInstantiationParams = [] ) {
84 $this->extraInstantiationParams
= $extraInstantiationParams;
88 * Destroys all contained service instances that implement the DestructibleService
89 * interface. This will render all services obtained from this MediaWikiServices
90 * instance unusable. In particular, this will disable access to the storage backend
91 * via any of these services. Any future call to getService() will throw an exception.
93 * @see resetGlobalInstance()
95 public function destroy() {
96 foreach ( $this->getServiceNames() as $name ) {
97 $service = $this->peekService( $name );
98 if ( $service !== null && $service instanceof DestructibleService
) {
103 $this->destroyed
= true;
107 * @param array $wiringFiles A list of PHP files to load wiring information from.
108 * Each file is loaded using PHP's include mechanism. Each file is expected to
109 * return an associative array that maps service names to instantiator functions.
111 public function loadWiringFiles( array $wiringFiles ) {
112 foreach ( $wiringFiles as $file ) {
113 // the wiring file is required to return an array of instantiators.
114 $wiring = require $file;
116 Assert
::postcondition(
118 "Wiring file $file is expected to return an array!"
121 $this->applyWiring( $wiring );
126 * Registers multiple services (aka a "wiring").
128 * @param array $serviceInstantiators An associative array mapping service names to
129 * instantiator functions.
131 public function applyWiring( array $serviceInstantiators ) {
132 Assert
::parameterElementType( 'callable', $serviceInstantiators, '$serviceInstantiators' );
134 foreach ( $serviceInstantiators as $name => $instantiator ) {
135 $this->defineService( $name, $instantiator );
140 * Imports all wiring defined in $container. Wiring defined in $container
141 * will override any wiring already defined locally. However, already
142 * existing service instances will be preserved.
146 * @param ServiceContainer $container
147 * @param string[] $skip A list of service names to skip during import
149 public function importWiring( ServiceContainer
$container, $skip = [] ) {
150 $newInstantiators = array_diff_key(
151 $container->serviceInstantiators
,
155 $this->serviceInstantiators
= array_merge(
156 $this->serviceInstantiators
,
160 $newManipulators = array_diff(
161 array_keys( $container->serviceManipulators
),
165 foreach ( $newManipulators as $name ) {
166 if ( isset( $this->serviceManipulators
[$name] ) ) {
167 $this->serviceManipulators
[$name] = array_merge(
168 $this->serviceManipulators
[$name],
169 $container->serviceManipulators
[$name]
172 $this->serviceManipulators
[$name] = $container->serviceManipulators
[$name];
178 * Returns true if a service is defined for $name, that is, if a call to getService( $name )
179 * would return a service instance.
181 * @param string $name
185 public function hasService( $name ) {
186 return isset( $this->serviceInstantiators
[$name] );
190 * Returns the service instance for $name only if that service has already been instantiated.
191 * This is intended for situations where services get destroyed/cleaned up, so we can
192 * avoid creating a service just to destroy it again.
194 * @note This is intended for internal use and for test fixtures.
195 * Application logic should use getService() instead.
199 * @param string $name
201 * @return object|null The service instance, or null if the service has not yet been instantiated.
202 * @throws RuntimeException if $name does not refer to a known service.
204 public function peekService( $name ) {
205 if ( !$this->hasService( $name ) ) {
206 throw new NoSuchServiceException( $name );
209 return $this->services
[$name] ??
null;
215 public function getServiceNames() {
216 return array_keys( $this->serviceInstantiators
);
220 * Define a new service. The service must not be known already.
223 * @see redefineService().
225 * @param string $name The name of the service to register, for use with getService().
226 * @param callable $instantiator Callback that returns a service instance.
227 * Will be called with this MediaWikiServices instance as the only parameter.
228 * Any extra instantiation parameters provided to the constructor will be
229 * passed as subsequent parameters when invoking the instantiator.
231 * @throws RuntimeException if there is already a service registered as $name.
233 public function defineService( $name, callable
$instantiator ) {
234 Assert
::parameterType( 'string', $name, '$name' );
236 if ( $this->hasService( $name ) ) {
237 throw new ServiceAlreadyDefinedException( $name );
240 $this->serviceInstantiators
[$name] = $instantiator;
244 * Replace an already defined service.
246 * @see defineService().
248 * @note This will fail if the service was already instantiated. If the service was previously
249 * disabled, it will be re-enabled by this call. Any manipulators registered for the service
250 * will remain in place.
252 * @param string $name The name of the service to register.
253 * @param callable $instantiator Callback function that returns a service instance.
254 * Will be called with this MediaWikiServices instance as the only parameter.
255 * The instantiator must return a service compatible with the originally defined service.
256 * Any extra instantiation parameters provided to the constructor will be
257 * passed as subsequent parameters when invoking the instantiator.
259 * @throws NoSuchServiceException if $name is not a known service.
260 * @throws CannotReplaceActiveServiceException if the service was already instantiated.
262 public function redefineService( $name, callable
$instantiator ) {
263 Assert
::parameterType( 'string', $name, '$name' );
265 if ( !$this->hasService( $name ) ) {
266 throw new NoSuchServiceException( $name );
269 if ( isset( $this->services
[$name] ) ) {
270 throw new CannotReplaceActiveServiceException( $name );
273 $this->serviceInstantiators
[$name] = $instantiator;
274 unset( $this->disabled
[$name] );
278 * Add a service manipulator callback for the given service.
279 * This method may be used by extensions that need to wrap, replace, or re-configure a
280 * service. It would typically be called from a MediaWikiServices hook handler.
282 * The manipulator callback is called just after the service is instantiated.
283 * It can call methods on the service to change configuration, or wrap or otherwise
286 * @see defineService().
287 * @see redefineService().
289 * @note This will fail if the service was already instantiated.
293 * @param string $name The name of the service to manipulate.
294 * @param callable $manipulator Callback function that manipulates, wraps or replaces a
295 * service instance. The callback receives the new service instance and this the
296 * ServiceContainer as parameters, as well as any extra instantiation parameters specified
297 * when constructing this ServiceContainer. If the callback returns a value, that
298 * value replaces the original service instance.
300 * @throws NoSuchServiceException if $name is not a known service.
301 * @throws CannotReplaceActiveServiceException if the service was already instantiated.
303 public function addServiceManipulator( $name, callable
$manipulator ) {
304 Assert
::parameterType( 'string', $name, '$name' );
306 if ( !$this->hasService( $name ) ) {
307 throw new NoSuchServiceException( $name );
310 if ( isset( $this->services
[$name] ) ) {
311 throw new CannotReplaceActiveServiceException( $name );
314 $this->serviceManipulators
[$name][] = $manipulator;
318 * Disables a service.
320 * @note Attempts to call getService() for a disabled service will result
321 * in a DisabledServiceException. Calling peekService for a disabled service will
322 * return null. Disabled services are listed by getServiceNames(). A disabled service
323 * can be enabled again using redefineService().
325 * @note If the service was already active (that is, instantiated) when getting disabled,
326 * and the service instance implements DestructibleService, destroy() is called on the
329 * @see redefineService()
330 * @see resetService()
332 * @param string $name The name of the service to disable.
334 * @throws RuntimeException if $name is not a known service.
336 public function disableService( $name ) {
337 $this->resetService( $name );
339 $this->disabled
[$name] = true;
343 * Resets a service by dropping the service instance.
344 * If the service instances implements DestructibleService, destroy()
345 * is called on the service instance.
347 * @warning This is generally unsafe! Other services may still retain references
348 * to the stale service instance, leading to failures and inconsistencies. Subclasses
349 * may use this method to reset specific services under specific instances, but
350 * it should not be exposed to application logic.
352 * @note This is declared final so subclasses can not interfere with the expectations
353 * disableService() has when calling resetService().
355 * @see redefineService()
356 * @see disableService().
358 * @param string $name The name of the service to reset.
359 * @param bool $destroy Whether the service instance should be destroyed if it exists.
360 * When set to false, any existing service instance will effectively be detached
361 * from the container.
363 * @throws RuntimeException if $name is not a known service.
365 final protected function resetService( $name, $destroy = true ) {
366 Assert
::parameterType( 'string', $name, '$name' );
368 $instance = $this->peekService( $name );
370 if ( $destroy && $instance instanceof DestructibleService
) {
371 $instance->destroy();
374 unset( $this->services
[$name] );
375 unset( $this->disabled
[$name] );
379 * Returns a service object of the kind associated with $name.
380 * Services instances are instantiated lazily, on demand.
381 * This method may or may not return the same service instance
382 * when called multiple times with the same $name.
384 * @note Rather than calling this method directly, it is recommended to provide
385 * getters with more meaningful names and more specific return types, using
386 * a subclass or wrapper.
388 * @see redefineService().
390 * @param string $name The service name
392 * @throws NoSuchServiceException if $name is not a known service.
393 * @throws ContainerDisabledException if this container has already been destroyed.
394 * @throws ServiceDisabledException if the requested service has been disabled.
396 * @return object The service instance
398 public function getService( $name ) {
399 if ( $this->destroyed
) {
400 throw new ContainerDisabledException();
403 if ( isset( $this->disabled
[$name] ) ) {
404 throw new ServiceDisabledException( $name );
407 if ( !isset( $this->services
[$name] ) ) {
408 $this->services
[$name] = $this->createService( $name );
411 return $this->services
[$name];
415 * @param string $name
417 * @throws InvalidArgumentException if $name is not a known service.
420 private function createService( $name ) {
421 if ( isset( $this->serviceInstantiators
[$name] ) ) {
422 $service = ( $this->serviceInstantiators
[$name] )(
424 ...$this->extraInstantiationParams
427 if ( isset( $this->serviceManipulators
[$name] ) ) {
428 foreach ( $this->serviceManipulators
[$name] as $callback ) {
429 $ret = call_user_func_array(
431 array_merge( [ $service, $this ], $this->extraInstantiationParams
)
434 // If the manipulator callback returns an object, that object replaces
435 // the original service instance. This allows the manipulator to wrap
436 // or fully replace the service.
437 if ( $ret !== null ) {
443 // NOTE: when adding more wiring logic here, make sure importWiring() is kept in sync!
445 throw new NoSuchServiceException( $name );
452 * @param string $name
453 * @return bool Whether the service is disabled
456 public function isServiceDisabled( $name ) {
457 return isset( $this->disabled
[$name] );