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 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. It adds no class members.

• IocTypeAliases defines PHPStan type aliases to aid static analysis.

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.

• 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 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 affords obtaining a new instance of IocContainer.

• 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 extends Throwable to mark an Exception as IOC-related. It adds no class members.

IocTypeAliases defines PHPStan type aliases to aid static analysis.

• ioc_service_name_string class-string<T>|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.

• Directives:

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

• Notes:

  • Reference implementations may be found at https://github.com/ioc-interop/impl.

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.

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.

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.

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

IocContainer is explicitly a service container, not a general config container for scalar or array values. (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.) Limiting services to objects helps maintain consistent expectations regarding service types and behavior.

Ioc-Interop recognizes that implementors and consumers often want to make config values easily available. Instead of storing config values directly inside a container, Ioc-Interop encourages the use of one or more config services or value objects to make those values available.

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().