The Imports facade

Everything goes through one facade, RoundlyConsulting\Imports\Facades\Imports, sugar over the ImportsManager singleton. It is also registered as the global alias Imports:

use RoundlyConsulting\Imports\Enums\{SessionStatus, TemplateFormat};
use RoundlyConsulting\Imports\Facades\Imports;

// Importers and templates
Imports::importers()->available($user, $team);
Imports::register(AssetsImporter::class);
Imports::importer('assets')->descriptor('sk');
Imports::template('assets', TemplateFormat::Xlsx, locale: 'sk')->download();

// Everything for one owner — the entry point HTTP code uses
$imports = Imports::for($team)->by($user);
$session = $imports->upload('assets', $request->file('file'));
$files = $imports->uploadFiles('documents', $request->file('files'));
$imports->sessions('assets', SessionStatus::Previewed)->paginate();
$imports->session($id)->counts();
$imports->batch($id)->summary();
$imports->mappings('assets')->all();
$imports->running('assets');

// Trusted paths, the reader and housekeeping
Imports::session($model); Imports::batch($id);
Imports::read($request->file('file'));
Imports::sweep(); Imports::prune();

The whole flow, start to finish:

$session = Imports::for($team)->by($user)->upload('assets', $request->file('file'));   // checked + stored
$session->suggestMapping();                       // MappingSuggestion (applied already when complete)
$session->map(['Inventory no' => 'asset_tag', 'Name' => 'name'])   // optional: by header text or column number
    ->saveMapping('ERP export');                  // optional: reused for identical headers
$session->mode(DuplicateMode::Update)->preview(); // ≤ 500 rows: now; more: queued (poll isPreviewed())
$session->counts();                               // ImportCounts
$session->rows(RowFilter::invalid())->paginate(50);
$batch = $session->commit();                      // a Laravel job batch
$batch->progress();
$batch->summary();
$batch->rollback();                               // within imports.undo.window

Manager methods

container() and perform() are public on the manager but internal — perform() is the funnel every handle runs its action through, the hook the fake records with. Don’t call them from app code.

Imports::for($owner)

$sheet is a name (exact, then case-insensitive) or a 1-based position among visible sheets; $headerRow is 1-based; $locale is the session locale — labels, messages and the decimal separator.

The session handle

Mutators return the handle, so a flow chains. Reads ask authorize(View) once per handle; writes ask their own operation. Source, mapping, mode, preview and discard are refused with ImportStateException once a commit holds the session:

The batch handle

Importers, templates and saved mappings

• Imports::importers() — all() (every ImportDefinition), find($key), has($key), describe($key, ?$locale), available(?$user, $owner, ?$locale).
• Imports::importer($key) — descriptor(?$locale), template(?$format, ?$locale), modes() (empty for a file importer).
• Template — format and filename properties; download(?$filename), store($disk, $path), toTemporaryFile(?$target), contents().
• Imports::for($owner)->mappings($importer) — all(), find($name), save($name, $columns), delete($name).
• RowQuery ($session->rows($filter)) — paginate($perPage = 50, ?$page), cursor(), count().

Value objects, DTOs and enums

• Definitions (Definition\): Field, NaturalKey, Ownership, ChangeDetection, FileRules, FileDuplicates, Limits, FieldChange. Callback arguments (Rows\): ImportRow, ImportContext, ImportFile. Reading (Reading\): SpreadsheetFile, Cell, ReadOptions.
• DTOs (final readonly): ImportSource, UploadData, UploadFilesData, SaveMappingData, ColumnMapping, MappedColumn, MappingSuggestion, SuggestedColumn, SavedMapping, SheetInfo, ImportCounts, ImportPreview, RowFilter, RowResult, CellError, RecordReference, Progress, ImportSummary, RollbackReport, ImportedRecordView, ImportAudit, FileReference, ImporterDescriptor, FieldDescriptor, OptionDescriptor, PruneReport, SweepReport, DoctorFinding.
• Models (swappable via imports.models.*): ImportSession, ImportBatch, ImportRowResult, ImportedRecord. ImportSession and ImportBatch have handle() and countOf(string $key) — one stored count (valid, creates, created, …), 0 when absent; the static ImportSession::count() is Eloquent’s row count.
• Enums are string-backed, use enums-for-laravel’s helpers (label(), labels(), options(), values(), fromLabel(), is(), …) and translate their labels in English and Slovak: