Čítanie súborov

Obe čítačky sú súčasťou balíka a streamujú: v pamäti je len aktuálny riadok a zdieľané reťazce XLSX sa presúvajú do streamu php://temp (v pamäti do xlsx.shared_strings_memory, potom na disk) — zošit s 200 000 reťazcami sa prečíta s výrazne menej než 16 MB. Nie je potrebná žiadna externá knižnica na tabuľky, ktorú by bolo treba inštalovať a aktualizovať.

Formát podľa obsahu

Prípona aj MIME typ od klienta sa ignorujú. Prázdny súbor sa odmietne (empty) a súbor väčší než limits.file_size sa odmietne ešte pred čítaním (too_large):

CSV

• UTF-8 s BOM aj bez neho. Celý súbor sa kontroluje po 64 KB blokoch; prvý neplatný bajt ho odmietne ako not_utf8 s uvedením riadka a odhadu (Windows-1250, Windows-1252, ISO-8859) a používateľovi poradí uložiť súbor ako „CSV UTF-8“. Čisté ASCII prejde.
• Prvý riadok sep=; z Excelu určí oddeľovač. Inak sa rozpozná spomedzi csv.delimiters (čiarka a bodkočiarka) podľa najkonzistentnejšieho rozdelenia, alebo ho nastavíte cez upload(…, delimiter: ';') či useDelimiter().
• Úvodzovky podľa RFC 4180 (oddeľovače, úvodzovky a nové riadky v úvodzovkách), bez escape znaku; súbory s LF, CRLF aj len CR.
• Čísla riadkov zodpovedajú tým, ktoré ukáže tabuľkový editor; prázdne záznamy sa rátajú, ale neimportujú; chýbajúce bunky na konci sú prázdne; neprázdna hodnota za posledným stĺpcom hlavičky je chyba riadka.
• Úvodný ' pred = + - @, tabulátorom alebo CR sa odstráni (csv.unescape_formula_prefix) — to pridáva vlastný CSV zapisovač balíka.

XLSX

Bezpečnosť kontajnera a XML: ZIP sa otvára len na čítanie s kontrolou konzistencie lokálnych a centrálnych hlavičiek; počet položiek je obmedzený (xlsx.max_entries); šifrované položky sa odmietnu; žiadna časť nesmie deklarovať viac než xlsx.max_part_size; skutočne rozbalené bajty sa rátajú počas spracovania, pre každú časť aj za celé čítanie (xlsx.max_inflated), takže nepravdivá veľkosť sa zastaví uprostred streamu; položky sa spracúvajú priamo zo ZIP-u, nikdy sa nerozbaľujú; DOCTYPE v ktorejkoľvek spracúvanej časti súbor odmietne skôr, než by sa mohla deklarovať entita, a externá entita sa nikdy nerozrieši. Čítačka po zatvorení súboru obnoví predchádzajúci režim chýb libxml procesu, takže queue workery aj Octane si ponechajú svoj.

Hárky, oddeľovače a nadpisy

// A title row above the headers, a named sheet, a forced delimiter
$session = Imports::for($team)->by($user)->upload(
    'assets',
    $request->file('file'),
    sheet: 'Assets',        // a name (exact, then case-insensitive) or a 1-based position among visible sheets
    delimiter: ';',
    headerRow: 2,
    locale: 'sk',           // labels, messages and the decimal separator of this session
);

// Change it later — the preview is dropped (preview again)
$session->useSheet('Assets');   // XLSX: another sheet
$session->useDelimiter(';');    // CSV: override the sniffed delimiter
$session->useHeaderRow(2);      // a title row above the headers

Limity

limits.file_size (KB, predvolene 10 240), limits.rows (dátové riadky, predvolene 10 000, strop 100 000), limits.columns (predvolene 100 — len neprázdne bunky) a limits.cell_length. Importér môže každý z nich prepísať cez limits() — dĺžku bunky cez withCellLength().

Odmietnutia

Odmietne sa celé nahratie a nič sa neuloží. ImportFileRejectedException (HTTP 422) nesie reason (RejectionReason) a context; jej správa je preložená do angličtiny a slovenčiny a hovorí, čo urobiť:

use RoundlyConsulting\Imports\Exceptions\ImportFileRejectedException;

try {
    $session = Imports::for($team)->by($user)->upload('assets', $request->file('file'));
} catch (ImportFileRejectedException $e) {
    $e->reason;          // RejectionReason::NotUtf8
    $e->context;         // the values in the message (line, encoding guess)
    $e->getMessage();    // translated, and says how to fix the file
}

Neexistujúci hárok vyhodí SheetNotFoundException (422) — available uvádza názvy hárkov.

Samostatná čítačka

Vlastná čítačka spracovania, použiteľná samostatne pre akýkoľvek CSV alebo XLSX súbor, ktorý vaša aplikácia potrebuje prečítať — bez relácie, nič sa neukladá, s rovnakými bezpečnostnými kontrolami:

use RoundlyConsulting\Imports\DataTransferObjects\ImportSource;
use RoundlyConsulting\Imports\Facades\Imports;

$file = Imports::read($request->file('file'), sheet: 'Assets', delimiter: null, headerRow: 1);
// or Imports::read('/path/to/file.csv'), Imports::read(ImportSource::disk('s3', 'exports/assets.xlsx'))

try {
    $file->format();            // SourceFormat::Csv | SourceFormat::Xlsx
    $file->sheets();            // list<SheetInfo> (XLSX), [] for CSV
    $file->sheet();             // the sheet read (XLSX) or null
    $file->delimiter();         // CSV: the delimiter used; delimiterSource(): Sniffed | Hint | Override
    $file->encoding();          // CSV: `utf-8` or `utf-8-bom`; null for XLSX
    $file->headerRow();         // 1-based
    $file->headers();           // list<string|null>, null for a blank header cell
    $file->displayHeaders();    // list<string>, a blank header is `Column C`
    foreach ($file->rows() as $rowNumber => $cells) {   // keyed by the row number a user sees
        // list<Cell|null> — null for an empty cell
    }
    $file->count();             // data rows, in one full pass (every limit enforced)
} finally {
    $file->close();             // also closed on destruct
}

rows() súbor odmietne (too_many_rows) pri prvom riadku nad limitom. Zdroj z disku sa skopíruje do dočasného adresára, ktorý vyčistí imports:sweep. SpreadsheetFile::open() číta lokálnu cestu priamo s ReadOptions:

use RoundlyConsulting\Imports\Reading\{Cell, ReadOptions, SpreadsheetFile};

$file = SpreadsheetFile::open('/path/to/file.xlsx', ReadOptions::fromConfig(sheet: 'Assets', headerRow: 2));

foreach ($file->rows() as $rowNumber => $cells) {
    $cell = $cells[0];      // ?Cell
    $cell?->type;           // CellType: text, number, boolean, date, error
    $cell?->value;          // string, numeric string, bool, CarbonImmutable or an error code (#N/A)
    $cell?->display();
}

// Accepted everywhere a file is
ImportSource::upload($uploadedFile); ImportSource::path('/tmp/a.csv'); ImportSource::disk('s3', 'exports/a.xlsx');