NovinkaZverejnili sme 50+ Laravel balíkov ako open source
Custom AI apps, agents and automation — Roundly ConsultingRoundly
Všetky balíky
Imports for Laravel

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

RowFilterVypíš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

RiadokSkipUpdateCreateNew
platnývytvorívytvorívytvorí
spárovaný (existujúci záznam)preskočíaktualizujevytvorí
duplicita v súborepreskočípreskočípreskočí
neplatnýnikdy sa nezapíšenikdy sa nezapíšenikdy 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 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.

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 kryptomien

Odoslaní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.