Transformer Contract¶

Reference for the pluggable transformation and storage pipeline introduced in CFX-46. This covers the interface every platform transformer must implement, the result value objects, and the unified Eloquent models.

Interface: TransformerContract¶

Namespace: App\Contracts\TransformerContract

public function transform(Collection $data, SystemConnection $connection): TransformationResult;

Accepts a Collection<int, CustomerData|OrderData|ProductData> (the output of an integration's requestBulkExport()) and a SystemConnection. Persists each item to the unified Eloquent models. Returns a TransformationResult summarising successes and failures.

The method never throws — any exception raised while storing an individual item is captured and included in the result.

Abstract Base Class: AbstractTransformer¶

Namespace: App\Services\AbstractTransformer

Implements TransformerContract. Concrete transformers extend this class and implement store().

transform() is declared final. It iterates over the data collection, calls store() for each item, and catches any Throwable per item — meaning a failure on one record does not abort the rest of the batch. The result carries the full failure list so callers can log or retry specific items.

abstract protected function store(CustomerData|OrderData|ProductData $item, SystemConnection $connection): void;

This is the only method a concrete transformer must implement.

Result Value Objects¶

TransformationResult¶

Namespace: App\Data\TransformationResult

TransformationFailure¶

Namespace: App\Data\TransformationFailure

Unified Eloquent Models¶

These models are the persistent representation of normalised platform data inside Conflux. All use HasUuids and SoftDeletes.

Customer¶

Namespace: App\Models\Customer
Table: customers

Unique constraint: (system_connection_id, source_id)

Relations: systemConnection() → BelongsTo<SystemConnection>, consents() → HasMany<CustomerConsent>, orders() → HasMany<Order>

CustomerConsent¶

Namespace: App\Models\CustomerConsent Table: customer_consents

Unique constraint: (customer_id, channel) — one consent record per channel per customer.

Relations: customer() → BelongsTo<Customer>

Order¶

Namespace: App\Models\Order
Table: orders

Unique constraint: (system_connection_id, source_id)

Relations: systemConnection() → BelongsTo<SystemConnection>, customer() → BelongsTo<Customer>, lineItems() → HasMany<LineItem>

LineItem¶

Namespace: App\Models\LineItem Table: line_items

Unique constraint: (order_id, source_id)

Relations: order() → BelongsTo<Order>, product() → BelongsTo<Product>

product_id is resolved at import time by looking up Product with (system_connection_id, product_source_id). If the product has not been synced yet, product_id remains null until the order is re-imported after the product sync.

Product¶

Namespace: App\Models\Product
Table: products

Unique constraint: (system_connection_id, source_id)

Relations: systemConnection() → BelongsTo<SystemConnection>

Default store() Implementation¶

AbstractTransformer provides a concrete store() method that handles all three entity types via a match expression. It uses updateOrCreate keyed on (system_connection_id, source_id) so that re-running a bulk export updates existing records rather than creating duplicates.

Platform-specific transformers extend AbstractTransformer and override store() only when they need behaviour that differs from the default. Until that need arises, a minimal subclass with no overrides is sufficient.

TransformerRegistry¶

Namespace: App\Services\TransformerRegistry

A singleton that maps each SystemDriver to a concrete transformer class. It mirrors IntegrationRegistry and is the only mechanism by which Conflux locates the correct transformer at runtime.

public function register(SystemDriver $driver, string $transformer): void
public function resolve(SystemDriver $driver): AbstractTransformer

• register() — associates a SystemDriver case with a class-string<AbstractTransformer>. Called once per platform in AppServiceProvider::boot().
• resolve() — returns an instance of the registered transformer, resolved via the service container (app($class)). Throws RuntimeException if no transformer has been registered for the given driver.

The registry is bound as a singleton in AppServiceProvider::register():

$this->app->singleton(TransformerRegistry::class);

PersistBulkDataJob receives the registry via constructor injection and calls resolve() at job execution time to obtain the transformer for the connection's system driver.

PersistBulkDataJob¶

Namespace: App\Jobs\PersistBulkDataJob
Queue connection: rabbitmq

The job that bridges the bulk-fetch stage and the persistence stage. BulkSyncJob dispatches it after each successful requestBulkExport() call when the result is non-empty.

public function __construct(
    public readonly Collection $data,           // Collection<int, CustomerData|OrderData|ProductData>
    public readonly SystemConnection $systemConnection,
) {}

On execution, it resolves the correct transformer from TransformerRegistry using the system driver of the associated SystemConnection, then calls transform(). If the connection has no associated system, the job exits silently.

The job runs on the rabbitmq connection, which places it on a different queue from BulkSyncJob (which runs on the default redis-backed queue). This separates the fetch stage from the persistence stage and allows them to scale independently.