Class \avadim\FastExcelLaravel\ExcelReader

ExcelReader is a thin Laravel wrapper around a FastExcelReader book. It does not extend a concrete reader; instead it composes an avadim\FastExcelReader\AbstractBook and adds the Eloquent-aware import helpers. Because it relies only on the shared AbstractBook / AbstractSheet public API, the same wrapper works for every format the reader supports — XLSX, legacy XLS (Excel 97-2003) and CSV — and the format is detected automatically from the file content (see Reading legacy XLS files and Reading CSV files).

Any method that is not listed below is transparently forwarded to the wrapped AbstractBook (see Delegated methods).

Upgrade note. Up to and including 3.x ExcelReader extended \avadim\FastExcelReader\Excel. It no longer does, so it is not an instance of that class anymore. Type-hint on \avadim\FastExcelLaravel\ExcelReader instead. Static helpers that used to be inherited (validate(), colLetter(), colNum(), setTempDir(), …) now live only on \avadim\FastExcelReader\Excel.

Own methods:

• open() -- Open a workbook (XLSX or XLS) for import
• openString() -- Open a workbook held in a string for import
• openStream() -- Open a workbook from an open stream resource for import
• sheet() -- Returns the current or a named sheet as a SheetReader
• withHeadings() -- Set headings for the current sheet
• mapping() -- Set mapping callback for the current sheet
• importModel() -- Import data into a model from the current sheet
• readRows() -- Read rows from the current sheet (applies the mapping, if any)
• getBook() -- Returns the wrapped book instance
• wrapSheet() -- Wraps a book sheet in a SheetReader (used internally)
• __construct()

open()#

public static function open(string $file, ?array $options = []): ExcelReader

Open a workbook for import. The format is selected from the file content, so XLSX, XLS and CSV are opened the same way; the file extension is ignored. A file that is neither a valid XLSX (ZIP) nor XLS (OLE2) is read as CSV.

Parameters#

• string $file
• array|null $options -- supported keys:
  • temp_dir -- directory for temporary files used when reading XLSX; falls back to the fast-excel.temp_dir config value. XLS and CSV are read straight from the file and never use a temp dir.
  • CSV options -- delimiter, enclosure, escape, encoding, skip_empty_lines, comment_prefix, mode ('strict'/'tolerant'). They apply only to CSV and fall back to the fast-excel.csv config values; a per-call option wins, a null keeps the reader default. See Reading CSV files.

openString()#

public static function openString(string $content, ?array $options = []): ExcelReader

Open a workbook held in a string. The content is written to a temporary file and then opened by open(), so the format is detected from the bytes (XLSX, XLS or CSV) and the same options apply. The temporary file is removed when the script ends; it is created in the temp_dir option directory, then config('fast-excel.temp_dir'), then storage_path('app/tmp/fast-excel'). Throws \avadim\FastExcelReader\Exception for an empty string. See Reading from a string or a stream.

Parameters#

• string $content
• array|null $options -- same keys as open()

openStream()#

public static function openStream($stream, ?array $options = []): ExcelReader

Open a workbook from an open readable stream resource. The stream is copied into a temporary file from its current position (it is not rewound, so non-rewindable streams work) and then opened by open(). The caller keeps the ownership of the stream: it is not closed here. Throws \avadim\FastExcelReader\Exception if the argument is not a resource or the stream produces no data.

Parameters#

• resource $stream
• array|null $options -- same keys as open()

sheet()#

public function sheet(?string $name = null): ?SheetReader

Returns the current sheet, or the sheet with the given name, wrapped in a SheetReader. Returns null if the named sheet does not exist.

Parameters#

• string|null $name

withHeadings()#

public function withHeadings(?array $headers = []): ExcelReader

Set headings for the current sheet. The first row of the read area is always skipped; if $headers is not empty, these names are used as attribute names (in column order) instead of the values of the first row. The setting applies to the next import operation only.

Naming. This is the wrapper's name for the reader's own withHeader() (avadim\FastExcelReader\AbstractSheet::withHeader()). The wrapper uses withHeadings() to match the Laravel ecosystem convention (as in maatwebsite/excel); the underlying reader calls the same concept withHeader().

Parameters#

• array|null $headers

mapping()#

public function mapping($callback): ExcelReader

Set a mapping for the current sheet. Accepts a callback function (array $row): array or an array of column => attribute correspondences. The setting applies to importModel() and readRows().

Parameters#

• \Closure|callable|array $callback

importModel()#

public function importModel(string $modelClass, $address = null, $columns = null, ?int $batchSize = null): ExcelReader

Import data from the current sheet into a model in a single transaction: a new model is filled and saved for each row (fill() + save()), or the rows are inserted in batches when $batchSize is given, see SheetReader::importModel().

Parameters#

• string $modelClass
• string|bool|null $address -- read area, e.g. 'B:D', 'B4', 'B4:D7'
• array|bool|null $columns
• int|null $batchSize -- insert rows in batches of this size instead of saving each model

readRows()#

public function readRows($columnKeys = [], ?int $resultMode = null, ?bool $styleIdxInclude = null): array

Returns cell values of the current sheet as a two-dimensional array [row][col]. If a mapping is set, it is applied to every row.

Parameters#

• array|bool|int|null $columnKeys
• int|null $resultMode
• bool|null $styleIdxInclude

getBook()#

public function getBook(): \avadim\FastExcelReader\AbstractBook

Returns the wrapped book instance (an avadim\FastExcelReader\Excel for XLSX, avadim\FastExcelReader\Xls\XlsBook for XLS or avadim\FastExcelReader\Csv\CsvBook for CSV).

Parameters#

None

wrapSheet()#

public function wrapSheet(\avadim\FastExcelReader\AbstractSheet $sheet): SheetReader

Wraps a sheet returned by the book in a SheetReader, reusing the wrapper so that state set on a sheet (headings, mapping) survives later access to the same sheet. Called internally; you normally use sheet() instead.

Parameters#

• \avadim\FastExcelReader\AbstractSheet $sheet

__construct()#

public function __construct(\avadim\FastExcelReader\AbstractBook $book)

Wraps an already opened book. Use the static open() factory instead of constructing directly.

Parameters#

• \avadim\FastExcelReader\AbstractBook $book

Delegated methods#

Every reading method not listed above is forwarded to the wrapped AbstractBook via __call. When a delegated call returns a sheet (or a list of sheets), the result is re-wrapped in a SheetReader so fluent chains keep working, e.g.:

$excel->mapping($callback)->from('A2')->readRows();

The full list of delegated methods — getSheetNames(), getSheet(), selectSheet(), setReadArea(), from(), readCells(), readColumns(), readCallback(), getDefinedNames(), getProperties() (XLSX only), setDateFormat(), dateFormatter(), image and style helpers, and so on — is documented in the underlying FastExcelReader library: https://github.com/aVadim483/fast-excel-reader#readme