Skip to content

Commit 17a3dbf

Browse files
l-xusox
l-x
authored and
usox
committed
Extend README.md
(cherry picked from commit d4db20881ab9b2a6b79c1d1aa7c687bd80f3da93) Signed-off-by: Alexander Wühr <[email protected]>
1 parent eac5ea8 commit 17a3dbf

File tree

1 file changed

+189
-0
lines changed

1 file changed

+189
-0
lines changed

‎README.md

+189
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
# scn/hydrator
22

3+
[![Latest Stable Version](https://poser.pugx.org/scn/hydrator/v/stable)](https://packagist.org/packages/scn/hydrator)
34
[![Monthly Downloads](https://poser.pugx.org/scn/hydrator/d/monthly)](https://packagist.org/packages/scn/hydrator)
45
[![License](https://poser.pugx.org/scn/hydrator/license)](LICENSE)
56
[![Build Status](https://travis-ci.org/SC-Networks/Hydrator.svg?branch=master)](https://travis-ci.org/SC-Networks/Hydrator)
@@ -17,3 +18,191 @@ $ composer require scn/hydrator
1718
### Usage
1819

1920
See the `examples` folder for usage instructions by code.
21+
22+
#### Extraction
23+
24+
First of all you'll need a class that implements `\Scn\Hydrator\Config\ExtractorConfigInterface`.
25+
The only method `getExtractorProperties` has to return an array with string keys and callables as values.
26+
27+
The string keys of this array are used to craft the result of the extraction.
28+
29+
The corresponding callables must have the signature `callable(string $propertyName): mixed`. The `$propertyName`
30+
parameter will be the corresponding string key. You will usually not need this information.
31+
32+
If this callable is an instance of `\Closure`, its' `$this` and `static` context are bound to the entity object to
33+
extract. As a result of this the closure will have access to private and protected properties and methods of the entity.
34+
35+
A short example:
36+
37+
```php
38+
<?php
39+
40+
require_once 'vendor/autoload.php';
41+
42+
class ExtractorConfig implements \Scn\Hydrator\Configuration\ExtractorConfigInterface
43+
{
44+
45+
public function getExtractorProperties(): array
46+
{
47+
return [
48+
'property' => function (string $propertyName): string {
49+
return $this->privateProperty; // `$this` will be the entity to extract
50+
}
51+
];
52+
}
53+
}
54+
55+
class Entity
56+
{
57+
private $privateProperty = 'private value';
58+
}
59+
60+
$hydrator = new \Scn\Hydrator\Hydrator();
61+
62+
$result = $hydrator->extract(
63+
new ExtractorConfig(),
64+
new Entity()
65+
);
66+
67+
var_dump(assert($result === ['property' => 'private value'])); // -> bool(true)
68+
69+
```
70+
71+
### Hydration
72+
73+
For hydration you'll need a class implementing `\Scn\Hydrator\Configuration\HydratorConfigInterface`.
74+
The only method `getHydratorProperties` has to return an array with string keys and callables as values.
75+
76+
As an alternative you can use the `\Scn\Hydrator\Configuration\GenericHydratorConfig`.
77+
78+
The string keys have to correspond the keys in the data to hydrate your object with.
79+
80+
The corresponding callables must have the signature `callable(mixed $value, string $propertyName): void`.
81+
The `$propertyName` parameter will be the corresponding string key. You will usually not need this information.
82+
83+
If this callable is an instance of `\Closure`, its' `$this` and `static` context are bound to the entity object to
84+
hydrate. As a result of this the closure will have access to private and protected properties and methods of the entity.
85+
86+
A short example:
87+
88+
```php
89+
<?php
90+
91+
require_once __DIR__.'vendor/autoload.php';
92+
93+
class HydratorConfig implements \Scn\Hydrator\Configuration\HydratorConfigInterface
94+
{
95+
96+
public function getHydratorProperties(): array
97+
{
98+
return [
99+
'property' => function (string $value, string $propertyName): void {
100+
$this->privateProperty = $value; // $this will be the entity to hydrate
101+
}
102+
];
103+
}
104+
}
105+
106+
class Entity
107+
{
108+
private $privateProperty = 'private value';
109+
110+
public function getPropertyValue(): string
111+
{
112+
return $this->privateProperty;
113+
}
114+
}
115+
116+
$hydrator = new \Scn\Hydrator\Hydrator();
117+
$data = [
118+
'property' => 'hydrated private value',
119+
];
120+
121+
$entity = new Entity();
122+
123+
$hydrator->hydrate(
124+
new HydratorConfig(),
125+
$entity,
126+
$data
127+
);
128+
129+
var_dump(assert('hydrated private value' === $entity->getPropertyValue())); // -> bool(true)
130+
```
131+
132+
#### Hydration flags
133+
134+
The `hydrate` method has a fourth, optional bit flag parameter `$flags`.
135+
136+
Currently there are two options available
137+
138+
##### `\Scn\Hydrator\Hydrator::NO_STRICT_KEYS` (1)
139+
140+
If this bit is set in `$flags`, the hydrator will ignore keys in the data array that have no corresponding key in the array
141+
the `getHydratorProperties` method returns.
142+
143+
This bit is not set by default, additional keys in the data array will lead to an `\InvalidArgumentException` exception thrown by the hydrator.
144+
145+
##### `\Scn\Hydrator\Hydrator::IGNORE_KEYS` (2)
146+
147+
If this bit is set, the hydrator will ignore the keys of the data array but assume the entries in the data array are in
148+
the same order as in the hydrator configuration array.
149+
150+
Example:
151+
152+
```php
153+
<?php
154+
155+
use Scn\Hydrator\Hydrator;
156+
157+
require_once __DIR__.'vendor/autoload.php';
158+
159+
class HydratorConfig implements \Scn\Hydrator\Configuration\HydratorConfigInterface
160+
{
161+
162+
public function getHydratorProperties(): array
163+
{
164+
return [
165+
'property_a' => function (string $value, string $propertyName): void {
166+
$this->privatePropertyA = $value;
167+
},
168+
'property_b' => function (string $value, string $propertyName): void {
169+
$this->privatePropertyB = $value;
170+
},
171+
'property_c' => function (string $value, string $propertyName): void {
172+
$this->privatePropertyC = $value;
173+
},
174+
175+
];
176+
}
177+
}
178+
179+
class Entity
180+
{
181+
private $privatePropertyA;
182+
private $privatePropertyB;
183+
private $privatePropertyC;
184+
185+
public function getPropertyValues(): array
186+
{
187+
return [
188+
$this->privatePropertyA,
189+
$this->privatePropertyB,
190+
$this->privatePropertyC,
191+
];
192+
}
193+
}
194+
195+
$hydrator = new \Scn\Hydrator\Hydrator();
196+
$data = ['value a', 'value_b', 'value_c'];
197+
198+
$entity = new Entity();
199+
200+
$hydrator->hydrate(
201+
new HydratorConfig(),
202+
$entity,
203+
$data,
204+
Hydrator::IGNORE_KEYS
205+
);
206+
207+
var_dump(assert($data === $entity->getPropertyValues())); // -> bool(true)
208+
```

0 commit comments

Comments
 (0)