README

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

Interfaces

This package defines the following interfaces:

• ResolverService affords resolving classes, calls, parameter arrays, and types.

• 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.

• Resolvable affords allowing the implementing object to resolve itself to a value.

• ResolverThrowable extends Throwable to mark an Exception as resolver-related.

ResolverService

ResolverService affords resolving classes, calls, parameter arrays, and types.

ResolverService Methods

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

  • Resolves the $class to return a new instance.

  • Directives:

    • Implementations MUST support parameter injection on the $class constructor using logic equivalent to that specified by resolveParameters().

    • 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 isResolvableClass(string $class) : bool;

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

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

  • Resolves the $callable to return its result.

  • Directives:

    • Implementations MUST support parameter injection on the $callable using logic equivalent to that specified by resolveParameters().

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

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

  • Resolves the $parameters into the $arguments.

  • Directives:

    • Implementations MUST NOT attempt to resolve a ReflectionParameter whose name or position already exists in the $arguments keys.

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

    • Implementations MUST retain each resolved ReflectionParameter by name in the $arguments.

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

• public function resolveType(
      IocInterop\Interface\IocContainer $ioc,
      ReflectionType $type,
  ) : ?string;

  • Resolves a ReflectionType to a string, or null if it cannot be be resolved.

  • Notes:

    • TBD Typically only for named types, but may help to convert union and intersection types to a single named type.

ReflectionParameterResolver

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.

ReflectionParameterResolver Methods

• 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 resolvable using logic equivalent to the [ReflectionService][] method resolveType() 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

ReflectionMethodResolver affords invoking a method on an object.

• Notes:

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

ReflectionMethodResolver Methods

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

  • Invokes the ReflectionMethod on the $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 $object is by reference so you can set to a replacement object a la immutability.

ReflectionPropertyResolver

ReflectionPropertyResolver affords setting a property on an object.

• Notes:

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

ReflectionPropertyResolver Methods

• 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.

Resolvable

Resolvable affords allowing the implementing object to resolve itself to a value.

• Notes:

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

Resolvable Methods

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

  • Resolves the implementing object to a value.

  • Directives:

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

    • TBD Must recursively resolve all Resolvable in the resolved value.

ResolverThrowable

ResolverThrowable extends Throwable to mark an Exception as resolver-related.

It adds no class members.

Implementations

• 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.

Q & A