README

Laravel Data Enrichment helps you enrich and augment data across your Laravel applications. It offers a flexible, extensible workflow to collect enrichment requests and resolve them against repositories, whether you work with arrays, HTTP messages, or custom data sources.

Features

Multiple sources: Enrich array data, HTTP requests, and responses.
Middleware support: Pin enrichment requests to controller responses automatically.
Extensible managers: Plug in custom logic via interfaces and repositories.
Simple facades: Convenient API via ArrayEnrichment and HttpEnrichment.

Additional Info

Core library: diffhead/php-data-enrichment-kit
This package provides Laravel integration (service provider, facades, middleware, and configuration) on top of the core kit.

Installation

Install via Composer:

composer require diffhead/laravel-data-enrichment

Publish the configuration (if needed):

php artisan vendor:publish --provider="Diffhead\PHP\LaravelDataEnrichment\ServiceProvider"

Configuration

The configuration file config/enrichment.php controls how enrichment works. Customize it for your application.

Repositories: On the receiver side, create repositories implementing \Diffhead\PHP\DataEnrichmentKit\Interface\Repository and list them under enrichment.repositories.
Bindings: Optionally map repository interfaces to implementations via enrichment.bindings for auto-resolution.
Custom logic: Override the enrichment workflow by providing your implementations for:
- \Diffhead\PHP\DataEnrichmentKit\Interface\Parser — parse raw requests
- \Diffhead\PHP\DataEnrichmentKit\Interface\Serializer — serialize request objects
- \Diffhead\PHP\DataEnrichmentKit\Interface\Enrichment — core enrichment business logic

Usage

Array Enrichment

Use the ArrayEnrichment facade to enrich plain PHP arrays:

use Diffhead\LaravelDataEnrichment\Facade\ArrayEnrichment;

$books = [
    [
        'title' => 'Magic Things: How To',
        'author_id' => 353,
    ],
];

ArrayEnrichment::addRequest('user', 'id', [
    ['key' => '*.author_id', 'alias' => 'author'],
]);

$enrichedBooks = ArrayEnrichment::enrich($books);
/**
 * Result:
 * [
 *   [
 *     'title' => 'Magic Things: How To',
 *     'author_id' => 353,
 *     'author' => [
 *       'id' => 353,
 *       'name' => 'John Doe',
 *       'email' => 'john-doe@mysite.com'
 *     ]
 *   ],
 * ]
 */
print_r($enrichedBooks);

/**
 * When done, clear the request storage and add new
 * requests for the next data object to enrich.
 */
ArrayEnrichment::clearRequests();

HTTP Enrichment

Use the HttpEnrichment facade to enrich HTTP requests or responses:

use Diffhead\LaravelDataEnrichment\Facade\HttpEnrichment;

enum Header: string
{
    case XEnrich = 'X-Enrich';
}

$psrFactory = new PsrHttpFactory();
/**
 * @var \Symfony\Component\HttpFoundation\Response $response
 * @var \Psr\Http\Message\MessageInterface $psrMessage
 */
$psrMessage = $psrFactory->createResponse($response);

/**
 * Optionally set the header used for enrichment.
 * Default: \Diffhead\LaravelDataEnrichment\Header::XEnrichRequest
 * Accepts any BackedEnum.
 * Note: if you change the default on the client, also change it on the server.
 */
HttpEnrichment::useHeader(Header::XEnrich);

/**
 * Add enrichment requests to storage.
 */
HttpEnrichment::addRequest('user', 'id', [
    ['key' => 'data.*.assigned.*.user_id', 'alias' => 'user'],
    ['key' => 'data.*.created_by', 'alias' => 'creator'],
]);

/**
 * Client-side step: attach requests before passing the message downstream.
 */
$psrMessagePrepared = HttpEnrichment::setRequests($psrMessage);

/**
 * Example (gateway side): enrich a response.
 * This method parses and enriches the JSON payload in the PSR message.
 * Note: call HttpEnrichment::useHeader again if you changed it earlier.
 */
$psrMessageEnriched = HttpEnrichment::enrichMessage($psrMessagePrepared);

Middleware

Use the enrichment.pin-requests middleware to automatically pin added requests to the controller response:

use Diffhead\LaravelDataEnrichment\Facade\HttpEnrichment;

Route::middleware(['enrichment.pin-requests'])->group(
    function () {
        Route::get('/posts', function () {
            HttpEnrichment::addRequest('user', 'id', [
                ['key' => 'data.*.owner_id', 'alias' => 'owner'],
            ]);

            return response()->json([
                'data' => [
                    ['id' => 1, 'title' => 'Cats Dev', 'owner_id' => 1],
                    ['id' => 2, 'title' => "Sponge Bob's Bio", 'owner_id' => 2],
                ],
            ]);
        });
    }
);

Repository Examples

Below is an example of a repository interface and its Laravel Eloquent implementation used for enrichment. The repository searches users by a field with multiple values and returns an iterable cursor.

Interface

namespace App\Shared\Service\User;

use Diffhead\PHP\DataEnrichmentKit\Interface\Repository;

interface SearchByFieldValuesInterface extends Repository
{
    /**
     * @param string $field
     * @param array $values
     *
     * @return iterable<int,\App\Models\User\User>
     */
    public function getByFieldValues(string $field, array $values): iterable;
}

Implementation

namespace App\Shared\Service\User;

use App\Models\User\User;

class SearchByFieldValues implements SearchByFieldValuesInterface
{
    /**
     * @param string $field
     * @param array<int,mixed> $values
     *
     * @return iterable<int,\App\Models\User\User>
     */
    public function getByFieldValues(string $field, array $values): iterable
    {
        return User::query()->whereIn($field, $values)->cursor();
    }
}

Registration

config/enrichment.php

return [
    /** ... */
    'bindings' => [
        \App\Shared\Service\User\SearchByFieldValuesInterface::class =>
        \App\Shared\Service\User\SearchByFieldValues::class
    ],
    'repositories' => [
        'user' => \App\Shared\Service\User\SearchByFieldValuesInterface::class
    ],
    /** ... */
];

diffhead / laravel-data-enrichment

Maintainers

Details