Dependency injection

Constructor injection

Lets say we're writing a controller that renders a list of users. Those users are found using a UserRepository service, making the user repository service a direct dependency of the controller service. A typical constructor dependency injection to resolve the dependency by the framework looks like this:

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use MyVendor\MyExtension\Repository\UserRepository;

final class UserController
{
    public function __construct(
        private readonly UserRepository $userRepository,
    ) {}
}

The symfony container setup process will now see UserRepository as a dependency of UserController when scanning its __construct() method. Since autowiring is enabled by default (more on that below), an instance of the UserRepository is created and provided to __construct() when the controller is created. The instance is set as a class property using constructor property promotion and the property is declared readonly.

Method injection

A second way to get services injected is by using inject*() methods:

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use MyVendor\MyExtension\Repository\UserRepository;

final class UserController
{
    private ?UserRepository $userRepository = null;

    public function injectUserRepository(UserRepository $userRepository)
    {
        $this->userRepository = $userRepository;
    }
}

This ends up with basically the same result as above: The controller instance retrieves an object of type UserRepository in class property $userRepository. The service container calls such inject*() methods directly after class instantiation, so after __construct() has been executed, and before anything else. The injection via methods was introduced by Extbase. TYPO3 core implemented it in addition to the default Symfony constructor injection. Why did we do that, you may ask? Both strategies have subtle differences: First, when using inject*() methods, the type hinted class property needs to be nullable, otherwise PHP >= 7.4 throws a warning since the instance is not set during __construct(). But that's just an implementation detail. More important is an abstraction scenario. Consider this case:

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use MyVendor\MyExtension\Logger\Logger;
use MyVendor\MyExtension\Repository\UserRepository;

abstract class AbstractController
{
    protected ?Logger $logger = null;

    public function injectLogger(Logger $logger)
    {
        $this->logger = $logger;
    }
}

final class UserController extends AbstractController
{
    public function __construct(
        private readonly UserRepository $userRepository,
    ) {}
}

We have an abstract controller service with a dependency plus a controller service that extends the abstract and has further dependencies.

Now assume the abstract class is provided by TYPO3 core and the consuming class is provided by an extension. If the abstract class would use constructor injection, the consuming class would need to know the dependencies of the abstract, add its own dependencies to the constructor, and then call parent::__construct($logger) to satisfy the abstracts dependency. This would hardcode all dependencies of the abstract into extending classes. If later the abstract is changed and another dependency is added to the constructor, this would break consuming classes.

Differently put: When core classes "pollute" __construct() with dependencies, the core can not add dependencies without being breaking. This is the reason why for example the extbase AbstractController uses inject*() methods for its dependencies: Extending classes can then use constructor injection, do not need to call parent::__construct(), and the core is free to change dependencies of the abstract.

In general, when the core provides abstract classes that are expected to be extended by extensions, the abstract class should use inject*() methods instead of constructor injection. Extensions of course can follow this idea in similar scenarios.

This construct has some further implications: Abstract classes should think about making their dependency properties private, so extending classes can not rely on them. Furthermore, classes that should not be extended by extensions are free to use constructor injection and should be marked final, making sure they can't be extended to allow internal changes.

Interface injection

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use MyVendor\MyExtension\Logger\LoggerInterface;

final class UserController extends AbstractController
{
    public function __construct(
        private readonly LoggerInterface $logger,
    ) {}
}

Notice the difference? The code requests the injection of an interface and not a class! This is permissible with both constructor and method injection. It compels the service container to determine which specific class is configured as the implementation of the interface and inject an instance of that class. A class can declare itself as the default implementation of such an interface. This is the essence of dependency injection: a consuming class no longer relies on a specific implementation but on an interface's signature.

The framework ensures that something fulfilling the interface is injected. The consuming class remains unaware of the specific implementation, focusing solely on the interface methods. An instance administrator can configure the framework to inject a different implementation, either globally or for specific classes. The consumer remains unconcerned, interacting only with the interface methods.

The example below has a couple of controller classes as service consumers. There is a service interface with a default implementation. The default implementation uses the symfony PHP attribute AsAlias to register itself as default. A Services.yaml file configures different service implementation for some service consumers:

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use MyVendor\MyExtension\Service\MyServiceInterface;

