You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

127 lines
4.1 KiB
PHP

<?php
/**
* Interface Injector.
*
* @link https://www.mwpd.io/
*
* @copyright 2019 Alain Schlesser
* @license MIT
*/
/**
* Original code modified for this project.
*
* @copyright 2021 Google LLC
* @license https://www.apache.org/licenses/LICENSE-2.0 Apache License 2.0
*/
declare(strict_types = 1);
namespace Google\Web_Stories\Infrastructure;
/**
* The dependency injector should be the only piece of code doing actual
* instantiations, with the following exceptions:
* - Factories can instantiate directly.
* - Value objects should be instantiated directly where they are being used.
*
* Through technical features like "binding" interfaces to classes or
* "auto-wiring" to resolve all dependency of a class to be instantiated
* automatically, the dependency injector allows for the largest part of the
* code to adhere to the "Code against Interfaces, not Implementations"
* principle.
*
* Finally, the dependency injector should be the only one to decide what
* objects to "share" (always handing out the same instance) or not to share
* (always returning a fresh new instance on each subsequent call). This
* effectively gets rid of the dreaded Singletons.
*
* @internal
*
* @since 1.6.0
*
* @template T
*/
interface Injector extends Service {
/**
* Make an object instance out of an interface or class.
*
* @since 1.6.0
*
* @param string $interface_or_class Interface or class to make an object instance out of.
* @param string[] $arguments Optional. Additional arguments to pass to the constructor.
* Defaults to an empty array.
* @return C Instantiated object.
*
* @phpstan-param class-string<C> $interface_or_class Interface or class to make an object instance out of.
* @phpstan-param class-string[] $arguments Optional. Additional arguments to pass to the constructor.
* Defaults to an empty array.
*
* @phpstan-return C
*
* @template C
*/
public function make( string $interface_or_class, array $arguments = [] );
/**
* Bind a given interface or class to an implementation.
*
* Note: The implementation can be an interface as well, as long as it can
* be resolved to an instantiatable class at runtime.
*
* @since 1.6.0
*
* @param string $from Interface or class to bind an implementation to.
* @param string $to Interface or class that provides the implementation.
*
* @phpstan-param class-string<T> $from Interface or class to bind an implementation to.
* @phpstan-param class-string<T> $to Interface or class that provides the implementation.
*/
public function bind( string $from, string $to ): Injector;
/**
* Bind an argument for a class to a specific value.
*
* @since 1.6.0
*
* @param string $interface_or_class Interface or class to bind an argument
* for.
* @param string $argument_name Argument name to bind a value to.
* @param mixed $value Value to bind the argument to.
*
* @phpstan-param class-string<T> $interface_or_class Interface or class to bind an argument
*/
public function bind_argument(
string $interface_or_class,
string $argument_name,
$value
): Injector;
/**
* Always reuse and share the same instance for the provided interface or
* class.
*
* @since 1.6.0
*
* @param string $interface_or_class Interface or class to reuse.
*
* @phpstan-param class-string<T> $interface_or_class Interface or class to reuse.
*/
public function share( string $interface_or_class ): Injector;
/**
* Delegate instantiation of an interface or class to a callable.
*
* @since 1.6.0
*
* @param string $interface_or_class Interface or class to delegate the
* instantiation of.
* @param callable $callback Callable to use for instantiation.
*
* @phpstan-param class-string<T> $interface_or_class Interface or class to delegate the
* instantiation of.
*/
public function delegate( string $interface_or_class, callable $callback ): Injector;
}