ServiceContainer provides a generic service to manage named services using lazy instantiation based on instantiator callback functions. More...

Inheritance diagram for Wikimedia\Services\ServiceContainer:

[legend]

Collaboration diagram for Wikimedia\Services\ServiceContainer:

[legend]

Public Member Functions
	__construct (array $extraInstantiationParams=[])

	addServiceManipulator ( $name, callable $manipulator)
	Add a service manipulator callback for the given service.

	applyWiring (array $serviceInstantiators)
	Registers multiple services (aka a "wiring").

	defineService ( $name, callable $instantiator)
	Define a new service.

	destroy ()
	Destroys all contained service instances that implement the DestructibleService interface.

	disableService ( $name)
	Disables a service.

	get ( $name)

	getService ( $name)
	Returns a service object of the kind associated with $name.

	getServiceNames ()

	has ( $name)

	hasService ( $name)
	Returns true if a service is defined for $name, that is, if a call to getService( $name ) would return a service instance.

	importWiring (ServiceContainer $container, $skip=[])
	Imports all wiring defined in $container.

	isServiceDisabled ( $name)

	loadWiringFiles (array $wiringFiles)

	peekService ( $name)
	Returns the service instance for $name only if that service has already been instantiated.

	redefineService ( $name, callable $instantiator)
	Replace an already defined service.

Protected Member Functions
	resetService ( $name, $destroy=true)
	Resets a service by dropping the service instance.

Private Member Functions
	createService ( $name)

Private Attributes
bool	$destroyed = false

bool[]	$disabled = []
	disabled status, per service name

array	$extraInstantiationParams

callable[]	$serviceInstantiators = []

callable[][]	$serviceManipulators = []

object[]	$services = []

array	$servicesBeingCreated = []
	Set of services currently being created, to detect loops.

Detailed Description

ServiceContainer provides a generic service to manage named services using lazy instantiation based on instantiator callback functions.

Services managed by an instance of ServiceContainer may or may not implement a common interface.

Note: When using ServiceContainer to manage a set of services, consider creating a wrapper or a subclass that provides access to the services via getter methods with more meaningful names and more specific return type declarations.

See also: docs/injection.txt for an overview of using dependency injection in the MediaWiki code base.

Definition at line 49 of file ServiceContainer.php.

Constructor & Destructor Documentation

◆ __construct()

Wikimedia\Services\ServiceContainer::__construct ( array $extraInstantiationParams = [] )

Parameters

array $extraInstantiationParams Any additional parameters to be passed to the instantiator function when creating a service. This is typically used to provide access to additional ServiceContainers or Config objects.

Definition at line 91 of file ServiceContainer.php.

References Wikimedia\Services\ServiceContainer\$extraInstantiationParams.

Member Function Documentation

◆ addServiceManipulator()

Wikimedia\Services\ServiceContainer::addServiceManipulator	(		$name,
		callable	$manipulator )

Add a service manipulator callback for the given service.

This method may be used by extensions that need to wrap, replace, or re-configure a service. It would typically be called from a MediaWikiServices hook handler.

The manipulator callback is called just after the service is instantiated. It can call methods on the service to change configuration, or wrap or otherwise replace it.

See also: defineService().; redefineService().

Note: This will fail if the service was already instantiated.

Since: 1.32

Parameters

string	$name	The name of the service to manipulate.
callable	$manipulator	Callback function that manipulates, wraps or replaces a service instance. The callback receives the new service instance and this ServiceContainer as parameters, as well as any extra instantiation parameters specified when constructing this ServiceContainer. If the callback returns a value, that value replaces the original service instance.

Exceptions

NoSuchServiceException	if $name is not a known service.
CannotReplaceActiveServiceException	if the service was already instantiated.

Definition at line 322 of file ServiceContainer.php.

References Wikimedia\Services\ServiceContainer\hasService().

◆ applyWiring()

Wikimedia\Services\ServiceContainer::applyWiring ( array $serviceInstantiators )

Registers multiple services (aka a "wiring").

Parameters

array $serviceInstantiators An associative array mapping service names to instantiator functions.

Definition at line 145 of file ServiceContainer.php.

References Wikimedia\Services\ServiceContainer\$serviceInstantiators, and Wikimedia\Services\ServiceContainer\defineService().

Referenced by Wikimedia\Services\ServiceContainer\loadWiringFiles().

◆ createService()

Wikimedia\Services\ServiceContainer::createService ( $name )

private

Parameters

string $name

Exceptions

InvalidArgumentException	if $name is not a known service.
RuntimeException	if a circular dependency is detected.

Returns: object

Definition at line 445 of file ServiceContainer.php.

Referenced by Wikimedia\Services\ServiceContainer\getService().

◆ defineService()

Wikimedia\Services\ServiceContainer::defineService	(		$name,
		callable	$instantiator )

