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()->paginate(50); // every row: RowResult(rowNumber, status, outcome, errors, match, changes, label)
$session->rows(RowFilter::invalid())->paginate(50);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()->paginate(50); // every row in file order (since 1.1.0)
$session->rows(RowFilter::flagged())->paginate(50); // stored rows only: invalid, failed, duplicate, matched
$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::updates() pridá rozdiel polí, načítaný znova pre každú stránku.
Výpis riadkov
| RowFilter | Vypíše |
|---|---|
all() | Každý dátový riadok — nový, aktualizácia, preskočený, chybný — v poradí súboru; predvolený filter rows() (od 1.1.0). |
flagged() | Každý uložený riadok: neplatný, zlyhaný, duplicitný v súbore, spárovaný — to, čo all() vypisoval pred 1.1.0. |
invalid() · duplicates() · updates() · creates() · skips() | Podľa stavu alebo plánovaného výsledku. |
status(RowStatus ...) | Podľa stavu; status(RowStatus::Valid) vypíše aj obyčajné vytvorenia. |
field($name) | Neplatné alebo zlyhané riadky s chybou v danom poli. |
Import riadkov nikdy neukladá obyčajné vytvorenia ani žiadne hodnoty riadkov, preto filter, ktorý ich môže vypísať — all(), creates(), status(Valid) — streamuje zdrojový súbor (pracovnú kópiu XLSX) a doplní do neho uložené riadky. Vzdialená stránka nečíta súbor od začiatku: začne pri dávke importu, ktorá ju obsahuje (náhľad si ukladá posun každej dávky), takže stránka stojí približne commit.chunk_size + per_page prečítaných riadkov a total pri all() pochádza z counts()->total. Filtre len nad uloženými riadkami stránkujú v SQL. Pred náhľadom a po odstránení súboru vypíše all() uložené riadky; dávka súborov ukladá každú položku, takže vypisuje z tabuľky ako doteraz.
Označenia riadkov
Každý RowResult má label, ktorý sa pre každú stránku číta z buniek riadka a nikdy sa neukladá — v databáze sa teda neuchováva nič ďalšie zo súboru. Najviac 255 znakov; položky dávky súborov sa označia názvom súboru:
- bunka z labelField() importéra, ak je deklarované a vyplnené;
- inak prirodzený kľúč tak, ako ho riadok zapísal — kandidát, podľa ktorého sa riadok spároval, inak prvý, ktorý vypĺňa — s časťami spojenými „ · “ (Laptop · Acme), odkazom v podobe, ako bol zadaný, a prázdnou bunkou nahradenou default() poľa;
- inak hodnota kľúča uniqueInFile() v rovnakej podobe (od 1.2.0);
- inak Riadok N (imports::preview.row_label v jazyku relácie, v angličtine Row N) — aj pre chybný riadok s prázdnou bunkou kľúča a pre každý riadok po odstránení súboru.
Režimy duplicít
| Riadok | Skip | Update | CreateNew |
|---|---|---|---|
| platný | vytvorí | vytvorí | vytvorí |
| spárovaný (existujúci záznam) | preskočí | aktualizuje | vytvorí |
| duplicita v súbore | preskočí | preskočí | preskočí |
| neplatný | nikdy sa nezapíše | nikdy sa nezapíše | nikdy sa nezapíše |
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 updatesRež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.
Prejavte lásku k open source
Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.
Ďalšie spôsoby podpory vrátane kryptomienOdoslaním daru súhlasíte s našimi podmienkami prijímania darov.
Chcete to zabudovať do svojho produktu?
Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.