Containers / Dependency Injection

Introduction

Modern software applications are composed of various components that need to interact with one another. Traditionally, objects create their own dependencies internally, which leads to tight coupling and makes code harder to test, maintain, and extend. Dependency injection (DI) is a software design pattern that helps solve this problem by having dependencies provided from the outside, rather than being constructed inside the object itself.

Dependency injection may sound like a big concept, but it’s really just about making your code easier to work with and more flexible. Instead of each part of your app creating the things it needs by itself, those “dependencies” are handed to it – usually by a special helper called a container. This means your classes don’t need to know how to create their collaborators; they just need to know how to use them.

The App Framework in Nextcloud assembles applications using a container based on this design pattern. This approach leads to more modular, testable, and maintainable code.

Using dependency injection is about more than just elegant code. When all apps follow this pattern:

  • It’s easier to test and upgrade both apps and the server, since dependencies can be swapped out or mocked.

  • Apps stay decoupled from internal server details, making it safer for Nextcloud to evolve without breaking your app.

  • Core features like autowiring, service discovery, and new APIs become available to all apps without extra boilerplate.

  • Memory and resource usage can be reduced.

  • New services or APIs become easier to adopt as Nextcloud evolves.

By sharing a consistent approach to building and wiring up dependencies, everyone – core and app developers alike – benefits from a more robust, secure, and future-proof platform.

If you are unfamiliar with the DI design pattern, don’t worry – it’s widely used in modern frameworks, and you’ll soon become comfortable with it. You can also watch the following video introduction:

Basic Pattern of Dependency Injection

The essence of dependency injection is: don’t instantiate dependencies directly inside your classes or methods, but instead pass them in as parameters. This allows swapping out dependencies (such as with mocks in unit tests), makes dependencies explicit, and centralizes object creation logic.

For example, consider the following pattern:

/**
 * Without dependency injection:
 */

use OCP\IDBConnection;

class AuthorMapper {

  // Define a property to store the dependency
  private IDBConnection $db;

  public function __construct() {
    // The dependency is instantiated within the class
    $this->db = new Db();
  }
}

With dependency injection, you would instead request the dependency as part of the constructor parameters:

/**
 * Using dependency injection:
 */

use OCP\IDBConnection;

class AuthorMapper {

  // Define a property to store the dependency
  private IDBConnection $db;

  // The dependency is passed in from outside (typically by the container)
  public function __construct(IDBConnection $db) {
    // Assigned to the property
    $this->db = $db;
  }
}

Or, more succinctly, by using constructor property promotion (available in current PHP versions). The following is exactly equivalent:

/**
 * Using dependency injection with constructor property promotion:
 */

use OCP\IDBConnection;

class AuthorMapper {

  /**
   * Constructor property promotion with DI reduces boilerplate code by
   * handling everything within the constructor parameters. The example below
   * does exactly the same thing as the prior example, but in less code:
   *
   * - The dependency is passed in from outside (by the container)
   * - The private property is established to store the dependency
   * - The dependency is assigned directly to that property
   */
  public function __construct(private IDBConnection $db) {
  }
}

Advantages

  • Testability: You can inject mock objects for unit testing.

  • Maintainability: Changing how a dependency is constructed (in the container) updates it wherever it is injected in the application.

  • Explicitness: Dependencies are clearly listed in constructors or method signatures, improving readability and maintainability.

Controller Injection

For controllers, Nextcloud allows dependencies to also be injected directly into individual methods, not just constructors. This is referred to as method injection and enables you to specify dependencies only where needed, potentially reducing resource usage for rarely required services.

lib/Controller/ApiController.php
<?php

namespace OCA\MyApp\Controller;

use OCA\MyApp\Service\BarService;
use OCA\MyApp\Service\FooService;
use OCP\AppFramework\Controller;
use OCP\IRequest;

class ApiController extends Controller {
    public function __construct(string $appName, IRequest $request) {
        parent::__construct($appName, $request);
    }

    public function foo(FooService $service) {
        $service->foo();
    }

    public function bar(BarService $service) {
        $service->bar();
    }
}

Using a container

Note

Please do use automatic dependency injection (see below). For most apps there is no need to register services manually.

Passing dependencies into the constructor rather than instantiating them in the constructor has the following drawback: Every line in the source code where new AuthorMapper is being used has to be changed, once a new constructor argument is being added to it.

