|This page is under construction|
Please help review and edit this page.
This page describes the use of the Dependency Injection (DI) facility provided by the MediaWikiServices class.
- 1 Quick Start
- 2 Concepts and Best Practices
- 3 Glossary
- 4 The MediaWikiServices class
- 5 Registering Services
- 6 Using Dependency Injection in Hook Handlers
- 7 Mocking Services for Testing
- 8 References
This section provides a quick start to those who are already familiar with DI.
- To acquire a reference to the service container, use
MediaWikiServices::getInstance(). This should only be done in bootstrap code and static entry points. Accessing the service container say in application logic (as per the Service Locator pattern) or passing the service container as a parameter or keeping a reference to the service container in a member variable (as per the Context Object pattern) is strongly discouraged.
- To acquire an instance of a well known service, use a dedicated getter on the service container object, e.g.
- To acquire an instance of a custom service defined by an extension, use the generic
getService( $name )method. Extensions may provide static convenience functions of the form
MyExtensionServices::getFooService()implemented to return
MediaWikiServices::getInstance()->getService( 'MyExtensionFoo' );
- To temporarily override a service for testing, use the
setService( $name, $service )method of
- To add a new well known service to MediaWiki core:
- add an instantiator callback to
includes/ServiceWiring.phpthat returns a new instance of the desired service class.
- add a getter to MediaWikiServices that corresponds to the service name used in the wiring file. The getter should be implemented trivially implemented to return
$this->getService( 'SomeServiceName' ).
- add the new service name and expected class to the list in
MediaWikiServicesTest::provideGetService. Note that the expected class name should refer to the service interface, not the concrete service implementation.
- add an instantiator callback to
- To register a custom service using the MediaWikiServices hook:
- Register a hander for the MediaWikiServices hook. The handler function should expect a MediaWikiServices object as the only parameter. To avoid name conflicts, the service name should be prefixed with the extension's name.
- In the handler function, call
defineService(), providing an instantiator callback for the custom service which returns a new instance of the desired service class.
- To register a custom service via the ServiceWiringFiles registry:
- Create a wiring file, e.g.
src/ServiceWiring.php, in the extension directory. The wiring file should consist of a single return statement, returning an associative array that maps service names to instantiator functions. To avoid name conflicts, the service names should be prefixed with the extension's name.
- Register the wiring file in the ServiceWiringFiles section of the extension.json file, or add it to
$wgServiceWiringFilesin the extension's bootstrap code.
- Create a wiring file, e.g.
- To re-use the same service instance for multiple service names:
- register the instantiator for the implementation under an "internal" service name (by convention, use a name starting with an underscore "_")
- for each name the service should be available under, register an pseudo-instantiator that just calls
getService()with the internal service name.
Concepts and Best Practices
Best practices for using Dependency Injection in MediaWiki:
- When a service (or application logic) needs access to another service, it asks for it in the constructor. This is the actual injection of dependencies.
- Objects that need access to services can only be constructed via factories (not directly using the
- Services are constructed by other services (factories and registries being special types of service). At the top of this chain of registries/factories there is the application-scope service container which acts as the top-level service registry.
- Access to global default instances ("singletons") should be restricted to static entry points (e.g. hook handlers and callbacks in bootstrap code). Ideally, there is only one such global default instance, namely the service container.
- Injecting/passing around factories, registries, and especially "kitchen sinks" like
RequestContextshould be avoided. The service container should never be passed as a parameter.
- Mutable global state should especially be avoided.
- Services should be represented by narrow interfaces.
- Registries use instantiator functions to instantiate services.
- Bootstrap code should avoid instantiating services, but define instantiator function instead.
These principles effectively promote dependency injection, without binding to a particular DI framework. In fact, it allows DI to be implemented entirely "on foot", without any configurable DI container - instantiation and decisions regarding the life cycle of service objects (lazy initialization, etc) can be left to plain old PHP code.
TBD: DI vs Service Locator
TBD: DI vs Container injection (context objects)
Static entry points
A static entry point is code in a static context (directly in global scope, or in a global function, or in a static method) that gets called by a framework (e.g. the PHP runtime, or MediaWiki's Hooks mechanism). In MediaWiki, typical static entry points are:
- Global scope code in web entry points like
- Global scope code in maintenance scripts.
- Bootstrap code in old-style extension entry points
- (Static) hook handler functions
- Instantiator functions in wiring files
The application-scope service container is the top-level registry for the services that the application's logic needs to operate. Extensions can define their own service containers (which may depend on MediaWiki's service container).
Access to the service container should be restricted to static entry points. Direct access to the global service container instance from application logic following the service locator pattern is discouraged. See Assembly comparison for a discussion of service locator vs. DI container logic.
Bootstrap code refers to code that is executed at the beginning of every request. Bootstrap code creates the initial scaffolding for initializing the application by loading configuration and instantiating the most basic services. In MediaWiki, bootstrap code is typically:
- global scope code in a web entry point (or maintenance script).
- extension entry points (see #Registry bootstrap)
A factory is a service that instantiates objects. These objects can be services, or data objects. Factory methods that are guaranteed to create a new instance should have names starting with "new". Other factory methods should have names starting with "get", and may or may not return singletons.
Factories are used to inject the ability to instantiate certain kinds of objects. They can be understood as partial applications of constructors. Factory methods typically, but not necessarily, take parameters.
A "factory" in the more narrow sense would typically have only one factory method, and create only one kind of object.
Registries are factories for services. Factory methods in a registry typically do not take any parameters. Registries can be used to
- provide access to instances of a variety of services, e.g. various storage level services.
- provide access to specialized instances of a single service interface implemented for different "targets", e.g. different MediaHandler instances for each type of media.
- provide lazy instantiation of services, to avoid overhead at startup time.
A registry may be implemented by hardcoding the logic for instantiating the services (typical especially for the top-level registry), or by bootstrap code defining instatiator functions (aka factory functions). See the #Registry bootstrap example. Note that registering class names should be avoided, since that prevents injection of services via constructor arguments (because the constructor's signature is prescribed by the registry).
A instantiator function (or factory callback) is a callable that returns a new instance of some class.
The MediaWikiServices class
Using Dependency Injection in Hook Handlers
Mocking Services for Testing