Overený náhľad

upload() skontroluje celý súbor (formát, kódovanie, limity, riadok hlavičky), uloží ho a vytvorí ImportSession. Relácia obsahuje zdroj, mapovanie, režim, počty, priebeh a stav — nikdy hodnoty riadkov.

Stavy

uploaded → needs_mapping | mapped → validating → previewed → committing → completed → rolling_back → rolled_back
                                      └ preview_failed        └ failed (resumable)      └ rollback_failed
                                                               └ cancelled
any status before the commit → discarded (discard()) | expired (imports:sweep after sessions.expire_after)

Spustenie náhľadu

use RoundlyConsulting\Imports\DataTransferObjects\RowFilter;

$session->preview();                    // up to preview.sync_threshold data rows: now; more: ValidatePreviewJob
$session->preview(queue: true);         // force the queue (false: force inline)
$session->isValidating();               // still on the queue: poll until…
$session->isPreviewed();                // …every row is checked and the session can be committed
$session->isCommitted();                // committing or past it
$session->progress();                   // Progress(processed, total, percent, phase)
$session->counts();                     // ImportCounts
$session->previewData();                // ImportPreview(counts, updateNotice, mode, unmappedColumns)
$session->rows(RowFilter::invalid())->paginate(50);   // RowResult(rowNumber, status, outcome, errors, match, changes)

Každý riadok prejde spracovaním hodnôt, validáciou Laravelu, vyhľadaním odkazov v dávkach a párovaním prirodzeného kľúča v dávkach, okno po okne — v rámci vlastníka, bez zápisu do vašich tabuliek a bez volania callbackov importéra. Do preview.sync_threshold (500) dátových riadkov sa overenie urobí priamo v požiadavke; väčšie súbory sa overujú vo fronte s priebehom (ImportPreviewProgressed každých preview.progress_every riadkov).

Počty

• total = valid + invalid + duplicates; duplicates = matched + duplicatesInFile.
• creates, updates a skips sa riadia režimom.
• templateRows (zostávajúce vzorové riadky či riadky s nápovedou) a blankRows sa uvádzajú osobitne.

Výsledky riadkov

use RoundlyConsulting\Imports\DataTransferObjects\RowFilter;
use RoundlyConsulting\Imports\Enums\RowStatus;

$session->rows(RowFilter::invalid())->paginate(50);
$session->rows(RowFilter::updates())->paginate(20);      // with the field diff: [{field, from, to}]
$session->rows(RowFilter::field('email'))->count();      // invalid or failed rows with an error on email
$session->rows(RowFilter::status(RowStatus::Matched))->cursor();

foreach ($session->rows(RowFilter::invalid())->cursor() as $row) {
    foreach ($row->errors as $error) {
        // $error->field, column, columnLetter, code, message (translated), value (≤ 100 characters)
    }
}

Výsledky riadkov sa ukladajú len pre výnimky — neplatné, duplicitné, spárované a neskôr zlyhané riadky — takže čistý súbor s 10 000 riadkami neuloží žiadny. Každý obsahuje chyby po bunkách (pole, číslo a písmeno stĺpca, kód, preloženú správu, výňatok do 100 znakov), ale žiadne hodnoty riadka. RowFilter::creates() streamuje súbor; RowFilter::updates() pridá rozdiel polí, načítaný znova pre každú stránku. Filtre: all(), invalid(), duplicates(), updates(), creates(), skips(), status(...), field($name).

Režimy duplicít

use RoundlyConsulting\Imports\Enums\DuplicateMode;

$session->mode(DuplicateMode::Update);   // on a previewed session: re-planned without re-reading the file
$session->previewData()->updateNotice;   // translated: undo removes created records only, never updates

Režim, ktorý importér neponúka, vyhodí ImportModeNotSupportedException (422). Pri relácii v stave previewed sa zmena režimu odmietne ako zastaraný náhľad (ImportStateException), ak sa náhľad medzitým posunul. Vždy, keď sú naplánované aktualizácie, updateNotice upozorní, že vrátenie importu odstráni len vytvorené záznamy a aktualizácie nikdy nevráti.

Zmeny počas overovania veľkého súboru

Zmena mapovania alebo zdroja (hárok, oddeľovač, riadok hlavičky) zahodí náhľad a zvýši preview_version. Náhľad vo fronte je unikátny pre reláciu a verziu a každý zápis behu sa uloží len vtedy, keď je jeho verzia aktuálna — novší náhľad teda vyhrá vždy, bez ohľadu na to, ktorý worker skončí prvý. Pri XLSX náhľad zapíše pracovnú kópiu (normalizované CSV hárka) a zaznamená posuny, od ktorých začínajú časti importu, takže import zošit nikdy znova neparsuje.

Každá zmena pred importom — zdroj, mapovanie, režim, náhľad, zahodenie aj expirácia — znova načíta reláciu so zámkom riadka a odmietne sa výnimkou ImportStateException (409), keď reláciu už prevzal import, aj keď sa začal o okamih skôr z inej karty alebo workera. Nikdy tak neprepíše plán bežiaceho importu ani nezmaže jeho súbor.

Stratené overovanie

imports:sweep označí reláciu v stave validating ako preview_failed, ak je jej priebeh starší než sessions.stale_after a jej úloha už nie je vo fronte ani nebeží — alebo ak prekročila sessions.abandon_after — a spustí ImportPreviewFailed s dôvodom abandoned. Úloha, ktorá sa objaví neskôr, nič nezapíše. Na opakovanie spustite náhľad znova.