bluepsyduck / zend-autowire-factory
A Zend factory implementation allowing for auto-wiring like in Symfony.
Requires
- php: >=7.1
- zendframework/zend-servicemanager: ^3.0
Requires (Dev)
- bluepsyduck/test-helper: ^1.0
- mikey179/vfsstream: ^1.6
- phpstan/phpstan: ^0.11
- phpstan/phpstan-phpunit: ^0.11
- phpstan/phpstan-strict-rules: ^0.11
- phpunit/phpunit: ^7.0 || ^8.0
- rregeer/phpunit-coverage-check: ^0.1
- squizlabs/php_codesniffer: ^3.4
- zendframework/zend-config-aggregator: ^1.1
This package is auto-updated.
Last update: 2020-11-11 09:56:35 UTC
README
DEPRECATED: Use package bluepsyduck/laminas-autowire-factory instead.
bluepsyduck/laminas-autowire-factory contains the same functionality as this package, with the only difference being the namespace. Except for the imports no changes are required.
This library provides few factories helping with auto-wiring service classes to make writing actual factories less common.
AutoWireFactory
The AutoWireFactory
uses reflection on the constructor of the actual service class to determine how to resolve the
dependencies and creating the actual service. The factory is adopting
Symfony's approach of handling auto wiring,
especially dealing with multiple implementations of the same type.
Resolving strategies
The factory uses the following strategies to resolve a parameter of the constructor, depending on how it is type-hinted. The first alias available in the container will be used to resolve the dependency. If no alias is available, an exception gets triggered.
Each parameter is resolved on its own, so they can be combined in any way.
Parameter with class type-hint
Example: __construct(FancyClass $fancy)
If the parameter has a class name as type-hint, then the following aliases are checked in the container:
FancyClass $fancy
: The combination of class name and parameter name. This allows for multiple implementations of the same interface as stated in the Symphony documentation.FancyClass
: "Default" case of registering a class with its name to the container.$fancy
: Fallback of using the parameter name alone, mostly to make the aliases uniform between cases.
The first alias which can be provided by the container will be used.
Parameter with scalar type-hint
Example: __construct(array $fancyConfig)
If the parameter is type-hinted with a scalar type, e.g. to pull config values into the service, the following aliases are checked:
array $fancyConfig
: The combination of type and parameter name, the same as for class type-hints.$fancyConfig
: Fallback using only the parameter name.
Note that the type alone, array
, is not used as alias.
Parameter without type-hint
Example: __construct($fancyParameter)
In this case, only one alias can be checked due to missing information:
$fancyParameter
: Fallback is the only possible alias.
AutoWireFactory as AbstractFactory
Next to the FactoryInterface
to use the AutoWireFactory
as an explicit factory in the container configuration,
it also implements the AbstractFactoryInterface
: If you add this factory as an abstract factory, it will try
to auto-wire everything it can. This will make configuring the container mostly obsolete, with the exception of
parameters using scalar values or multiple implementations (where the parameter name is part of the container alias).
Caching
The AutoWireFactory
uses reflections to resolve dependencies. To make things faster, the factory offers building up
a cache on the filesystem to avoid using reflections on each script call. To enable the cache, add the following line
e.g. in the config/container.php
file:
\BluePsyduck\ZendAutoWireFactory\AutoWireFactory::setCacheFile('data/cache/autowire-factory.cache.php');
ConfigReaderFactory
To help further with making self-written factories obsolete, the ConfigReaderFactory
is able to provide values from
the application config to the container to be e.g. used together with auto-wiring.
Usage
The ConfigReaderFactory
requires the application config to be added as array to the container. If the alias for the
config differs from the default "config", call ConfigReaderFactory::setConfigAlias('yourAlias')
to set the
alias.
Then, use the readConfig(string ...$keys)
function (or new ConfigReaderFactory(string ...$keys)
) to read a config
value for the container, where $keys
are the array keys to reach your desired value in the config. Note that if a key
is not set, an exception will be triggered by the factory.
AliasArrayInjectorFactory
The AliasArrayInjectorFactory
reads an array of aliases from the config (using the ConfigReaderFactory
), and creates
all instances to these aliases and returns them to be injected into other services. All aliases must be known to the
container.
To use this factory, simply call injectAliasArray(string ...$configKeys)
(or
new AliasArrayInjectorFactory(string ...$configKeys)
) within the container config.
Example
The following example should show how to use both the AutoWireFactory
and the ConfigReaderFactory
to auto-wire a
service class.
Let's assume we have the following application config from which we want to take a value:
[ 'fancy-service' => [ 'fancy-property' => 'Hello World!', 'fancy-adapters' => [ FancyAdapterAlpha::class, FancyAdapterOmega::class, ], ], ]
We want to auto-wire the following service class:
class FancyService { public function __construct(FancyComponent $component, string $fancyProperty, array $fancyAdapters) { } } class FancyComponent {} class FancyAdapterAlpha {} class FancyAdapterOmega {}
The following configuration can be used for the container without writing any factories:
<?php use BluePsyduck\ZendAutoWireFactory\AutoWireFactory; use Zend\ServiceManager\Factory\InvokableFactory; use function BluePsyduck\ZendAutoWireFactory\injectAliasArray; use function BluePsyduck\ZendAutoWireFactory\readConfig; return [ 'dependencies' => [ 'factories' => [ // Enable auto-wiring for the service itself. FancyService::class => AutoWireFactory::class, // FancyComponent does not need any factory as it does not have a constructor. // Both InvokableFactory and AutoWireFactory are usable here. FancyComponent::class => InvokableFactory::class, FancyAdapterAlpha::class => InvokableFactory::class, FancyAdapterOmega::class => InvokableFactory::class, // Enable the scalar property for auto-wiring into the service. // In this example, the factory would fetch "Hello World!" from the config. 'string $fancyProperty' => readConfig('fancy-service', 'fancy-property'), // Inject an array of other services through their aliases into the service. // In this example, instances of FancyAdapterAlpha and FancyAdapterOmega would be injected. 'array $fancyAdapters' => injectAliasArray('fancy-service', 'fancy-adapters'), ], ], ];
This configuration can be made even shorter if we use the AutoWireFactory
as an abstract factory:
<?php use BluePsyduck\ZendAutoWireFactory\AutoWireFactory; use function BluePsyduck\ZendAutoWireFactory\injectAliasArray; use function BluePsyduck\ZendAutoWireFactory\readConfig; return [ 'dependencies' => [ 'abstract_factories' => [ // Will auto-wire everything possible to be auto-wired, in our case both FancyService and FancyComponent. AutoWireFactory::class, ], 'factories' => [ // Any aliases using property names cannot be handled by the AutoWireFactory and must still get listed. 'string $fancyProperty' => readConfig('fancy-service', 'fancy-property'), 'array $fancyAdapters' => injectAliasArray('fancy-service', 'fancy-adapters'), ], ], ];
Of course it is always possible to add a concrete factory to any service if auto-wiring is not possible due to more complex initialization requirements.