README

Ioc-Interop provides an interoperable package of standard interfaces for inversion-of-control (IOC) service container functionality. It reflects, refines, and reconciles the common practices identified within several pre-existing projects.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174).

This package attempts to adhere to the Package Development Standards approach to naming and versioning.

Interfaces

This package defines the following interfaces:

• IocContainer affords obtaining services by name.

• IocContainerFactory affords obtaining a new instance of IocContainer.

• IocThrowable extends Throwable to mark an Exception as IOC-related.

• IocTypeAliases provides custom PHPStan types to aid static analysis.

IocContainer

IocContainer affords obtaining services by name.

• Notes:

  • This interface does not afford service management. The container will need to obtain services somehow, e.g. from a Service-Interop implementation.

IocContainer Methods

• public function hasService(ioc_service_name_string $serviceName) : bool;

  • Is the container able to return an instance of the $serviceName?

  • Notes:

    • The logic for this method is expressly unspecified. The ability check may be accomplished by querying a service management subsystem, or by some other means.

• public function getService(
      ioc_service_name_string $serviceName,
  ) : ioc_service_object;

  • Returns an instance of the $serviceName.

  • Directives:

    • Implementations MUST throw IocThrowable if the container cannot return an instance of the $serviceName.

  • Notes:

    • The logic for this method is expressly unspecified. Retrieval may be accomplished via a service management subsystem, or by some other means.

    • The returned instance may be new or shared. The retrieval logic defines the service lifetime, not the container (per se) and not the caller requesting the service.

IocContainerFactory

IocContainerFactory affords obtaining a new instance of IocContainer.

IocContainerFactory Methods

• public function newContainer() : IocContainer;

  • Returns a new instance of IocContainer.

  • Notes:

    • Container instantiation logic is not specified. Implementations might use providers, configuration files, attribute or annotation collection, or some other means to create and populate a container. Implementations might also choose to return a compiled or otherwise reconstituted container.

IocThrowable

IocThrowable extends Throwable to mark an Exception as IOC-related.

It adds no class members.

IocTypeAliases

IocTypeAliases provides custom PHPStan types to aid static analysis.

• ioc_service_name_string class-string<T>|non-empty-string
  

  • A class-string or string name for a service.

• ioc_service_object ($serviceName is class-string<T> ? T : object)
  

  • The service object for a given service name.

Implementations

Implementations MAY define additional class members not defined in these interfaces.

Notes:

• Reference implementations are available at https://github.com/ioc-interop/impl.

Q & A

How is Ioc-Interop different from PSR-11?

PSR-11 is an earlier recommendation that offers an interface to get items from a container, and to see if that container has a particular item.

Ioc-Interop is functionally almost identical to PSR-11. However, Ioc-Interop is intended to contain only services (object). PSR-11 is intended to contain anything (mixed).

Ioc-Interop also offers an IocContainerFactory interface, whereas PSR-11 offers none.

Is Ioc-Interop compatible with PSR-11?

No, in the sense that the method names, signatures, and intents are different.

Yes, in the sense that both may be implemented on the same class; the method names are different, and so are non-conflicting.

Why does Ioc-Interop not afford service management?

Ioc-Interop is focused on the concerns around obtaining and consuming services. The affordances for managing and producing services are a set of separate concerns.

Earlier drafts of Ioc-Interop were much more expansive, including a resolver subsystem and a service management subsystem. These have been extracted to separate standards, each of which is dependent on Ioc-Interop:

• Service-Interop
• Resolver-Interop

This separation helps to maintain a boundary between the needs of service consumers (afforded by Ioc-Interop) and service producers (afforded by Service-Interop and Resolver-Interop).

Note that Ioc-Interop is independent of Service-Interop and Resolver-Interop. Ioc-Interop implementations can use them, or avoid them, as implementors see fit.

Is IocContainer for Dependency Injection or is it a Service Locator?

IocContainer acts a Service Locator only when it is used as a dependency in order to retrieve other dependencies from it.

Why does IocContainer disallow non-object values?

IocContainer is explicitly a service container, not a general config container for scalar or array values.

Limiting services to objects helps maintain consistent expectations regarding service types and behavior. Of the researched projects, 10 return object, and 8 return mixed, so this restriction is consistent with the majority.

Ioc-Interop recognizes that implementors and consumers often want to make config values easily available, though Ioc-Interop questions what it means (or if it is possible) to get a "shared" scalar or array that works the same as a "shared" object.

With that in mind, Ioc-Interop encourages the use of one or more config services or value objects to make those values available, instead of storing config values directly inside a container.

Why does IocContainer define getService() and not just get() ?

The vast majority of researched projects, whether PSR-11 conforming or not, use the method name get(). Contra the research, Ioc-Interop asserts that get() is too generic, and that the method name should hint at what is being gotten; thus, getService().