Как я перевожу Битрикс на PHP 8.2/8.4 и UTF-8, когда шаблон застрял в прошлом

После переключения PHP главная открылась, административная часть работает, проверка системы не показывает критических ошибок. А ночью перестал приходить обмен из 1С, утром пропали настройки доставки. Именно такие поломки я ищу при миграции. Я — Семёнов Евгений Сергеевич, директор ООО «АйТи-Фреш». Покажу, как разделяю обновление ядра, адаптацию коммерческого решения и преобразование данных, где ставлю контрольные точки и при каких результатах останавливаю переход.

1. Сначала определяю конечную конфигурацию

На сентябрь 2026 года оставлять PHP 8.1 постоянной основой проекта я не планирую. Официальная поддержка этой ветки сообществом PHP завершилась 31 декабря 2025 года, а её последним выпуском стал PHP 8.1.34. С 1 февраля 2026 года «1С-Битрикс» требует PHP не ниже 8.2.0 и рекомендует PHP 8.4 или более новую совместимую ветку. С версии главного модуля main 24.0.0 продукты поставляются только в UTF-8, поддержка однобайтовых установок прекращена. Эти ограничения выясняю до установки обновлений, а не после появления нечитаемых строк и ошибок модулей. Требования «1С-Битрикс».

Для нового рабочего состояния я выбираю PHP 8.4, если ядро, шаблон, сторонние модули и интеграции проходят проверку именно на этой ветке. У PHP 8.2 поддержка исправлений безопасности заканчивается 31 декабря 2026 года, у PHP 8.4 — 31 декабря 2028 года. Поэтому PHP 8.2 можно использовать как диагностическую или короткую промежуточную остановку, но тогда я сразу назначаю срок следующего перехода. Поддержку конкретных пакетов в репозитории операционной системы проверяю отдельно: поставщик дистрибутива может сопровождать пакет по своему графику, однако это не меняет официальный жизненный цикл самой ветки PHP. Поддерживаемые версии PHP, завершённые ветки PHP.

При выборе между PHP 8.4 и более новой веткой я не ориентируюсь только на формулировку «и выше». Рекомендация платформы не подтверждает совместимость конкретного шаблона, платёжного модуля или защищённого кода. Для этой статьи целевой веткой остаётся PHP 8.4: она прямо рекомендована «1С-Битрикс», получает обновления безопасности и имеет достаточно зрелую поддержку со стороны распространённых зависимостей. На сервер ставлю актуальный исправляющий выпуск ветки из доверенного репозитория, а не закрепляю в регламенте номер, который со временем устареет.

Мой порядок аудита такой: фактические версии main и прикладных модулей, ограничения шаблона и сторонних решений, расширения и конфигурация PHP, затем структура и содержимое данных. Порядок самих изменений иной: сначала ставлю совместимые подготовительные обновления, потом перевожу установку в UTF-8, после этого продолжаю обновление платформы и меняю PHP. В этом различии вся суть. Обнаружить несовместимый модуль нужно заранее, даже если заменять или исправлять его будем на более позднем этапе.

• Зафиксировать версии модулей main, sale, catalog, iblock, search и perfmon.
• Записать текущие версии PHP для веб-запросов, командной строки и заданий cron.
• Проверить кодировку файлов, базы, соединения с СУБД и внешних обменов.
• Назначить целевую ветку PHP и критерии допуска к переключению.

2. Выясняю, что именно коммерческий шаблон «требует»

Я выписываю версии main, sale, catalog, iblock, search, perfmon и всех сторонних модулей. Рядом отмечаю доступность обновлений, заявленные требования поставщика и местные изменения. Проверяю каталог /local, старые шаблоны в /bitrix/templates, скопированные компоненты, файлы result_modifier.php, component_epilog.php и обработчики событий. Обновление модуля поставщика не доказывает, что обновился файл, когда-то скопированный в шаблон. Такие копии легко переживают несколько поколений платформы и продолжают вызывать давно исправленный код.

