К содержимому
Akmelo

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

PHP SDK: Excel и CSV: ячейки, диапазоны и записи

Лист возвращает $document->sheet(). Адреса ячеек и номера строк начинаются с единицы, индексы выбора листов с нуля. Файл может содержать несколько секций, объединения и пустые строки: они не удаляются при чтении. Методы работают с уже извлечёнными данными. Перед обработкой полного файла проверяйте $document->complete().

name

name(): string

Имя листа в исходном файле.

$document = $ctx->documents()->fromBytes("Артикул;Остаток\nTEST-001;17", 'report.csv');
$sheet = $document->sheet();
$ctx->log($sheet->name());

rows

rows(): array

Все строки без предположений о заголовках. Пустые строки и промежутки сохраняются. Строки и столбцы массива индексируются с нуля.

$document = $ctx->documents()->fromBytes("Артикул;Остаток\nTEST-001;17", 'report.csv');
$sheet = $document->sheet();
$rows = $sheet->rows();

rowCount

rowCount(): int

Количество извлечённых строк, включая пустые. Это не число записей: у файла могут быть заголовки, итоги и несколько секций.

$document = $ctx->documents()->fromBytes("Артикул;Остаток\nTEST-001;17", 'report.csv');
$sheet = $document->sheet();
$count = $sheet->rowCount();

columnCount

columnCount(): int

Ширина самой длинной извлечённой строки. У неполных строк недостающие ячейки остаются пустыми.

$document = $ctx->documents()->fromBytes("Артикул;Остаток\nTEST-001;17", 'report.csv');
$sheet = $document->sheet();
$count = $sheet->columnCount();

cell

cell(string $address, bool $resolveMerged = false): string|int|float|bool|null

Значение по адресу A1, в том числе абсолютному $A$1. Возвращает исходный скалярный тип или null. resolveMerged=true читает значение верхней левой ячейки объединения; по умолчанию объединения не заполняются. Вне извлечённой части возвращает null, поэтому сначала проверяйте complete().

$document = $ctx->documents()->fromBytes("Артикул;Остаток\nTEST-001;17", 'report.csv');
$sheet = $document->sheet();
$stock = $sheet->cell('B2');
$title = $sheet->cell('C1', true);

row

row(int $number): array

Строка по номеру с единицы. За пределами листа возвращает пустой массив; нулевой и отрицательный номер вызывают ошибку.

$document = $ctx->documents()->fromBytes("Артикул;Остаток\nTEST-001;17", 'report.csv');
$sheet = $document->sheet();
$values = $sheet->row(2);

column

column(int|string $column, int $startRow = 1, ?int $endRow = null): array

Столбец по буквам или номеру с единицы. startRow и endRow включительны. Пропущенные значения сохраняются как null.

$document = $ctx->documents()->fromBytes("Артикул;Остаток\nTEST-001;17", 'report.csv');
$sheet = $document->sheet();
$stocks = $sheet->column('B', 2);

range

range(string $range, bool $resolveMerged = false): array

Прямоугольная матрица A1:C10, включая пустоты. До 50 000 ячеек. resolveMerged=true размножает значение якоря объединения только в возвращаемом массиве. Обратные и неверные диапазоны вызывают ошибку.

$document = $ctx->documents()->fromBytes("Артикул;Остаток\nTEST-001;17", 'report.csv');
$sheet = $document->sheet();
$values = $sheet->range('A1:B2');

nonEmptyRows

nonEmptyRows(): array

Непустые строки с исходными номерами в ключах с единицы. Значения 0 и false считаются данными, а не пустотой.

$document = $ctx->documents()->fromBytes("Артикул;Остаток\nTEST-001;17", 'report.csv');
$sheet = $document->sheet();
$rows = $sheet->nonEmptyRows();

find

find(string $text, bool $exact = false, int $limit = 100): array

Поиск по значениям без учёта регистра. exact=true требует полного совпадения. Возвращает address и value, максимум limit совпадений (1–1000). Формулы не исполняются и не участвуют в поиске вместо значений.