class MyFirstController
{
    public function __construct(
        private readonly MyServiceInterface $myService,
    ) {}
}

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use MyVendor\MyExtension\Service\MyServiceInterface;

class MySecondController
{
    public function __construct(
        private readonly MyServiceInterface $myService,
    ) {}
}

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use MyVendor\MyExtension\Service\MyServiceInterface;

class MyThirdController
{
    private MyServiceInterface $myService;

    public function injectMyService(MyServiceInterface $myService): void
    {
        $this->myService = $myService;
    }
}

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Service;

interface MyServiceInterface
{
    public function foo();
}

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Service;

use Symfony\Component\DependencyInjection\Attribute\AsAlias;

#[AsAlias(MyServiceInterface::class)]
class MyDefaultServiceImplementation implements MyServiceInterface
{
    public function foo()
    {
        // do something
    }
}

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Service;

class MyOtherServiceImplementation implements MyServiceInterface
{
    public function foo()
    {
        // do something
    }
}

services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: false

  # Within MySecondController and MyThirdController different implementations
  # than the default MyDefaultServiceImplementation of MyServiceInterface
  # shall be injected.

  # When working with constructor injection
  MyVendor\MyExtension\Controller\MySecondController:
    arguments:
      $service: '@MyVendor\MyExtension\Service\MyOtherServiceImplementation'

  # When working with method injection
  MyVendor\MyExtension\Controller\MyThirdController:
    calls:
      - method: 'injectMyService'
        arguments:
          $service: '@MyVendor\MyExtension\Service\MyOtherServiceImplementation'

Services.yaml declaring service defaults

Extensions have to configure their classes to make use of dependency injection. This can be done in Configuration/Services.yaml. Alternatively, Configuration/Services.php can also be used, if PHP syntax is required to apply conditional logic to definitions. A basic Services.yaml file of an extension looks like the following.

services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: false

  MyVendor\MyExtension\:
    resource: '../Classes/*'
    exclude: '../Classes/Domain/Model/*'

autowire

autowire: true instructs the dependency injection component to calculate the required dependencies from type declarations. The calculation generates service initialization code.

An extension is not required to use autowiring. It can manually wire dependencies. However, opting out of autowiring is less convenient and is not further documented in this guide.

autoconfigure

This directive instructs the dependency injection component to automatically add Symfony service tags based on implemented interfaces and base classes. For instance, autoconfiguration ensures that classes implementing SingletonInterface are publicly available from the Symfony container and marked as shared ( shared: true).

TYPO3 dependency injection relies on this this for various default configurations. It is recommended to set autoconfigure: true.

public

public: false is a performance optimization and should therefore be set in extensions. This settings controls which services are available through the dependency injection container used internally by GeneralUtility::makeInstance(). See "What to make public?" for more information.

Model exclusion

The path exclusion exclude: '../Classes/Domain/Model/*' excludes your models from the dependency injection container: You cannot inject them nor inject dependencies into them. Models are not services but data objects and therefore should not require dependency injection. Also, these objects are usually created by the Extbase persistence layer, which does not support the DI container.

Autoconfiguration using attributes and Services.yaml

Single service classes may need to change auto configuration to be different than above declared defaults. This can be done using PHP attributes. The most common use case is public: true:

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Service;

use Symfony\Component\DependencyInjection\Attribute\Autoconfigure;

/**
 * This service is instantiated using GeneralUtility::makeInstance()
 * in some cases, which requires 'public' being set to 'true'.
 */
#[Autoconfigure(public: true)]
readonly class MyServiceUsingAutoconfigurePublicTrue
{
    public function __construct(
        private SomeDependency $someDependency,
    ) {}
}

The above usage of the Autoconfigure attribute declares this service as public: true which overrides a public: false default from a Services.yaml file for this specific class.

Similar with shared: false:

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Service;

use Symfony\Component\DependencyInjection\Attribute\Autoconfigure;

/**
 * This service is stateful and configures the service container to
 * inject new instances to consuming services when they are instantiated.
 */
#[Autoconfigure(shared: false)]
class MyServiceUsingAutoconfigureSharedFalse
{
    private string $foo = 'foo';

    public function __construct(
        private readonly SomeDependency $someDependency,
    ) {}

