Сообщение «неверный файл» скрывает минимум три разных отказа: веб-сервер не принял 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-таблицы остаются неизменными.

Применение должно переживать повтор запуска

  1. Присвоить импорту уникальный ID и сохранить checksum исходного файла.
  2. Зафиксировать подтверждённый план изменений из staging.
  3. Обновлять товары по устойчивому SKU или внутреннему ключу в транзакции либо порциями с checkpoint.
  4. Повтор того же import ID не должен второй раз создавать товары.
  5. После commit сравнить контрольные количества и сохранить отчёт для отката.

Для больших книг полная транзакция может держать блокировки слишком долго; тогда применяйте небольшие порции и журнал изменений с компенсирующей операцией. Пользователь должен видеть состояние queued, validating, ready, applying, completed или failed, а не бесконечный индикатор.

Проблемный файл передаём без лишних данных

Для диагностики достаточно версии PHP и PhpSpreadsheet, безопасного образца с теми же листами и типами ячеек, размера файла, ожидаемых заголовков и точного этапа отказа. Удалите реальные цены, контакты и коммерческие данные. После завершения настройте срок хранения карантина и очищайте исходники по import ID.

Проверенные источники