Unopim Data Transfer

UnoPim Data Transfer

Import/export runs as a queued, batched, state-tracked pipeline in packages/Webkul/DataTransfer. The pipeline instantiates your classes through config — a wrong signature is a fatal at runtime, and an invented method is silently never called. Verify every override against the base class before writing it.

REQUIRED BACKGROUND: Use unopim-standards for Laravel 13 / PHP 8.4 idiom, comments, localization and scale rules. Use unopim-exec to resolve commands for this workspace. Use unopim-verify before claiming any change complete. For package scaffolding, providers, credentials and cURL clients, use unopim-plugin-development.

Reference files

Invented API vs real API

Earlier docs invented methods that do not exist anywhere in the codebase. NEVER write the left column; the right column is what core ships.

Core keeps the misspellings initilize() and getSkippedtemsCount(). Match them in subclasses; "fixing" the spelling creates a new method core never calls.

Hard rules

• Exporters extend Webkul\DataTransfer\Helpers\Exporters\AbstractExporter; importers extend Webkul\DataTransfer\Helpers\Importers\AbstractImporter and MUST pass JobTrackBatchRepository to parent::__construct().
• Counters: $this->createdItemsCount++ after a create, $this->updatedItemsCount++ after an update, $this->skippedItemsCount++ on skip. Never swap them — job summaries report them by name.
• The async quartet (async, track_by, label_by, list_route) is required ONLY for route-backed select options. Static inline options are correct for fixed lists — core ships file_format and date_format that way in packages/Webkul/DataTransfer/src/Config/exporters.php.
• Export sources MUST stream for large entities: override getResults() with an id-cursor (keyset) source like packages/Webkul/DataTransfer/src/Helpers/Sources/Export/ProductCursor.php. The inherited default hydrates source->all() — acceptable only for small entities (locales, currencies, channels).
• Bulk existence lookups inside batches use array_chunk($keys, 1000) + whereIn, never one query per row — see packages/Webkul/DataTransfer/src/Helpers/Importers/Product/SKUStorage.php.
• State machines include validating (import), paused and cancelled besides pending/validated/processing/completed/failed — pause, resume and cancel are live flows; see pipeline.md.
• Job config title values and every user-facing string are translation keys ({package}::app...), propagated to all 33 locales.
• No comments inside method bodies, array literals, route groups or Blade markup in any code you write here.

Checklist

• Exporter: exportBatch(JobTrackBatchContract $batch, $filePath): bool; opens with Event::dispatch + initilize(); closes with updateBatchState(..., Export::STATE_PROCESSED)
• Importer: both validateRow() and importBatch() implemented with the exact base signatures; parent constructor called
• Validator: extends Default\JobValidator, named {Entity}JobValidator, declarative $rules
• getResults() streams via id-cursor for any large entity — no unbounded ->all()/->get()
• External-id/SKU lookups preloaded chunked (array_chunk(..., 1000) + whereIn), not queried per row
• Select filter fields: static options for fixed lists; async quartet only with a real list_route returning objects keyed by track_by/label_by
• Dependent selects use depends_on
• Config files merged in the provider (exporters, importers, quick_exporters keys) — exemplar packages/Webkul/AiAgent/src/Providers/AiAgentServiceProvider.php
• Counters increment on the matching action; summary counts verified in the job report
• New admin routes (e.g. list_route endpoints) registered under ['admin'] middleware and ACL-covered — enforcement is fail-open by route name