How much type-safety do we need for this PSR?

[mindplay-dk]

How much type-safety is required for this PSR?

Current Package

The current, published container-interop/service-provider package consists simply of this:

/**
 * A service provider provides entries to a container.
 */
interface ServiceProviderInterface
{
    /**
     * Returns a list of all container entries registered by this service provider.
     *
     * - the key is the entry name
     * - the value is a callable that will return the entry, aka the **factory**
     *
     * Factories have the following signature:
     *        function(\Psr\Container\ContainerInterface $container)
     *
     * @return callable[]
     */
    public function getFactories();

    /**
     * Returns a list of all container entries extended by this service provider.
     *
     * - the key is the entry name
     * - the value is a callable that will return the modified entry
     *
     * Callables have the following signature:
     *        function(Psr\Container\ContainerInterface $container, $previous)
     *     or function(Psr\Container\ContainerInterface $container, $previous = null)
     *
     * About factories parameters:
     *
     * - the container (instance of `Psr\Container\ContainerInterface`)
     * - the entry to be extended. If the entry to be extended does not exist and the parameter is nullable, `null` will be passed.
     *
     * @return callable[]
     */
    public function getExtensions();
}

Optional Callable Types

We could improve on the type-safety by introducing interface to describe the callables:

/**
 * A service provider provides entries to a container.
 */
interface ServiceProviderInterface
{
    /**
     * Returns a list of all container entries registered by this service provider.
     *
     * - the key is the entry name
     * - the value is a callable that will return the entry, aka the **factory**
     *
     * A factory is an instance of {@see FactoryDefinitionInterface}, or a `callable` with the following signature:
     * 
     *     function(\Psr\Container\ContainerInterface $container)
     *
     * @return (callable|FactoryDefinitionInterface)[]
     */
    public function getFactories(): array;

    /**
     * Returns a list of all container entries extended by this service provider.
     *
     * - the key is the entry name
     * - the value is a callable that will return the modified entry
     *
     * An extension is an instance of {@see ExtensionDefinitionInterface}, or a `callable` with the following signature:
     * 
     *        function(Psr\Container\ContainerInterface $container, $previous)
     *     or function(Psr\Container\ContainerInterface $container, $previous = null)
     *
     * About factories parameters:
     *
     * - the container (instance of `Psr\Container\ContainerInterface`)
     * - the entry to be extended. If the entry to be extended does not exist and the parameter is nullable, `null` will be passed.
     *
     * @return (callable|ExtensionDefinitionInterface)[]
     */
    public function getExtensions(): array;
}

/**
 * A factory class may implement this interface for type-safety.
 */
interface FactoryDefinitionInterface
{
    /**
     * Creates the entry, using the given container to resolve dependencies.
     * 
     * @param ContainerInterface $container The container that should be used to resolve dependencies
     *
     * @return mixed The created entry
     */
    public function __invoke(ContainerInterface $container): mixed;
}

/**
 * An extension implement this interface for type-safety.
 */
interface ExtensionDefinitionInterface
{
    /**
     * Extends a given service, using the given container to resolve dependencies.
     * 
     * @param ContainerInterface $container The container that should be used to resolve dependencies
     * @param mixed              $previous  The previous service
     *
     * @return mixed The extended service.
     */
    public function __invoke(ContainerInterface $container, mixed $previous): mixed;
}

Note that this is just a formalization of the callable types - implementing these would be optional, and callable is still supported.

Required Callable Types

Another option would be to have strict type-safety:

/**
 * A service provider provides entries to a container.
 */
interface ServiceProviderInterface
{
    /**
     * Returns a list of all container entries registered by this service provider.
     *
     * - the key is the entry name
     * - the value is a callable that will return the entry, aka the **factory**
     *
     * A factory is an instance of {@see FactoryDefinitionInterface}, or a `callable` with the following signature:
     * 
     *     function(\Psr\Container\ContainerInterface $container)
     *
     * @return FactoryDefinitionInterface[]
     */
    public function getFactories(): array;

    /**
     * Returns a list of all container entries extended by this service provider.
     *
     * - the key is the entry name
     * - the value is a callable that will return the modified entry
     *
     * An extension is an instance of {@see ExtensionDefinitionInterface}, or a `callable` with the following signature:
     * 
     *        function(Psr\Container\ContainerInterface $container, $previous)
     *     or function(Psr\Container\ContainerInterface $container, $previous = null)
     *
     * About factories parameters:
     *
     * - the container (instance of `Psr\Container\ContainerInterface`)
     * - the entry to be extended. If the entry to be extended does not exist and the parameter is nullable, `null` will be passed.
     *
     * @return ExtensionDefinitionInterface[]
     */
    public function getExtensions(): array;
}

