Integration Contract¶

Reference for the integration communication contract. This covers the interface every platform integration must implement, the request/response DTOs, and the exceptions. The contract covers connection verification (CFX-53), outbound bulk exports (CFX-45), and inbound webhook processing (CFX-48).

Interface: IntegrationContract¶

Namespace: App\Contracts\IntegrationContract

public function verify(SystemConnection $connection): VerificationResult;

public function requestBulkExport(SystemConnection $connection, ExportRequest $request): Collection;

/** @param Closure(Collection<int, CustomerData|OrderData|ProductData>): void $onBatch */
public function streamBulkExport(SystemConnection $connection, ExportRequest $request, Closure $onBatch): void;

public function probeBulkExport(SystemConnection $connection, ExportRequest $request): BulkExportProbe;

/** @param Closure(Collection<int, CustomerData|OrderData|ProductData>): void $onBatch */
public function fetchBulkExportPageRange(SystemConnection $connection, ExportRequest $request, int $startPage, int $endPage, int $perPage, Closure $onBatch): void;

/** @param array<string, mixed> $payload */
public function handleWebhook(SystemConnection $connection, array $payload): void;

/** @return class-string<TransformerContract> */
public function transformerClass(): string;

• verify() — authenticates the connection's credentials against the live system and resolves the external user/account identifier. Never throws; failures are reported through the returned VerificationResult.
• requestBulkExport() — returns a Collection<int, CustomerData|OrderData|ProductData> containing every fetched record. Throws IntegrationRequestException (or a subclass) on any integration-layer failure. Built on top of streamBulkExport().
• streamBulkExport() — invokes $onBatch once per fetched page, without accumulating the full result set in memory. Throws IntegrationRequestException (or a subclass).
• probeBulkExport() — returns the total page count and page size without fetching any records, so the job layer can fan out parallel fetchBulkExportPageRange() calls. Throws IntegrationRequestException (or a subclass).
• fetchBulkExportPageRange() — fetches a specific [startPage, endPage] range, invoking $onBatch once per page. Throws IntegrationRequestException (or a subclass).
• handleWebhook() — processes an inbound webhook payload for the given connection. Throws IntegrationRequestException (or a subclass) on any integration-layer failure.
• transformerClass() — returns the TransformerContract implementation responsible for persisting this integration's fetched data.

Abstract Base Class: AbstractIntegration¶

Namespace: App\Services\AbstractIntegration

Implements IntegrationContract. Concrete integrations extend this class and implement the abstract/overridable methods below.

verify(), requestBulkExport(), streamBulkExport(), probeBulkExport(), fetchBulkExportPageRange(), handleWebhook(), and transformerClass() are all declared final on AbstractIntegration — concrete integrations never override them directly. The bulk-export and webhook methods wrap their integration-provided counterparts in the same error-handling strategy: any Throwable that is not already an IntegrationRequestException is caught and re-thrown as InvalidIntegrationResponseException. verify() uses a different strategy — see below.

performVerification() (abstract, required)¶

abstract protected function performVerification(SystemConnection $connection): VerificationResult;

Every concrete integration must implement this method. It performs the integration-specific credential check against the live system and resolves the external user/account identifier consumed by the Connection Flow. Return VerificationResult::success($externalUserId) on success. On failure, either return VerificationResult::failure($message) explicitly, or simply throw — verify() catches any Throwable and converts it into a failed VerificationResult, so an integration can rely on $response->throw() as its failure path without any local try/catch.

fetchBulkExportBatches() (abstract, required)¶

/** @param Closure(Collection<int, CustomerData|OrderData|ProductData>): void $onBatch */
abstract protected function fetchBulkExportBatches(SystemConnection $connection, ExportRequest $request, Closure $onBatch): void;

Every concrete integration must implement this method. It fetches records from the external system in pages, calling $onBatch once per non-empty page — page size and pagination strategy are entirely up to the integration. Called by streamBulkExport()/requestBulkExport().

provideTransformerClass() (abstract, required)¶

/** @return class-string<TransformerContract> */
abstract protected function provideTransformerClass(): string;

Every concrete integration must implement this method, returning the AbstractTransformer subclass responsible for persisting the DTOs this integration produces. Backs the public, sealed transformerClass().

performProbeBulkExport() (virtual, optional)¶

