Docs (#67)

Co-authored-by: Alexander Makarov <sam@rmcreative.ru>
yiisoft · Jan 20, 2024 · 6606094 · 6606094
1 parent a8ae309
commit 6606094
Show file tree

Hide file tree

Showing 39 changed files with 848 additions and 222 deletions.
diff --git a/README.md b/README.md
@@ -15,7 +15,7 @@
 [![type-coverage](https://shepherd.dev/github/yiisoft/hydrator/coverage.svg)](https://shepherd.dev/github/yiisoft/hydrator)
 [![psalm-level](https://shepherd.dev/github/yiisoft/hydrator/level.svg)](https://shepherd.dev/github/yiisoft/hydrator)
 
-The package provides a way to create or hydrate objects from a set of raw data.
+The package provides a way to create and hydrate objects from a set of raw data.
 
 Features are:
 
@@ -27,7 +27,19 @@ Features are:
 - supports mapping;
 - allows fine-tuning hydration via PHP attributes.
 
-## Basic usage
+## Requirements
+
+- PHP 8.0 or higher.
+
+## Installation
+
+The package could be installed with composer:
+
+```shell
+composer require yiisoft/hydrator
+```
+
+## General usage
 
 To hydrate existing object:
 
@@ -38,7 +50,7 @@ $hydrator = new Hydrator();
 $hydrator->hydrate($object, $data);
 ```
 
-To create a new object and fill it with the data: 
+To create a new object and fill it with the data:
 
 ```php
 use Yiisoft\Hydrator\Hydrator;
@@ -83,171 +95,10 @@ $object = $hydrator->create(Car::class, [
 That would pass the `name` constructor argument of the `Car` object and create a new `Engine` object for `engine`
 argument passing `V8` as the `name` argument to its constructor.
 
-## Configuration with PHP attributes
-
-You can configure how the hydrator creates or hydrates a specific class using attributes. 
-
-### Mapping 
-
-To map attributes to specific data keys, use `Data` attribute:
-
-```php
-use \Yiisoft\Hydrator\Attribute\Parameter\Data;
-
-final class Person
-{
-    public function __construct(
-        #[Data('first_name')]
-        private string $firstName,
-        #[Data('last_name')]
-        private string $lastName,
-    ) {}
-}
-
-$person = $hydrator->create(Person::class, [
-    'first_name' => 'John',
-    'last_name' => 'Doe',
-]);
-```
-
-### Casting value to string
-
-To cast a value to string, use `ToString` attribute:
-
-```php
-use \Yiisoft\Hydrator\Attribute\Parameter\ToString;
-
-class Money
-{
-    public function __construct(
-        #[ToString]
-        private string $value,
-        private string $currency,
-    ) {}
-}
-
-$money = $hydrator->create(Money::class, [
-    'value' => 4200,
-    'currency' => 'AMD',
-]);
-```
-
-### Skipping hydration
-
-To skip hydration of a specific property, use `SkipHydration` attribute:
-
-```php
-use \Yiisoft\Hydrator\Attribute\SkipHydration;
-
-class MyClass
-{
-    #[SkipHydration]
-    private $property;
-}
-```
-
-### Resolving dependencies
-
-To resolve dependencies by specific ID using DI container, use `Di` attribute:
-
-```php
-ues \Yiisoft\Hydrator\Attribute\Parameter\Di;
-
-class MyClass
-{
-    public function __construct(
-        #[Di(id: 'importConnection')]
-        private ConnectionInterface $connection,
-    ) {}
-}
-```
-
-The annotation will instruct hydrator to get `$connection` from DI container by `importConnection` ID.
-
-### Your own attributes
-
-There are two main parts:
-
-- Attribute class.
-  It only stores configuration options and a reference to its handler.
-- Attribute resolver.
-  Given an attribute reflection and extra data, it resolves an attribute.
-
-Besides responsibilities' separation,
-this approach allows the package to automatically resolve dependencies for attribute resolver.
-
-#### Data attributes
-
-You apply data attributes to a whole class.
-The main goal is getting data from external sources such as from request.
-Additionally, it's possible to specify how external source attributes map to hydrated class.
-
-Data attribute class should implement `DataAttributeInterface` and the corresponding data attribute resolver should
-implement `DataAttributeResolverInterface`.
-
-#### Parameter attributes
-
-You apply parameter attributes to class properties and constructor parameters.
-You use these attributes for getting value for specific parameter or for preparing the value
-(for example, by type casting).
-
-Parameter attribute class should implement `ParameterAttributeInterface` and the corresponding parameter attribute
-resolver should implement `ParameterAttributeResolverInterface`.
-
-## Requirements
-
-- PHP 8.0 or higher.
-
-## Installation
-
-The package could be installed with composer:
-
-```shell
-composer require yiisoft/hydrator
-```
-
-## General usage
-
-## Testing
-
-### Unit testing
-
-The package is tested with [PHPUnit](https://phpunit.de/). To run tests:
-
-```shell
-./vendor/bin/phpunit
-```
-
-### Mutation testing
-
-The package tests are checked with [Infection](https://infection.github.io/) mutation framework with
-[Infection Static Analysis Plugin](https://github.com/Roave/infection-static-analysis-plugin). To run it:
-
-```shell
-./vendor/bin/roave-infection-static-analysis-plugin
-```
-
-### Static analysis
-
-The code is statically analyzed with [Psalm](https://psalm.dev/). To run static analysis:
-
-```shell
-./vendor/bin/psalm
-```
-
-### Code style
-
-Use [Rector](https://github.com/rectorphp/rector) to make codebase follow some specific rules or 
-use either newest or any specific version of PHP: 
-
-```shell
-./vendor/bin/rector
-```
-
-### Dependencies
+## Documentation
 
-Use [ComposerRequireChecker](https://github.com/maglnet/ComposerRequireChecker) to detect transitive 
-[Composer](https://getcomposer.org/) dependencies.
+- [Guide](docs/guide/en/README.md)
+- [Internals](docs/internals.md)
 
 ## License
 

diff --git a/docs/guide/en/README.md b/docs/guide/en/README.md
@@ -0,0 +1,10 @@
+# Yii Hydrator
+
+The package provides a way to create and hydrate objects from a set of raw data.
+
+- [General usage](general-usage.md)
+- [Type casting](typecasting.md)
+- [Mapping](mapping.md)
+- [Creating own attributes](creating-own-attributes.md)
+- [Attribute resolver factory](attribute-resolver-factory.md)
+- [Object factory](object-factory.md)
diff --git a/docs/guide/en/attribute-resolver-factory.md b/docs/guide/en/attribute-resolver-factory.md
@@ -0,0 +1,31 @@
+# Attribute resolver factory
+
+The hydrator uses `AttributeResolverFactoryInterface` implementation to create attribute resolvers.
+The package provides two implementations out of the box:
+
+- `ReflectionAttributeResolverFactory`. Uses reflection to create attribute resolver, and can create attribute resolvers
+  without dependencies only.
+- `ContainerAttributeResolverFactory`. Uses [PSR-11](https://www.php-fig.org/psr/psr-11/) compatible DI container
+  to create attribute resolver.
+
+Default factory used depends on the environment. When using hydrator package within the Yii ecosystem (an application
+uses [Yii Config](https://github.com/yiisoft/config)), default is `ContainerAttributeResolverFactory`. Otherwise,
+it is `ReflectionAttributeResolverFactory`.
+
+## Using attribute resolver factory
+
+To use non-default attribute resolver factory, pass it to the hydrator constructor:
+
+```php
+use Yiisoft\Hydrator\AttributeHandling\ResolverFactory\ContainerAttributeResolverFactory;
+
+/**
+ * @var Psr\Container\ContainerInterface $container
+ */ 
+$attributeResolverFactory = new ContainerAttributeResolverFactory($container);
+
+$hydrator = new Hydrator(
+    attributeResolverFactory: $attributeResolverFactory,
+    // ...
+);
+```