Resolver-Interop provides an interoperable package of standard interfaces for autowiring resolver 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:

• ResolverService affords resolving a class name to a new instance of that class.

• ReflectionParametersResolver affords resolving an array of ReflectionParameters to an array of named arguments.

• ReflectionParameterResolver affords resolving a ReflectionParameter to an argument value.

• ReflectionMethodResolver affords invoking a method on an object.

• ReflectionPropertyResolver affords setting a property on an object.

• CallResolverService affords invoking a callable with resolved ReflectionParameters and argument overrides.

• InvokableResolver affords resolving the implementing object to a value.

• ResolverThrowable extends Throwable to mark an Exception as resolver-related. It adds no class members.

ResolverService affords resolving a class name to a new instance of that class.

• public function resolve(
      IocInterop\Interface\IocContainer $ioc,
      class-string $class,
      mixed[] $arguments = [],
  ) : T;

  • Returns a new instance of the $class with constructor $arguments.

  • Directives:

    • Implementations MUST support constructor injection using logic equivalent to that specified by ReflectionParametersResolver.

    • Implementations MAY support ReflectionPropertyResolver attributes on the instantiated class properties.

    • Implementations MAY support ReflectionMethodResolver attributes on the instantiated class methods.

    • Implementations MAY support other forms of injection not specified herein.

    • Implementations MUST throw ResolverThrowable if the $class cannot be resolved.

• public function isResolvable(string $class) : bool;

  • Does the $class exist, and is it instantiable?

ReflectionParametersResolver affords resolving an array of ReflectionParameters to an array of named arguments.

• public function resolveParameters(
      IocInterop\Interface\IocContainer $ioc,
      ReflectionParameter[] $parameters,
      mixed[] $arguments = [],
  ) : mixed[];

  • Resolves an array of ReflectionParameters to an array of named arguments, allowing for an array of override arguments.

  • Directives:

    • Implementations MUST NOT attempt to resolve a ReflectionParameter that already exists by name as an argument.

    • When resolving a ReflectionParameter to an argument, implementations MUST do so using logic equivalent to that specified by ReflectionParameterResolver.

    • Implementations MUST resolve all InvokableResolver objects in the $arguments.

    • Implementations MUST return an array of arguments keyed by the ReflectionParameter names.

ReflectionParameterResolver affords resolving a ReflectionParameter to an argument value.

• Notes:

  • This interface can be implemented as an attribute. Doing so allows implementors to define custom resolution approaches for consumers to apply to specific ReflectionParameters. For example, implementors may declare a #[GetEnv($name)] attribute to resolve the ReflectionParameter to an environment value.

• public function resolveParameter(
      IocInterop\Interface\IocContainer $ioc,
      ReflectionParameter $parameter,
  ) : mixed;

  • Resolves the ReflectionParameter to an argument value.

  • Directives:

    • Implementations MUST resolve the $parameter in this order:

      • If the $parameter has an Attribute that implements ReflectionParameterResolver, implementations MUST resolve the $parameter using that attribute.

      • Otherwise, if the $parameter type is a ReflectionNamedType, and the container has a service for that type, implementations MUST resolve the $parameter to that service.

      • Otherwise, implementations MAY attempt to resolve the $parameter using implementation-specific logic; such logic is not defined herein.

      • Otherwise, if the $parameter has a default value, implementations MUST resolve the $parameter to that value.

    • Implementations MUST throw ResolverThrowable if the $parameter cannot be resolved.

ReflectionMethodResolver affords invoking a method on an object.

• Notes:

  • TBD Marks a method for setter injection or post-instantiation invocation.

  • This interface can be implemented as an attribute. Doing so allows implementors to define custom resolution approaches for consumers to apply to specific ReflectionMethods.

• public function resolveMethod(
      IocInterop\Interface\IocContainer $ioc,
      ReflectionMethod $method,
      object $object,
  ) : object;

  • Invokes the ReflectionMethod on the $object, returning either the $object itself or a replacement object.

  • Directives:

    • Implementations MUST support parameter injection using logic equivalent to that specified by ReflectionParametersResolver.

    • Implementations MUST throw ResolverThrowable if the $method cannot be resolved.

  • Notes:

    • TBD Implement on TARGET_METHOD attributes for setter or immutable injection.

ReflectionPropertyResolver affords setting a property on an object.

• Notes:

  • TBD Marks a property for injection.

  • This interface can be implemented as an attribute. Doing so allows implementors to define custom resolution approaches for consumers to apply to specific ReflectionPropertys.

• public function resolveProperty(
      IocInterop\Interface\IocContainer $ioc,
      ReflectionProperty $property,
      object $object,
  ) : void;

  • Sets the ReflectionProperty on an object.

  • Directives:

    • Implementations MUST throw ResolverThrowable if the $property cannot be resolved.

CallResolverService affords invoking a callable with resolved ReflectionParameters and argument overrides.

• public function resolveCall(
      IocInterop\Interface\IocContainer $ioc,
      callable $callable,
      mixed[] $arguments = [],
  ) : mixed;

  • Invokes the $callable with $arguments overrides, and returns the result.

  • Directives:

    • Implementations MUST resolve the $callable ReflectionParameters and $arguments using logic equivalent to that specified by ReflectionParametersResolver.

    • Implementations MUST throw ResolverThrowable if the callable ReflectionParameters or arguments cannot be resolved.

InvokableResolver affords resolving the implementing object to a value.

• Notes:

  • TBD Use e.g. to defer container calls (i.e. Lazy), then can use in $arguments without actually creating anything until the moment of resolution.

• public function __invoke(IocInterop\Interface\IocContainer $ioc) : mixed;

  • Resolves the implementing object to a value.

  • Directives:

    • Implementations MUST throw ResolverThrowable if the object cannot be resolved.

ResolverThrowable extends Throwable to mark an Exception as resolver-related. It adds no class members.

• Directives:

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

• Notes:

  • Reference implementations may be found at https://github.com/Resolver-Interop/impl.