Dependency Injection Container

MODX 3 introduces a Dependency Injection Container, based on Pimple 3, that holds core services and custom services.

$modx->getService() still works but is deprecated. Register new services with add() (and read them with get()) here instead of getService(). See modX.getService.

The container (MODX\Revolution\Services\Container, a PSR-11 Pimple 3 container) lives in modX::$services, so you reach it as:

• $modx->services (in snippets, plugins, etc)
• $this->modx->services (in controllers, processors, etc)
• $this->xpdo->services (in model classes)

Available Services¶

The core registers these services by default:

Psr\Http\Client\ClientInterface is registered with factory() — a fresh client per get(), not a shared instance. The container throws MODX\Revolution\Services\ContainerException / NotFoundException; catch them via the PSR-11 interfaces (ContainerExceptionInterface, NotFoundExceptionInterface).

Loading Services¶

Fetch a service by its ID with get(); use has() to check first:

try {
    $config = $modx->services->get('config');
}
catch (ContainerExceptionInterface $e) {
    // handle a missing or broken service
}

To check registration first:

$service = null;
try {
    if ($modx->services->has('custom_service')) {
        $service = $modx->services->get('custom_service');
    }
}
catch (ContainerExceptionInterface $e) {
    // handle a missing or broken service
}

A service that exists (has() returns true) can still throw when get() is called on it.

Injecting Services¶

Register or override services from your Extra’s namespace bootstrap.php; it runs as early in the initialization process as possible.

Caveat: bootstrap.php runs before some services are registered. registry, lexicon and modManagerDateFormatter are (re)registered unconditionally after bootstrap — an override of those IDs will be overwritten (or throw Pimple’s FrozenError if the service was already resolved). For the remaining services (error, parser, errorHandler, the PSR-17 factories, session_handler) core registration is guarded with has(), so your bootstrap override sticks.

Register a service with add():

$modx->services->add('my_service', function($c) use ($modx) {
    return new MyPackage\MyService($modx);
});

Pull dependencies from the container instead of hard-wiring them:

$modx->services->add('my_service', function($c) use ($modx) {
    return new MyPackage\MyService($c['parser'], $c['config']);
});

For a fresh instance on every get(), use factory():

$modx->services['my_service'] = $modx->services->factory(function($c) use ($modx) {
    return new MyPackage\MyService($modx);
});

To wrap an already registered service, use extend():

$modx->services->extend('existing_service', function($existing, $c) use ($modx) {
    $existing->...();
    return $existing;
});

See the Pimple documentation for more information.