Фраза поставщика «PHP 8.1 и cp1251» требует расшифровки. Это минимальная версия PHP, единственная протестированная версия или жёсткое ограничение исполняемого кода? Кодировка относится к работающему сайту, исходным файлам или установочному архиву? При установке UTF-8-дистрибутива «1С-Битрикс» умеет преобразовывать размещённые в языковой папке мастера файлы с расширениями .php, .sql, .js, .snp и .csv; по умолчанию исходной считается Windows-1251, а иную кодировку разработчик указывает в описании мастера. Поэтому кодировка архива сама по себе ещё не доказывает, что готовый сайт обязан работать в cp1251. Документация по созданию дистрибутива решения.

Сначала запрашиваю у поставщика точную матрицу: версия решения, версия main, допустимые ветки PHP, требуемые расширения и кодировка рабочей установки. Формулировку «должно работать» подтверждаю журналом изменений или результатом испытаний. Если поддерживаемое обновление существует, устанавливаю его на копии штатным механизмом. Если открытый код доступен, оцениваю сопровождаемый патч. Если решение заброшено, сравниваю стоимость собственного сопровождения со стоимостью замены зависимого компонента.

С защищёнными файлами свободы меньше. Наличие ionCube Loader для PHP 8.4 не означает, что любой старый зашифрованный файл запустится на этой версии. В руководстве ionCube Encoder 15 указано, что файлы, закодированные специально для PHP 8.1, работают только на PHP 8.1, тогда как кодирование для PHP 8.2 рассчитано также на PHP 8.3 и PHP 8.4 при наличии подходящего Loader. Следовательно, для старой поставки может потребоваться новая сборка от вендора. Снимать проверку версии в установщике бессмысленно, если исполняемый файл несовместим с целевым интерпретатором. Руководство ionCube Encoder 15, раздел 2.1.

Если открытый код действительно привязан к однобайтовым строкам, я оцениваю объём переделки до назначения даты переезда. Проверяю вычисление длины и смещений, обрезку строк, регулярные выражения, формирование заголовков, экспорт и сравнение идентификаторов. Исправить несколько обработчиков обычно разумно. Брать на собственное сопровождение большой заброшенный модуль — отдельное бизнес-решение, цену которого нужно обсуждать прямо. Изменения поставки сохраняю отдельным патчем и повторно применяю в тестовом контуре после обновлений, чтобы новая версия не вернула старое поведение молча.

• Обновление от поставщика с заявленной поддержкой PHP 8.4.
• Сопровождаемый патч для доступного исходного кода.
• Новая сборка защищённых файлов для целевой ветки PHP.
• Замена решения, если поставщик прекратил поддержку и исправление экономически не оправдано.

3. Собираю промежуточный маршрут на изолированной копии

Копия должна воспроизводить файлы, базу, настройки PHP, веб-сервер, фоновые задания и внешние зависимости. Дамп без каталога /upload и конфигурации окружения для полноценной репетиции недостаточен. Я заранее проверяю восстановление, отделяю кеши и сессии стенда, блокирую настоящие письма, платежи, вебхуки и исходящий обмен. Доступ к копии ограничиваю. Клон, который отправляет тестовые изменения в рабочую учётную систему, способен испортить репетицию ещё до обновления.

Для исходной установки в cp1251 сначала ставлю только те совместимые обновления, которые нужны для штатной конвертации. Мастер конвертации сайта в UTF-8 появился в модуле «Монитор производительности» perfmon 23.200.0, выпущенном 14 декабря 2023 года. Это версия модуля perfmon, а не главного модуля main. Я использую наиболее свежую совместимую версию мастера, доступную конкретной лицензии и текущему ядру: после первого выпуска исправлялись отдельные случаи обработки данных. История версий perfmon.

Если нужные промежуточные обновления не предлагаются штатной системой, я не собираю ядро из случайных архивов. Сначала проверяю лицензию, цепочку зависимостей и поддерживаемый маршрут у «1С-Битрикс». Перед каждым этапом убеждаюсь, что резервная копия не только создана, но и действительно восстанавливается. Официальная инструкция прямо предупреждает о риске потери данных и рекомендует предварительную конвертацию на отдельной копии. Инструкция по смене кодировки сайта.