    public function setFoo(): void
    {
        $this->foo = 'bar';
    }
}

It is possible to set both using #[Autoconfigure(public: true, shared: false)].

The Autoconfigure attribute is beneficial when an extension includes a service class that is either stateful or instantiated using GeneralUtility::makeInstance(). This attribute embeds the configuration directly within the class file, eliminating the need for additional entries in Services.yaml - the configuration is "in place".

To reconfigure "foreign" services - those not provided by the extension itself but by another extension (such as a service class from ext:core) - the Services.yaml file can be utilized. A common scenario is when a core service is not declared public because all core extensions retrieve instances via constructor or method injection, rather than GeneralUtility::makeInstance(). If an extension must use GeneralUtility::makeInstance() for a specific reason, it can declare the "foreign" service as "public" in Services.yaml:

services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: false

  MyVendor\MyExtension\:
    resource: '../Classes/*'

  # Declare a "foreign" service "public: true" since this extension needs
  # to instantiate the service using GeneralUtility::makeInstance() and
  # the service is configured "public: false" by the extension delivering
  # that service.
  TYPO3\CMS\Core\Some\Service:
    public: true

Autowiring using attributes

Autowiring, particularly the Autowire PHP attribute, is a powerful tool for making dependency injection more convenient and transparent. TYPO3 core includes default configurations that facilitate its use. Let’s explore some examples.

Consider a service performing an expensive operation that caches the result within the TYPO3 runtime cache to avoid repeating the operation within the same request. The runtime cache, being a dependent service, should be injected. A naive approach is to inject the core CacheManager and retrieve the runtime cache instance:

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Service;

use TYPO3\CMS\Core\Cache\CacheManager;
use TYPO3\CMS\Core\Cache\Frontend\FrontendInterface;

class MyServiceUsingCacheManager
{
    private FrontendInterface $runtimeCache;

    public function __construct(
        CacheManager $cacheManager,
    ) {
        $this->runtimeCache = $cacheManager->getCache('runtime');
    }

    public function calculateSomethingExpensive()
    {
        // do something using runtime cache
    }
}

This can be simplified, resulting in more streamlined code:

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Service;

use Symfony\Component\DependencyInjection\Attribute\Autowire;
use TYPO3\CMS\Core\Cache\Frontend\FrontendInterface;

class MyServiceGettingRuntimeCacheInjected
{
    public function __construct(
        #[Autowire(service: 'cache.runtime')]
        private readonly FrontendInterface $runtimeCache,
    ) {}

    public function calculateSomethingExpensive()
    {
        // do something using runtime cache
    }
}

The "cache.runtime" service alias, configured by the TYPO3 core extension, performs the CacheManager->getCache() operation behind the scenes. Utilizing such shortcuts simplifies the consumers.

The autowire attribute also enables the execution of expressions and injection of the results, which is useful for "compile-time" state that remains constant during requests. For example, to inject a feature toggle status:

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Service;

use Symfony\Component\DependencyInjection\Attribute\Autowire;

class MyServiceGettingFeatureToggleResultInjected
{
    public function __construct(
        #[Autowire(expression: 'service("features").isFeatureEnabled("myExtension.foo")')]
        private readonly bool $fooEnabled,
    ) {}
}

Another example, including alias definition, is new in TYPO3 v13. It enables injecting values from ext_conf_templates.txt files using the ExtensionConfiguration API.

<?php

declare(strict_types=1);

namespace TYPO3\CMS\Core\Configuration;

use Symfony\Component\DependencyInjection\Attribute\AsAlias;

#[AsAlias('extension-configuration', public: true)]
class ExtensionConfiguration
{
    public function get(string $extension, string $path = ''): mixed
    {
        // implementation
    }
}

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Service;

use Symfony\Component\DependencyInjection\Attribute\Autowire;

class MyServiceGettingExtensionConfigurationValueInjected
{
    public function __construct(
        #[Autowire(expression: 'service("extension-configuration").get("my_extension", "something.isEnabled")')]
        private readonly bool $somethingIsEnabled,
    ) {}
}

This example demonstrates the combination of a service class with an alias and a consumer utilizing this alias in an Autowire attribute.

