DataEnrichmentKit/README.md

# 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.