Add container resolution modes

[brendt]

A interesting question was raised in #2256 on how the container should resolve dependencies.

First, we should discuss the current situation: Tempest's container defaults to non-singletons. Whenever you ->get() a dependency from the container, it will create a new one, unless there's an explicit singleton definition for it (defined either with $container->singleton, an initializer with #[Singleton], or a class tagged with #[Singleton]).

Now there are three questions to discuss:

• Can we design an API that makes it trivial for users to explicitly retrieve non-singleton objects, even though they have a singleton definition?
• Can we make it so the container's default resolution strategy can be changed?
• What should the default resolution strategy be?

Let's discuss

[brendt]

Pitching in myself

Can we design an API that makes it trivial for users to explicitly retrieve non-singleton objects, even though they have a singleton definition?

Personally I like a two-part answer to this question. First we can build on top of tags, which we already have, and allow "dynamic tags": tags that are "defined" when retrieving a dependency rather than when defining them.

$container->get(BlogRepository::class, tag: 'web');

Currently, if there's no explicit definition for BlogRepository#web, this call fails. However, we could easily make it so that it is allowed; maybe only when #[AllowDynamicTag] is added to BlogRepository — to be discussed.

The second part of my answer is to also add a new method (instead of make, I think that's a much more unclear name):

$container->new(BlogRepository::class);

This method will always make a new instance, ignoring all possible singleton definitions.

Can we make it so the container's default resolution strategy can be changed?

We can, but I think this is an incredible footgun and we shouldn't do it. Let's say the default changes from "non-singleton" to "singleton". Let's then say a third party package relies on the default mode, which is suddenly changed at runtime by the project code.

The only way this can work IMO is if we define a resolution mode on some kind of "context-based" basis. The most logical option would be the namespace level. However, we also have tagged dependencies which you can use for this purpose by defining explicit initializers for specific tags.

What should the default resolution strategy be?

Assuming we find a good reason to add configurable resolution strategies, then I would argue non-singleton is still a much better default. Shared objects can lead to many unforeseen side-effects, and thus I rather make that an explicit opt-in.

[Crell]

As the person who prompted this discussion, I'll offer my thoughts.

1. I am actually quite shocked and appalled at how many DI containers default to non-singleton. That is a fundamentally broken design. The purpose of a DI container is to wire together stateless services. If it's not stateless (modulo some resettable caching layer), then it's not a service. Period. This was discussed to death and resolved around 2010/2011. Shared objects only lead to unforseen side-effects if those objects are mutable. "Shared mutable state" is already well-understood to be the source of a vast number of bugs. (Usually that is said in reference to multi-threaded code, but it also applies to single-threaded code if you don't know you're sharing something.) If you have a stateful object in the container, then you are already doing it wrong and your code is broken.
2. Assuming your services are stateless (which, as above, is the only correct answer), then creating a separate one for each dependency leads to memory bloat. How many instances of the Foo service are there? I dunno, but all of them take up memory. If it's stateful, then how do I know I need to reset their state at the end of a request if I don't know which ones or how many there are?
3. It's only a footgun to change the default, assuming users are relying on the current behavior. It's not a footgun to default to singletons. Every app using the Symfony container (which is a massive percentage of the ecosystem) is defaulting to singletons, and they run just fine TYVM. That is provably not a footgun.

What prompted me to look into the Temptest container in the first place is I'm trying to replace PHP-DI in MiDy. PHP-DI is grossly inflexible and doesn't allow extending/modifying a service once created, as far as I can tell, and it's internally quite convoluted and slow. However, one feature it does have, which I use and need, is a make() method that lets you create an arbitrary, non-container-registered object and autowire it's constructor arguments from the container on the fly. I use this for controller classes in MiDy's unconventional routing mechanism, which checks a file to see what class it has, then calls $container->make($thatClass) to instantiate it, and populate any dependencies. Registering the classes in the container ahead of time is impractical.

So the behavior of make() is like so:

class Foo {}
class Bar {}

$container->add(Foo::class);
$container->add(Bar::class);

// NOT a service.
class Baz {
  public function __construct(private Foo $foo, private Bar $bar, private int $count) {}
}

$baz1 = $container->make(Baz::class, count: 4);
$baz2 = $container->make(Baz::class, count: 4);

$baz1 === $baz2; // FALSE

Sadly, I haven't found any container implementations that offer singleton-default, make(), and a pluggable way to extend existing definitions (which is a requirement for a plugin system). I was hoping that Temptest would fit the bill, but it looks like not, so I will likely need to write my own at this point.

[shaffe-fr]

I think Crell’s and Brendt’s proposals could actually fit together quite nicely here.

What if the default for a registered service is simply singleton when no lifetime is explicitly specified? Then #[Transient] becomes an explicit opt-in for the cases that actually need a new instance on every resolution.

For explicitly creating an object, we could have:

$container->get(Foo::class);
// registered service → singleton by default

$container->new(Foo::class, ...);
// always a fresh Foo, regardless of its definition

new() would only make the root object new; its dependencies would still follow their own lifetimes. This seems to cover Crell’s make() use case for dynamically discovered controllers/classes without requiring them to be registered beforehand.

For the cases where we need different behaviour depending on context, I think Brendt’s dynamic tags could fit nicely here. Since tags already exist, allowing something like:

$container->get(Foo::class, tag: 'web');

to dynamically resolve a Foo#web variant would give us a way to express contextual behaviour without changing the global resolution strategy.

That would leave us with a fairly simple model:

get()          → registered service, singleton by default
#[Transient]   → explicitly transient service
new()          → explicitly create a fresh object
dynamic tag    → contextual resolution

I’d still avoid a globally mutable default resolution mode, since that could change the behaviour of third-party packages in surprising ways.

This seems to preserve the nice part of Crell’s singleton-by-default argument while keeping Brendt’s concern about resolution behaviour being explicit and composable.

[brendt]

I am actually quite shocked and appalled at how many DI containers default to non-singleton. That is a fundamentally broken design.

First I want to point out that our definitions might differ. My definition of "a container" is that its sole purpose is to construct objects to facilitate dependency injection in a more convenient way. Whether these objects are singletons or not is a minor detail in that process.

Second, one of my core principles in programming (and anything in life) is that no one gets to claim something is fundamentally broken or factually wrong if practice shows that it works. Laravel's container defaults to non-singletons. We can like or dislike Laravel, that doesn't matter. It's PHP's biggest framework, countless people and companies are making huge profit with it. That means we cannot claim its approach is fundamentally broken as practice has proven that it's not. The best we can say is that it's not our personal preference.

Applying that same principle on my own reasoning though, you rightfully say:

Every app using the Symfony container (which is a massive percentage of the ecosystem) is defaulting to singletons, and they run just fine TYVM. That is provably not a footgun.

Good point. Practice has already shown that both approaches work. Which means it likely comes down to what people prefer the most. My preference is non-singleton mode.

I'm still open to exploring whether we can make it configurable, although the footguns there still exist (packages relying on behavior that is changed on the project level is one example.)

[brendt]

Also circling back to @Crell 's example, I just want to point out how you would do this in Tempest today. Again, way may disagree whether we like this approach or not, just want to add it for clarity.

Option one is to use the #[Singleton] attributes:

#[Singleton]
class Foo {}

#[Singleton]
class Bar {}

#[Singleton]
class Baz {
    public function __construct(private Foo $foo, private Bar $bar, private int $count) {}
}


$a = $this->container->get(Baz::class, count: 4);
$b = $this->container->get(Baz::class, count: 4);

$a === $b; // true

Option two is to use initializers:

final class BazInitializer implements Initializer
{
    #[Singleton]
    public function initialize(Container $container): Baz
    {
        return new Baz($container->get(Foo::class), $container->get(Bar::class), 4);
    }
}

// And then also one for Foo and Bar

Edit: there's also a third option with dynamic initializers, you can read about them here: https://tempestphp.com/3.x/essentials/container#dynamically-matching-classes-or-interfaces

[aidan-casey]

I am actually quite shocked and appalled at how many DI containers default to non-singleton. That is a fundamentally broken design.

While I think it is important to challenge the status quo, it is equally important to do so with an open mind in hopes of actually accomplishing something.

The historical record doesn't support your claim. Apache Avalon/Excalibur's ECM, one of the earliest documented IoC component containers and in production use by 2001, explicitly treated an unspecified component as SingleThreaded, meaning “a brand new instance is created every time the Component is requested.” Shared ThreadSafe components were an explicit lifestyle. Later mainstream DI containers, including Guice, Autofac, StructureMap, Ninject, and Unity, also deliberately adopted transient/non-cached defaults.

Perhaps, rather than calling all of these implementations broken designs, we should ask why they made the decisions they did?

The purpose of a DI container is to wire together stateless services.

Is it though? Let's have a look.

Dependency injection is a newer term made popular by Martin Fowler in his article Inversion of Control Containers and the Dependency Injection pattern. It describes a specific application of the much earlier defined Inversion of Control, which can be traced back to the 1980s.

Martin Fowler breaks down the goals of Dependency Injection in his article:

For this new breed of containers the inversion is about how they lookup a plugin implementation. In my naive example the lister looked up the finder implementation by directly instantiating it. This stops the finder from being a plugin. The approach that these containers use is to ensure that any user of a plugin follows some convention that allows a separate assembler module to inject the implementation into the lister.

Martin later describes the goals of dependency injection:

The basic idea of the Dependency Injection is to have a separate object, an assembler, that populates a field in the lister class with an appropriate implementation for the finder interface...

Fowler defines the problem DI solves in terms of separating configuration and assembly from use. Object lifetime is something separate layered on top of that mechanism.

Martin Fowler favors PicoContainer for his examples because he and his colleagues had an active role in its development. Interestingly enough, in their development of PicoContainer, they made the intentional decision to move away from cached objects to transients by default in v2.

Important note about caching: If you intend the components to be cached, you should pass in a factory that creates Cached instances, such as for example Caching. Caching can delegate to other ComponentAdapterFactories.

http://picocontainer.com/javadoc/core/org/picocontainer/DefaultPicoContainer.html

Retrieve the component instance. This method will usually create a new instance each time it is called, but that is not required. For example, Cached will always return the same instance.

http://picocontainer.com/javadoc/core/org/picocontainer/ComponentAdapter.html

Martin Fowler completes his article by reiterating the thing that is important (note: it's not lifecycle and it's not a container!):

The choice between Service Locator and Dependency Injection is less important than the principle of separating service configuration from the use of services within an application.

---

So, putting aside the unhelpful claim about "fundamentally broken designs," let's focus on the question that actually affects Tempest: should the container default to transient objects or singletons?

I am going to suggest that transient objects make fewer assumptions about the service. Stateless does not immediately imply singleton-safe. Consider the following:

final class CreateEmployeeCommandHandler
{
    public function __construct(
        private readonly EmployeeRepository $employeeRepository,
        private readonly TenantContext $tenant
    ) {}
}

This class itself is stateless. It doesn't cache anything or maintain any mutable state of its own. Yet, if the tenant context is scoped to the current request, this class would be a dangerous singleton in a long-running process such as Swoole or a queue worker.

A singleton implicitly makes assumptions not only about the service itself, but also about the lifetime of the dependencies it captures. A transient does not impose those same assumptions.

There is, of course, a cost to constructing multiple instances, but transient does not mean that the container keeps every object it creates alive for the lifetime of the application. Once nothing references an object, PHP can release it. In a traditional request-per-process model, that lifetime is often bounded by the request anyway. In long-running workers, it is bounded by whatever continues to hold a reference to the object. If constructing a particular service is expensive enough that reusing it is worthwhile, that is a perfectly valid reason to explicitly give it a longer lifetime. I don't think that justifies assuming application-wide sharing for every service by default.

I believe we create fewer surprises by defaulting to transient and allowing developers to opt in to singleton and even scoped services. At the same time, I also believe we could improve manual registration in the container by adding explicit singleton, scoped, and transient registration methods.