$document = $ctx->documents()->fromBytes("Артикул;Остаток\nTEST-001;17", 'report.csv');
$sheet = $document->sheet();
$matches = $sheet->find('TEST-', false, 20);

findHeader

findHeader(array $labels, int $maxRows = 50): ?int

Находит первую строку, в которой есть все перечисленные подписи. Сравнение без учёта регистра и пробелов по краям. По умолчанию проверяет первые 50 строк; maxRows от 1 до 5000. Если шапка не найдена, возвращает null. Для многоуровневой шапки используйте явные диапазоны.

$document = $ctx->documents()->fromBytes("Артикул;Остаток\nTEST-001;17", 'report.csv');
$sheet = $document->sheet();
$header = $sheet->findHeader(['Артикул', 'Остаток']);

merged

merged(): array

Список объединений XLSX/XLS вида A1:C1. Значения остальных ячеек по умолчанию не дублируются. В CSV объединений нет.

$document = $ctx->documents()->fromBytes("Артикул;Остаток\nTEST-001;17", 'report.csv');
$sheet = $document->sheet();
$ranges = $sheet->merged();

formula

formula(string $address): ?string

Исходный текст формулы XLSX с ведущим = или null. Расчётное значение читается через cell(), исходное выражение через formula(). Общие формулы зависимых ячеек могут не содержать полный текст: ориентируйтесь на сохранённое значение.

$document = $ctx->documents()->fromBytes("Артикул;Остаток\nTEST-001;17", 'report.csv');
$sheet = $document->sheet();
$formula = $sheet->formula('B2');

error

error(string $address): ?string

Сохранённая ошибка XLSX, например #DIV/0!, либо null. Не подменяет ошибку нулём.

$document = $ctx->documents()->fromBytes("Артикул;Остаток\nTEST-001;17", 'report.csv');
$sheet = $document->sheet();
$error = $sheet->error('B2');

records

records(int $headerRow = 1, ?int $startRow = null, ?int $endRow = null): array

Превращает выбранную секцию в записи. headerRow задаёт шапку с единицы, startRow/endRow задают включительный диапазон данных. headerRow=0 использует буквенные ключи A, B, C. Пустые строки пропускаются. Пустые подписи заменяются буквами, дубликаты получают суффиксы _2, _3 без потери полей. Итоги и примечания не распознаются автоматически: ограничьте диапазон явно.

$document = $ctx->documents()->fromBytes("Артикул;Остаток\nTEST-001;17", 'report.csv');
$sheet = $document->sheet();
$records = $sheet->records(1, 2);
foreach ($records as $record) $ctx->emit(['sku' => $record['Артикул'], 'stock' => (int) $record['Остаток']]);

structure

structure(): array

Обезличенная структура для AI-плана: rows, columns, merged и sample первых 24×16 ячеек. sample содержит только e (пусто), s (строка), n (число), b (логическое). Имена листов, заголовки, значения, ссылки и формулы отсутствуют. Сам метод не вызывает модель.

$document = $ctx->documents()->fromBytes("Артикул;Остаток\nTEST-001;17", 'report.csv');
$sheet = $document->sheet();
$layout = $sheet->structure();

calculation

calculation(string $address): string

Статус пересчёта XLSX: calculated, unsupported, external_reference, circular_reference, error или limit. not_calculated означает, что формула есть, но пересчёт не проводился; not_formula означает обычную ячейку. Неподдерживаемые формулы дают явную ошибку, не ноль и не скрытую подмену старым значением.

$document = $ctx->documents()->fromBytes("Название;Количество\nТовар;17", 'report.csv');
$sheet = $document->sheet();
$status = $sheet->calculation('B2');

cachedValue

cachedValue(string $address): string|int|float|bool|null

Значение, которое автор XLSX сохранил в файле до пересчёта. Оно может отсутствовать или устареть. Для обычной ячейки совпадает с cell(). Используйте только как явно выбранный резерв: по умолчанию SDK возвращает пересчитанные значения.

$document = $ctx->documents()->fromBytes("Название;Количество\nТовар;17", 'report.csv');
$sheet = $document->sheet();
$saved = $sheet->cachedValue('B2');