protected function performProbeBulkExport(SystemConnection $connection, ExportRequest $request): BulkExportProbe;

Override to report the total page count and page size without fetching any records, enabling BulkSyncJob to fan out parallel fetchBulkExportPageRange() jobs. The default returns new BulkExportProbe(totalPages: 1, perPage: 0), so performFetchBulkExportPageRange() falls back to a single fetchBulkExportBatches() call.

performFetchBulkExportPageRange() (virtual, optional)¶

/** @param Closure(Collection<int, CustomerData|OrderData|ProductData>): void $onBatch */
protected function performFetchBulkExportPageRange(SystemConnection $connection, ExportRequest $request, int $startPage, int $endPage, int $perPage, Closure $onBatch): void;

Override alongside performProbeBulkExport() to fetch a specific page range, calling $onBatch once per page. The default ignores the range and delegates to fetchBulkExportBatches(), which is correct for integrations whose probe always returns a single page.

processWebhook() (virtual, optional)¶

/** @param array<string, mixed> $payload */
protected function processWebhook(SystemConnection $connection, array $payload): void;

Override this method to handle inbound webhooks. The default implementation throws BadMethodCallException. Only integrations that receive webhooks need to implement it.

Verification DTO: VerificationResult¶

Namespace: App\Data\VerificationResult

Plain readonly class — not a Spatie\LaravelData\Data object, so it is never serialised directly and has no SnakeCaseMapper. Construct it via the named constructors rather than new:

public static function success(string $externalUserId): self;
public static function failure(?string $message = null): self;

Request DTO: ExportRequest¶

Namespace: App\Data\ExportRequest

SystemCapability enum¶

Response DTO: BulkExportProbe¶

Namespace: App\Data\BulkExportProbe

Plain class (not a Spatie\LaravelData\Data object), returned by probeBulkExport().

Response DTOs¶

All DTOs use Spatie\LaravelData\Data and the SnakeCaseMapper — property names are camelCase in PHP and snake_case when serialised.

Monetary values (price, originalPrice, unitPrice, total, totalTax, totalShipping, totalSpent) are always integers in minor currency units (e.g. cents). A price of €12.99 is stored as 1299.

Datetime fields (createdAt, updatedAt, subscribedAt, etc.) are strings — integrations are responsible for formatting them consistently (ISO 8601 recommended).

CustomerData¶

Namespace: App\Data\CustomerData

ProductData¶

Namespace: App\Data\ProductData

OrderData¶

Namespace: App\Data\OrderData

Sub-DTOs¶

ConsentData¶

Namespace: App\Data\ConsentData

AddressData¶

Namespace: App\Data\AddressData

All fields are optional (?string).

CustomAttributeData¶

Namespace: App\Data\CustomAttributeData

Represents a single platform-specific attribute. Serialises as an object in a JSON array: [{"key": "shop_id", "value": "7"}, ...].

LineItemData¶

Namespace: App\Data\LineItemData

Enums¶

SystemDriver¶

Gender¶

ProductStatus¶

ConsentChannel¶

ConsentSource¶

IntegrationRegistry¶

Namespace: App\Services\IntegrationRegistry

A singleton that maps each SystemDriver to a concrete integration class. It is the only mechanism by which Conflux locates the correct integration at runtime — no integration class is referenced directly outside of AppServiceProvider.

public function register(SystemDriver $driver, string $integration): void
public function resolve(SystemDriver $driver): IntegrationContract

• register() — associates a SystemDriver case with a class-string<IntegrationContract>. By convention, every integration is registered directly in App\Providers\AppServiceProvider::boot() — there is no per-integration service provider.
• resolve() — returns an instance of the registered integration, resolved via the service container (app($class)). Throws RuntimeException if no integration has been registered for the given driver.

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

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

Because it is a singleton, all register() calls in AppServiceProvider::boot() accumulate in the same instance throughout the application lifecycle.

Registered Integrations¶

Both are registered in App\Providers\AppServiceProvider::boot(). RapidMail and UserPlatform are internal consuming products, not sync integrations, and have no IntegrationRegistry entry.

Exceptions¶

See also¶

• Webhook Receiver — inbound webhook endpoint that dispatches ProcessWebhookJob and routes payloads to handleWebhook()
• Integration Contract design — reasoning behind the design decisions for both directions