The TYPO3 core provides a couple such service aliases, with the above ones being the most important ones for extension developers. TYPO3 core does not arbitrarily add aliases.

Installation-wide configuration

A global service configuration for a project can be set up to be utilized across multiple project-specific extensions. This allows, for example, the aliasing of an interface with a concrete implementation that can be used in several extensions. Additionally, project-specific CLI commands can be registered without the need for a project-specific extension.

However, this is only possible - due to security restrictions - if TYPO3 is configured such that the project root is outside the document root, which is typically the case in Composer-based installations.

In Composer-based installations, the global service configuration files services.yaml and services.php are located within the config/system/ directory of a TYPO3 project.

Consider the following scenario: You want to use the PSR-20 clock interface as a type hint for dependency injection in the service classes of your project's various extensions. This setup allows the concrete implementation to change without altering your code. In this example, we use lcobucci/clock as the concrete implementation.

The global files services.yaml and services.php are read before files from extensions. The global files can provide defaults but can not override service definitions from service configuration files loaded afterwards.

services:

  Psr\Clock\ClockInterface:
    factory: ['Lcobucci\Clock\SystemClock', 'fromUTC']

The concrete clock implementation is now injected when a type hint to the interface is given:

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use Psr\Clock\ClockInterface;

final class MyServiceUsingClockInterface
{
    public function __construct(
        private readonly ClockInterface $clock,
    ) {}

    // ...
}

What to make public?

The basic difference between public and private is well explained in the symfony documentation:

When defining a service, it can be made to be public or private. If a service is public, it means that you can access it directly from the container at runtime. For example, the doctrine service is a public service:

// only public services can be accessed in this way
$doctrine = $container->get('doctrine');

Copied!

But typically, services are accessed using dependency injection. And in this case, those services do not need to be public.

So unless you specifically need to access a service directly from the container via $container->get(), the best-practice is to make your services private.

The implementation of GeneralUtility::makeInstance() utilizes $container->get(). As a result, services instantiated using makeInstance() must be declared public if they have dependencies that need to be injected.

Services without dependencies can be instantiated using makeInstance() without the service made public, as they are instantiated using new without constructor arguments.

Some services are automatically declared public by basic TYPO3 dependency injection configuration since they are instantiated using makeInstance() by the core framework. The most common ones are:

• Extbase controllers implementing ControllerInterface , usually by inheriting ActionController . They are additionally declared shared: false.

• Backend controllers with AsController class attribute. They are additionally declared shared: false:

  use TYPO3\CMS\Backend\Attribute\AsController;
  
  #[AsController]
  final readonly class MyBackendController
  {
      // implementation
  }

  Copied!
• Classes implementing SingletonInterface
• Fluid view helpers implementing \ViewHelperInterface . They are additionally declared shared: false.
• Fluid data processors tagged with data.processor.

Examples of classes that must be made public:

• User functions
• Hooks
• Authentication services

Services that use dependency injection and are not declared public typically error out with typical messages when instantiated using makeInstance() They should be declared public:

(1/1) ArgumentCountError

Too few arguments to function MyVendor\MyExtension\Namespace\Class::__construct(),
0 passed in typo3/sysext/core/Classes/Utility/GeneralUtility.php on line 3461 and exactly 1 expected

(1/1) Error

Call to a member function methodName() on null

How to override service arguments?

Some services in the TYPO3 core use service arguments, which can be overridden by third-party extensions. For example, the $rateLimiterFactory argument in the \ControllerPasswordRecoveryController of the typo3/cms-felogin extension uses a service with the ID feloginPasswordRecovery.rateLimiterFactory. This service is defined in the Services.yaml file of ext:felogin and includes a service argument named $config, which specifies the configuration for the Symfony Rate Limiter used in the class.

A third-party extension can override the feloginPasswordRecovery.rateLimiterFactory service in its own Services.yaml file, as shown in the example below:

feloginPasswordRecovery.rateLimiterFactory:
  class: Symfony\Component\RateLimiter\RateLimiterFactory
  arguments:
    $config:
      id: 'felogin-password-recovery'
      policy: 'sliding_window'
      limit: 10
      interval: '30 minutes'
    $storage: '@storage.cachingFramework'

It is important that the 3rd party extension is loaded after the extension whose service it overrides. This can be achieved by requiring the original extension as a dependency in the packages/my-extension/composer.json file of the 3rd party extension.

