Установка модулей и тем в Drupal: что проверить заранее

В Drupal 10 и 11 модуль или тему обычно сначала добавляют в проект через Composer, а затем включают в самой CMS. Если пропустить проверку совместимости или загрузить файлы прямо на сервер, сайт может не обновиться, потерять часть зависимостей или перестать работать после следующего деплоя. Ниже — порядок действий, который помогает установить расширение без сюрпризов.

Что подготовить до установки

Инструкция рассчитана на сайт Drupal 10 или 11, созданный с помощью Composer. Если ваш проект обновляли вручную или файлы Drupal лежат не в каталоге web, структура может отличаться: сперва выясните, как именно устроен проект.

• Доступ к командной строке на компьютере разработки или сервере, где запускают Composer.
• Установленный Composer и, если вы хотите включать модуль из терминала, Drush.
• Доступ к каталогу проекта и возможность развернуть изменения на сайте.
• Резервная копия файлов и базы данных. Для рабочего сайта заранее подготовьте тестовую копию.
• Точные версии Drupal и PHP, а также требования к ним у выбранного расширения.

Не начинайте с загрузки архива на production-сервер. В Composer-проекте список зависимостей хранится в файлах проекта, а изменения обычно проходят через систему контроля версий и деплой. Ручная загрузка файлов в обход этого процесса может оставить файлы на одном сервере и потерять их при следующем развёртывании.

Термин. Машинное имя — идентификатор расширения, который Drupal и Drush используют в командах и настройках. Он обычно отличается от названия, которое видно посетителю. Например, машинное имя проекта Token — token.

Установка модуля через Composer

Сначала найдите страницу проекта на Drupal.org и проверьте, поддерживает ли он вашу версию ядра и PHP. Смотрите на требования именно выбранной ветки: название модуля само по себе не гарантирует совместимость.

1. Откройте корень проекта. Это каталог, где лежит файл composer.json. Если не уверены, найдите его и проверьте, что это файл вашего Drupal-проекта, а не соседнего приложения. Проверка: Composer видит конфигурацию проекта.
2. Проверьте требования на странице расширения. Уточните машинное имя, подходящую версию и список зависимостей. Проверка: вы знаете, какой пакет нужно устанавливать и что ему требуется.
3. Добавьте пакет Composer. Для проекта Token команда выглядит так: composer require drupal/token. Для другого расширения замените token на его машинное имя. Если проект требует определённую ветку, укажите ограничение версии согласно инструкции автора, а не выбирайте его наугад. Проверка: Composer завершил операцию без ошибки, а изменения появились в composer.json и composer.lock.
4. Включите модуль. Если Drush установлен, выполните drush en token -y, заменив token на машинное имя модуля. Либо откройте административный раздел расширений Drupal и включите модуль там. Проверка: Drupal сообщает, что модуль включён, и его настройки доступны.
5. Проверьте сайт. Откройте страницы, связанные с новой функцией, и просмотрите журнал ошибок Drupal. Проверка: ожидаемая возможность работает, в журналах нет новых ошибок, а основная часть сайта открывается как прежде.

Если Composer остановился на проверке требований, не обходите её принудительной установкой. Сначала выясните, какая версия Drupal, PHP или другой зависимости не подходит, затем подберите совместимую версию расширения или согласуйте обновление проекта.

Установка и включение темы

Тему устанавливают тем же способом: через Composer в корне проекта. Перед установкой выясните, есть ли у неё зависимости и совместима ли она с вашей версией ядра. Для Drupal 10 и 11 точные требования зависят от самой темы, поэтому их нужно сверять на странице проекта.

1. Найдите машинное имя темы и проверьте её требования на Drupal.org. Проверка: вы нашли подходящую версию и знаете, нужно ли устанавливать дополнительные пакеты.
2. Добавьте тему через Composer. Команда строится по схеме composer require drupal/машинное_имя; вместо слов после косой черты подставьте настоящее машинное имя. Проверка: Composer добавил пакет и обновил файлы зависимостей.
3. Включите тему в административной части Drupal. Откройте раздел оформления, найдите установленную тему и выберите действие включения или установки по умолчанию. Названия пунктов меню могут различаться в зависимости от версии и перевода интерфейса. Проверка: тема появилась в списке доступных, а после назначения по умолчанию отображается на сайте.
4. Проверьте страницы и блоки. Убедитесь, что меню, формы, изображения и основные шаблоны выглядят ожидаемо. Проверка: посетитель видит сайт без ошибок, а администратор может вернуться к прежней теме.

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

Если установка не удалась

• Composer сообщает о конфликте требований. Проверьте версии Drupal, PHP и зависимостей, которые указаны в сообщении и на странице проекта. Не добавляйте флаги, отключающие проверку платформы, чтобы просто добиться установки.
• Команда говорит, что пакет не найден. Проверьте машинное имя, каталог, в котором запущен Composer, и доступность проекта на Drupal.org. Название, показанное в интерфейсе сайта, может не совпадать с именем пакета.
• Drupal не показывает расширение. Убедитесь, что Composer завершился без ошибки и установил файлы в каталог, который использует ваш сайт. Затем проверьте, что вы смотрите именно на ту копию проекта, куда добавили пакет.
• После включения появились ошибки или пустая страница. Верните предыдущую тему либо отключите проблемный модуль доступным вам способом, изучите журнал Drupal и восстановите резервную копию, если сайт не удаётся вернуть в рабочее состояние.
• На production всё исчезло после деплоя. Проверьте, попали ли изменения в composer.json и composer.lock и использует ли ваш процесс развёртывания эти файлы для установки зависимостей.

Безопасная установка — это не просто появление папки расширения на сервере. Composer, Drupal и процесс деплоя должны согласованно знать, откуда пришёл пакет и как его включили.

Что делать дальше

После успешной проверки зафиксируйте изменения в репозитории и повторите деплой на тестовой копии тем же способом, которым обновляется production. Перед обновлением расширения снова сверяйте его требования и просматривайте журнал ошибок после развёртывания. Если сайт не создан через Composer, сначала восстановите картину его установки: команды из этой инструкции нельзя без проверки переносить на проект с другой структурой.

Инвалидация кеша и настройка обновлений Drupal — отдельные темы; здесь мы разбирали только установку и включение модулей и тем.