Reading files

Both readers are part of the package and stream: only the current row is in memory, and XLSX shared strings are spooled to a php://temp stream (memory up to xlsx.shared_strings_memory, then disk) — a workbook with 200,000 strings reads in well under 16 MB. There is no third-party spreadsheet library to install or keep updated.

Format by content

The extension and the client MIME type are ignored. An empty file is rejected (empty), and one larger than limits.file_size is rejected before reading (too_large):

CSV

• UTF-8 with or without a BOM. The whole file is checked in 64 KB blocks; the first invalid byte rejects it as not_utf8 with its line and a guess (Windows-1250, Windows-1252, ISO-8859) and tells the user to save as “CSV UTF-8”. Pure ASCII passes.
• Excel’s sep=; first line sets the delimiter. Otherwise it is sniffed among csv.delimiters (comma and semicolon) from the most consistent parse, or set with upload(…, delimiter: ';') or useDelimiter().
• RFC 4180 quoting (delimiters, quotes and newlines inside quotes), no escape character; LF, CRLF and CR-only files.
• Row numbers are the ones a spreadsheet would show; blank records count but are not imported; missing trailing cells are empty; a non-empty value beyond the header’s last column is a row error.
• A leading ' before = + - @, a tab or a CR is stripped (csv.unescape_formula_prefix) — what the package’s own CSV writer adds.

XLSX

Container and XML safety: the ZIP is opened read-only with a local-vs-central header consistency check; the entry count is capped (xlsx.max_entries); encrypted entries are refused; no part may declare more than xlsx.max_part_size; the bytes really inflated are counted while parsing, per part and across the read (xlsx.max_inflated), so a size that lies is stopped mid-stream; entries are parsed straight from the ZIP, never extracted; a DOCTYPE in any parsed part rejects the file before an entity could be declared, and an external entity is never resolved. The reader restores the process’s previous libxml error mode when the file closes, so queue workers and Octane keep their own.

Sheets, delimiters and title rows

// 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

Limits

limits.file_size (KB, default 10,240), limits.rows (data rows, default 10,000, ceiling 100,000), limits.columns (default 100 — non-empty cells only) and limits.cell_length. An importer may override each with limits() — withCellLength() for the cell length.

Rejections

A whole upload is rejected and nothing is stored. ImportFileRejectedException (HTTP 422) carries reason (a RejectionReason) and context; its message is translated in English and Slovak and says what to do:

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
}

A sheet that does not exist throws SheetNotFoundException (422) — available lists the sheet names.

The standalone reader

The pipeline’s own reader, usable on its own for any CSV or XLSX your app needs to read — no session, nothing stored, the same safety checks:

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() rejects the file (too_many_rows) at the first row over the limit. A disk source is copied to a temp directory imports:sweep clears. SpreadsheetFile::open() reads a local path directly with 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');