Merge 7c83ac8 into f270cec

docs/book/v3/migration.md

@@ -30,6 +30,14 @@ The minimum supported version of zend-serializer (used by the
 The minimum supported version of zend-servicemanager (used by the
 `HydratorPluginManager`) is now 3.3.2.
 
+## Renamed interfaces
+
+The following interfaces were renamed:
+
+- `Zend\Hydrator\FilterEnabledInterface` becomes `Zend\Hydrator\Filter\FilterEnabledInterface`.
+- `Zend\Hydrator\NamingStrategyEnabledInterface` becomes `Zend\Hydrator\NamingStrategy\NamingStrategyEnabledInterface`.
+- `Zend\Hydrator\StrategyEnabledInterface` becomes `Zend\Hydrator\Strategy\StrategyEnabledInterface`.
+
 ## Interface changes
 
 Each of the interfaces provided by this package have been updated to add
@@ -38,7 +46,7 @@ on parameters and return values. These include:
 
 - `Zend\Hydrator\ExtractionInterface`:
   - `extract($object)` becomes `extract(object $object) : array`
-- `Zend\Hydrator\FilterEnabledInterface`:
+- `Zend\Hydrator\Filter\FilterEnabledInterface` (was `Zend\Hydrator\FilterEnabledInterface`):
   - `addFilter($name, $filter, $condition = Zend\Hydrator\Filter\FilterComposite::CONDITION_OR)` becomes `addFilter(string $name, $filter, int $condition = Zend\Hydrator\Filter\FilterComposite::CONDITION_OR) : void`
   - `hasFilter($name)` becomes `hasFilter(string $name) : bool`
   - `removeFilter($name)` becomes `removeFilter(string $name) : void`
@@ -53,11 +61,11 @@ on parameters and return values. These include:
   - `setOptions($options)` becomes `setOptions(iterable $options) : void`
 - `Zend\Hydrator\HydratorProviderInterface`:
   - `getHydratorConfig()` becomes `getHydratorConfig() : array`
-- `Zend\Hydrator\NamingStrategyEnabledInterface`:
+- `Zend\Hydrator\NamingStrategy\NamingStrategyEnabledInterface` (was `Zend\Hydrator\NamingStrategyEnabledInterface`):
   - `setNamingStrategy(Zend\Hydrator\NamingStrategy\NamingStrategyInterface $strategy)` becomes `setNamingStrategy(Zend\Hydrator\NamingStrategy\NamingStrategyInterface $strategy) : void`
   - `getNamingStrategy()` becomes `getNamingStrategy() : Zend\Hydrator\NamingStrategy\NamingStrategyInterface`
   - `removeNamingStrategy()` becomes `removeNamingStrategy() : void`
-- `Zend\Hydrator\StrategyEnabledInterface`:
+- `Zend\Hydrator\Strategy\StrategyEnabledInterface` (was `Zend\Hydrator\StrategyEnabledInterface`):
   - `addStrategy($name, Zend\Hydrator\Strategy\StrategyInterface $strategy)` becomes `addStrategy(string $name, Zend\Hydrator\Strategy\StrategyInterface $strategy) : void`
   - `getStrategy($name)` becomes `getStrategy(string $name) : Zend\Hydrator\Strategy\StrategyInterface`
   - `hasStrategy($name)` becomes `hasStrategy(string $name) : bool`

docs/book/v3/naming-strategy/intro.md

@@ -0,0 +1,88 @@
+# Naming Strategies
+
+Sometimes, the representation of a property should not share the same name as
+the property itself. As an example, when serializing an object for a JSON
+payload, you may want to convert camelCase properties to underscore_separated
+properties, and vice versa when deserializing JSON to an object.
+
+To make that possible, zend-hydrator provides _naming strategies_. These are
+similar to [strategies](../strategies.md), but instead of operating on the
+_value_, they operate on the _name_.
+
+## NamingStrategyInterface
+
+Naming strategies implement `Zend\Hydrator\NamingStrategy\NamingStrategyInterface`:
+
+```php
+namespace Zend\Hydrator\NamingStrategy;
+
+/**
+ * Allow property extraction / hydration for hydrator
+ */
+interface NamingStrategyInterface
+{
+    /**
+     * Converts the given name so that it can be extracted by the hydrator.
+     *
+     * @param null|mixed[] $data The original data for context.
+     */
+    public function hydrate(string $name, ?array $data = null) : string;
+
+    /**
+     * Converts the given name so that it can be hydrated by the hydrator.
+     *
+     * @param null|object $object The original object for context.
+     */
+    public function extract(string $name, ?object $object = null) : string;
+}
+```
+
+## Providing naming strategies
+
+Hydrators can indicate they will consume naming strategies, as well as allow
+registration of them, by implementing `Zend\Hydrator\NamingStrategy\NamingStrategyEnabledInterface`:
+
+```php
+namespace Zend\Hydrator\NamingStrategy;
+
+interface NamingStrategyEnabledInterface
+{
+    /**
+     * Sets the naming strategy.
+     */
+    public function setNamingStrategy(NamingStrategyInterface $strategy) : void;
+
+    /**
+     * Gets the naming strategy.
+     */
+    public function getNamingStrategy() : NamingStrategyInterface;
+
+    /**
+     * Checks if a naming strategy exists.
+     */
+    public function hasNamingStrategy() : bool;
+
+    /**
+     * Removes the naming strategy.
+     */
+    public function removeNamingStrategy() : void;
+}
+```
+
+We provide a default implementation of this interface via
+`Zend\Hydrator\NamingStrategy\NamingStrategyEnabledTrait`. Its
+`getNamingStrategy()` will lazy-load an `IdentityNamingStrategy` if none has
+been previously registered.
+
+`AbstractHydrator` uses `NamingStategyEnabledTrait` to implement
+`NamingStrategyEnabledInterface`, and thus all shipped hydrators can consume
+naming strategies.
+
+## Shipped naming strategies
+
+We provide the following naming strategies:
+
+- [CompositeNamingStrategy](composite-naming-strategy.md)
+- [IdentityNamingStrategy](identity-naming-strategy.md)
+- [MapNamingStrategy](map-naming-strategy.md)
+- [UnderscoreNamingStrategy](underscore-naming-strategy.md)

docs/book/v3/strategy.md

@@ -1,87 +1,86 @@
 # Zend\\Hydrator\\Strategy
 
-You can add `Zend\Hydrator\Strategy\StrategyInterface` to any of the hydrators
-(except if it extends `Zend\Hydrator\AbstractHydrator` or implements
-`Zend\Hydrator\HydratorInterface` and `Zend\Hydrator\Strategy\StrategyEnabledInterface`)
-to manipulate the way how they behave on `extract()` and `hydrate()` for
-specific key / value pairs. This is the interface that needs to be implemented:
+You can compose `Zend\Hydrator\Strategy\StrategyInterface` instances in any of
+the hydrators to manipulate the way they behave on `extract()` and `hydrate()`
+for specific key/value pairs. The interface offers the following definitions:
 
 ```php
 namespace Zend\Hydrator\Strategy;
 
 interface StrategyInterface
 {
-     /**
-      * Converts the given value so that it can be extracted by the hydrator.
-      *
-      * @param mixed $value The original value.
-      * @return mixed Returns the value that should be extracted.
-      */
-     public function extract($value);
-
-     /**
-      * Converts the given value so that it can be hydrated by the hydrator.
-      *
-      * @param mixed $value The original value.
-      * @return mixed Returns the value that should be hydrated.
-      */
-     public function hydrate($value);
+    /**
+     * Converts the given value so that it can be extracted by the hydrator.
+     *
+     * @param  mixed       $value The original value.
+     * @param  null|object $object (optional) The original object for context.
+     * @return mixed       Returns the value that should be extracted.
+     */
+    public function extract($value, ?object $object = null);
+
+    /**
+     * Converts the given value so that it can be hydrated by the hydrator.
+     *
+     * @param  mixed      $value The original value.
+     * @param  null|array $data (optional) The original data for context.
+     * @return mixed      Returns the value that should be hydrated.
+     */
+    public function hydrate($value, ?array $data = null);
 }
 ```
 
-This interface is similar to `Zend\Hydrator\HydratorInterface`; the reason
-is that strategies provide a proxy implementation for `hydrate()` and `extract()`.
+This interface is similar to what the `Zend\Hydrator\ExtractionInterface` and
+`Zend\Hydrator\HydrationInterface` provide; the reason is that strategies
+provide a proxy implementation for `hydrate()` and `extract()` on individual
+values. For this reason, their return types are listed as mixed, versus as
+`array` and `object`, respectively.
 
 ## Adding strategies to the hydrators
 
-To allow strategies within your hydrator, `Zend\Hydrator\Strategy\StrategyEnabledInterface`
-provides the following methods:
+This package provides the interface `Zend\Hydrator\Strategy\StrategyEnabledInterface`.
+Hydrators can implement this interface, and then call on its `getStrategy()`
+method in order to extract or hydrate individual values. The interface has the
+following definition:
 
 ```php
-namespace Zend\Hydrator;
-
-use Zend\Hydrator\Strategy\StrategyInterface;
+namespace Zend\Hydrator\Strategy;
 
 interface StrategyEnabledInterface
 {
     /**
      * Adds the given strategy under the given name.
-     *
-     * @param string $name The name of the strategy to register.
-     * @param StrategyInterface $strategy The strategy to register.
-     * @return HydratorInterface
      */
-    public function addStrategy($name, StrategyInterface $strategy);
+    public function addStrategy(string $name, StrategyInterface $strategy) : void;
 
     /**
      * Gets the strategy with the given name.
-     *
-     * @param string $name The name of the strategy to get.
-     * @return StrategyInterface
      */
-    public function getStrategy($name);
+    public function getStrategy(string $name) : StrategyInterface;
 
     /**
      * Checks if the strategy with the given name exists.
-     *
-     * @param string $name The name of the strategy to check for.
-     * @return bool
      */
-    public function hasStrategy($name);
+    public function hasStrategy(string $name) : bool;
 
     /**
      * Removes the strategy with the given name.
-     *
-     * @param string $name The name of the strategy to remove.
-     * @return HydratorInterface
      */
-    public function removeStrategy($name);
+    public function removeStrategy(string $name) : void;
 }
 ```
 
-Every hydrator shipped by default provides this functionality;
-`AbstractHydrator` fully implements it as well. As such, if you want to use this
-functionality in your own hydrators, you should extend `AbstractHydrator`.
+We provide a default implementation of the interface via
+`Zend\Hydrator\Strategy\StrategyEnabledTrait`; it uses an array property to
+store and retrieve strategies by name. The `AbstractHydrator`, on which all
+shipped hydrators are based, uses this trait to provide an implementation of
+`StrategyEnabledInterface`. Internally, `AbstractHydrator` creates the methods
+`extractValue()` and `hydrateValue()`, which proxy to the strategy corresponding
+to the value if present.
+
+Additionally, the `StrategyEnabledTrait` will check to see if the class
+composing it also implements `Zend\Hydrator\NamingStrategy\NamingStrategyEnabledInterface`,
+and use the composed naming strategy, if present, to translate the property name
+prior to looking up a strategy for it.
 
 ## Available implementations
 
@@ -104,11 +103,11 @@ This is a strategy that allows you to pass in options for:
 and DateTime instances. The input and output formats can be provided as
 constructor arguments.
 
-As of version 2.4.1, this strategy now allows `DateTime` formats that use `!` to
-prepend the format, or `|` or `+` to append it; these ensure that, during
-hydration, the new `DateTime` instance created will set the time element
-accordingly. As a specific example, `Y-m-d|` will drop the time component,
-ensuring comparisons are based on a midnight time value.
+The strategy allows `DateTime` formats that use `!` to prepend the format, or
+`|` or `+` to append it; these ensure that, during hydration, the new `DateTime`
+instance created will set the time element accordingly. As a specific example,
+`Y-m-d|` will drop the time component, ensuring comparisons are based on a
+midnight time value.
 
 ### Zend\\Hydrator\\Strategy\\DefaultStrategy
 

mkdocs.yml

@@ -8,6 +8,7 @@ pages:
       - "Strategies": v3/strategy.md
       - "Aggregates": v3/aggregate.md
       - "Naming Strategies":
+        - "Introduction": v3/naming-strategy/intro.md
         - "Identity": v3/naming-strategy/identity-naming-strategy.md
         - "Mapping": v3/naming-strategy/map-naming-strategy.md
         - "Underscore Mapping": v3/naming-strategy/underscore-naming-strategy.md