На исходном PHP 8.1 выполняю преобразование в UTF-8 и проверяю результат, пока подготовленная версия платформы ещё поддерживает это окружение. Затем ставлю доступные обновления штатных и сторонних модулей, проверяю проект на PHP 8.2 и устанавливаю обновления, которые стали доступны после переключения. До перехода на main 24.0.0 установка уже должна быть переведена в UTF-8: начиная с этой версии однобайтовый режим не поддерживается. Универсального номера main, который гарантирует совместимость всех коммерческих решений, не существует; маршрут определяется реальными зависимостями проекта. История версий main.

После стабилизации UTF-8 и обновлённых модулей испытываю PHP 8.4. Между этапами сохраняю согласованные контрольные точки: файлы, базу и конфигурацию. При новой ошибке сразу видно, какая группа изменений её принесла. Прохождение через PHP 8.2 — мой диагностический приём, а не обязательное требование языка. Если прямой переход на PHP 8.4 подготовлен, все зависимости совместимы и одинаковый набор тестов проходит, искусственная остановка на PHP 8.2 не нужна.

• Контрольная точка А: исходная установка восстанавливается и проходит базовые сценарии.
• Контрольная точка Б: установка работает в UTF-8, данные сверены, ветка PHP пока не изменена.
• Контрольная точка В: обновлённые модули и собственный код проходят испытания на PHP 8.2.
• Контрольная точка Г: целевой PHP 8.4 проходит тот же набор функциональных и фоновых проверок.

4. Проверяю байты, сериализацию и итоговый utf8mb4

Перед конвертацией сравниваю заявленные кодировки столбцов с фактическими данными. Для подозрительных записей смотрю байтовое представление функцией HEX() и сверяю известные русские строки. Название cp1251 в схеме не исключает, что старый импорт записал в столбец уже готовые UTF-8-байты. Если преобразовать их повторно, получатся нечитаемые символы. Особенно внимательно разбираю собственные поля типов TEXT и BLOB, историю обмена и настройки сторонних модулей. Для смешанного содержимого нужен отдельный разбор: СУБД не может достоверно угадать происхождение каждой записи. Правила преобразования кодировки столбцов MySQL.

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

SELECT
    @@character_set_client,
    @@character_set_connection,
    @@character_set_results,
    @@collation_connection;

SELECT
    TABLE_NAME,
    COLUMN_NAME,
    CHARACTER_SET_NAME,
    COLLATION_NAME
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
  AND CHARACTER_SET_NAME IS NOT NULL
ORDER BY TABLE_NAME, ORDINAL_POSITION;

Самая неприятная ловушка — сериализованные значения PHP. Слово «Кран» занимает четыре байта в Windows-1251 и восемь байт в UTF-8. В сериализованной строке длина задаётся в байтах, поэтому простая перекодировка с сохранением маркера s:4: повреждает структуру. Для известного формата я сначала разбираю значение штатным декодером приложения, преобразую текстовые ключи и значения, затем сериализую структуру заново. Сжатые данные предварительно распаковываю и после преобразования упаковываю тем же предусмотренным форматом. Универсальной регуляркой байтовые длины не исправляю. Описание функции serialize в PHP, предупреждение «1С-Битрикс» о сериализованных данных.

Штатный мастер предпочитаю массовым запросам ALTER TABLE, но отдельно проверяю покрытие нестандартных таблиц и полей. Официальный урок по смене кодировки содержит старые примеры с набором символов utf8, который в актуальном MySQL обозначает устаревающий трёхбайтовый вариант utf8mb3. Копировать эти примеры в новую конфигурацию без проверки нельзя. В требованиях «1С-Битрикс» 2026 года указан utf8mb4: для MySQL 8 и MySQL 9 — сортировка utf8mb4_0900_ai_ci, для MariaDB 10 и MariaDB 11 — utf8mb4_unicode_ci.

