NewWe open-sourced 50+ Laravel packages
Custom AI apps, agents and automation — Roundly ConsultingRoundly
All packages

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

MethodRequiredDefaultNotes
model(): class-string<Model>yes—Must live on the package tables’ connection — one transaction.
fields(): list<Field>yes—At least one; names unique, ^[a-z][a-z0-9_]*$.
ownership(): Ownershipyes—Fail closed — see Owners and permissions.
authorize(?Authenticatable, Model $owner, ImportOperation): boolyes—Asked for View, Upload, Commit and Rollback.
create(ImportRow, ImportContext): Modelyes—Return a saved model inside the owner. Returning an existing record is fine — it is ledgered as linked and never undone.
update(Model, ImportRow, ImportContext): Modelfor UpdatethrowsOverriding it enables the Update mode.
key(): stringnothe class name without Importer, snake case (AssetsImporter → assets, TeamMembersImporter → team_members)^[a-z][a-z0-9_.-]{0,63}$, unique. Declare it in production — saved mappings and HasImportSource lookups are keyed by it.
label(): string|arraynothe key as a headline (Team Members)A translation key, text, or ['en' => …, 'sk' => …].
naturalKey(): ?NaturalKeynonullNo key, no duplicate detection. May hold references with storeAs().
uniqueInFile(): ?FileKeynonullWhat makes a row unique within one file, without matching existing records (since 1.2.0) — see Duplicates within a file.
labelField(): ?stringnonullThe field whose cell labels a row in the preview; null = the natural key’s value, else the file key’s, else Row N.
modes(): list<DuplicateMode>noSkip, Update (when update() is overridden), CreateNew—
defaultMode(): DuplicateModenoSkipMust be one of modes().
rollback(Model, ImportContext): RollbackOutcomenodeletes → DeletedReturn Handled (undone another way) or Kept.
changeDetection(): ChangeDetectionnoChangeDetection::checksum()Or ::updatedAt(), or ::checksum(['name', …]).
checksumAttributes(Model): arraynoraw attributes minus key, timestamps, deleted_atWhat the checksum covers.
diff(Model, ImportRow): list<FieldChange>nomapped, non-blank, non-reference fields vs same-named attributesThe preview of updates — a blank cell is no change.
formats(): list<SourceFormat>noCSV, XLSX—
limits(): Limitsnofrom configLimits::fromConfig()->withRows(50_000)->withColumns(200)->withFileSize(20_480)->withCellLength(255) — rows capped at 100,000, columns at 16,384, the cell length clamped to 1 … 1,048,576 and checked per cell (too_long).

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.

References in a natural key

Since 1.1.0 a candidate may hold a reference field that declares storeAs() — named by the field (vendor) or by its column (vendor_id), both mean the same part. “Product + vendor + plan” is then one key:

Field::text('product')->required(),
Field::reference('vendor')->to(Vendor::class)->by('vat_id', 'name')->storeAs('vendor_id'),
Field::reference('plan')->to(Plan::class)->by('code')->storeAs('plan_id'),

public function naturalKey(): NaturalKey
{
    return NaturalKey::by('product', 'vendor', 'plan_id');   // a reference by its field or its storeAs() column
}

The reference is resolved first — inside the owner, by its by() columns — and the part compares the referenced record’s key with the model’s storeAs() column, so Acme and its VAT id SK100 are the same key and two such rows are duplicate_in_file. A reference that cannot be resolved is the usual row error (unknown_reference, ambiguous_reference; another owner’s record is never found) and the row is never matched; a blank reference leaves its candidate out, like any blank key part. caseInsensitive() folds the plain parts only — a key column is compared exactly (bigint, UUID or ULID). Messages and labels show the reference as the row wrote it. A reference without storeAs() is refused: there is no column to compare it with.

Duplicates within a file — uniqueInFile()

Since 1.2.0. An importer that always creates — one invitation per email, where old invitations (accepted, revoked, expired or soft-deleted) must not count — declares what makes a row unique within one file, instead of or next to a natural key:

use RoundlyConsulting\Imports\Definition\FileKey;

public function uniqueInFile(): ?FileKey
{
    return FileKey::by('email')->caseInsensitive();   // ->then('phone') adds a candidate
}
  • Normalised like a natural key: trimmed, lower-cased with caseInsensitive(), a reference (with storeAs()) by the record it resolves to. A blank part leaves its candidate out, so blank key cells are never duplicates of each other — required() is validation’s job.
  • The first row holding a key is evaluated as usual. Every later row sharing a filled candidate with it is duplicate_in_file, skipped at commit and counted under duplicates (the preview’s duplicatesInFile). Its error names the earlier row — “Same as row 3” (imports::validation.same_as_row) — and its label is the label field, else the natural key, else the file key.
  • Existing records are never looked up: no match, no matches_deleted_record, no matched status.
  • The check carries across preview windows (row 1 and row 1001 are compared), and its result is what the commit skips.
  • With a natural key too, matching works as before; the file key then checks the rows that are still valid or matched, and a row already a natural-key duplicate keeps that reason and message.
  • null (the default) changes nothing. A file key naming an unknown field, or a reference without storeAs(), is refused at registration.

Row labels

labelField() names the field whose cell labels a row in the preview — without it the label is the natural key’s value, else the file key’s, else Row N (see Validated preview):

public function labelField(): ?string
{
    return 'asset_tag';   // the cell that labels a row in the preview: "AST-0042"
}

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();
  • a natural-key part that is neither a field nor a reference’s storeAs() column, a natural-key reference without storeAs(), or one reference named twice in one candidate (vendor and vendor_id);
  • a labelField() that is not a field;
  • a uniqueInFile() key naming a field that is not one, or a reference without storeAs();
  • 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.

Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

More ways to support, including crypto

By donating, you agree to our donation terms.

Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.