Define a new service.

The service must not be known already.

See also: getService().; redefineService().

Parameters

string	$name	The name of the service to register, for use with getService().
callable	$instantiator	Callback that returns a service instance. Will be called with this ServiceContainer instance as the only parameter. Any extra instantiation parameters provided to the constructor will be passed as subsequent parameters when invoking the instantiator.

Exceptions

RuntimeException if there is already a service registered as $name.

Definition at line 252 of file ServiceContainer.php.

References Wikimedia\Services\ServiceContainer\hasService().

Referenced by Wikimedia\Services\ServiceContainer\applyWiring().

◆ destroy()

Wikimedia\Services\ServiceContainer::destroy ( )

Destroys all contained service instances that implement the DestructibleService interface.

This will render all services obtained from this ServiceContainer instance unusable. In particular, this will disable access to the storage backend via any of these services. Any future call to getService() will throw an exception.

See also: resetGlobalInstance()

Implements Wikimedia\Services\DestructibleService.

Definition at line 103 of file ServiceContainer.php.

References Wikimedia\Services\ServiceContainer\getServiceNames(), and Wikimedia\Services\ServiceContainer\peekService().

◆ disableService()

Wikimedia\Services\ServiceContainer::disableService ( $name )

Disables a service.

Note: Attempts to call getService() for a disabled service will result in a DisabledServiceException. Calling peekService for a disabled service will return null. Disabled services are listed by getServiceNames(). A disabled service can be enabled again using redefineService().; If the service was already active (that is, instantiated) when getting disabled, and the service instance implements DestructibleService, destroy() is called on the service instance.

See also: redefineService(); resetService()

Parameters

string $name The name of the service to disable.

Exceptions

RuntimeException if $name is not a known service.

Definition at line 355 of file ServiceContainer.php.

References Wikimedia\Services\ServiceContainer\resetService().

◆ get()

Wikimedia\Services\ServiceContainer::get ( $name )

Definition at line 434 of file ServiceContainer.php.

References Wikimedia\Services\ServiceContainer\getService().

◆ getService()

Wikimedia\Services\ServiceContainer::getService ( $name )

Returns a service object of the kind associated with $name.

Services instances are instantiated lazily, on demand. This method may or may not return the same service instance when called multiple times with the same $name.

Note: Rather than calling this method directly, it is recommended to provide getters with more meaningful names and more specific return types, using a subclass or wrapper.

See also: redefineService().

Parameters

string $name The service name

Exceptions

NoSuchServiceException	if $name is not a known service.
ContainerDisabledException	if this container has already been destroyed.
ServiceDisabledException	if the requested service has been disabled.

Returns: mixed The service instance

Definition at line 417 of file ServiceContainer.php.

References Wikimedia\Services\ServiceContainer\createService().

Referenced by Wikimedia\Services\ServiceContainer\get().

◆ getServiceNames()

Wikimedia\Services\ServiceContainer::getServiceNames ( )

Returns: string[]

Definition at line 234 of file ServiceContainer.php.

Referenced by Wikimedia\Services\ServiceContainer\destroy().

◆ has()

Wikimedia\Services\ServiceContainer::has ( $name )

Definition at line 204 of file ServiceContainer.php.

References Wikimedia\Services\ServiceContainer\hasService().

◆ hasService()

Wikimedia\Services\ServiceContainer::hasService ( $name )

Returns true if a service is defined for $name, that is, if a call to getService( $name ) would return a service instance.

Parameters

string $name

Returns: bool

Definition at line 199 of file ServiceContainer.php.

Referenced by Wikimedia\Services\ServiceContainer\addServiceManipulator(), Wikimedia\Services\ServiceContainer\defineService(), Wikimedia\Services\ServiceContainer\has(), Wikimedia\Services\ServiceContainer\peekService(), and Wikimedia\Services\ServiceContainer\redefineService().

◆ importWiring()

Wikimedia\Services\ServiceContainer::importWiring	(	ServiceContainer	$container,
			$skip = [] )

Imports all wiring defined in $container.

Wiring defined in $container will override any wiring already defined locally. However, already existing service instances will be preserved.

Since: 1.28

Parameters

ServiceContainer	$container
string[]	$skip	A list of service names to skip during import

Definition at line 163 of file ServiceContainer.php.

◆ isServiceDisabled()

Wikimedia\Services\ServiceContainer::isServiceDisabled ( $name )

Parameters

string $name

Returns: bool Whether the service is disabled

Since: 1.28

Definition at line 492 of file ServiceContainer.php.

◆ loadWiringFiles()

Wikimedia\Services\ServiceContainer::loadWiringFiles ( array $wiringFiles )

Parameters

array $wiringFiles A list of PHP files to load wiring information from. Each file is loaded using PHP's include mechanism. Each file is expected to return an associative array that maps service names to instantiator functions.

