Сообщение «неверный файл» скрывает минимум три разных отказа: веб-сервер не принял upload, библиотека не распознала книгу или бизнес-валидатор отклонил данные. Запишите этап и безопасный код ошибки отдельно. Пользователю можно показать строку и колонку, но не путь временного файла, stack trace и внутренний SQL.
Расширение .xlsx недостаточно. Office Open XML хранится как пакет OPC с частями SpreadsheetML, а файл с переименованным CSV или HTML может выглядеть правдоподобно только по имени. Reader должен подтвердить формат содержимого до того, как приложение начнёт читать ячейки и менять каталог.
Ошибка на каждом этапе выглядит по-разному
| Этап | Наблюдаемый признак | Что записать в диагностику |
|---|---|---|
| HTTP upload | Файл отсутствует или обрезан | upload error, фактический размер, серверный лимит |
| Распознавание | Reader не может открыть пакет | Определённый формат, версия библиотеки, код исключения |
| Структура книги | Нет листа или обязательной колонки | Имя листа, найденные заголовки, ожидаемый шаблон |
| Строки | Цена, SKU или остаток не проходят правила | Номер строки, колонка, безопасное описание причины |
| Применение | Часть товаров обновилась | ID запуска, стадия транзакции, способ отката |
Сначала сохраните upload под сгенерированным именем вне публичного каталога и ограничьте размер. OWASP рекомендует allowlist расширений, проверку типа и сигнатуры, безопасное имя и лимиты; ни одна отдельная проверка не является достаточной. Файл остаётся недоверенным даже после успешного открытия Excel.
Reader выбираем по содержимому и ловим исключение
$type = \PhpOffice\PhpSpreadsheet\IOFactory::identify($tmpPath);
if ($type !== "Xlsx") { throw new DomainException("Ожидался файл XLSX"); }
$reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($type);
$reader->setReadDataOnly(false);
$book = $reader->load($tmpPath);PhpSpreadsheet умеет определить подходящий reader и проверяет, соответствует ли содержимое заявленному формату. Актуальный reader также блокирует XML с объявленными внешними сущностями. Библиотеку всё равно нужно обновлять: обработчик сложных файлов является частью поверхности атаки.
Заголовки проверяем до товарных строк
- Нормализуйте пробелы и регистр только для сопоставления заголовков, но показывайте пользователю исходное значение.
- Связывайте колонки по именам, а не по буквам A, B, C, если шаблон допускает перестановку.
- Различайте пустую ячейку, ноль и формулу с пустым результатом — для цены и остатка это разные команды.
- Даты читайте с учётом формата ячейки; режим read data only может скрыть маску, по которой число отличалось от даты.
- Ограничьте число листов, строк и формул согласно возможностям очереди импорта.
Если шаблон версии 3 получил файл версии 2, не пытайтесь угадывать новые значения по позициям. Храните version в отдельной ячейке или проверяемом наборе заголовков и выдавайте ссылку на актуальный шаблон. Это быстрее исправляет файл и не создаёт тихих сдвигов колонок.
Dry run формирует отчёт, но не меняет каталог
Разберите строки в staging: нормализуйте SKU, валюту и числа, найдите дубликаты внутри файла, затем сопоставьте с каталогом. Результат — количество вставок, обновлений, пропусков и таблица ошибок с ограниченным числом примеров. Пока есть блокирующие ошибки, production-таблицы остаются неизменными.
Применение должно переживать повтор запуска
- Присвоить импорту уникальный ID и сохранить checksum исходного файла.
- Зафиксировать подтверждённый план изменений из staging.
- Обновлять товары по устойчивому SKU или внутреннему ключу в транзакции либо порциями с checkpoint.
- Повтор того же import ID не должен второй раз создавать товары.
- После commit сравнить контрольные количества и сохранить отчёт для отката.
Для больших книг полная транзакция может держать блокировки слишком долго; тогда применяйте небольшие порции и журнал изменений с компенсирующей операцией. Пользователь должен видеть состояние queued, validating, ready, applying, completed или failed, а не бесконечный индикатор.
Проблемный файл передаём без лишних данных
Для диагностики достаточно версии PHP и PhpSpreadsheet, безопасного образца с теми же листами и типами ячеек, размера файла, ожидаемых заголовков и точного этапа отказа. Удалите реальные цены, контакты и коммерческие данные. После завершения настройте срок хранения карантина и очищайте исходники по import ID.