Importers

An importer describes one record type: its model, its fields, how its records belong to an owner, who may import them, how a row becomes a record and how an existing one is recognised. Extend RoundlyConsulting\Imports\Importer and register the class:

// config/imports.php
'importers' => [
    App\Imports\AssetsImporter::class,
    App\Imports\DocumentsImporter::class,
],

// or at runtime, e.g. in a service provider's boot()
use RoundlyConsulting\Imports\Facades\Imports;

Imports::register(AssetsImporter::class);

Importers are resolved through the container — constructor injection works — and validated once per process, lazily, on first use.

Methods and defaults

Final helpers on every importer: kind() (ImportKind::Rows), supportsUpdate() (whether update() is overridden), field(string $name) and labelIn(?string $locale).

use RoundlyConsulting\Imports\Definition\{ChangeDetection, Limits};
use RoundlyConsulting\Imports\Enums\{DuplicateMode, SourceFormat};

public function key(): string { return 'assets'; }          // declare it in production
public function label(): string|array { return ['en' => 'Assets', 'sk' => 'Majetok']; }

public function modes(): array { return [DuplicateMode::Skip, DuplicateMode::Update]; }
public function defaultMode(): DuplicateMode { return DuplicateMode::Update; }
public function formats(): array { return [SourceFormat::Xlsx]; }

public function limits(): Limits
{
    return Limits::fromConfig()->withRows(50_000)->withColumns(200)->withFileSize(20_480)->withCellLength(255);
}

public function changeDetection(): ChangeDetection
{
    return ChangeDetection::checksum(['name', 'serial_number']);   // or ChangeDetection::updatedAt()
}

Declare key() for production importers. Saved mappings and HasImportSource lookups are keyed by it, so with the default, renaming the class renames the key and orphans them. A class name that gives no valid key — an anonymous class, a class named just Importer — is refused naming the class.

Natural keys

use RoundlyConsulting\Imports\Definition\NaturalKey;

public function naturalKey(): ?NaturalKey
{
    return NaturalKey::by('asset_tag')->then('serial_number');   // candidates, tried in order
}

NaturalKey::by('first_name', 'last_name')->caseInsensitive();    // one candidate, several fields

• Validation comes first: an invalid row never matches or counts as a duplicate.
• A row’s first filled candidate that finds a record is its match. A later candidate finding a different record is conflicting_match; two records for one key is ambiguous_match.
• A row repeating an earlier valid row’s key, or matching the same record, is duplicate_in_file.
• Keys are matched against soft-deleted records too. A live record always wins, but a key only a soft-deleted record holds makes the row invalid (matches_deleted_record, in every mode) — your unique index still covers that record, so a create would fail at commit.

The create and update callbacks

public function create(ImportRow $row, ImportContext $context): Model
{
    return Asset::create([...$row->attributes(), ...$context->ownerAttributes()]);
}

public function update(Model $asset, ImportRow $row, ImportContext $context): Model
{
    return tap($asset)->update($row->changes());
}

ImportRow carries two fill-ready maps. attributes() holds every value, each reference field becoming its storeAs() column with the referenced key (['asset_tag' => 'AST-1', 'vendor_id' => 5]) — use it for create(). changes() is attributes() restricted to mapped fields whose cell was not blank — use it for update().

Blank cells in the Update mode keep the stored value: exports from other tools routinely leave columns blank, and updates are never reverted by undo. update() writing $row->changes() follows that rule, and the default diff() previews no change for a blank cell. To clear values on purpose, write $row->attributes() in update() and override diff() to match.

What callbacks receive

use RoundlyConsulting\Imports\Exceptions\ImportRowException;

public function create(ImportRow $row, ImportContext $context): Model
{
    $row->number();                    // the spreadsheet row number
    $row->get('name');                 // the coerced value
    $row->has('purchased_on');         // the field is mapped
    $row->filledIn('serial_number');   // mapped and not blank
    $row->reference('vendor');         // the resolved Vendor model, or null
    $row->raw('name');                 // the cell as text
    $row->cell('name');                // the Cell (type, value)
    $row->all(); $row->filled(); $row->only('name'); $row->except('vendor');
    $row->attributes();                // ['asset_tag' => 'AST-1', …, 'vendor_id' => 5]
    $row->changes();                   // attributes() of mapped, non-blank cells only

    $context->owner; $context->actor; $context->mode; $context->locale; $context->timezone;
    $context->sessionId; $context->batchId;
    $context->query(Vendor::class);    // a query constrained to the owner
    $context->ownerAttributes();       // ['team_id' => 7] for Ownership::column('team_id')

    if ($row->get('status') === 'retired') {
        throw ImportRowException::because(__('app.imports.retired'));   // fails this row only
    }

    return Asset::create([...$row->attributes(), ...$context->ownerAttributes()]);
}

ImportContext exposes owner, actor, importer, sessionId, batchId, mode, locale and timezone (the session’s — the clock the file’s times were read in) as public properties, plus query(string $model, ?Ownership $rule = null) — a query constrained to the owner by the importer’s rule or the one you pass — and ownerAttributes(). Throw ImportRowException::because('…') to fail one row with your own translated message.

The rollback hook

Undo deletes created records unless they changed since. Override rollback() to undo a record another way:

use RoundlyConsulting\Imports\Enums\RollbackOutcome;

public function rollback(Model $record, ImportContext $context): RollbackOutcome
{
    if ($record->accepted_at !== null) {
        return RollbackOutcome::Kept;      // leave it alone
    }

    $record->revoke();                     // undone another way

    return RollbackOutcome::Handled;       // the default deletes it: RollbackOutcome::Deleted
}

Registration rules

Registration refuses, with InvalidImporterDefinitionException naming the importer and the rule:

• a bad key, two importers with one key, no ownership, a model on another connection;
• no fields, bad or duplicate field names, a choice without options, a reference without to() or by();
• natural-key fields that are missing or are references;
• the Update mode without update(), a default mode outside modes(), no formats;
• storeAs() on a field that is not a reference, or a storeAs() column that is not a column name or is another field’s name;
• database presence rules — exists: / unique: strings, Rule::exists() / Rule::unique() — because they bypass the owner scope and could reveal another owner’s data. Use Field::reference() and naturalKey() instead.

A reference that inherits a rule its model cannot carry (team_id on a model without it) throws UnscopedQueryException — declare ->ownedBy() on the field.

Discovery for a UI

Imports::importers()->available($user, $team);     // list<ImporterDescriptor> the user may view
Imports::importers()->describe('assets', 'sk');    // fields: label, type, required, options, example, help, aliases, format
Imports::importers()->all(); Imports::importers()->has('assets'); Imports::importers()->find('assets');
Imports::importer('assets')->modes();
Imports::importer('assets')->descriptor('sk');

available() lists only the importers whose authorize() allows View. The registry is printed by:

php artisan imports:importers   # key, label, kind, fields, modes, formats

Octane and long-running workers

Importer instances are container singletons inside the registry for the life of the process — a queue worker, an Octane worker. Inject nothing request-scoped into an importer’s constructor (the current user, the request, a tenant): it would leak into the next request or job. Everything per import arrives through ImportContext and the ImportRow.