Plugin import/export
Register import targets, export sources, transforms and reusable import plans.
Status in the current release
These PluginRegistrar seams are shipped in the current release:
importTransform(Transform|TransformContract $transform)— register custom transforms for mapping chainsimportableModel(ImportableModelContract $model)— register a plugin import target (+ optionalSupportsPolymorphicImport)exportableModel(ExportableModelContract $model)— register a plugin export source (extendsPluginExportHandler)planTemplate(ImportPlanTemplateDefinition|PlanTemplateContract $template)— register a reusable migration-plan template
All four are manifest-agnostic infrastructure seams (no manifest section required today).
What already exists (not registrar seams)
App\ValueObjects\FieldDefinition carries importable and exportable booleans. Core fields exposed through SchemaRegistry for the plugin entity map are importable today — see the tables on Plugin data models.
That metadata feeds the import/export engine’s field mapping UI; it is not the same as registering a plugin importable/exportable model via the registrar.
Sync integrations
For sync-style integrations (the Ledger pattern):
- Declare
data_accessfor the entities/fields you need. - Subscribe to Event hooks (
account.updated,invoice.issued, …). - Push/pull via
PluginHttpClient+ write back ids throughPluginContext::update()custom fields. - Keep plugin-private state in
plugin_*tables.
See Getting started, Data access, and Examples.
Related registry contracts
See Registries and resolvers for the registrar signatures and Plugin Export Registry for export registrations. Field metadata lives on SchemaRegistry / FieldDefinition; access to core data still goes through the guarded SDK.
Worked transform registration
A transform receives one cell, the source row and the import context. This example normalises a partner reference. The name is persisted in mapping chains, so keep it stable.
use App\Contracts\Imports\TransformContract;
use App\Services\Imports\Transforms\TransformContext;
final class PartnerReference implements TransformContract
{
public function name(): string
{
return 'acme_partner_reference';
}
public function configSchema(): array
{
return [];
}
public function apply(mixed $value, array $row, TransformContext $context): mixed
{
return is_string($value) ? strtoupper(trim($value)) : $value;
}
}
$registrar->importTransform(new PartnerReference);
importTransform(Transform|TransformContract $transform): self accepts either contract name. The registration needs no manifest declaration.
Worked import target registration
The target supplies wizard fields, duplicate lookup, validation and create/update behaviour. Here Acme\Inventory\Models\PartnerItem is a plugin-owned Eloquent model with a plugin_acme_partner_items table and fillable reference attribute. Declare that table under tables[] and create it in the package migration. Core records must still be changed through the mediated SDK or an authorised core action.
use Acme\Inventory\Models\PartnerItem;
use App\Contracts\Imports\ImportableModelContract;
use App\Services\Imports\Commit\ImportRowContext;
use App\ValueObjects\FieldDefinition;
use Illuminate\Database\Eloquent\Model;
final class PartnerItems implements ImportableModelContract
{
public function modelSlug(): string
{
return 'acme_partner_items';
}
public function label(): string
{
return 'Partner items';
}
public function fields(): array
{
return [
'reference' => new FieldDefinition(
name: 'reference', type: 'string', label: 'Reference',
rules: ['required', 'string', 'max:255'], required: true, nullable: false,
),
];
}
public function defaultDuplicateFields(): array
{
return ['reference'];
}
public function validate(array $mapped, ImportRowContext $context): array
{
return is_string($mapped['reference'] ?? null) && trim($mapped['reference']) !== ''
? []
: [['message' => 'A reference is required.', 'column' => 'reference']];
}
public function findDuplicate(array $mapped, array $duplicateFields): ?Model
{
return PartnerItem::query()->where('reference', $mapped['reference'])->first();
}
public function create(array $mapped): array
{
$item = PartnerItem::query()->create(['reference' => $mapped['reference']]);
return ['id' => (string) $item->getKey(), 'outcome' => 'created'];
}
public function update(Model $existing, array $mapped, bool $fillEmptyOnly = false): array
{
if (! $fillEmptyOnly || blank($existing->getAttribute('reference'))) {
$existing->setAttribute('reference', $mapped['reference']);
$existing->save();
}
return ['id' => (string) $existing->getKey(), 'outcome' => 'updated'];
}
}
$registrar->importableModel(new PartnerItems);
importableModel(ImportableModelContract $model): self needs no import-specific manifest declaration. The named FieldDefinition exposes the reference in the mapping wizard. Enforce any package-specific permission in your writer before mutating data. SupportsPolymorphicImport is an optional additional contract for polymorphic targets.
Worked export source registration
An export source builds a query under the creating user's authority and describes its columns. The example uses the same plugin-owned table. Declare and register acme.inventory.export as a plugin permission before assigning it to users.
use Acme\Inventory\Models\PartnerItem;
use App\Contracts\Exports\ExportableModelContract;
use App\Models\User;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Support\Facades\Gate;
final class PartnerItemsExport implements ExportableModelContract
{
public function key(): string
{
return 'acme_partner_items';
}
public function label(): string
{
return 'Partner items';
}
public function query(User $user, ?array $filters = null): Builder
{
Gate::forUser($user)->authorize('acme.inventory.export');
return PartnerItem::query();
}
public function columns(User $user): array
{
return [['key' => 'reference', 'label' => 'Reference', 'type' => 'string']];
}
}
$registrar->exportableModel(new PartnerItemsExport);
exportableModel(ExportableModelContract $model): self needs no export-specific manifest declaration. The contract extends PluginExportHandler; export jobs use source_type=plugin and the registered key as source_id. Apply any supported filters inside the handler instead of accepting arbitrary query input.
Worked plan registration
A plan template describes ordered import steps and their dependencies. This one uses the target registered above:
use App\Enums\ImportPlanType;
use App\Services\Imports\Plans\ImportPlanStepDefinition;
use App\Services\Imports\Plans\ImportPlanTemplateDefinition;
$registrar->planTemplate(new ImportPlanTemplateDefinition(
key: 'acme_partner_inventory',
name: 'Partner inventory',
type: ImportPlanType::BulkImport,
steps: [new ImportPlanStepDefinition(
name: 'Partner items',
targetModel: 'acme_partner_items',
duplicateFields: ['reference'],
)],
));
planTemplate(ImportPlanTemplateDefinition|PlanTemplateContract $template): self needs no manifest declaration. A PlanTemplateContract implementation can supply the same key, name, description, type and steps. Multi-step templates use dependsOn to reference dependency step names.
Plan step definitions also accept skip: true to leave a step disabled in the initial plan. The flag is preserved when the definition is serialized; the remaining steps retain their dependency order.