Definition at line 125 of file ServiceContainer.php.

References $file, and Wikimedia\Services\ServiceContainer\applyWiring().

◆ peekService()

Wikimedia\Services\ServiceContainer::peekService ( $name )

Returns the service instance for $name only if that service has already been instantiated.

This is intended for situations where services get destroyed/cleaned up, so we can avoid creating a service just to destroy it again.

Note: This is intended for internal use and for test fixtures. Application logic should use getService() instead.

See also: getService().

Parameters

string $name

Returns: object|null The service instance, or null if the service has not yet been instantiated.

Exceptions

RuntimeException if $name does not refer to a known service.

Definition at line 223 of file ServiceContainer.php.

References Wikimedia\Services\ServiceContainer\hasService().

Referenced by Wikimedia\Services\ServiceContainer\destroy(), and Wikimedia\Services\ServiceContainer\resetService().

◆ redefineService()

Wikimedia\Services\ServiceContainer::redefineService	(		$name,
		callable	$instantiator )

Replace an already defined service.

See also: defineService().

Note: This will fail if the service was already instantiated. If the service was previously disabled, it will be re-enabled by this call. Any manipulators registered for the service will remain in place.

Parameters

string	$name	The name of the service to register.
callable	$instantiator	Callback function that returns a service instance. Will be called with this ServiceContainer instance as the only parameter. The instantiator must return a service compatible with the originally defined service. Any extra instantiation parameters provided to the constructor will be passed as subsequent parameters when invoking the instantiator.

Exceptions

NoSuchServiceException	if $name is not a known service.
CannotReplaceActiveServiceException	if the service was already instantiated.

Definition at line 281 of file ServiceContainer.php.

References Wikimedia\Services\ServiceContainer\hasService().

◆ resetService()

Wikimedia\Services\ServiceContainer::resetService	(		$name,
			$destroy = true )

finalprotected

Resets a service by dropping the service instance.

If the service instances implements DestructibleService, destroy() is called on the service instance.

Warning: This is generally unsafe! Other services may still retain references to the stale service instance, leading to failures and inconsistencies. Subclasses may use this method to reset specific services under specific instances, but it should not be exposed to application logic.

Note: This is declared final so subclasses can not interfere with the expectations disableService() has when calling resetService().

See also: redefineService(); disableService().

Parameters

string	$name	The name of the service to reset.
bool	$destroy	Whether the service instance should be destroyed if it exists. When set to false, any existing service instance will effectively be detached from the container.

Exceptions

RuntimeException if $name is not a known service.

Definition at line 384 of file ServiceContainer.php.

References Wikimedia\Services\ServiceContainer\peekService().

Referenced by Wikimedia\Services\ServiceContainer\disableService().

Member Data Documentation

◆ $destroyed

bool Wikimedia\Services\ServiceContainer::$destroyed = false

private

Definition at line 79 of file ServiceContainer.php.

◆ $disabled

bool [] Wikimedia\Services\ServiceContainer::$disabled = []

private

disabled status, per service name

Definition at line 69 of file ServiceContainer.php.

◆ $extraInstantiationParams

array Wikimedia\Services\ServiceContainer::$extraInstantiationParams

private

Definition at line 74 of file ServiceContainer.php.

Referenced by Wikimedia\Services\ServiceContainer\__construct().

◆ $serviceInstantiators

callable [] Wikimedia\Services\ServiceContainer::$serviceInstantiators = []

private

Definition at line 59 of file ServiceContainer.php.

Referenced by Wikimedia\Services\ServiceContainer\applyWiring().

◆ $serviceManipulators

callable [][] Wikimedia\Services\ServiceContainer::$serviceManipulators = []

private

Definition at line 64 of file ServiceContainer.php.

◆ $services

object [] Wikimedia\Services\ServiceContainer::$services = []

private

Definition at line 54 of file ServiceContainer.php.

◆ $servicesBeingCreated

array Wikimedia\Services\ServiceContainer::$servicesBeingCreated = []

private

Set of services currently being created, to detect loops.

Definition at line 84 of file ServiceContainer.php.

The documentation for this class was generated from the following file:

includes/libs/services/ServiceContainer.php

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ addServiceManipulator()

◆ applyWiring()

◆ createService()

◆ defineService()

◆ destroy()

◆ disableService()

◆ get()

◆ getService()

◆ getServiceNames()

◆ has()

◆ hasService()

◆ importWiring()

◆ isServiceDisabled()

◆ loadWiringFiles()

◆ peekService()

◆ redefineService()

◆ resetService()

Member Data Documentation

◆ $destroyed

◆ $disabled

◆ $extraInstantiationParams

◆ $serviceInstantiators

◆ $serviceManipulators

◆ $services

◆ $servicesBeingCreated