Download the PHP package dmachehin/sheet-mapper without Composer
On this page you can find all versions of the php package dmachehin/sheet-mapper. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download dmachehin/sheet-mapper
More information about dmachehin/sheet-mapper
Files in dmachehin/sheet-mapper
Package sheet-mapper
Short Description Map spreadsheet rows to structured PHP data objects
License
Informations about the package sheet-mapper
Sheet Mapper
PHP библиотека, которая превращает строки CSV/XLS/XLSX в DTO-классы на основе атрибутов-схем. Внутри используется PhpSpreadsheet, так что поддерживаются как таблицы с заголовками, так и файлы с фиксированными колонками.
Возможности
#[SheetMapping]на классе описывает лист и наличие строки заголовков. Еслиtarget_sheetне указан, при чтении файла будут обработаны все листы книги.#[SheetField]на свойствах задаёт номер колонки (с нуля) либо имя заголовка.- Для merge-ячеек можно точечно включить наследование значения из master-ячейки через
allow_merge. - Поиск колонок по регулярным выражениям:
header_regexpпомогает, если заголовки динамические. - Опциональная проверка значений по регулярному выражению через
value_regexp. - Кастомные преобразования значений перед приведением типов через
value_callback. - Проверка структуры листа:
enforce_field_mapping=trueгарантирует наличие всех обязательных колонок/заголовков и отсутствие лишних. По умолчаниюenforce_field_mapping=false.ignored_columnsпозволяет пометить исключения (по индексу колонки или имени заголовка). - Автоматическое приведение типов для
string,int,float,bool, а такжеDateTimeInterfaceи enum. - Пропуск полностью пустых строк и понятные исключения, если значения отсутствуют или заголовок не найден.
Быстрый старт
DTO с атрибутами:
Чтение файла:
Если target_sheet не задан, map() пройдёт по всем листам workbook и вернёт объединённый результат.
Чтение без заголовков
Если в листе нет строки заголовков, установите has_header_row: false и укажите индекс колонки:
Merge-ячейки
По умолчанию merge-ячейки не разворачиваются: дочерние ячейки диапазона считаются пустыми. Если для конкретного поля нужно читать значение из верхней левой ячейки merge-диапазона, включите allow_merge: true.
Это полезно для вертикально объединённых ячеек, где значение задано только в первой строке группы.
Проверка структуры листа
Если обязательная колонка/заголовок не найден, будет выброшено SheetMapperException. Лишние заголовки тоже приводят к ошибке. Все элементы из ignored_columns допускается пропустить и/или оставить в файле как исключения — полю останется значение по умолчанию.
Регулярные выражения для заголовков
Поле name найдёт любую колонку, чей заголовок начинается со слова «Product». Можно комбинировать header и header_regexp, но как минимум одно из column, header, header_regexp должно быть задано.
Регулярные выражения для значений
value_regexp проверяет каждое непустое значение и выбрасывает SheetMapperException, если оно не совпало с шаблоном.
Кастомные преобразования значений
Если стандартного приведения типов недостаточно, используйте value_callback — он получает исходное значение ячейки и должен вернуть преобразованный результат (подойдёт любая callable: 'trim', ['ClassName', 'method'] и т.п.).
При ошибке внутри callback будет выброшено SheetMapperException, так что можно смело кидать собственные исключения с пояснениями.