Skip to content
This repository has been archived by the owner on Jan 30, 2020. It is now read-only.

Commit

Permalink
Merge pull request #89 from weierophinney/feature/hydrator-suffix
Browse files Browse the repository at this point in the history
Add the suffix "Hydrator" to all hydrators
  • Loading branch information
Ocramius committed Dec 5, 2018
2 parents f63d038 + 01723e2 commit aeb4c53
Show file tree
Hide file tree
Showing 31 changed files with 753 additions and 636 deletions.
18 changes: 17 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,17 @@ All notable changes to this project will be documented in this file, in reverse

### Changed

- [#89](https://github.com/zendframework/zend-hydrator/pull/89) renames the various hydrators to use the "Hydrator" suffix:
- `ArraySerializable` becomes `ArraySerializableHydrator`
- `ClassMethods` becomes `ClassMethodsHydrator`
- `ObjectProperty` becomes `ObjectPropertyHydrator`
- `Reflection` becomes `ReflectionHydrator`
In each case, the original class was re-added to the repository as a
deprecated extension of the new class, to be removed in version 4.0.0.

Aliases resolving the original class name to the new class were also added to
the `HydratorPluginManager` to ensure you can still obtain instances.

- [#83](https://github.com/zendframework/zend-hydrator/pull/83) renames `Zend\Hydrator\FilterEnabledInterface` to `Zend\Hydrator\Filter\FilterEnabledInterface` (new namespace).

- [#83](https://github.com/zendframework/zend-hydrator/pull/83) renames `Zend\Hydrator\NamingStrategyEnabledInterface` to `Zend\Hydrator\NamingStrategy\NamingStrategyEnabledInterface` (new namespace).
Expand Down Expand Up @@ -70,7 +81,12 @@ All notable changes to this project will be documented in this file, in reverse

### Deprecated

- Nothing.
- [#89](https://github.com/zendframework/zend-hydrator/pull/89) deprecates the
following classes, which will be removed in 4.0.0:
- `Zend\Hydrator\ArraySerializable` (becomes `ArraySerializableHydrator`)
- `Zend\Hydrator\ClassMethods` (becomes `ClassMethodsHydrator`)
- `Zend\Hydrator\ObjectProperty` (becomes `ObjectPropertyHydrator`)
- `Zend\Hydrator\Reflection` (becomes `ReflectionHydrator`)

### Removed

Expand Down
28 changes: 14 additions & 14 deletions docs/book/v3/filter.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,19 +28,19 @@ returns false, you'll not see them again.

### Zend\\Hydrator\\Filter\\GetFilter

This filter is used in the `ClassMethods` hydrator to decide which getters will
This filter is used in the `ClassMethodsHydrator` to decide which getters will
be extracted. It checks if the key to extract starts with `get` or the object
contains a method beginning with `get` (e.g., `Zend\Foo\Bar::getFoo`).

### Zend\\Hydrator\\Filter\\HasFilter

This filter is used in the `ClassMethods` hydrator to decide which `has` methods
This filter is used in the `ClassMethodsHydrator` to decide which `has` methods
will be extracted. It checks if the key to extract begins with `has` or the
object contains a method beginning with `has` (e.g., `Zend\Foo\Bar::hasFoo`).

### Zend\\Hydrator\\Filter\\IsFilter

This filter is used in the `ClassMethods` hydrator to decide which `is` methods
This filter is used in the `ClassMethodsHydrator` to decide which `is` methods
will be extracted. It checks if the key to extract begins with `is` or the
object contains a method beginning with `is` (e.g., `Zend\Foo\Bar::isFoo`).

Expand All @@ -55,7 +55,7 @@ the behavior.

### Zend\\Hydrator\\Filter\\NumberOfParameterFilter

This filter is used in the `ClassMethods` hydrator to check the number of
This filter is used in the `ClassMethodsHydrator` to check the number of
parameters. By convention, the `get`, `has` and `is` methods do not get any
parameters - but it may happen. You can add your own number of required
parameters, simply add the number to the constructor. The default value is 0. If
Expand Down Expand Up @@ -132,7 +132,7 @@ $composite->addFilter(
$hydrator->addFilter('excludes', $composite, FilterComposite::CONDITION_AND);

// Internal
if (( // default composite inside the ClassMethods hydrator:
if (( // default composite inside the ClassMethodsHydrator:
($getFilter
|| $hasFilter
|| $isFilter
Expand All @@ -148,7 +148,7 @@ if (( // default composite inside the ClassMethods hydrator:
}
```

If you perform this on the `ClassMethods` hydrator, all getters will get
If you perform this on the `ClassMethodsHydrator`, all getters will get
extracted, except for `getServiceManager()` and `getEventManager()`.

## Using the provider interface
Expand Down Expand Up @@ -222,7 +222,7 @@ Class Foo implements FilterProviderInterface
}
}

$hydrator = new ClassMethods(false);
$hydrator = new ClassMethodsHydrator(false);
$extractedArray = $hydrator->extract(new Foo());
```

Expand All @@ -231,7 +231,7 @@ excluded from extraction.

> ### Note
>
> All pre-registered filters from the `ClassMethods` hydrator are ignored when
> All pre-registered filters from the `ClassMethodsHydrator` hydrator are ignored when
> this interface is used. More on those methods below.
## Filter-enabled hydrators and the composite filter
Expand Down Expand Up @@ -294,8 +294,8 @@ by a `Zend\Hydrator\Filter\FilterComposite`; the various `addFilter()`,

`AbstractHydrator`, on which all the hydrators shipped in this package are
built, implements `FilterEnabledInterface`. Of the hydrators shipped, only one,
`ClassMethods`, defines any filters from the outset. Its constructor includes
the following:
`ClassMethodsHydrator`, defines any filters from the outset. Its constructor
includes the following:

```php
$this->filterComposite->addFilter('is', new IsFilter());
Expand All @@ -310,11 +310,11 @@ $this->filterComposite->addFilter(

### Remove filters

If you want to tell a filter-enabled hydrator such as `ClassMethods` not to
extract methods that start with `is`, remove the related filter:
If you want to tell a filter-enabled hydrator such as `ClassMethodsHydrator` not
to extract methods that start with `is`, remove the related filter:

```php
$hydrator = new ClassMethods(false);
$hydrator = new ClassMethodsHydrator(false);
$hydrator->removeFilter('is');
```

Expand All @@ -333,7 +333,7 @@ $hydrator->addFilter('len', function($property) {
```

By default, every filter you add will be added with a conditional `OR`. If you
want to add it with `AND` (such as the `ClassMethods` hydrator does with its
want to add it with `AND` (such as the `ClassMethodsHydrator` does with its
composed `NumberOfParameterFilter`, demonstrated above) provide the conditon as
the third argument to `addFilter`:

Expand Down
18 changes: 17 additions & 1 deletion docs/book/v3/migration.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,22 @@ The following interfaces were renamed:
- `Zend\Hydrator\NamingStrategyEnabledInterface` becomes `Zend\Hydrator\NamingStrategy\NamingStrategyEnabledInterface`.
- `Zend\Hydrator\StrategyEnabledInterface` becomes `Zend\Hydrator\Strategy\StrategyEnabledInterface`.

## Renamed classes

The following classes were renamed:

- `Zend\Hydrator\ArraySerializable` becomes `Zend\Hydrator\ArraySerializableHydrator`
- `Zend\Hydrator\ClassMethods` becomes `Zend\Hydrator\ClassMethodsHydrator`
- `Zend\Hydrator\ObjectProperty` becomes `Zend\Hydrator\ObjectPropertyHydrator`
- `Zend\Hydrator\Reflection` becomes `Zend\Hydrator\ReflectionHydrator`

In each case, a class named after the original has been created as a deprecated
extension of the new class. This means you can continue to use the old class
names, but only until version 4, at which point they will be removed.

Additionally, aliases for the old class names have been added to the
`HydratorPluginManager`, pointing to services named after the new class names.

## Interface changes

Each of the interfaces provided by this package have been updated to add
Expand Down Expand Up @@ -118,7 +134,7 @@ typehints:
- `onHydrate(HydrateEvent $event)` becomes `onHydrate(HydrateEvent $event) : object`
- `onExtract(ExtractEvent $event)` becomes `onExtract(ExtractEvent $event) : array`

- `Zend\Hydrator\ClassMethods`:
- `Zend\Hydrator\ClassMethodsHydrator` (was `Zend\Hydrator\ClassMethods`):
- `__construct($underscoreSeparatedKeys = true, $methodExistsCheck = false)` becomes `__construct(bool $underscoreSeparatedKeys = true, bool $methodExistsCheck = false)`
- `setUnderscoreSeparatedKeys($underscoreSeparatedKeys)` becomes `setUnderscoreSeparatedKeys(bool $underscoreSeparatedKeys) : void`
- `getUnderscoreSeparatedKeys()` becomes `getUnderscoreSeparatedKeys() : bool`
Expand Down
4 changes: 2 additions & 2 deletions docs/book/v3/naming-strategy/composite-naming-strategy.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ $namingStrategy = new Zend\Hydrator\NamingStrategy\CompositeNamingStrategy([
'barBat' => $underscoreNamingStrategy,
]);

$hydrator = new Zend\Hydrator\ObjectProperty();
$hydrator = new Zend\Hydrator\ObjectPropertyHydrator();
$hydrator->setNamingStrategy($namingStrategy);

$foo = new Foo();
Expand Down Expand Up @@ -64,7 +64,7 @@ $namingStrategy = new Zend\Hydrator\NamingStrategy\CompositeNamingStrategy([
'bar_bat' => $underscoreNamingStrategy,
]);

$hydrator = new Zend\Hydrator\ObjectProperty();
$hydrator = new Zend\Hydrator\ObjectPropertyHydrator();
$hydrator->setNamingStrategy($namingStrategy);

$foo = new Foo();
Expand Down
2 changes: 1 addition & 1 deletion docs/book/v3/naming-strategy/identity-naming-strategy.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ class Foo
}

$namingStrategy = new Zend\Hydrator\NamingStrategy\IdentityNamingStrategy();
$hydrator = new Zend\Hydrator\ObjectProperty();
$hydrator = new Zend\Hydrator\ObjectPropertyHydrator();
$hydrator->setNamingStrategy($namingStrategy);

$foo = new Foo();
Expand Down
2 changes: 1 addition & 1 deletion docs/book/v3/naming-strategy/map-naming-strategy.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ $namingStrategy = Zend\Hydrator\NamingStrategy\MapNamingStrategy::createFromHydr
'foo' => 'bar',
'baz' => 'bash',
]);
$hydrator = new Zend\Hydrator\ObjectProperty();
$hydrator = new Zend\Hydrator\ObjectPropertyHydrator();
$hydrator->setNamingStrategy($namingStrategy);

$foo = new Foo();
Expand Down
2 changes: 1 addition & 1 deletion docs/book/v3/naming-strategy/underscore-naming-strategy.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ class Foo
public $fooBar;
}

$hydrator = new Zend\Hydrator\ObjectProperty();
$hydrator = new Zend\Hydrator\ObjectPropertyHydrator();
$hydrator->setNamingStrategy(new Zend\Hydrator\NamingStrategy\UnderscoreNamingStrategy());

$foo = new Foo();
Expand Down
16 changes: 8 additions & 8 deletions docs/book/v3/quick-start.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ Usage involves instantiating the hydrator, and then passing information to it.

```php
use Zend\Hydrator;
$hydrator = new Hydrator\ArraySerializable();
$hydrator = new Hydrator\ArraySerializableHydrator();

// To hydrate an object from values in an array:
$object = $hydrator->hydrate($data, new ArrayObject());
Expand All @@ -73,12 +73,12 @@ $data = $hydrator->extract($object);

## Available Implementations

### Zend\\Hydrator\\ArraySerializable
### Zend\\Hydrator\\ArraySerializableHydrator

Follows the definition of `ArrayObject`. Objects must implement either the `exchangeArray()` or
`populate()` methods to support hydration, and the `getArrayCopy()` method to support extraction.

### Zend\\Hydrator\\ClassMethods
### Zend\\Hydrator\\ClassMethodsHydrator

Any data key matching a setter method will be called in order to hydrate; any method matching a
getter method will be called for extraction, according to the following rules:
Expand All @@ -95,8 +95,8 @@ on.

```php
// Instantiate each hydrator you wish to delegate to
$albumHydrator = new Zend\Hydrator\ClassMethods;
$artistHydrator = new Zend\Hydrator\ClassMethods;
$albumHydrator = new Zend\Hydrator\ClassMethodsHydrator();
$artistHydrator = new Zend\Hydrator\ClassMethodsHydrator();

// Map the entity class name to the hydrator using the HydratorPluginManager.
// In this case we have two entity classes, "Album" and "Artist".
Expand All @@ -112,14 +112,14 @@ $array = $delegating->extract(new Artist());
$artist = $delegating->hydrate($data, new Artist());
```

### Zend\\Hydrator\\ObjectProperty
### Zend\\Hydrator\\ObjectPropertyHydrator

Any data key matching a publicly accessible property will be hydrated; any public properties
will be used for extraction.

### Zend\\Hydrator\\Reflection
### Zend\\Hydrator\\ReflectionHyrator

Similar to the `ObjectProperty` hydrator, but uses [PHP's reflection API](http://php.net/manual/en/intro.reflection.php)
Similar to the `ObjectPropertyHydrator`, but uses [PHP's reflection API](http://php.net/manual/en/intro.reflection.php)
to hydrate or extract properties of any visibility. Any data key matching an
existing property will be hydrated; any existing properties will be used for
extraction.
7 changes: 4 additions & 3 deletions docs/book/v3/strategy.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,8 +121,9 @@ only be used for `extract` operations.
### Zend\\Hydrator\\Strategy\\SerializableStrategy

`SerializableStrategy` provides the functionality backing
`Zend\Hydrator\ArraySerializable`. You can use it with custom implementations
for `Zend\Serializer\Adapter\AdapterInterface` if you want to as well.
`Zend\Hydrator\ArraySerializableHydrator`. You can use it with custom
implementations for `Zend\Serializer\Adapter\AdapterInterface` if you want to as
well.

### Zend\\Hydrator\\Strategy\\StrategyChain

Expand Down Expand Up @@ -190,7 +191,7 @@ $foo = new Foo();
$foo->setFoo('bar');
$foo->setBar('foo');

$hydrator = new ClassMethods();
$hydrator = new ClassMethodsHydrator();
$hydrator->addStrategy('foo', new Rot13Strategy());
```

Expand Down
88 changes: 5 additions & 83 deletions src/ArraySerializable.php
Original file line number Diff line number Diff line change
@@ -1,95 +1,17 @@
<?php
/**
* @see https://github.com/zendframework/zend-hydrator for the canonical source repository
* @copyright Copyright (c) 2010-2018 Zend Technologies USA Inc. (http://www.zend.com)
* @copyright Copyright (c) 2018 Zend Technologies USA Inc. (https://www.zend.com)
* @license https://github.com/zendframework/zend-hydrator/blob/master/LICENSE.md New BSD License
*/

declare(strict_types=1);

namespace Zend\Hydrator;

use function array_merge;
use function is_callable;
use function method_exists;
use function sprintf;

class ArraySerializable extends AbstractHydrator
/**
* @deprecated since 3.0.0; to be removed in 4.0.0. Use ArraySerializableHydrator instead.
*/
class ArraySerializable extends ArraySerializableHydrator
{
/**
* Extract values from the provided object
*
* Extracts values via the object's getArrayCopy() method.
*
* {@inheritDoc}
* @throws Exception\BadMethodCallException for an $object not implementing getArrayCopy()
*/
public function extract(object $object) : array
{
if (! method_exists($object, 'getArrayCopy') || ! is_callable([$object, 'getArrayCopy'])) {
throw new Exception\BadMethodCallException(
sprintf('%s expects the provided object to implement getArrayCopy()', __METHOD__)
);
}

$data = $object->getArrayCopy();
$filter = $this->getFilter();

foreach ($data as $name => $value) {
if (! $filter->filter($name)) {
unset($data[$name]);
continue;
}

$extractedName = $this->extractName($name, $object);

// replace the original key with extracted, if differ
if ($extractedName !== $name) {
unset($data[$name]);
$name = $extractedName;
}

$data[$name] = $this->extractValue($name, $value, $object);
}

return $data;
}

/**
* Hydrate an object
*
* Hydrates an object by passing $data to either its exchangeArray() or
* populate() method.
*
* {@inheritDoc}
* @throws Exception\BadMethodCallException for an $object not implementing exchangeArray() or populate()
*/
public function hydrate(array $data, object $object)
{
$replacement = [];
foreach ($data as $key => $value) {
$name = $this->hydrateName($key, $data);
$replacement[$name] = $this->hydrateValue($name, $value, $data);
}

if (method_exists($object, 'exchangeArray') && is_callable([$object, 'exchangeArray'])) {
// Ensure any previously populated values not in the replacement
// remain following population.
if (method_exists($object, 'getArrayCopy') && is_callable([$object, 'getArrayCopy'])) {
$original = $object->getArrayCopy($object);
$replacement = array_merge($original, $replacement);
}
$object->exchangeArray($replacement);
return $object;
}

if (method_exists($object, 'populate') && is_callable([$object, 'populate'])) {
$object->populate($replacement);
return $object;
}

throw new Exception\BadMethodCallException(
sprintf('%s expects the provided object to implement exchangeArray() or populate()', __METHOD__)
);
}
}
Loading

0 comments on commit aeb4c53

Please sign in to comment.