https://github.com/sc-networks/hydrator
A pragmatic hydrator and extractor library
https://github.com/sc-networks/hydrator
extract extract-data extraction hydrate hydration hydrator php php7 php8
Last synced: 3 months ago
JSON representation
A pragmatic hydrator and extractor library
- Host: GitHub
- URL: https://github.com/sc-networks/hydrator
- Owner: SC-Networks
- License: mit
- Created: 2018-07-20T11:12:11.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2022-01-21T07:15:06.000Z (over 3 years ago)
- Last Synced: 2025-03-17T12:21:53.596Z (3 months ago)
- Topics: extract, extract-data, extraction, hydrate, hydration, hydrator, php, php7, php8
- Language: PHP
- Homepage:
- Size: 50.8 KB
- Stars: 2
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# scn/hydrator
[](https://packagist.org/packages/scn/hydrator)
[](https://packagist.org/packages/scn/hydrator)
[](LICENSE)
## A pragmatic hydrator and extractor library
### Installation
Via Composer:
```
$ composer require scn/hydrator
```
### Usage
See the `examples` folder for usage instructions by code.
#### Extraction
First of all you'll need a class that implements `\Scn\Hydrator\Config\ExtractorConfigInterface`.
The only method `getExtractorProperties` has to return an array with string keys and callables as values.
The string keys of this array are used to craft the result of the extraction.
The corresponding callables must have the signature `callable(string $propertyName): mixed`. The `$propertyName`
parameter will be the corresponding string key. You will usually not need this information.
If this callable is an instance of `\Closure`, its' `$this` and `static` context are bound to the entity object to
extract. As a result of this the closure will have access to private and protected properties and methods of the entity.
A short example:
```php
function (string $propertyName): string {
return $this->privateProperty; // `$this` will be the entity to extract
}
];
}
}
class Entity
{
private $privateProperty = 'private value';
}
$hydrator = new \Hydrator();
$result = $hydrator->extract(
new ExtractorConfig(),
new Entity()
);
var_dump(assert($result === ['property' => 'private value'])); // -> bool(true)
```
### Hydration
For hydration you'll need a class implementing `\Scn\Hydrator\Configuration\HydratorConfigInterface`.
The only method `getHydratorProperties` has to return an array with string keys and callables as values.
As an alternative you can use the `\Scn\Hydrator\Configuration\GenericHydratorConfig`.
The string keys have to correspond the keys in the data to hydrate your object with.
The corresponding callables must have the signature `callable(mixed $value, string $propertyName): void`.
The `$propertyName` parameter will be the corresponding string key. You will usually not need this information.
If this callable is an instance of `\Closure`, its' `$this` and `static` context are bound to the entity object to
hydrate. As a result of this the closure will have access to private and protected properties and methods of the entity.
A short example:
```php
function (string $value, string $propertyName): void {
$this->privateProperty = $value; // $this will be the entity to hydrate
}
];
}
}
class Entity
{
private $privateProperty = 'private value';
public function getPropertyValue(): string
{
return $this->privateProperty;
}
}
$hydrator = new \Hydrator();
$data = [
'property' => 'hydrated private value',
];
$entity = new Entity();
$hydrator->hydrate(
new HydratorConfig(),
$entity,
$data
);
var_dump(assert('hydrated private value' === $entity->getPropertyValue())); // -> bool(true)
```
#### Hydration flags
The `hydrate` method has a fourth, optional bit flag parameter `$flags`.
Currently there are two options available
##### `\Scn\Hydrator\Hydrator::NO_STRICT_KEYS` (1)
If this bit is set in `$flags`, the hydrator will ignore keys in the data array that have no corresponding key in the array
the `getHydratorProperties` method returns.
This bit is not set by default, additional keys in the data array will lead to an `\InvalidArgumentException` exception thrown by the hydrator.
##### `\Scn\Hydrator\Hydrator::IGNORE_KEYS` (2)
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
the same order as in the hydrator configuration array.
Example:
```php
function (string $value, string $propertyName): void {
$this->privatePropertyA = $value;
},
'property_b' => function (string $value, string $propertyName): void {
$this->privatePropertyB = $value;
},
'property_c' => function (string $value, string $propertyName): void {
$this->privatePropertyC = $value;
},
];
}
}
class Entity
{
private $privatePropertyA;
private $privatePropertyB;
private $privatePropertyC;
public function getPropertyValues(): array
{
return [
$this->privatePropertyA,
$this->privatePropertyB,
$this->privatePropertyC,
];
}
}
$hydrator = new \Hydrator();
$data = ['value a', 'value_b', 'value_c'];
$entity = new Entity();
$hydrator->hydrate(
new HydratorConfig(),
$entity,
$data,
Hydrator::IGNORE_KEYS
);
var_dump(assert($data === $entity->getPropertyValues())); // -> bool(true)
```