Version 1.0.0

README.md

@@ -0,0 +1,230 @@
+# Data Enrichment Kit
+
+A collection of components for building microservice-based applications.
+This library provides tools for enriching data during communication 
+between system components.
+
+# Installation
+
+```bash
+# Install the package
+composer require diffhead/php-data-enrichment-kit
+
+# Run library tests
+composer test
+```
+
+# Usage
+
+To use this library, you first need to create repositories 
+that implement the `Repository` interface:
+
+```php
+namespace Diffhead\PHP\DataEnrichmentKit\Interface;
+
+interface Repository
+{
+    /**
+     * @param string $field
+     * @param array $values
+     *
+     * @return iterable<int,\Diffhead\PHP\DataEnrichmentKit\Interface\Entity>
+     */
+    public function getByFieldValues(string $field, array $values): iterable;
+}
+```
+
+Each entity must implement the `Entity` interface:
+
+```php
+namespace Diffhead\PHP\DataEnrichmentKit\Interface;
+
+interface Entity extends \ArrayAccess, \JsonSerializable {}
+```
+
+### Creating Enrichment Requests and Attaching to HTTP Messages
+
+```php
+use Diffhead\PHP\DataEnrichmentKit\Builder;
+use Diffhead\PHP\DataEnrichmentKit\Message;
+use Diffhead\PHP\DataEnrichmentKit\Header;
+use Diffhead\PHP\DataEnrichmentKit\Service\Serializer;
+use Diffhead\PHP\DataEnrichmentKit\Service\Parser;
+use Diffhead\PHP\DataEnrichmentKit\Storage\Requests;
+
+$builder = Builder::withTarget('user', 'id');
+$builder
+    ->item('data.posts.*.creator_id', 'creator')
+    ->item('data.posts.*.moderator_id', 'moderator');
+
+$requests = new Requests([
+    $builder->build()
+]);
+
+$message = new Message(new Serializer(), new Parser());
+
+/**
+ * @var \Psr\Http\Message\MessageInterface $psrMessage
+ *
+ * Message contains the following body data:
+ * 
+ * {"data":{"posts":[{"id":1,"title":"String","creator_id":1,"moderator_id":3}]}}
+ * 
+ * This call will attach enrichment requests to a message
+ */
+$message->setRequests($psrMessage, Header::XEnrichmentRequest, $requests);
+```
+
+### Receiving Data and Performing Enrichment
+
+```php
+use Diffhead\PHP\DataEnrichmentKit\Enricher;
+use Diffhead\PHP\DataEnrichmentKit\Message;
+use Diffhead\PHP\DataEnrichmentKit\Header;
+use Diffhead\PHP\DataEnrichmentKit\Service\Enrichment;
+use Diffhead\PHP\DataEnrichmentKit\Service\Serializer;
+use Diffhead\PHP\DataEnrichmentKit\Service\Parser;
+use Diffhead\PHP\DataEnrichmentKit\Storage\Repositories;
+use Diffhead\PHP\DataEnrichmentKit\Interface\Repository;
+
+/**
+ * Repository implementation example
+ */
+$repository = new class() implements Repository
+{
+    private array $items = [
+        ['id' => 1, 'name' => 'Antony'],
+        ['id' => 3, 'name' => 'Martin']
+    ];
+
+    public function getByFieldValues(string $field, array $values): iterable
+    {
+        return array_filter($this->items, fn(array $item) => in_array($item[$field], $values));
+    }
+};
+
+$repositories = new Repositories([
+    'user' => $repository
+]);
+
+/**
+ * Initialize services
+ */
+$enricher = new Enricher(new Enrichment($repositories));
+$message = new Message(new Serializer(), new Parser());
+
+/**
+ * Getting enrichment requests from psr message
+ */
+$requests = $message->getRequests($psrMessage, Header::XEnrichmentRequest);
+
+/**
+ * Getting array payload from message
+ */
+$payload = $message->getPayload($psrMessage);
+
+/**
+ * Enrich the payload using the registered repositories
+ * Expected enriched structure:
+ * 
+ * [
+ *   "data" => [
+ *     "posts" => [
+ *       [
+ *         "id" => 1,
+ *         "title" => "String",
+ *         "creator_id" => 1,
+ *         "moderator_id" => 3,
+ *         "creator" => ["id" => 1, "name" => "Antony"],
+ *         "moderator" => ["id" => 3, "name" => "Martin"]
+ *       ]
+ *     ]
+ *   ]
+ * ]
+ */
+$enriched = $enricher->enrich($payload, $requests);
+
+/**
+ * Set new payload to psr message
+ */
+$psrMessage = $message->setPayload($psrMessage, $enriched);
+```
+
+# Anatomy
+
+This library consists of the following **high-level service components**:
+
+* **Enricher** – a self-explanatory service that enriches data.
+* **Message** – a PSR-compatible component for interacting with 
+HTTP requests and responses using `MessageInterface`.
+* **Builder** – helps build enrichment request objects.
+
+**Lower-level components** for building custom enrichment algorithms:
+
+* **Enrichment** – implements the `Enrichment` interface and contains 
+the enrichment logic.
+* **Parser** – parses raw and returns `Request` objects.
+* **Serializer** – serializes `Request` objects to strings.
+
+**Value objects:**
+
+* **Item** – a unit describing an enrichment reference and alias.
+* **ItemsBag** – stores multiple `Item` instances.
+* **Request** – represents a single enrichment request.
+* **Target** – specifies the entity to enrich.
+
+**Storage objects:**
+
+* **Requests** – contains enrichment requests and implements `IteratorAggregate`.
+* **Repositories** – stores a map of entity repositories.
+
+# Customize
+
+You can extend the library by implementing your own:
+
+### Data enrichment logic
+
+```php
+namespace Diffhead\PHP\DataEnrichmentKit\Interface;
+
+use Diffhead\PHP\DataEnrichmentKit\Storage\Requests;
+
+interface Enrichment
+{
+    public function enrich(array $data, Requests $requests): array;
+}
+```
+
+### Request parsing
+
+```php
+namespace Diffhead\PHP\DataEnrichmentKit\Interface;
+
+use Diffhead\PHP\DataEnrichmentKit\Object\Request;
+
+interface Parser
+{
+    public function parse(string $value): Request;
+}
+```
+
+### Request serialization
+
+```php
+namespace Diffhead\PHP\DataEnrichmentKit\Interface;
+
+use Diffhead\PHP\DataEnrichmentKit\Object\Request;
+
+interface Serializer
+{
+    public function toString(Request $request): string;
+}
+```
+
+# Notes
+
+* Designed primarily for HTTP, but low-level components allow you 
+to quickly implement high-level integrations for any data source.
+
+* Supports PSR-compliant messages and can be integrated into 
+frameworks like Laravel with custom adapters.