После работы мастера проверяю, не остался ли промежуточный utf8mb3. Кириллица в нём читается, однако символы за пределами основной многоязычной плоскости не помещаются. Переход на utf8mb4 репетирую отдельно: оцениваю перестроение таблиц, длину индексируемых значений, поведение сравнений и возможные конфликты уникальных ключей. MySQL 8.4 выполняет изменение кодировки столбцов через копирование таблицы, поэтому время и дополнительное место на диске измеряю на копии. Одной смены кодировки базы по умолчанию недостаточно: она не преобразует существующие столбцы. Переход MySQL с utf8mb3 на utf8mb4.

Затем согласую признаки UTF-8 в исторической установке: константу BX_UTF в /bitrix/php_interface/dbconn.php, параметр utf_mode в /bitrix/.settings.php, региональные настройки, директиву default_charset в используемом php.ini и фактическую инициализацию соединения с СУБД. Эти признаки сами данные не преобразуют. Проверяю языковые файлы, включаемые области, имена файлов и URL; текстовые PHP-файлы сохраняю в UTF-8 без BOM. Параметр mbstring.func_overload не возвращаю: PHP пометил его устаревшим в PHP 7.2 и удалил в PHP 8.0, а main начиная с версии 20.100.0 требует его удалить. После преобразования очищаю кеши и завершаю старые сессии. Документация PHP по mbstring.func_overload.

• Поиск старых кодировочных настроек и ручной инициализации соединения: ```bash rg -n 'windows-1251|cp1251|BX_UTF|utf_mode|SET NAMES|mb_internal_encoding' local bitrix/templates bitrix/php_interface bitrix/.settings.php ```
• Проверка определения таблиц и соединения выполняется SQL-запросами из абзаца выше.
• Перед изменением таблиц сохраняется проверенная согласованная копия файлов и базы.

5. Испытываю PHP вместе с расширениями и собственным кодом

Команда проверки версии в SSH показывает PHP для командной строки. Сайт может обслуживаться другим процессом PHP-FPM, с другим php.ini и другим набором расширений. Поэтому через закрытый диагностический запрос сверяю PHP_VERSION, PHP_SAPI, результат php_ini_loaded_file(), список файлов из php_ini_scanned_files() и загруженные расширения. Публичный файл с таким выводом после проверки удаляю. Затем отдельно проверяю CLI и каждое задание cron. Иначе после успешного переключения сайта ночной импорт продолжит исполняться старым PHP. Порядок загрузки конфигурации PHP.

Путь и имя бинарника зависят от дистрибутива. В примере ниже предполагается, что целевой интерпретатор доступен как /usr/bin/php8.4; на конкретном сервере сначала проверяю фактический путь. Опция --ini выводит загруженный конфигурационный файл и просканированные дополнительные файлы, -m — модули, -l — результат проверки синтаксиса одного файла.

/usr/bin/php8.4 -v
/usr/bin/php8.4 --ini
/usr/bin/php8.4 -m
/usr/bin/php8.4 -l local/php_interface/init.php

Проверяю расширения, которые требует установка: поддержку MySQL, mbstring, XML, GD, FreeType, zlib, OpenSSL, hash, DOM и ZIP. Затем добавляю зависимости конкретного проекта: cURL, intl, SOAP, Redis, AMQP или загрузчик защищённого кода. Сам факт загрузки расширения ещё не подтверждает нужные возможности. Например, GD может быть собрано без формата изображения, который использует шаблон. Поэтому после сравнения списков запускаю реальные операции: обработку картинки, создание документа, отправку запроса и чтение кеша.

В собственном коде на PHP 8.2 ищу создание необъявленных динамических свойств. Оно считается устаревшим, кроме классов с предусмотренным исключением, stdClass и корректной реализацией магических методов. Предпочитаю объявить свойство и его тип, а не скрывать предупреждение атрибутом без разбора. На PHP 8.4 проверяю неявно nullable-параметры. Сигнатуру с допускающим null значением записываю явно, предварительно проверив контракт всех вызовов.

function load(?string $id = null): void
{
    // Реализация обработчика.
}

