Обновления: hook_update_N

Обновление — функция, которая один раз приводит уже работающий сайт к новой версии модуля: добавляет столбец в таблицу, переносит данные, записывает новую настройку. Пока модуль не установлен нигде, кроме вашего компьютера, его можно просто переустановить. Но на рабочем сайте переустановка удалит данные — там изменения вносят обновлениями.

Где пишут обновления

В файле blog.install, рядом с blog_schema(). Имя функции — blog_update_N, где N — номер. Drupal запоминает номер последнего выполненного обновления и запускает только те, что больше.

Первое обновление

Добавим в таблицу подписчиков столбец с именем:

// web/modules/custom/blog/blog.install
 
/**
 * Добавляет столбец name в таблицу подписчиков.
 */
function blog_update_10001(): void
{
    $schema = \Drupal::database()->schema();
 
    if (!$schema->fieldExists('blog_subscribers', 'name')) {
        $schema->addField('blog_subscribers', 'name', [
            'type' => 'varchar',
            'length' => 100,
            'not null' => TRUE,
            'default' => '',
        ]);
    }
}

schema() возвращает объект для изменения структуры базы. Описание столбца — тот же массив, что в blog_schema(). Комментарий над функцией обязателен: его текст Drush показывает как описание обновления.

Запуск

vendor/bin/drush updatedb

Короткая запись — drush updb. Команда покажет список ожидающих обновлений с их описаниями и после подтверждения выполнит их. Повторный запуск сообщит, что обновлений нет: номер 10001 уже записан как выполненный.

Не забыть про схему

Обновление меняет уже установленные сайты. Чтобы новые установки модуля сразу получали столбец, его добавляют и в blog_schema():

// web/modules/custom/blog/blog.install
'fields' => [
    'id' => ['type' => 'serial', 'unsigned' => TRUE, 'not null' => TRUE],
    'email' => ['type' => 'varchar', 'length' => 255, 'not null' => TRUE],
    'name' => ['type' => 'varchar', 'length' => 100, 'not null' => TRUE, 'default' => ''],
    'created' => ['type' => 'int', 'not null' => TRUE, 'default' => 0],
],

При свежей установке выполняется только blog_schema(), а обновления считаются уже применёнными.

Номера

Номер — целое число, каждое следующее больше предыдущего: 10001, 10002, 10003. Принято начинать его с версии Drupal, под которую написан модуль: 10 или 11, затем порядковый номер из трёх цифр.

Обновление настроек

Тем же способом добавляют значение в конфигурацию:

// web/modules/custom/blog/blog.install
 
/**
 * Добавляет настройку show_reading_time.
 */
function blog_update_10002(): void
{
    \Drupal::configFactory()
        ->getEditable('blog.settings')
        ->set('show_reading_time', TRUE)
        ->save();
}

Новую настройку также добавляют в config/install/blog.settings.yml и в схему config/schema/blog.schema.yml.

Методы изменения структуры

Обновление ядра и модулей

Ядро и готовые модули обновляет Composer, а их собственные функции обновления выполняет та же команда:

composer update "drupal/core-*" --with-all-dependencies
vendor/bin/drush updatedb -y
vendor/bin/drush cache:rebuild

Перед обновлением сделайте резервную копию базы: drush sql:dump --result-file=../backup.sql. Наличие обновлений безопасности показывает страница «Отчёты → Доступные обновления».

Частая ошибка

Обновление, которое уже выполнено на каком-либо сайте, нельзя править: Drupal запомнил его номер и изменённый код не запустит. Если в функции нашлась ошибка или нужно ещё одно изменение, пишите новую функцию со следующим номером. Править можно только обновление, которое ещё не покидало ваш компьютер.