diff --git a/README.md b/README.md index 4510314..d1acfb4 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,196 @@ The normalization which is under the object control. 1. `NormalizableInterface` 2. `NormalizationFacadeInterface` +## Quick Start + +#### Having: + +```php +id = uniqid(); + $this->occurredAt = new DateTimeImmutable(); + } + + public function getId(): string + { + return $this->id; + } + + public function getOccurredAt(): DateTimeInterface + { + return $this->occurredAt; + } +} + +final class FileCreatedEvent extends BaseEvent +{ + /** + * @var string + */ + private $title; + + public function __construct(string $title) + { + $this->title = $title; + } +} +``` + +#### To make **FileCreatedEvent** normalizable needed: + +1. `use NormalizableTrait` + 1. by `FileCreatedEvent` to normalize **title** as normalization happens only in the frames of current visibility + bounds + 2. by `BaseEvent` to normalize **occurredAt** and **id** +2. implement `NormalizableInterface` by **BaseEvent** +3. make properties Normalizable: + 1. replace DateTime with **DateTimeImmutableRfc3339Normalizable** or do normalization manually + +```php +abstract class BaseEvent implements \Era269\Normalizable\NormalizableInterface +{ + use \Era269\Normalizable\Traits\NormalizableTrait; + /** + * @var string + */ + private $id; + /** + * @var DateTimeImmutableRfc3339Normalizable + */ + private $occurredAt; + + public function __construct() + { + $this->id = uniqid(); + $this->occurredAt = new DateTimeImmutableRfc3339Normalizable(); + } + + public function getId(): string + { + return $this->id; + } + + public function getOccurredAt(): DateTimeInterface + { + return $this->occurredAt; + } +} + +final class FileCreatedEvent extends BaseEvent +{ + use \Era269\Normalizable\Traits\NormalizableTrait; + + /** + * @var string + */ + private $title; + + public function __construct(string $title) + { + parent::__construct(); + $this->title = $title; + } +} + +$event = new FileCreatedEvent('BBB'); +print_r($event->normalize()); +``` + +#### output: + +```bash +Array +( + [@type] => FileCreatedEvent + [id] => 6236f3ab706df + [occurredAt] => Array + ( + [@type] => DateTimeImmutableRfc3339Normalizable + [dateTime] => 2022-03-20T09:28:11+00:00 + ) + + [title] => BBB +) +``` + +#### To customise output you need + +1. implement `NormalizationFacadeAwareInterface` +2. create own Normalization strategy using the DefaultNormalizationFacade as example + 1. use `CamelCaseToSnackCaseKeyDecorator` or own implementation to decorate keys + 2. change the order of Normalizers, remove unneeded ar add own to influence the normalization + +#### Customised normalization config + +```php +normalize($event)); +//or +$event->setNormalizationFacade($normalizationFacade); +print_r($event->normalize()); +``` + +#### output: + +```bash +Array +( + [id] => 6236f74d4ca26 + [occurred_at] => 2022-03-20T09:43:41+00:00 + [title] => BBB +) +Array +( + [id] => 6236f74d4ca26 + [occurred_at] => 2022-03-20T09:43:41+00:00 + [title] => BBB +) +``` + +## Description: + +### NormalizableInterface + +The basic interface. Could be used separately to build fully manual normalization. How: + +1. any objet implements `NormalizableInterface` +2. It is called object::normalize in `NormalizableInterface::normalize` for all required to be present in normalized + view objects + +### NormalizableTrait + +If it is needed to have all normalization happen automatically then `NormalizableTrait` has to be used +with `NormalizableInterface`. In that case all objects should be supported by the `DefaultNormalizationFacade` + +#### DefaultNormalizationFacade + +Will normalize all private object properties by the next rules: + +======= ## Description: ### NormalizableInterface