The solution for this particular problem is to limit the new AuthorMapper to one file, the container. The container contains all the factories for creating these objects and is configured in lib/AppInfo/Application.php.

Nextcloud 20 and later uses the PSR-11 standard for the container interface, so working with the container might feel familiar if you’ve worked with other php applications before that also adhere to the convention.

To add the app’s classes simply open the lib/AppInfo/Application.php and use the IRegistrationContext::registerService method:

<?php

namespace OCA\MyApp\AppInfo;

use OCP\AppFramework\App;
use OCP\AppFramework\Bootstrap\IBootstrap;
use OCP\AppFramework\Bootstrap\IBootContext;
use OCP\AppFramework\Bootstrap\IRegistrationContext;
use OCP\IDBConnection;
use OCP\IRequest;
use OCA\MyApp\Controller\AuthorController;
use OCA\MyApp\Service\AuthorService;
use OCA\MyApp\Db\AuthorMapper;
use Psr\Container\ContainerInterface;

class Application extends App implements IBootstrap {

  public function __construct(array $urlParams = []){
    parent::__construct('myapp', $urlParams);
  }

  public boot(IBootContext $context): void {
    // ...
  }

  /**
   * Define your dependencies in here
   */
  public function register(IRegistrationContext $context): void {
    /**
     * Controllers
     */
    $context->registerService(AuthorController::class, function(ContainerInterface $c): AuthorController {
      return new AuthorController(
        $c->get('appName'),
        $c->get(IRequest::class),
        $c->get(AuthorService::class)
      );
    });

    /**
     * Services
     */
    $context->registerService(AuthorService::class, function(ContainerInterface $c): AuthorService {
      return new AuthorService(
        $c->get(AuthorMapper::class)
      );
    });

    /**
     * Mappers
     */
    $context->registerService(AuthorMapper::class, function(ContainerInterface $c): AuthorMapper {
      return new AuthorMapper(
        $c->get(IDBConnection::class)
      );
    });
  }
}

How the container works

The container works in the following way:

  • A request comes in and is matched against a route (for the AuthorController in this case)

  • The matched route queries AuthorController service from the container:

    return new AuthorController(
  $c->get('appName'),
  $c->get(IRequest::class),
  $c->get(AuthorService::class)
);

  • The appName is queried and returned from the base class

  • The Request is queried and returned from the server container

  • AuthorService is queried. This triggers the registered Callable:

    $container->registerService(AuthorService::class, function(ContainerInterface $c): AuthorService {
  return new AuthorService(
    $c->get(AuthorMapper::class)
  );
});

  • AuthorMapper is queried:

    $container->registerService(AuthorMapper::class, function(ContainerInterface $c): AuthorMapper {
  return new AuthorMapper(
    $c->get(IDBConnection::class)
  );
});

  • The database connection is returned from the server container

  • Now AuthorMapper has all of its dependencies and can be constructed by the DI code. The object is returned.

  • AuthorService gets the AuthorMapper, is constructed, and returns the object

  • AuthorController gets the AuthorService and finally the controller can be instantiated and the object is returned

So basically the container is used as a giant factory to build all the classes that are needed for the application. Because it centralizes all the creation of objects (the new Class() lines), it is very easy to add new constructor parameters without breaking existing code: only the __construct method and the container line where the new is being called need to be changed.

Which classes should be added

In general all of the app’s controllers need to be registered inside the container. Then the following question is: What goes into the constructor of the controller? Pass everything into the controller constructor that matches one of the following criteria:

  • It does I/O (database, write/read to files)

  • It is a global (e.g. $_POST, etc. This is in the request class by the way)

  • The output does not depend on the input variables (also called impure function), e.g. time, random number generator

  • It is a service, basically it would make sense to swap it out for a different object

What not to inject:

  • It is pure data and has methods that only act upon it (arrays, data objects)

  • It is a pure function

Optional services

Added in version 28.

If an injected dependency can’t be found or build, an exception is thrown. This can be avoided by using the a nullable type notation for a dependency:

namespace OCA\MyApp\MyService;

use Some\Service;

class MyService {
  public function __construct(private ?Service $service) {
  }
}

If \Some\Service exists and can be built, it will be injected. Else MyService will receive null.

Accessing the container from anywhere

Sometimes it can be hard to inject some service inside legacy code, in these cases you can use OCPServer::get(MyService::class). This should only be used as the last resort, as this makes your code more complicated to unit test and is considered an anti-pattern.