Merge branch 'feature/146' into develop

Close #146

Author: weierophinney

CHANGELOG.md

@@ -6,7 +6,11 @@ All notable changes to this project will be documented in this file, in reverse
 
 ### Added
 
-- Nothing.
+- [#146](https://github.com/zendframework/zend-servicemanager/pull/146) adds
+  `Zend\ServiceManager\AbstractFactory\ConfigAbstractFactory`, which enables a
+  configuration-based approach to providing class dependencies when all
+  dependencies are services known to the `ServiceManager`. Please see
+  [the documentation](doc/book/config-abstract-factory.md) for details.
 
 ### Deprecated
 

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,144 @@
+# Config Abstract Factory
+
+- Since 3.2.0
+
+You can simplify the process of creating factories by registering
+`Zend\ServiceManager\AbstractFactory\ConfigAbstractFactory` with your service
+manager instance. This allows you to define services using a configuration map,
+rather than having to create separate factories for each of your services. 
+
+## Enabling the ConfigAbstractFactory
+
+Enable the `ConfigAbstractFactory` in the same way that you would enable 
+any other abstract factory.
+
+Programmatically:
+
+```php
+$serviceManager = new ServiceManager();
+$serviceManager->addAbstractFactory(new ConfigAbstractFactory());
+```
+
+Or within configuration:
+
+```php
+return [
+    // zend-mvc:
+    'service_manager' => [
+        'abstract_factories' => [
+            ConfigAbstractFactory::class,
+        ],
+    ],
+
+    // zend-expressive or ConfigProvider consumers:
+    'dependencies' => [
+        'abstract_factories' => [
+            ConfigAbstractFactory::class,
+        ],
+    ],
+];
+```
+
+Like all abstract factories starting in version 3, you may also use the config
+abstract factory as a mapped factory, registering it as a factory for a specific
+class:
+
+```php
+return [
+    'service_manager' => [
+        'factories' => [
+            SomeCustomClass::class => ConfigAbstractFactory::class,
+        ],
+    ],
+];
+```
+
+## Configuration
+
+Configuration should be provided via the `config` service, which should return
+an array or `ArrayObject`. `ConfigAbstractFactory` looks for a top-level key in
+this service named after itself (i.e., `Zend\ServiceManager\AbstractFactory\ConfigAbstractFactory`)
+that is an array value. Each item in the array:
+
+- Should have a key representing the service name (typically the fully
+  qualified class name)
+- Should have a value that is an array of each dependency, ordered using the
+  constructor argument order, and using service names registered with the
+  container.
+
+As an example:
+
+```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 `get()` with that key on the container
+passed to it. In this way, you can create the correct tree of
+dependencies to successfully return any given service.
+
+In the above example, note that the abstract factory configuration does not
+contain configuration for the `Handler` class. At first glance, this appears as
+if it will fail; however, if `Handler` is configured directly with the container
+already — for example, mapped to a custom factory — the service will
+be created and used as a dependency.
+
+As another, more complete 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
+        ],
+    ],    
+],
+```

mkdocs.yml

@@ -8,6 +8,7 @@ pages:
       - Delegators: delegators.md
       - 'Lazy services': lazy-services.md
       - 'Plugin managers': plugin-managers.md
+      - 'Configuration-based Abstract Factory': config-abstract-factory.md
     - 'Migration Guide': migration.md
 site_name: zend-servicemanager
 site_description: 'zend-servicemanager: factory-driven dependency injection container'

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);
+    }
+}