Merge branch 'feature/23-metadata-factories'

Close #23

Author: weierophinney

CHANGELOG.md

@@ -4,6 +4,47 @@ All notable changes to this project will be documented in this file, in reverse
 
 Versions prior to 0.4.0 were released as the package "weierophinney/hal".
 
+## 0.6.0 - 2017-11-07
+
+### Added
+
+- Nothing.
+
+### Changed
+
+- [#23](https://github.com/zendframework/zend-expressive-hal/pull/23) modifies
+  how the resource generator factory adds strategies and maps metadata to
+  strategies. It now adds the following factories under the
+  `Zend\Expressive\Hal\Metadata` namespace:
+
+  - `RouteBasedCollectionMetadataFactory`
+  - `RouteBasedResourceMetadataFactory`
+  - `UrlBasedCollectionMetadataFactory`
+  - `UrlBasedResourceMetadataFactory`
+
+  Each implements a new `MetadataFactoryInterface` under that same namespace
+  that accepts the requested metadata type name and associated metadata in order
+  to create an `AbstractMetadata` instance. Metadata types are mapped to their
+  factories under the `zend-expressive-hal.metadata-factories` key.
+
+  Strategies are now configured as metadata => strategy class pairings under the
+  `zend-expressive-hal.resource-generator.strategies` key.
+
+  In both cases, defaults that mimic previous behavior are provided via the
+  `ConfigProvider`.
+
+### Deprecated
+
+- Nothing.
+
+### Removed
+
+- Nothing.
+
+### Fixed
+
+- Nothing.
+
 ## 0.5.1 - 2017-11-07
 
 ### Added

docs/book/cookbook/generating-custom-resources.md

@@ -0,0 +1,73 @@
+# Generating custom resources
+
+The `ResourceGenerator` allows composing `Zend\Expressive\Hal\ResourceGenerator\StrategyInterface`
+instances. The `StrategyInterface` defines the following:
+
+```php
+namespace Zend\Expressive\Hal\ResourceGenerator;
+
+use Psr\Http\Message\ServerRequestInterface;
+use Zend\Expressive\Hal\HalResource;
+use Zend\Expressive\Hal\Metadata;
+use Zend\Expressive\Hal\ResourceGenerator;
+
+interface StrategyInterface
+{
+    /**
+     * @param object $instance Instance from which to create Resource.
+     * @throws Exception\UnexpectedMetadataTypeException for metadata types the
+     *     strategy cannot handle.
+     */
+    public function createResource(
+        $instance,
+        Metadata\AbstractMetadata $metadata,
+        ResourceGenerator $resourceGenerator,
+        ServerRequestInterface $request
+    ) : HalResource;
+}
+```
+
+When you register a strategy, you will map a metadata type to the strategy; the
+`ResourceGenerator` will then call your strategy whenever it encounteres
+metadata of that type.
+
+```php
+$resourceGenerator->addStrategy(CustomMetadata::class, CustomStrategy::class);
+
+// or:
+$resourceGenerator->addStrategy(CustomMetadata::class, $strategyInstance);
+```
+
+You can also add your strategies via the configuration:
+```php
+return [
+    'zend-expressive-hal' => [
+        'resource-generator' => [
+            'strategies' => [
+                CustomMetadata::class => CustomStrategy::class,
+            ],
+        ],
+    ],
+];
+```
+
+If a strategy already is mapped for the given metadata type, this method will
+override it.
+
+To facilitate common operations, this library provides two traits,
+`Zend\Expressive\Hal\ResourceGenerator\ExtractCollectionTrait` and
+`Zend\Expressive\Hal\ResourceGenerator\ExtractInstanceTrait`; inspect these if you
+decide to write your own strategies.
+
+In order for the `MetadataMap` to be able to use your `CustomMetadata` you need to register 
+a factory (implementing `Zend\Expressive\Hal\Metadata\MetadataFactoryInterface`) for it.
+You can register them via the configuration:
+```php
+return [
+    'zend-expressive-hal' => [
+        'metadata-factories' => [
+            CustomMetadata::class => CustomMetadataFactory::class,
+        ],
+    ],
+];
+```

docs/book/resource-generator.md

@@ -149,51 +149,3 @@ $resource = $resourceGenerator->fromObject($book, $request);
 (Where `$request` is a `Psr\Http\Message\ServerRequestInterface` instance; the
 instance is passed along to the `LinkGenerator` in order to generate route-based
 URIs for `Link` instances.)
-
-### Customizing resource generation
-
-The `ResourceGenerator` allows composing `Zend\Expressive\Hal\ResourceGenerator\StrategyInterface`
-instances. The `StrategyInterface` defines the following:
-
-```php
-namespace Zend\Expressive\Hal\ResourceGenerator;
-
-use Psr\Http\Message\ServerRequestInterface;
-use Zend\Expressive\Hal\HalResource;
-use Zend\Expressive\Hal\Metadata;
-use Zend\Expressive\Hal\ResourceGenerator;
-
-interface StrategyInterface
-{
-    /**
-     * @param object $instance Instance from which to create Resource.
-     * @throws Exception\UnexpectedMetadataTypeException for metadata types the
-     *     strategy cannot handle.
-     */
-    public function createResource(
-        $instance,
-        Metadata\AbstractMetadata $metadata,
-        ResourceGenerator $resourceGenerator,
-        ServerRequestInterface $request
-    ) : HalResource;
-}
-```
-
-When you register a strategy, you will map a metadata type to the strategy; the
-`ResourceGenerator` will then call your strategy whenever it encounteres
-metadata of that type.
-
-```php
-$resourceGenerator->addStrategy(CustomMetadata::class, CustomStrategy::class);
-
-// or:
-$resourceGenerator->addStrategy(CustomMetadata::class, $strategyInstance);
-```
-
-If a strategy already is mapped for the given metadata type, this method will
-override it.
-
-To facilitate common operations, this library provides two traits,
-`Zend\Expressive\Hal\ResourceGenerator\ExtractCollectionTrait` and
-`Zend\Expressive\Hal\ResourceGenerator\ExtractInstanceTrait`; inspect these if you
-decide to write your own strategies.

mkdocs.yml

@@ -7,6 +7,7 @@ pages:
       - "HAL": hal.md
       - "Links and Resources": links-and-resources.md
       - "Generating Resources": resource-generator.md
+      - "Custom Resources": generating-custom-resources.md
       - "Representations": representations.md
       - "Factories": factories.md
     - Cookbook:

src/ConfigProvider.php

@@ -7,27 +7,73 @@
 
 namespace Zend\Expressive\Hal;
 
+use Zend\Expressive\Hal\LinkGenerator\ExpressiveUrlGenerator;
+use Zend\Expressive\Hal\LinkGenerator\UrlGeneratorInterface;
+use Zend\Expressive\Hal\Metadata\MetadataMap;
+use Zend\Expressive\Hal\Metadata\RouteBasedCollectionMetadata;
+use Zend\Expressive\Hal\Metadata\RouteBasedCollectionMetadataFactory;
+use Zend\Expressive\Hal\Metadata\RouteBasedResourceMetadata;
+use Zend\Expressive\Hal\Metadata\RouteBasedResourceMetadataFactory;
+use Zend\Expressive\Hal\Metadata\UrlBasedCollectionMetadata;
+use Zend\Expressive\Hal\Metadata\UrlBasedCollectionMetadataFactory;
+use Zend\Expressive\Hal\Metadata\UrlBasedResourceMetadata;
+use Zend\Expressive\Hal\Metadata\UrlBasedResourceMetadataFactory;
+use Zend\Expressive\Hal\ResourceGenerator\RouteBasedCollectionStrategy;
+use Zend\Expressive\Hal\ResourceGenerator\RouteBasedResourceStrategy;
+use Zend\Expressive\Hal\ResourceGenerator\UrlBasedCollectionStrategy;
+use Zend\Expressive\Hal\ResourceGenerator\UrlBasedResourceStrategy;
+
 class ConfigProvider
 {
     public function __invoke() : array
     {
         return [
-            'dependencies' => $this->getDependencies(),
+            'dependencies'        => $this->getDependencies(),
+            'zend-expressive-hal' => $this->getHalConfig(),
         ];
     }
 
     public function getDependencies() : array
     {
         return [
             'aliases' => [
-                LinkGenerator\UrlGeneratorInterface::class => LinkGenerator\ExpressiveUrlGenerator::class,
+                UrlGeneratorInterface::class => LinkGenerator\ExpressiveUrlGenerator::class,
             ],
             'factories' => [
-                HalResponseFactory::class => HalResponseFactoryFactory::class,
-                LinkGenerator::class => LinkGeneratorFactory::class,
-                LinkGenerator\ExpressiveUrlGenerator::class => LinkGenerator\ExpressiveUrlGeneratorFactory::class,
-                Metadata\MetadataMap::class => Metadata\MetadataMapFactory::class,
-                ResourceGenerator::class => ResourceGeneratorFactory::class,
+                HalResponseFactory::class     => HalResponseFactoryFactory::class,
+                LinkGenerator::class          => LinkGeneratorFactory::class,
+                ExpressiveUrlGenerator::class => LinkGenerator\ExpressiveUrlGeneratorFactory::class,
+                MetadataMap::class            => Metadata\MetadataMapFactory::class,
+                ResourceGenerator::class      => ResourceGeneratorFactory::class,
+            ],
+            'invokables' => [
+                RouteBasedCollectionStrategy::class => RouteBasedCollectionStrategy::class,
+                RouteBasedResourceStrategy::class   => RouteBasedResourceStrategy::class,
+
+                UrlBasedCollectionStrategy::class   => UrlBasedCollectionStrategy::class,
+                UrlBasedResourceStrategy::class     => UrlBasedResourceStrategy::class
+            ],
+        ];
+    }
+
+    public function getHalConfig() : array
+    {
+        return [
+            'resource-generator' => [
+                'strategies' => [ // The registered strategies and their metadata types
+                    RouteBasedCollectionMetadata::class => RouteBasedCollectionStrategy::class,
+                    RouteBasedResourceMetadata::class   => RouteBasedResourceStrategy::class,
+
+                    UrlBasedCollectionMetadata::class   => UrlBasedCollectionStrategy::class,
+                    UrlBasedResourceMetadata::class     => UrlBasedResourceStrategy::class,
+                ],
+            ],
+            'metadata-factories' => [ // The factories for the metadata types
+                RouteBasedCollectionMetadata::class => RouteBasedCollectionMetadataFactory::class,
+                RouteBasedResourceMetadata::class   => RouteBasedResourceMetadataFactory::class,
+
+                UrlBasedCollectionMetadata::class   => UrlBasedCollectionMetadataFactory::class,
+                UrlBasedResourceMetadata::class     => UrlBasedResourceMetadataFactory::class,
             ],
         ];
     }

src/Metadata/Exception/InvalidConfigException.php

@@ -9,6 +9,7 @@
 
 use RuntimeException;
 use Zend\Expressive\Hal\Metadata\AbstractMetadata;
+use Zend\Expressive\Hal\Metadata\MetadataFactoryInterface;
 use Zend\Expressive\Hal\Metadata\MetadataMap;
 use Zend\Expressive\Hal\Metadata\MetadataMapFactory;
 
@@ -64,14 +65,22 @@ public static function dueToNonMetadataClass(string $class) : self
         ));
     }
 
