Установка модулей и тем в Drupal на живом примере

На сайте Drupal 10.3+ или 11.x установка расширения — это не просто загрузка архива в папку modules. На живом примере установим Admin Toolbar и тему Gin через Composer, включим их в административной панели и проверим, что обновления не превратились в ручную сборку сайта. Для рабочего проекта понадобится примерно 15–30 минут, если Composer уже настроен.

Что установим и почему через Composer

Admin Toolbar расширяет стандартное административное меню Drupal: команды становятся доступнее, а переходы к разделам занимают меньше кликов. Gin заменяет административную тему и делает интерфейс управления удобнее для редакторов и администраторов.

Пример рассчитан на проект на Drupal 10.3+ или Drupal 11.x, установленный через официальный шаблон Drupal Composer. Команды выполняются из корня проекта — каталога, где лежит файл composer.json. Если Drupal размещён в подкаталоге web, это нормально: Composer сам установит код в настроенный document root.

Модуль и тема — это часть зависимостей проекта. Если они не записаны в Composer, через несколько месяцев вы можете уже не знать, какая версия работает на продакшене.

Сноска. Document root — каталог, который веб-сервер отдаёт браузеру. В Composer-шаблоне Drupal это часто web, а не корень репозитория.

Composer или загрузка архива

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

В примере выбираем Composer. Архивный способ упомянут только для сравнения: инвалидация кешей и ручное копирование файлов — отдельная тема.

Живой пример: Admin Toolbar и Gin

1. Проверьте окружение

До начала нужны доступ к командной строке, резервная копия базы и файлов, Composer 2 и права на изменение проекта. Версия PHP должна соответствовать требованиям вашей версии Drupal и установленным пакетам. Не подставляйте её наугад: проверьте composer.json проекта и официальные требования Drupal.

В корне проекта выполните:

composer validate
composer show drupal/core-recommended

Первая команда должна завершиться без ошибки в файле манифеста, а вторая — показать установленную версию ядра. Если Composer сообщает, что файл не найден, вы находитесь не в корне проекта.

2. Установите Admin Toolbar

Добавьте модуль как зависимость проекта:

composer require drupal/admin_toolbar

Composer скачает пакет и обновит composer.json и composer.lock. Не удаляйте второй файл: именно он фиксирует фактические версии зависимостей для других окружений.

Проверка: в выводе Composer не должно быть сообщения об ошибке разрешения зависимостей, а каталог модуля появится в директории, которую проект использует для contributed-модулей, обычно web/modules/contrib/admin_toolbar.

3. Включите модуль в Drupal

Откройте административную панель и перейдите в Расширение по адресу /admin/modules. Найдите Admin Toolbar, отметьте модуль и нажмите кнопку установки. В состав пакета могут входить несколько компонентов; начните с основного Admin Toolbar, а дополнительные включайте только при необходимости.

Проверка: после включения в верхней административной панели появятся более быстрые переходы к разделам управления. Если меню осталось прежним, очистите кеш через /admin/config/development/performance и повторите проверку.

4. Установите тему Gin

Вернитесь в корень проекта и выполните:

composer require drupal/gin

Команда устанавливает код темы, но не делает её активной. Это важное различие: наличие каталога темы ещё не означает, что Drupal использует её для админки.

Проверка: в административной панели откройте Оформление по адресу /admin/appearance. В списке тем должна появиться Gin.

5. Активируйте тему только для админки

На странице оформления найдите Gin и выберите действие, которое назначает тему административного интерфейса. Не устанавливайте её темой по умолчанию для публичной части, если вы хотите изменить только панель управления. Для посетителей сайта оставьте текущую frontend-тему.

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

Что изменилось в проекте

После двух команд Composer изменятся как минимум composer.json и composer.lock. Также появятся файлы пакетов в каталоге Drupal. Добавьте изменения в Git, но не коммитьте кеши, пользовательские загрузки и секреты.

git status
git diff -- composer.json composer.lock

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

Типичные ошибки и их причина

• «Could not find a matching version». Версия модуля не совместима с текущим ядром или PHP. Проверьте требования конкретной версии на странице проекта Drupal.org и не снимайте ограничения без понимания последствий.
• «Your requirements could not be resolved to an installable set of packages». В проекте конфликтуют зависимости. Посмотрите полный вывод Composer: там обычно указаны пакет и ограничение, которые мешают установке.
• Модуль установлен, но не появился в списке. Вы могли установить пакет не в тот проект или выполнить команду не из каталога с нужным composer.json. Проверьте путь и каталог web/modules/contrib.
• Gin видна, но не включается. У темы могут быть требования к версии ядра или PHP. Сначала проверьте совместимость, затем очистите кеш и повторите включение.
• После включения открывается белая страница или ошибка 500. Не продолжайте менять настройки наугад. Посмотрите журнал Drupal и журнал PHP, включите резервную копию и откатите последнее изменение на тестовом окружении.

Где этот подход ломается

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

Ещё один риск — установка темы для публичной части вместо административной. Gin меняет интерфейс управления, но не является универсальной заменой пользовательской теме. Разделение этих ролей особенно важно для интернет-магазина: редактору нужен удобный backend, а посетителю — проверенный frontend.

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

Откройте сайт под отдельной учётной записью редактора и проверьте права: Admin Toolbar меняет навигацию, но не выдаёт доступ к закрытым разделам. Затем создайте тестовую копию и выполните штатное обновление зависимостей, отслеживая сообщения Composer и журналы Drupal.

Для продакшена зафиксируйте в документации версию Drupal, PHP, Admin Toolbar и Gin. После следующего обновления сравните composer.lock, очистите кеш и проверьте три сценария: вход администратора, редактирование материала и открытие публичной страницы. Если проект собирается автоматически, добавьте эти проверки в процесс выкладки, а не выполняйте их только после аварии.