README

A collection of components for building microservice-based applications. This library provides tools for enriching data during communication between system components.

Installation

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

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:

namespace Diffhead\PHP\DataEnrichmentKit\Interface;

interface Entity extends \ArrayAccess, \JsonSerializable {}

Creating Enrichment Requests and Attaching to HTTP Messages

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

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

namespace Diffhead\PHP\DataEnrichmentKit\Interface;

use Diffhead\PHP\DataEnrichmentKit\Storage\Requests;

interface Enrichment
{
    public function enrich(array $data, Requests $requests): array;
}

Request parsing

namespace Diffhead\PHP\DataEnrichmentKit\Interface;

use Diffhead\PHP\DataEnrichmentKit\Object\Request;

interface Parser
{
    public function parse(string $value): Request;
}

Request serialization

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.

diffhead / php-data-enrichment-kit

Maintainers

Details