-    public static function dueToUnrecognizedMetadataClass(string $class, string $classWithoutNamespace) : self
+    public static function dueToInvalidMetadataFactoryClass(string $class) : self
     {
         return new self(sprintf(
-            '%s does not know how to construct a %s instance; please extend the '
-            . 'factory and create a "create%s" method',
-            MetadataMapFactory::class,
+            '%s is not a valid metadata factory class; does not implement %s',
             $class,
-            $classWithoutNamespace
+            MetadataFactoryInterface::class
+        ));
+    }
+
+    public static function dueToUnrecognizedMetadataClass(string $class) : self
+    {
+        return new self(sprintf(
+            '%s does not know how to construct a %s instance; please provide a '
+            . 'factory in your configuration',
+            MetadataMapFactory::class,
+            $class
         ));
     }
 

src/Metadata/MetadataFactoryInterface.php

@@ -0,0 +1,32 @@
+<?php
+/**
+ * @see       https://github.com/zendframework/zend-expressive-hal for the canonical source repository
+ * @copyright Copyright (c) 2017 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   https://github.com/zendframework/zend-expressive-hal/blob/master/LICENSE.md New BSD License
+ */
+
+namespace Zend\Expressive\Hal\Metadata;
+
+/**
+ * Interface describing factories that create metadata instances.
+ */
+interface MetadataFactoryInterface
+{
+    /**
+     * Creates a Metadata based on the MetadataMap configuration.
+     *
+     * @param string $requestedName The requested name of the metadata type
+     * @param array  $metadata      The metadata should have the following structure:
+     *     <code>
+     *     [
+     *         '__class__' => 'Fully qualified class name of an AbstractMetadata type',
+     *         // additional key/value pairs as required by the metadata type.
+     *     ]
+     *     </code>
+     *
+     *     The '__class__' key decides which AbstractMetadata should be used
+     *     (and which corresponding factory will be called to create it).
+     * @return AbstractMetadata
+     */
+    public function createMetadata(string $requestedName, array $metadata) : AbstractMetadata;
+}