Создание динамического свойства в PHP 8.2 и неявно nullable-параметр в PHP 8.4 вызывают предупреждения об устаревании, а не безусловные фатальные ошибки. Однако предупреждение, попавшее в вывод, способно повредить JSON-ответ AJAX, а пользовательский обработчик ошибок может превратить его в исключение. Кроме того, при переходе с PHP 8.2 на PHP 8.4 учитываю несовместимые и устаревшие возможности PHP 8.3, а не проверяю только две крайние ветки. Устаревшие возможности PHP 8.2, руководство по миграции на PHP 8.3, устаревшие возможности PHP 8.4.

На стенде включаю полный сбор ошибок в журнал, но не показываю сообщения посетителю. Сначала устраняю исключения, повреждение данных и сломанные сценарии, затем разбираю предупреждения об устаревании отдельными задачами. Для Composer-пакетов запускаю проверку реальных требований платформы: команда check-platform-reqs сверяет установленную версию PHP и расширения и игнорирует подмену версии через config.platform. Опция --no-dev исключает требования пакетов из require-dev; применять её можно только тогда, когда эти зависимости действительно не используются в production.

error_reporting = E_ALL
log_errors = On
display_errors = Off

/usr/bin/php8.4 /usr/local/bin/composer check-platform-reqs --no-dev

Документация Composer по check-platform-reqs.

• Версия и конфигурация PHP-FPM, обслуживающего HTTP-запрос.
• Версия и конфигурация PHP, указанного в заданиях cron.
• Расширения, библиотеки и возможности, реально используемые модулями.
• Синтаксис собственных файлов и полный набор прикладных сценариев.
• Требования Composer-пакетов к PHP и расширениям.

6. Разбор условного стенда: архитектурное бюро «Линия», 19 РМ

Разберу модельный проект «архитектурное бюро «Линия», 19 РМ». Название, объёмы и результаты ниже заданы для учебного сценария, а не взяты из отчёта о реальном клиенте. Исходные условия: 42 000 товарных предложений во внутреннем каталоге материалов и комплектаций, база 6,4 ГБ, каталог /upload объёмом 38 ГБ, PHP 8.1.34, главный модуль ветки 23, MariaDB 10.11 и шаблон с открытым кодом. Для стенда выделены 4 vCPU, 16 ГБ оперативной памяти и диск 250 ГБ. Численность бюро — 19 рабочих мест.

Целевые испытания выполняются на PHP 8.2.33 и PHP 8.4.25. Эти выпуски реальны: PHP 8.2.33 опубликован 30 июля 2026 года, PHP 8.4.25 — 27 августа 2026 года. Номера здесь фиксируют воспроизводимое состояние учебной репетиции, но не означают, что их следует навсегда закрепить в production. При фактическом выпуске я использую актуальный поддерживаемый исправляющий выпуск выбранной ветки после проверки на стенде. Журнал выпусков PHP 8, сообщение о выпуске PHP 8.4.25, сообщение о выпуске PHP 8.2.33.

В сценарий закладываю три дефекта: 37 сериализованных настроек собственного калькулятора, жёсткое преобразование каждого входящего CSV из Windows-1251 и устаревший обработчик шаблона. На этапе UTF-8 калькулятор проверяется отдельно от каталога. Его настройки читаются как структура, текст преобразуется и значение сохраняется повторно штатным сериализатором. Импорт получает явную кодировку источника. Поэтому файл в Windows-1251 преобразуется один раз, а уже готовый UTF-8-файл не проходит через лишнюю конвертацию. После импорта я сверяю наименования, артикулы, цены и сохранение настроек после выхода и повторного входа.

Для целевого пула использую приведённый ниже фрагмент, сохраняя существующие user, group, listen, владельца и права сокета. Режим ondemand, параметр pm.max_children и тайм-аут pm.process_idle_timeout существуют в PHP-FPM; при ondemand процессы создаются по запросу, а простой процесс завершается после заданного интервала. Значение 12 — исходная гипотеза учебного стенда, которую затем уточняю по памяти процессов, задержке и очереди запросов. Лимит 512 МБ относится к одному PHP-скрипту и не равен объёму памяти, заранее занятому каждым процессом.

