Šablóny a reporty chýb

Každý importér má šablónu pripravenú na vyplnenie, ako zošit XLSX alebo súbor CSV, s hlavičkami v požadovanom jazyku:

use RoundlyConsulting\Imports\Enums\TemplateFormat;
use RoundlyConsulting\Imports\Facades\Imports;

return Imports::template('assets', TemplateFormat::Xlsx, locale: 'sk')->download();
Imports::importer('assets')->template(TemplateFormat::Csv)->store('s3', 'templates/assets.csv');
$path = Imports::template('people')->toTemporaryFile();       // you own (and delete) the file

• Stĺpce sú polia importéra v poradí, bez tých s excludeFromTemplate(). Hlavičky sú popisy v požadovanom jazyku (záloha: záložný jazyk aplikácie, potom názov poľa); povinné polia končia znakom „ *“.
• Vzorový riadok (templates.example_row, predvolene zapnutý): example() každého poľa alebo ukážka pre jeho typ.
• CSV: UTF-8 s BOM (templates.csv_bom), oddeľovač podľa jazyka (templates.csv_delimiter: čiarka, v slovenčine bodkočiarka) a riadok s nápovedou (templates.hint_row.csv): povinné alebo voliteľné, povolené hodnoty, príklad dátumu, Áno/Nie, stĺpce s odkazmi.
• XLSX: tučná ukotvená hlavička; šírky stĺpcov; textové stĺpce vo formáte @, aby sa zachovali úvodné nuly, dátumy yyyy-mm-dd, desatinné čísla 0.00…; rozbaľovacie zoznamy (templates.data_validation) pre stĺpce s výberom a áno/nie — priamo, ak sa zoznam zmestí do 255 znakov, inak skrytý hárok Lists a definovaný názov; vstupná správa pri každom stĺpci (popis a nápoveda). Predvolene bez riadka s nápovedou (templates.hint_row.xlsx).
• Nezmenený vzorový riadok alebo riadok s nápovedou, ktorý v nahratej šablóne zostal, sa rozpozná a preskočí (ráta sa ako templateRows) v ktoromkoľvek dodanom jazyku — ale len v prvých dvoch neprázdnych dátových riadkoch, kam ich šablóna dáva. Skutočný riadok nižšie, ktorého hodnoty sa zhodujú so vzorom, sa normálne importuje.

Objekt Template

$template = Imports::template('assets');

$template->format;                    // TemplateFormat
$template->filename;                  // assets.xlsx — the label as a slug in the template's locale
$template->download('assets-template.xlsx');   // StreamedResponse
$template->store('s3', 'templates/assets.xlsx');
$template->toTemporaryFile();
$template->contents();

download() pošle prílohu s ASCII bezpečným filename a filename* v UTF-8, s hlavičkou X-Content-Type-Options: nosniff, a po odoslaní dočasný súbor odstráni. Dočasný súbor sa odstráni aj pri zániku objektu — okrem toho, ktorý ste získali cez toTemporaryFile(); ten patrí vám.

Z príkazového riadka

php artisan imports:template assets --format=csv --locale=sk --output=assets.csv

Reporty chýb

return $session->errorReport(TemplateFormat::Xlsx)->download();   // assets-errors.xlsx
$session->errorReport(TemplateFormat::Csv, 'sk');                    // the report's own labels in Slovak

Report obsahuje pôvodný riadok hlavičky a stĺpec Errors, len s chybnými riadkami — neplatnými v náhľade a zlyhanými pri importe — tak, ako boli nahraté, pripravené na opravu a nové nahratie. Pomenuje sa podľa nahratého súboru (assets-errors.xlsx), predvolene je to XLSX a overuje authorize(View). Argument jazyka vykreslí vlastné popisy reportu (stĺpec Errors, názov hárka, nepomenované stĺpce) v danom jazyku; správy zostanú v jazyku relácie a nahraté hlavičky tak, ako boli. Report dávky súborov má dva stĺpce, File a Errors, s jedným riadkom na každý odmietnutý súbor.

Vkladanie vzorcov

Každé CSV, ktoré balík zapíše — šablóny aj reporty chýb, ktoré opakujú hodnoty nahraté inými ľuďmi — pridá ' pred bunku, ktorá začína = + - @, tabulátorom alebo CR; obyčajné číslo (-5, 1,25) zostane bez zmeny. Pri čítaní CSV sa tento ' znova odstráni. Výstup XLSX je bezpečný zo svojej podstaty: inline reťazce, nikdy vzorce.