3 namespace Wikimedia\Services
;
5 use InvalidArgumentException
;
6 use Psr\Container\ContainerInterface
;
8 use Wikimedia\Assert\Assert
;
9 use Wikimedia\ScopedCallback
;
12 * Generic service container.
14 * This program is free software; you can redistribute it and/or modify
15 * it under the terms of the GNU General Public License as published by
16 * the Free Software Foundation; either version 2 of the License, or
17 * (at your option) any later version.
19 * This program is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 * GNU General Public License for more details.
24 * You should have received a copy of the GNU General Public License along
25 * with this program; if not, write to the Free Software Foundation, Inc.,
26 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
27 * http://www.gnu.org/copyleft/gpl.html
35 * ServiceContainer provides a generic service to manage named services using
36 * lazy instantiation based on instantiator callback functions.
38 * Services managed by an instance of ServiceContainer may or may not implement
41 * @note When using ServiceContainer to manage a set of services, consider
42 * creating a wrapper or a subclass that provides access to the services via
43 * getter methods with more meaningful names and more specific return type
46 * @see docs/injection.txt for an overview of using dependency injection in the
47 * MediaWiki code base.
49 class ServiceContainer
implements ContainerInterface
, DestructibleService
{
54 private $services = [];
59 private $serviceInstantiators = [];
64 private $serviceManipulators = [];
67 * @var bool[] disabled status, per service name
69 private $disabled = [];
74 private $extraInstantiationParams;
79 private $destroyed = false;
82 * @var array Set of services currently being created, to detect loops
84 private $servicesBeingCreated = [];
87 * @param array $extraInstantiationParams Any additional parameters to be passed to the
88 * instantiator function when creating a service. This is typically used to provide
89 * access to additional ServiceContainers or Config objects.
91 public function __construct( array $extraInstantiationParams = [] ) {
92 $this->extraInstantiationParams
= $extraInstantiationParams;
96 * Destroys all contained service instances that implement the DestructibleService
97 * interface. This will render all services obtained from this ServiceContainer
98 * instance unusable. In particular, this will disable access to the storage backend
99 * via any of these services. Any future call to getService() will throw an exception.
101 * @see resetGlobalInstance()
103 public function destroy() {
104 foreach ( $this->getServiceNames() as $name ) {
105 $service = $this->peekService( $name );
106 if ( $service !== null && $service instanceof DestructibleService
) {
111 // Break circular references due to the $this reference in closures, by
112 // erasing the instantiator array. This allows the ServiceContainer to
113 // be deleted when it goes out of scope.
114 $this->serviceInstantiators
= [];
115 // Also remove the services themselves, to avoid confusion.
116 $this->services
= [];
117 $this->destroyed
= true;
121 * @param array $wiringFiles A list of PHP files to load wiring information from.
122 * Each file is loaded using PHP's include mechanism. Each file is expected to
123 * return an associative array that maps service names to instantiator functions.
125 public function loadWiringFiles( array $wiringFiles ) {
126 foreach ( $wiringFiles as $file ) {
127 // the wiring file is required to return an array of instantiators.
128 $wiring = require $file;
130 Assert
::postcondition(
132 "Wiring file $file is expected to return an array!"
135 $this->applyWiring( $wiring );
140 * Registers multiple services (aka a "wiring").
142 * @param array $serviceInstantiators An associative array mapping service names to
143 * instantiator functions.
145 public function applyWiring( array $serviceInstantiators ) {
146 Assert
::parameterElementType( 'callable', $serviceInstantiators, '$serviceInstantiators' );
148 foreach ( $serviceInstantiators as $name => $instantiator ) {
149 $this->defineService( $name, $instantiator );
154 * Imports all wiring defined in $container. Wiring defined in $container
155 * will override any wiring already defined locally. However, already
156 * existing service instances will be preserved.
160 * @param ServiceContainer $container
161 * @param string[] $skip A list of service names to skip during import
163 public function importWiring( ServiceContainer
$container, $skip = [] ) {
164 $newInstantiators = array_diff_key(
165 $container->serviceInstantiators
,
169 $this->serviceInstantiators
= array_merge(
170 $this->serviceInstantiators
,
174 $newManipulators = array_diff(
175 array_keys( $container->serviceManipulators
),
179 foreach ( $newManipulators as $name ) {
180 if ( isset( $this->serviceManipulators
[$name] ) ) {
181 $this->serviceManipulators
[$name] = array_merge(
182 $this->serviceManipulators
[$name],
183 $container->serviceManipulators
[$name]
186 $this->serviceManipulators
[$name] = $container->serviceManipulators
[$name];
192 * Returns true if a service is defined for $name, that is, if a call to getService( $name )
193 * would return a service instance.
195 * @param string $name
199 public function hasService( $name ) {
200 return isset( $this->serviceInstantiators
[$name] );
204 public function has( $name ) {
205 return $this->hasService( $name );
209 * Returns the service instance for $name only if that service has already been instantiated.
210 * This is intended for situations where services get destroyed/cleaned up, so we can
211 * avoid creating a service just to destroy it again.
213 * @note This is intended for internal use and for test fixtures.
214 * Application logic should use getService() instead.
218 * @param string $name
220 * @return object|null The service instance, or null if the service has not yet been instantiated.
221 * @throws RuntimeException if $name does not refer to a known service.
223 public function peekService( $name ) {
224 if ( !$this->hasService( $name ) ) {
225 throw new NoSuchServiceException( $name );
228 return $this->services
[$name] ??
null;
234 public function getServiceNames() {
235 return array_keys( $this->serviceInstantiators
);
239 * Define a new service. The service must not be known already.
242 * @see redefineService().
244 * @param string $name The name of the service to register, for use with getService().
245 * @param callable $instantiator Callback that returns a service instance.
246 * Will be called with this ServiceContainer instance as the only parameter.
247 * Any extra instantiation parameters provided to the constructor will be
248 * passed as subsequent parameters when invoking the instantiator.
250 * @throws RuntimeException if there is already a service registered as $name.
252 public function defineService( $name, callable
$instantiator ) {
253 Assert
::parameterType( 'string', $name, '$name' );
255 if ( $this->hasService( $name ) ) {
256 throw new ServiceAlreadyDefinedException( $name );
259 $this->serviceInstantiators
[$name] = $instantiator;
263 * Replace an already defined service.
265 * @see defineService().
267 * @note This will fail if the service was already instantiated. If the service was previously
268 * disabled, it will be re-enabled by this call. Any manipulators registered for the service
269 * will remain in place.
271 * @param string $name The name of the service to register.
272 * @param callable $instantiator Callback function that returns a service instance.
273 * Will be called with this ServiceContainer instance as the only parameter.
274 * The instantiator must return a service compatible with the originally defined service.
275 * Any extra instantiation parameters provided to the constructor will be
276 * passed as subsequent parameters when invoking the instantiator.
278 * @throws NoSuchServiceException if $name is not a known service.
279 * @throws CannotReplaceActiveServiceException if the service was already instantiated.
281 public function redefineService( $name, callable
$instantiator ) {
282 Assert
::parameterType( 'string', $name, '$name' );
284 if ( !$this->hasService( $name ) ) {
285 throw new NoSuchServiceException( $name );
288 if ( isset( $this->services
[$name] ) ) {
289 throw new CannotReplaceActiveServiceException( $name );
292 $this->serviceInstantiators
[$name] = $instantiator;
293 unset( $this->disabled
[$name] );
297 * Add a service manipulator callback for the given service.
298 * This method may be used by extensions that need to wrap, replace, or re-configure a
299 * service. It would typically be called from a MediaWikiServices hook handler.
301 * The manipulator callback is called just after the service is instantiated.
302 * It can call methods on the service to change configuration, or wrap or otherwise
305 * @see defineService().
306 * @see redefineService().
308 * @note This will fail if the service was already instantiated.
312 * @param string $name The name of the service to manipulate.
313 * @param callable $manipulator Callback function that manipulates, wraps or replaces a
314 * service instance. The callback receives the new service instance and this
315 * ServiceContainer as parameters, as well as any extra instantiation parameters specified
316 * when constructing this ServiceContainer. If the callback returns a value, that
317 * value replaces the original service instance.
319 * @throws NoSuchServiceException if $name is not a known service.
320 * @throws CannotReplaceActiveServiceException if the service was already instantiated.
322 public function addServiceManipulator( $name, callable
$manipulator ) {
323 Assert
::parameterType( 'string', $name, '$name' );
325 if ( !$this->hasService( $name ) ) {
326 throw new NoSuchServiceException( $name );
329 if ( isset( $this->services
[$name] ) ) {
330 throw new CannotReplaceActiveServiceException( $name );
333 $this->serviceManipulators
[$name][] = $manipulator;
337 * Disables a service.
339 * @note Attempts to call getService() for a disabled service will result
340 * in a DisabledServiceException. Calling peekService for a disabled service will
341 * return null. Disabled services are listed by getServiceNames(). A disabled service
342 * can be enabled again using redefineService().
344 * @note If the service was already active (that is, instantiated) when getting disabled,
345 * and the service instance implements DestructibleService, destroy() is called on the
348 * @see redefineService()
349 * @see resetService()
351 * @param string $name The name of the service to disable.
353 * @throws RuntimeException if $name is not a known service.
355 public function disableService( $name ) {
356 $this->resetService( $name );
358 $this->disabled
[$name] = true;
362 * Resets a service by dropping the service instance.
363 * If the service instances implements DestructibleService, destroy()
364 * is called on the service instance.
366 * @warning This is generally unsafe! Other services may still retain references
367 * to the stale service instance, leading to failures and inconsistencies. Subclasses
368 * may use this method to reset specific services under specific instances, but
369 * it should not be exposed to application logic.
371 * @note This is declared final so subclasses can not interfere with the expectations
372 * disableService() has when calling resetService().
374 * @see redefineService()
375 * @see disableService().
377 * @param string $name The name of the service to reset.
378 * @param bool $destroy Whether the service instance should be destroyed if it exists.
379 * When set to false, any existing service instance will effectively be detached
380 * from the container.
382 * @throws RuntimeException if $name is not a known service.
384 final protected function resetService( $name, $destroy = true ) {
385 Assert
::parameterType( 'string', $name, '$name' );
387 $instance = $this->peekService( $name );
389 if ( $destroy && $instance instanceof DestructibleService
) {
390 $instance->destroy();
393 unset( $this->services
[$name] );
394 unset( $this->disabled
[$name] );
398 * Returns a service object of the kind associated with $name.
399 * Services instances are instantiated lazily, on demand.
400 * This method may or may not return the same service instance
401 * when called multiple times with the same $name.
403 * @note Rather than calling this method directly, it is recommended to provide
404 * getters with more meaningful names and more specific return types, using
405 * a subclass or wrapper.
407 * @see redefineService().
409 * @param string $name The service name
411 * @throws NoSuchServiceException if $name is not a known service.
412 * @throws ContainerDisabledException if this container has already been destroyed.
413 * @throws ServiceDisabledException if the requested service has been disabled.
415 * @return mixed The service instance
417 public function getService( $name ) {
418 if ( $this->destroyed
) {
419 throw new ContainerDisabledException();
422 if ( isset( $this->disabled
[$name] ) ) {
423 throw new ServiceDisabledException( $name );
426 if ( !isset( $this->services
[$name] ) ) {
427 $this->services
[$name] = $this->createService( $name );
430 return $this->services
[$name];
434 public function get( $name ) {
435 return $this->getService( $name );
439 * @param string $name
441 * @throws InvalidArgumentException if $name is not a known service.
442 * @throws RuntimeException if a circular dependency is detected.
445 private function createService( $name ) {
446 if ( isset( $this->serviceInstantiators
[$name] ) ) {
447 if ( isset( $this->servicesBeingCreated
[$name] ) ) {
448 throw new RuntimeException( "Circular dependency when creating service! " .
449 implode( ' -> ', array_keys( $this->servicesBeingCreated
) ) . " -> $name" );
451 $this->servicesBeingCreated
[$name] = true;
452 $removeFromStack = new ScopedCallback( function () use ( $name ) {
453 unset( $this->servicesBeingCreated
[$name] );
456 $service = ( $this->serviceInstantiators
[$name] )(
458 ...$this->extraInstantiationParams
461 if ( isset( $this->serviceManipulators
[$name] ) ) {
462 foreach ( $this->serviceManipulators
[$name] as $callback ) {
463 $ret = call_user_func_array(
465 array_merge( [ $service, $this ], $this->extraInstantiationParams
)
468 // If the manipulator callback returns an object, that object replaces
469 // the original service instance. This allows the manipulator to wrap
470 // or fully replace the service.
471 if ( $ret !== null ) {
477 $removeFromStack->consume();
479 // NOTE: when adding more wiring logic here, make sure importWiring() is kept in sync!
481 throw new NoSuchServiceException( $name );
488 * @param string $name
489 * @return bool Whether the service is disabled
492 public function isServiceDisabled( $name ) {
493 return isset( $this->disabled
[$name] );
498 * Retain the old class name for backwards compatibility.
499 * @deprecated since 1.33
501 class_alias( ServiceContainer
::class, 'MediaWiki\Services\ServiceContainer' );