MediaWiki  REL1_31
MediaWiki\Services\ServiceContainer Class Reference

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

Inheritance diagram for MediaWiki\Services\ServiceContainer:
Collaboration diagram for MediaWiki\Services\ServiceContainer:

Public Member Functions

 __construct (array $extraInstantiationParams=[])
 
 applyWiring (array $serviceInstantiators)
 Registers multiple services (aka a "wiring"). More...
 
 defineService ( $name, callable $instantiator)
 Define a new service. More...
 
 destroy ()
 Destroys all contained service instances that implement the DestructibleService interface. More...
 
 disableService ( $name)
 Disables a service. More...
 
 getService ( $name)
 Returns a service object of the kind associated with $name. More...
 
 getServiceNames ()
 
 hasService ( $name)
 Returns true if a service is defined for $name, that is, if a call to getService( $name ) would return a service instance. More...
 
 importWiring (ServiceContainer $container, $skip=[])
 Imports all wiring defined in $container. More...
 
 isServiceDisabled ( $name)
 
 loadWiringFiles (array $wiringFiles)
 
 peekService ( $name)
 Returns the service instance for $name only if that service has already been instantiated. More...
 
 redefineService ( $name, callable $instantiator)
 Replace an already defined service. More...
 

Protected Member Functions

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

Private Member Functions

 createService ( $name)
 

Private Attributes

bool $destroyed = false
 
bool[] $disabled = []
 disabled status, per service name More...
 
array $extraInstantiationParams
 
callable[] $serviceInstantiators = []
 
object[] $services = []
 

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 46 of file ServiceContainer.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\Services\ServiceContainer::__construct ( array  $extraInstantiationParams = [])
Parameters
array$extraInstantiationParamsAny 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 78 of file ServiceContainer.php.

References MediaWiki\Services\ServiceContainer\$extraInstantiationParams.

Member Function Documentation

◆ applyWiring()

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

Registers multiple services (aka a "wiring").

Parameters
array$serviceInstantiatorsAn associative array mapping service names to instantiator functions.

Definition at line 126 of file ServiceContainer.php.

References $name, MediaWiki\Services\ServiceContainer\$serviceInstantiators, as, and MediaWiki\Services\ServiceContainer\defineService().

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

◆ createService()

MediaWiki\Services\ServiceContainer::createService (   $name)
private
Parameters
string$name
Exceptions
InvalidArgumentExceptionif $name is not a known service.
Returns
object

Definition at line 356 of file ServiceContainer.php.

References $name.

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

◆ defineService()

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

Define a new service.

The service must not be known already.

See also
getService().
replaceService().
Parameters
string$nameThe name of the service to register, for use with getService().
callable$instantiatorCallback that returns a service instance. Will be called with this MediaWikiServices instance as the only parameter. Any extra instantiation parameters provided to the constructor will be passed as subsequent parameters when invoking the instantiator.
Exceptions
RuntimeExceptionif there is already a service registered as $name.

Definition at line 212 of file ServiceContainer.php.

References $name, and MediaWiki\Services\ServiceContainer\hasService().

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

◆ destroy()

MediaWiki\Services\ServiceContainer::destroy ( )

Destroys all contained service instances that implement the DestructibleService interface.

This will render all services obtained from this MediaWikiServices 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 MediaWiki\Services\DestructibleService.

Definition at line 90 of file ServiceContainer.php.

References $name, as, MediaWiki\Services\ServiceContainer\getServiceNames(), and MediaWiki\Services\ServiceContainer\peekService().

◆ disableService()

MediaWiki\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$nameThe name of the service to disable.
Exceptions
RuntimeExceptionif $name is not a known service.

Definition at line 272 of file ServiceContainer.php.

References $name, and MediaWiki\Services\ServiceContainer\resetService().

◆ getService()

MediaWiki\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$nameThe service name
Exceptions
NoSuchServiceExceptionif $name is not a known service.
ContainerDisabledExceptionif this container has already been destroyed.
ServiceDisabledExceptionif the requested service has been disabled.
Returns
object The service instance

Definition at line 334 of file ServiceContainer.php.

References $name, and MediaWiki\Services\ServiceContainer\createService().

◆ getServiceNames()

MediaWiki\Services\ServiceContainer::getServiceNames ( )
Returns
string[]

Definition at line 194 of file ServiceContainer.php.

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

◆ hasService()

MediaWiki\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 164 of file ServiceContainer.php.

References $name.

Referenced by MediaWiki\Services\ServiceContainer\defineService(), MediaWiki\Services\ServiceContainer\peekService(), and MediaWiki\Services\ServiceContainer\redefineService().

◆ importWiring()

MediaWiki\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[]$skipA list of service names to skip during import

Definition at line 144 of file ServiceContainer.php.

◆ isServiceDisabled()

MediaWiki\Services\ServiceContainer::isServiceDisabled (   $name)
Parameters
string$name
Returns
bool Whether the service is disabled
Since
1.28

Definition at line 375 of file ServiceContainer.php.

References $name.

◆ loadWiringFiles()

MediaWiki\Services\ServiceContainer::loadWiringFiles ( array  $wiringFiles)
Parameters
array$wiringFilesA 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 106 of file ServiceContainer.php.

References MediaWiki\Services\ServiceContainer\applyWiring(), and as.

◆ peekService()

MediaWiki\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
RuntimeExceptionif $name does not refer to a known service.

Definition at line 183 of file ServiceContainer.php.

References $name, and MediaWiki\Services\ServiceContainer\hasService().

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

◆ redefineService()

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

Replace an already defined service.

See also
defineService().
Note
This causes any previously instantiated instance of the service to be discarded.
Parameters
string$nameThe name of the service to register.
callable$instantiatorCallback function that returns a service instance. Will be called with this MediaWikiServices 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
RuntimeExceptionif $name is not a known service.

Definition at line 238 of file ServiceContainer.php.

References $name, and MediaWiki\Services\ServiceContainer\hasService().

Referenced by MediaWikiTestCase\installTestServices().

◆ resetService()

MediaWiki\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$nameThe name of the service to reset.
bool$destroyWhether 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
RuntimeExceptionif $name is not a known service.

Definition at line 301 of file ServiceContainer.php.

References $name, and MediaWiki\Services\ServiceContainer\peekService().

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

Member Data Documentation

◆ $destroyed

bool MediaWiki\Services\ServiceContainer::$destroyed = false
private

Definition at line 71 of file ServiceContainer.php.

◆ $disabled

bool [] MediaWiki\Services\ServiceContainer::$disabled = []
private

disabled status, per service name

Definition at line 61 of file ServiceContainer.php.

◆ $extraInstantiationParams

array MediaWiki\Services\ServiceContainer::$extraInstantiationParams
private

◆ $serviceInstantiators

callable [] MediaWiki\Services\ServiceContainer::$serviceInstantiators = []
private

◆ $services

object [] MediaWiki\Services\ServiceContainer::$services = []
private

Definition at line 51 of file ServiceContainer.php.


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