SIGNALS Documentation
API Reference

Plugin import/export

How plugins will extend the import/export engine — merge status on this branch, intended registrar seams, and what you can do today with SchemaRegistry field flags.

Status on this branch

These PluginRegistrar seams are shipped (import/export engine merge landed on this branch):

  • importTransform(Transform|TransformContract $transform) — register custom transforms for mapping chains
  • importableModel(ImportableModelContract $model) — register a plugin import target (+ optional SupportsPolymorphicImport)
  • exportableModel(ExportableModelContract $model) — register a plugin export source (extends PluginExportHandler)
  • planTemplate(ImportPlanTemplateDefinition|PlanTemplateContract $template) — register a reusable migration-plan template

All four are manifest-agnostic infrastructure seams (no manifest section required today). Worked example: External DB sync plugin.

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.

Intended SDK surface (post-merge)

When the phase-6 merge lands, expect seams roughly shaped as:

Method Role (intent)
importableModel(...) Register a model/entity the importer can target
exportableModel(...) Register a model/entity the exporter can target
importTransform(...) Transform rows during import
planTemplate(...) Named migration / sync plan templates (e.g. CRM migration)

Copy signatures from PluginRegistrar on the merged branch — do not invent them here. After merge, this page should be updated to paste the real method signatures and walk through a fixture plugin.

What to build today instead

For sync-style integrations (the Xero pattern):

  1. Declare data_access for the entities/fields you need.
  2. Subscribe to Event hooks (account.updated, invoice.issued, …).
  3. Push/pull via PluginHttpClient + write back ids through Signals::update() custom fields.
  4. Keep plugin-private state in plugin_* tables.

See Getting started, Data access, and Examples.

Import/export-specific registry contract pages may land with the engine. Until then, field metadata lives on SchemaRegistry / FieldDefinition, and plugin data touching goes through the guarded facade only.