pm = ondemand
pm.max_children = 12
pm.process_idle_timeout = 10s
php_admin_value[memory_limit] = 512M
php_admin_value[default_charset] = UTF-8
php_admin_flag[display_errors] = off
php_admin_flag[log_errors] = on

Документация PHP-FPM.

Фоновый обмен на стенде запускаю явным бинарником PHP 8.4. Версию MariaDB 10.11 во время этого испытания не меняю, чтобы не добавлять ещё одну независимую причину ошибок. Заданный итог модельной репетиции: 30 контрольных сценариев проходят на PHP 8.4, все 37 настроек читаются после повторного сохранения, два последовательных обмена оставляют ровно 42 000 предложений без дублей. Для планирования принимаю 46 минут на преобразование и проверки и 18 минут на восстановление. Это иллюстративные результаты учебного стенда архитектурного бюро «Линия», 19 РМ; для настоящего проекта время обязательно измеряю на свежей копии. Главная страница в этом сценарии проходит проверку раньше калькулятора, поэтому разрешение на выпуск дают данные и обмен, а не только внешний вид.

• Условный клиент: архитектурное бюро «Линия», 19 РМ.
• Исходный объём: база 6,4 ГБ, каталог `/upload` 38 ГБ, 42 000 предложений.
• Ресурсы учебного стенда: 4 vCPU, 16 ГБ RAM, диск 250 ГБ.
• Контроль: 30 сценариев, 37 сериализованных настроек и два последовательных обмена.
• Модельное время: 46 минут на преобразование и проверку, 18 минут на восстановление.

7. Выпускаю после проверки записи и репетиции отката

Перед переключением прохожу критичные операции с холодным и прогретым кешем. Создаю данные, перечитываю их новым запросом, изменяю и выгружаю наружу. Для кириллицы использую контрольные строки с буквой Ё, кавычками и длинным тире; четырёхбайтовый символ проверяю только в поле, где приложение допускает такие данные. Отдельно запускаю поиск после переиндексации, письма, документы, обработчики событий и фоновые задания. Непроверенный обязательный сценарий для меня означает незавершённую миграцию.

До начала работ фиксирую критерии остановки: повреждение текста, расхождение числа записей или сумм, повторное создание сущностей обменом, ошибка оформления заказа, невозможность прочитать старую настройку. Для каждого критерия есть проверка и точка возврата. Это избавляет от опасного решения «понаблюдаем ещё немного», когда запись уже открыта, а причина расхождения неизвестна.

На выпуске останавливаю запись: оформление заказов, административные изменения, обмены, очереди и задания, которые меняют базу. Создаю финальную согласованную копию и повторяю отрепетированную процедуру на свежих данных. После переключения перезапускаю нужные процессы PHP-FPM и рабочих очередей, проверяю OPcache, очищаю кеш приложения и выполняю короткую приёмку. Фоновые задания включаю осознанно, чтобы старый и новый узлы не выполняли их одновременно.

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

Если новый сайт уже принял заказы или другие изменения, восстановление старого дампа их потеряет. До открытия записи я определяю, можно ли вернуть новые операции в старую систему и каким способом они будут сверяться. Окончательное решение о продолжении или возврате принимаю до снятия режима обслуживания. После успешного запуска наблюдаю как минимум полный цикл обязательного обмена и регламентных задач, а не заканчиваю работу сразу после открытия главной страницы.

• Авторизация, восстановление пароля и повторное открытие сессии.
• Каталог, поиск, фильтр и AJAX после очистки кеша.
• Корзина, скидки, доставка, создание заказа и тестовый платёж.
• Обмен с 1С: загрузка, выгрузка и повторный запуск без дублей.
• Письма, документы, собственные агенты и задания cron.
• Сверка количества записей, сумм и контрольных текстовых значений.
• Проверенное восстановление согласованного набора файлов, базы и конфигурации.

Частые вопросы