Drupal Composer рецепты / Хабр

В этом посте мы хотим поделиться некоторыми рецептами использования Composer, которые мы накопили работая с Drupal проектами созданными с помощью Drupal Composer template. Так же мы рассмотрим как перевести существующий Drupal проект на Composer.

Если вы до сих пор не используете Composer в Drupal проектах, вы должны начать делать это прямо сейчас! Drupal Composer template поможет с справиться с этой задачей. Создать новый проект — очень просто.

Если вы до сих пор не уверенны, взгляните на преимущества Drupal Composer разработки:

Нет необходимости хранить код контриб модулей (и само ядро!) в вашей системе контроля версий.
Единый инструмент управления пакетами для всего: ядро Drupal, контриб модули, JS библиотеки, ваши собственные модули используемые в разных проектах, и т.д.
Максимально простой и удобный патчинг ядра и модулей.
Это гораздо проще использования Git submodules.

(Все рецепты подразумевают использование Drupal 8, но они так же должны работать и для Drupal 7)

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

composer require drupal/<MODULE_NAME>:~8.0 что бы установить последний стабильный релиз (или последнюю dev версию, если релизов для Drupal 8 пока нет)
composer require drupal/<MODULE_NAME>:dev-<BRANCH_NAME> что бы установить последнюю dev версию
composer require drupal/<MODULE_NAME>:dev-<BRANCH_NAME>#<COMMIT_HASH> что бы установить конкретную версию

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

composer update что бы обновить всё
composer update --dry-run что бы проверить обновления
composer update drupal/<MODULE_NAME> что бы обновить конкретный модуль

Патчинг пакетов

Плагин cweagans/composer-patches (входящий в состав Drupal Composer template) использует патчи описаные в секции «extra» файла composer.json:

   "extra": {
       "patches": {
           "<PACKAGE/NAME>": {
               "<PATCH DESCRIPTION>": "<PATH/TO/PATCH/OR/URL>",
               ...
           },
           ...
       }
   }

Пример:

   "extra": {
       "patches": {
           "drupal/core": {
               "Fix language detection": "patches/2189267-24.patch"
           }
       }
   }

После того как патч добавлен, запустите:

composer install что бы применить патч
composer update nothing (или composer update --lock) что бы composer-patches плагин сделал необходимые изменения в файле composer.lock

Установка кастомных/форкнутых модулей с Github

Если репозиторий модуля содержит собственный composer.json файл

Зарегистрируйте репозиторий в секции «repositories» файла composer.json:

   "repositories": [
       {
           "type": "vcs",
           "url": "https://github.com/<REPOSITORY/NAME>"
       },
       ...
   ],

Используйте composer require drupal/<MODULE_NAME>:dev-<BRANCH_NAME>#<COMMIT_HASH> что бы установить модуль.

Если файл composer.json отсутствует в репозитории модуля

Используйте чуть более расширенный вариант:

   "repositories": [
       {
           "type": "package",
           "package": {
               "name": "drupal/<MODULE_NAME>",
               "version": "dev-custom",
               "type": "drupal-module",
               "source": {
                   "type": "git",
                   "url": "git@github.com:<REPOSITORY/NAME>.git",
                   "reference": "<BRANCH-NAME>"
               }
           }
       },
       ...
   ],

Используйте composer require drupal/<MODULE_NAME>:dev-custom#<COMMIT_HASH> что бы установить модуль.

Если целевая директория должна отличаться от modules/contrib

В дополнение к вышеприведённым рецептам, используйте composer/installers плагин:

   "extra": {
       "installer-paths": {
           "web/modules/custom/<MODULE_NAME>": ["drupal/<MODULE_NAME>"],
           ...
       }
   }

Установка JS библиотеки

Популярные JS библиотеки могут быть с лёгкостью установлены с помощью Composer, так как они (скорее всего) уже существуют в репозитории Packagist. Сложность заключается в том что большинство Drupal модулей требуют установки JS библиотек в директорию «libraries», в то время как Composer устанавливает их в директорию «vendor».

Плагин composer/installers может переназначать путь установки, но только для тех пакетов которые указывают его как зависимость. Таким образом, вам нужно подменить файл composer.json библиотеки, указав в нём зависимость от composer/installers.

Взглянем на пример:

   "repositories": [
       {
           "type": "package",
           "package": {
               "name": "enyo/dropzone",
               "version": "4.3",
               "type": "drupal-library",
               "source": {
                   "url": "https://github.com/enyo/dropzone.git",
                   "type": "git",
                   "reference": "master"
               },
               "dist": {
                   "url": "https://github.com/enyo/dropzone/archive/v4.3.0.zip",
                   "type": "zip"
               },
               "require": {
                   "composer/installers": "~1.0"
               }
           }
       },
       ...
   ],  
   ...   
   "extra": {
       "installer-paths": {
           "web/libraries/{$name}" : ["type:drupal-library"],
           ...
       }
   }

После того как этот код добавлен в composer.json, запустите composer require enyo/dropzone:4.3 что бы установить библиотеку. Заметьте что мы указали конкретную версию и добавили секцию «dist» что бы Composer мог загрузить zip архив вместо клонирования репозитория.

Переключаем существующий пакет на форкнутую версию

Зарегистрируете форк-репозиторий в composer.json:

   "repositories": [
       {
           "type": "vcs",
           "url": "https://github.com/<REPOSITORY/NAME>"
       },
       ...
   ],

Запустите composer require <PACKAGE/NAME>:dev-<BRANCH_NAME>#<COMMIT_HASH>

Переключаем существующий Drupal 8 project на Composer

Сделайте бекап ;)
Удалите всё чем будет управлять Composer: директорию «core» Drupal, контриб модули, и т.д.
Удалите все корневые Drupal файлы, такие как index.php, update.php, README.txt… Все их.
Создайте директорию «web» в корне проекта и переместите туда все оставшиеся Drupal директории (sites, modules, themes, libraries, profiles, и т.д.)
Скопируйте файлы Drupal Composer template в корень проекта.
Приготовьте список версий контриб модулей используемых в проекте, ядра Drupal и всего остального чем будет управлять Composer. Затем запустите composer require указывая конкретную версию для каждой зависимости. Вам понадобится перевести Drupal версии в Composer версии, вот несколько примеров:
- drupal/core:8.1.8 тут всё сходится
- drupal/admin_toolbar:8.1.15 поразумевает admin_toolbar 8.x-1.15
- drupal/ctools:8.3.0-alpha26 поразумевает ctools 8.x-3.0-alpha26
- drupal/config_installer:dev-8.x-1.x#a16cc9acf84dd12b9714def53be0ce280a5b0c1a поразумевает dev версию config_installer созданную из коммита a16cc9a бранча 8.x-1.x
В секции «require» файла composer.json измените версии ядра Drupal и контрибных модулей на "~8.0". Это сделает возможным будущие обновления.
Запустите composer drupal-scaffold, это создаст необходимые корневые Drupal файлы.
Убедитесь что ваш веб-сервер использует диркторию «web» в качестве web root.