/**
 * A factory class may implement this interface for type-safety.
 */
interface FactoryDefinitionInterface
{
    /**
     * Creates the service, using the given container to resolve dependencies.
     * 
     * @param ContainerInterface $container The container that should be used to resolve dependencies
     *
     * @return mixed The created entry
     */
    public function createService(ContainerInterface $container): mixed;
}

/**
 * An extension implement this interface for type-safety.
 */
interface ExtensionDefinitionInterface
{
    /**
     * Extends a given service, using the given container to resolve dependencies.
     * 
     * @param ContainerInterface $container The container that should be used to resolve dependencies
     * @param mixed              $previous  The previous service
     *
     * @return mixed The extended service.
     */
    public function extendService(ContainerInterface $container, mixed $previous): mixed;
}

This way, the interfaces are required and must be implemented.

Discussion

The question is how much type-safety do we need?

To answer this question, keep in mind the purpose of this PSR, which in the current PSR draft is described as follows:

The service providers defined by this PSR are intended as a "lowest common denominator" format. They are NOT intended to compete with or replace the developer experience of using service providers in full-featured DI containers and frameworks.

Rather, the goal is to achieve interoperability between various containers and frameworks. This could be achieved by:

• DI containers implementing support for consuming and exporting PSR service providers.
• Dedicated "service provider builders" which provide more convenient and opinionated APIs, and generate PSR service providers.

While hand-authoring PSR service providers is possible, the expectation is that developers will use the service definition facilities native to their preferred container or framework, while interoperability will be achieved behind the scenes through support for PSR providers.

The choice of which container and provider implementations to use for application services is left open to developers.

Some things to consider:

• Performance implications of requiring classes and interface implementations vs just callable?
• Do the presence of interfaces make it easier or harder to implement providers?
• Is it reasonable to use __invoke in interfaces?

These are just suggestions for things to consider and discuss - feel free to add more.

[mindplay-dk]

I wrote a benchmark for each of these 3 patterns, to compare them in terms of performance.

https://github.com/mindplay-dk/provider-benchmarks

It's a rather pointless benchmark. 😅

But let me explain:

The optional_callable_types and minimal_type_safety versions perform the same, and in fact, these are practically identical. So while that might seem like a pointless exercise, this does demonstrate the fact that, if additional type-safety is optional, well, you can choose not to implement it at all.

It's difficult to say what you should conclude from that though - you could argue the point either way: if the optional interfaces are going to be optional, then why not include them. However, if they're going to be optional, favoring performance, most provider implementations would likely avoid using them, but then why include something you wouldn't want to use.

In my personal opinion, it would be difficult to argue in favor of additional complexity, if it's just going to be complexity that, ideally, nobody uses, for performance reasons. Might as well not have that feature then.

In addition, if a provider implementation wants extra type-safety at the expensive of performance, then there's nothing stopping them from adding these types themselves. If it doesn't buy us anything in terms of interoperability, again, difficult to argue in favor this.

Lastly, the required_types version adds about a 20% overhead.

Now, this is just for a naive boilerplate wrapper-class around the callable, so this isn't actually adding any useful type-checking - if you wanted to actually check callables, you'd need to use reflection, which would be slow, and only buys you run-time type-checking anyway. PHP does not support function-types, so the idea overall might look a bit moot.

However, as said, this is for a boilerplate wrapper-class around callables - which might not be how it's implemented in an actual DI container framework or a provider builder. It's not unthinkable you could do something safer/faster than using callables, so I wouldn't rule out this approach yet. Likely another test setup would be required to establish that.

EDIT: I did give that a try, and found that even the most basic builder would need to use functions anyway, and ends up doing the same (or more) work anyway. If you wanted to do something more interesting than that, it's almost definitely going to involve fluent configuration or attributes, or something more "opinionated", any of which would add even more overhead. Unless you were to do something really complex, like compiling and caching the result, you would likely only add overhead - and if you were to go to those lengths anyway, it probably doesn't even matter what the underlying interoperability standard looks like anymore, since you'd be handling everything above the bare factory functions yourself anyway, and can do whatever you need or want in terms of both performance and safety.

I would like to hear from someone who knows more details of how the Symfony container works, just to make sure we don't build something that's going to bottleneck a compiled container - but I don't really see how it could.

Personally, I am usually very much in favor of making everything as type-safe as possible - but my current opinion in this context, is that this PSR should probably focus on bare bones interoperability. My view might be different, if PHP had function types, but it doesn't seem like extra type-safety is really going to buy us anything in terms of "low-level" interoperability between container and frameworks.