Разработка updater.php для модулей 1С-Битрикс: Полное руководство

updater.php

Структура апдейтера

Апдейтер может создаваться в двух формах. При этом в каждом конкретном обновлении может присутствовать только какая-то одна.

• Файл /updater.php в корне папки с обновлением. Этот файл будет запускаться на выполнение в качестве апдейтера.
• Папка /updater в корне папки с обновлением. В качестве апдейтера будет запускаться файл index.php в ней.

Второй способ обычно используется если для выполнения апдейтера нужны какие-то дополнительные файлы: языковые ресурсы, файлы с данными и тому подобное.

Описание

Механизм апдейтеров служит для того, чтобы применить необходимые изменения к тем частям сайта, которые не являются ядром. С помощью этого механизма можно привести структуру базы данных, системные и публичные файлы в соответствие с текущей версией ядра.

В каждом обновлении может быть только один updater.php. Но может и не быть ни одного, если требуется обновить только ядро.

Апдейтер может выполнить PHP-код. При этом есть набор архитектурных ограничений, которые необходимо учитывать.

Ограничения

• Обновления устанавливаются на все модули, которые входят в лицензию и присутствуют на сайте Установлен модуль или нет, не имеет значения. Это надо учитывать при написании кода апдейтера.
• Обновления могут переустанавливаться несколько раз. Соответственно код апдейтера должен учитывать возможность многократного запуска.
• Апдейтер выполняется один раз непосредственно перед копированием файлов обновления из папки обновления в ядро на одном хите. Если за один хит обновляются несколько версий одного модуля, то их апдейтеры выполняются последовательно в соответствии с их версиями. Если за один хит обновляются несколько модулей, то выполняются апдейтеры всех этих модулей, но межмодульный порядок их выполнения не определен.
• АПИ текущего обновления недоступен на хите обновления В случае использования нового кода в апдейтере будет получена ошибка: Class 'Имя\Класса' not found. А если есть циклические межверсионные зависимости, которые связывают несколько версий одного модуля, то будет недоступен АПИ всех этих обновлений. Использование нового АПИ в коде updater.php невозможно. Использование любого АПИ в коде апдейтера возможно, но не рекомендуется.
• При выполнении апдейтера доступен и он, и вся папка с обновлением.

Обновление

Примечание: Ядро Ядро продукта - файлы, находящиеся в директории /bitrix/modules/, а также файлы системных компонентов: /bitrix/components/bitrix/.
Подробнее… обновляется системой обновлений автоматически при установке обновлений. Другие же части сайта, включая базу данных, автоматически не обновляются.

Все файлы обновления просто копируются как есть в папку модуля. И если ваш модуль полностью расположен в этом каталоге, то обновление завершено. Если же по логике работы модуля требуется чтобы часть файлов была вне ядра, в какой-либо другой папке, то с помощью updater.php нужно перенести их в нужное место.

Механизм апдейтеров (updater.php) служит именно для того, чтобы применить необходимые изменения к тем частям сайта, которые не являются ядром. С помощью этого механизма можно привести структуру базы данных, системные и публичные файлы в соответствие с текущей версией ядра.

Если возникла необходимость скопировать файлы в обновлении самостоятельно, то нужно использовать:

$updater->CopyFiles("install/classes", "modules/quintura.search/classes");

В этом случае файлы из папки /install/classes, находящиеся в папке обновления, скопируются в папку /local/modules/quintura.search/classes.

При выпуске последующих обновлений может возникнуть потребность установить его зависимость от новых модулей. Ссылки на версии модулей, от которых зависит данное обновление, содержатся в файле version_control.txt. Но необходимо помнить, что само обновление с зависимостью не будет по умолчанию требовать установки указанных модулей. В этом случае возможны два варианта:

1. Обновление всё равно устанавливать, проверять присутствие нужного модуля уже в функционале модуля.
2. Добавить в код обновления проверку на нужный модуль, и при его отсутствии выводить ошибку пользователю. Обновление не будет установлено, если присвоить переменной $errorMessage строку сообщения.

Примечание: При создании архива с решением/обновлением через консольную утилиту tar в MacOS, нужно предварительно выставлять переменную окружения: export COPYFILE_DISABLE=true

Курсы разработаны в компании «1С-Битрикс»

!Прокрутить вверх