FastExcelReader

🇬🇧 English · 🇷🇺 Русский

FastExcelReader — часть проекта FastExcelPhp, в который входят

• FastExcelWriter — создание Excel-таблиц
• FastExcelReader — чтение Excel-таблиц и CSV-файлов
• FastExcelTemplator — генерация Excel-таблиц из XLSX-шаблонов
• FastExcelLaravel — специальная редакция для Laravel

Введение#

Библиотека спроектирована лёгкой, очень быстрой и требует минимум памяти.

FastExcelReader умеет читать Excel-совместимые таблицы в формате XLSX (Office 2007+), в устаревшем формате XLS (Office 97-2003) и CSV-файлы. Она только читает данные, но делает это очень быстро и с минимальным расходом памяти.

Возможности#

Поддержка формата XLSX#

• Поддержка формата XLSX (Office 2007+) с несколькими листами
• Автоопределение типов валюта/число/дата
• Автоматическое и пользовательское форматирование значений даты-времени
• Библиотека умеет находить и извлекать изображения из XLSX-файлов
• Библиотека умеет читать параметры оформления ячеек — шаблоны форматирования, цвета, границы, шрифты и т.д.

Поддержка формата XLS#

• Поддержка устаревшего формата XLS (Office 97-2003, BIFF8) с тем же API, что и у XLSX
• Значения, даты, стили ячеек, текст формул и изображения возвращаются в той же форме
• Формат определяется по сигнатуре файла, а не по расширению
• Потоковый обход строк; метаданные книги, общие строки и изображения всё равно занимают память

Поддержка формата CSV#

• Открывается через Excel::open() как обычный файл с одним листом и тем же API чтения, что у XLSX/XLS, либо через Excel::openCsv() для низкоуровневого движка
• Определение разделителя: автоматическое или указанное вручную
• Широкая поддержка кодировок: любая кодировка, поддерживаемая вашим окружением PHP
• Поддержка полей с кавычками и без, а также экранированных кавычек (удвоенных)
• Многострочные поля: обработка переносов строк внутри полей в кавычках
• Два режима — строгий (следует RFC 4180) и толерантный (для нестандартных CSV-файлов)

Установка#

Используйте composer, чтобы установить FastExcelReader в свой проект:

composer require avadim/fast-excel-reader

Быстрый старт#

use \avadim\FastExcelReader\Excel;

// И XLSX, и устаревший XLS, и CSV открываются так же — ридер выбирается по сигнатуре файла
$excel = Excel::open(__DIR__ . '/files/demo.xlsx');

// Прочитать все строки в двумерный массив (СТРОКА x КОЛОНКА)
$rows = $excel->readRows();

// Или читать строку за строкой (экономно по памяти)
$sheet = $excel->sheet();
foreach ($sheet->nextRow() as $rowNum => $rowData) {
    // обработка $rowData
}

Подробнее — в руководстве Начало работы.

Выбор способа открытия#

Начиная с 4.5, используйте явную фабрику, если формат или уровень API известен:

Опции CSV принимают массив, CsvOptions или null. Явные CSV-фабрики допускают пустой CSV; универсальный open() отклоняет пустой вход. Принудительный формат в open() поддерживается только для ['format' => 'csv']; для XLSX/XLS используйте явные фабрики.

Подготовка к 5.0: в 4.x openCsv() по-прежнему возвращает CsvReader, но в 5.0 планируется возврат CsvBook. Замените низкоуровневые вызовы на openCsvReader(), чтобы сохранить методы getCsvLine() и fromRow(). Для API книги и листа выбирайте openCsvBook(); метод getReader() этой книги также даёт доступ к движку.

isXlsx() проверяет сигнатуру ZIP, а isXls() — OLE2; это не доказательство того, что контейнер содержит поддерживаемую книгу. validate() проверяет обязательные части XLSX и корректность XML, но не полную схему OOXML и не правильность формул.

Возможности форматов и ограничения ресурсов#

readRows() собирает результат в память; для больших импортов используйте nextRow(). Общие строки XLSX и XLS целиком загружаются в память, а XLS также загружает глобальное хранилище изображений. Потоковый обход строк не означает постоянную память всей книги. openString() и openStream() копируют вход на диск. Успешные временные файлы живут до завершения процесса, в том числе в долгоживущих workers; уничтожение книги не удаляет их немедленно. Метод close() на уровне книги в 4.5 отсутствует.

Документация#

Руководства#

• Начало работы — чтение ячеек, строк и колонок
• Чтение данных — построчно, ключи массивов, пустые ячейки и строки
• Продвинутое чтение — области чтения, именованные диапазоны, колбэки
• Типы значений и форматирование дат
• Стили ячеек — чтение полной информации о стиле ячеек
• Изображения — извлечение изображений из XLSX
• Метаданные листа — проверка данных, ширины колонок, высоты строк, закрепление областей, цвет вкладки, объединённые ячейки, размерность
• Разбор CSV — чтение CSV-файлов
• XLS (Excel 97-2003) — чтение XLS-файлов

Справочник API#

Справочник API генерируется автоматически из PHPDoc и доступен на английском языке:

• API Reference
  • Class Excel
  • Class Sheet
  • Class Csv\CsvReader
  • Class Csv\CsvOptions

Примеры#

Больше примеров — в папке /demo.

История изменений#

Список изменений — в CHANGELOG.ru.md.

Хотите поддержать FastExcelReader?#

Если этот пакет оказался полезным, вы можете поставить мне звезду на GitHub.

Или можете сделать донат :)

• USDT (TRC20) TSsUFvJehQBJCKeYgNNR1cpswY6JZnbZK7
• USDT (ERC20) 0x5244519D65035aF868a010C2f68a086F473FC82b
• ETH 0x5244519D65035aF868a010C2f68a086F473FC82b