Merge pull request #146 from GeeH/feature/config-abstract-factory

Adds a new Config Abstract Factory that allows service creation by config

Author: weierophinney

benchmarks/BenchAsset/Bar.php

@@ -0,0 +1,12 @@
+<?php
+namespace ZendBench\ServiceManager\BenchAsset;
+
+class Bar
+{
+    protected $options;
+
+    public function __construct($options = null)
+    {
+        $this->options = $options;
+    }
+}

benchmarks/FetchNewServicesBench.php

@@ -5,6 +5,7 @@
 use PhpBench\Benchmark\Metadata\Annotations\Iterations;
 use PhpBench\Benchmark\Metadata\Annotations\Revs;
 use PhpBench\Benchmark\Metadata\Annotations\Warmup;
+use Zend\ServiceManager\AbstractFactory\ConfigAbstractFactory;
 use Zend\ServiceManager\ServiceManager;
 
 /**
@@ -30,14 +31,20 @@ public function __construct()
             ],
             'services' => [
                 'service1' => new \stdClass(),
+                'config' => [
+                    ConfigAbstractFactory::class => [
+                        BenchAsset\Bar::class => [],
+                    ],
+                ],
             ],
             'aliases' => [
                 'factoryAlias1'          => 'factory1',
                 'recursiveFactoryAlias1' => 'factoryAlias1',
                 'recursiveFactoryAlias2' => 'recursiveFactoryAlias1',
             ],
             'abstract_factories' => [
-                BenchAsset\AbstractFactoryFoo::class
+                BenchAsset\AbstractFactoryFoo::class,
+                ConfigAbstractFactory::class,
             ],
         ]);
     }
@@ -145,4 +152,18 @@ public function benchBuildAbstractFactoryFoo()
 
         $sm->build('foo');
     }
+
+    public function benchFetchConfigAbstractFactoryBar()
+    {
+        $sm = clone $this->sm;
+
+        $sm->get(BenchAsset\Bar::class);
+    }
+
+    public function benchBuildConfigAbstractFactoryBar()
+    {
+        $sm = clone $this->sm;
+
+        $sm->build(BenchAsset\Bar::class);
+    }
 }

doc/book/config-abstract-factory.md

@@ -0,0 +1,120 @@
+# Config Abstract Factory
+
+You can simplify the process of creating factories by adding the 
+`ConfigAbstractFactory` to your service manager. This allows you to define
+services using a configuration map, rather than having to create separate 
+factories for all your services. 
+
+## Enabling
+You can enable the `ConfigAbstractFactory` in the same way that you would enable 
+any other abstract factory - in your own code:
+
+```php
+$serviceManager = new ServiceManager();
+$serviceManager->addAbstractFactory(new ConfigAbstractFactory());
+```
+
+Or within any config provider using:
+
+```php
+return [
+    'service_manager' => [
+        'abstract_factories' => [
+            ConfigAbstractFactory::class,
+        ],
+    ],
+];
+```
+
+It is also possible to use the config abstract factory in the traditional way; by registering
+it as a factory for a specific class. This marginally improves performance but loses
+the benefit of not needing to create a factory key for all of you configured factories:
+
+```php
+return [
+    'service_manager' => [
+        'factories' => [
+            SomeCustomClass::class => ConfigAbstractFactory::class,
+        ],
+    ],
+];
+```
+
+## Configuring
+
+Configuration is done through the `config` service manager key, in an array with
+the key `Zend\ServiceManager\AbstractFactory\ConfigAbstractFactory`. If you are using 
+config merging from the MVC/ModuleManager, in this just means that you can 
+add a `ConfigAbstractFactory::class` key to your merged config which contains service
+definitions, where the key is the service name (typically the FQNS of the class you are 
+defining), and the value is an array of it's dependencies, also defined as container keys.
+
+```php
+use Zend\ServiceManager\AbstractFactory\ConfigAbstractFactory;
+
+return [
+    ConfigAbstractFactory::class => [
+        MyInvokableClass::class => [],
+        MySimpleClass::class => [
+            Logger::class,          
+        ],
+        Logger::class => [
+            Handler::class,
+        ],
+    ],
+];
+```
+
+The definition tells the service manager how this abstract factory should manage dependencies in
+the classes defined. In the above example, `MySimpleClass` has a single dependency on a `Logger`
+instance. The abstract factory will simply look to fulfil that dependency by calling a `get` 
+call with that key on the service manager it is attached to. In this way, you can create the 
+correct tree of dependencies to successfully return any given service. Note that `Handler` does not have a 
+configuration for the abstract factory, but this would work if `Handler` had a traditional factory and 
+can be created by this service manager.
+
+For a better example, consider the following classes:
+
+```php
+class UserMapper
+{
+    public function __construct(Adapter $db, Cache $cache) {}
+}
+
+class Adapter
+{
+    public function __construct(array $config) {}
+}
+
+class Cache
+{
+    public function __construct(CacheAdapter $cacheAdapter) {}
+}
+
+class CacheAdapter
+{
+}
+```
+
+In this case, we can define the configuration for these classes as follows:
+
+```php
+// config/autoload/dependencies.php or anywhere that gets merged into global config
+return [
+    ConfigAbstractFactory::class => [
+        CacheAdapter::class => [], // no dependencies
+        Cache::class => [
+            CacheAdapter::class, // dependency on the CacheAdapter key defined above
+        ],
+        UserMapper::class => [
+            Adapter::class, // will be called using normal factory defined below
+            Cache::class, // defined above and will be created using this abstract factory
+        ],
+    ],
+    'service_manager' => [
+        'factories' => [
+            Adapter::class => AdapterFactory::class, // normal factory not using above config
+        ],
+    ],    
+],
+```

src/AbstractFactory/ConfigAbstractFactory.php

@@ -0,0 +1,73 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @link      http://github.com/zendframework/zf2 for the canonical source repository
+ * @copyright Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace Zend\ServiceManager\AbstractFactory;
+
+use Zend\ServiceManager\Exception\ServiceNotCreatedException;
+use Zend\ServiceManager\Factory\AbstractFactoryInterface;
+
+final class ConfigAbstractFactory implements AbstractFactoryInterface
+{
+
+    /**
+     * Factory can create the service if there is a key for it in the config
+     *
+     * {@inheritdoc}
+     */
+    public function canCreate(\Interop\Container\ContainerInterface $container, $requestedName)
+    {
+        if (!$container->has('config') || !array_key_exists(self::class, $container->get('config'))) {
+            return false;
+        }
+        $config = $container->get('config');
+        $dependencies = $config[self::class];
+
+        return is_array($dependencies) && array_key_exists($requestedName, $dependencies);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function __invoke(\Interop\Container\ContainerInterface $container, $requestedName, array $options = null)
+    {
+        if (!$container->has('config')) {
+            throw new ServiceNotCreatedException('Cannot find a config array in the container');
+        }
+
+        $config = $container->get('config');
+
+        if (!is_array($config)) {
+            throw new ServiceNotCreatedException('Config must be an array');
+        }
+
+        if (!array_key_exists(self::class, $config)) {
+            throw new ServiceNotCreatedException('Cannot find a `' . self::class . '` key in the config array');
+        }
+
+        $dependencies = $config[self::class];
+
+        if (!is_array($dependencies)
+            || !array_key_exists($requestedName, $dependencies)
+            || !is_array($dependencies[$requestedName])
+        ) {
+            throw new ServiceNotCreatedException('Dependencies config must exist and be an array');
+        }
+
+        $serviceDependencies = $dependencies[$requestedName];
+
+        if ($serviceDependencies !== array_values(array_map('strval', $serviceDependencies))) {
+            $problem = json_encode(array_map('gettype', $serviceDependencies));
+            throw new ServiceNotCreatedException('Service message must be an array of strings, ' . $problem . ' given');
+        }
+
+        $arguments = array_map([$container, 'get'], $serviceDependencies);
+
+        return new $requestedName(...$arguments);
+    }
+}