What do declare shared: false?

A service declared shared: false is not a singleton. Instead, a new instance is created each time the consuming service is instantiated. This approach makes the consuming service stateful as well, but declaring shared: false can help mitigate side effects between different services. It is often preferable to create stateful services using GeneralUtility::makeInstance() when needed, rather than within __construct().

When to use GeneralUtility::makeInstance()?

Ideally, all services in a framework are stateless: They depend on other stateless services and are always retrieved using dependency injection.

TYPO3 core development is gradually transitioning more services to be stateless. However, many historically stateful services still exist. The critical point is that injecting a stateful service into a stateless service makes the consumer stateful as well. This can create a chain of coupled stateful services, leading to unexpected results when these services are reused multiple times within a single request. While declaring a service shared: false can mitigate the issue, it doesn't solve the underlying problem. This scenario is a primary use case for GeneralUtility::makeInstance(). Instead of injecting a stateful service at service build time and reusing it frequently, the service can use makeInstance() at runtime when it needs a service instance.

For instance, the DataHandler class should create new instances for each use, as it becomes "tainted" after use and cannot reset its state properly. Such "dirty-after-use" services should be instantiated anew with makeInstance() when needed.

Some services are stateful but provide workarounds to be injectable. A good example is the Extbase UriBuilder . It is stateful due to its use of the method chaining pattern but includes a reset() method to reset its state. When used correctly, this service can be injected and reused. Additionally, UriBuilder is declared shared: false, so consumers receive distinct instances, reducing the risk of bugs from improper use of reset().

Various solutions exist to make existing services stateless. For instance, the extbase UriBuilder could deprecate its setX() chaining methods and introduce a UriParameterBag data object, which would be passed to the service worker methods. Implementing such changes in the TYPO3 core codebase is an ongoing process that requires careful consideration.

Deciding whether to use makeInstance() instead of dependency injection requires examining the dependency's behavior. Consider these factors:

• The service class is declared readonly and only declares stateless dependencies in __construct().
• The service has no class properties.
• All __construct() arguments are services and declared readonly.
• __construct() requires no manual non-service arguments.

The last point is particularly relevant: Some TYPO3 core services expect state to be passed to __construct(), making them stateful and unsuitable for injection, as dependency injection cannot handle consumer state. These services must be instantiated using makeInstance() until their constructors are updated to be compatible with dependency injection.

When to use new?

Services should be always retrieved using dependency injection. If that is not feasible because the dependent service is stateful or because the class is created using a "polluted" constructor with manual arguments, it should be created using makeInstance(). While services without dependencies could be instantiated with new, this approach has drawbacks: It introduces risks if the service is later modified to include dependencies and bypasses the XCLASS mechanism and potential service overrides by configuration.

Only data objects - preferably using public constructor property promotion - should be instantiated using the PHP keyword new.

Mix manual constructor arguments and service dependencies?

A service can not mix manual constructor arguments with service dependencies handled by dependency injection. Manual constructor arguments make services stateful. When a service is instantiated with manual arguments, such as $myService = GeneralUtility::makeInstance(MyService::class, $myState), dependency injection is bypassed, and any other service dependencies in the constructor are ignored. Mixing both blends the roles of services and data objects, which is poor PHP architecture.

The extbase-based dependency injection solution using ObjectManager allowed such mixtures, but this has been replaced by the Symfony-based dependency injection solution, which does not support this practice.

What about user functions?

It is possible to use dependency injection when calling custom user functions, for example .userFunc within TypoScript or in (legacy) hooks, usually via \TYPO3\CMS\Core\Utility\GeneralUtility::callUserFunction().

callUserFunction() internally uses the dependency-injection-aware helper GeneralUtility::makeInstance(), which can recognize and inject services that are marked public.

What about injection in a XCLASS'ed class?

When extending an existing class (for example, an Extbase controller) using XCLASS and injecting additional dependencies using constructor injection, ensure that a reference to the extended class is added in the Configuration/Services.yaml file of the extending extension, as shown in the example below:

TYPO3\CMS\Belog\Controller\BackendLogController: '@MyVendor\MyExtension\Controller\ExtendedBackendLogController'