Миграция с drupal-composer/drupal-project на drupal/recommended-project

Освежаем старые проекты и приводим их в «современный» вид в соответствии с официальными Composer шаблонами проектов.

15.01.2020

8 мин.

Начиная с Drupal 8.8.0 у нас появились официальные Composer шаблоны для управления Drupal.

Всего их было представлено два: drupal/recommended-project и drupal/legacy-project.

drupal/recommended-project — в данном шаблоне корень сайта вынесен на уровень ниже в папку web/ по умолчанию. Данный шаблон рекомендуется для всех новых проектов на Drupal 8.

Пример структуры проекта:

 project/
  ├─ web/
  │  ├─ core/
  │  ├─ libraries/
  │  ├─ modules/
  │  ├─ profiles/
  │  ├─ themes/
  │  └─ index.php
  ├─ vendor/
  └─ composer.json

drupal/legacy-project — аналогичный шаблон, но корень сайта находится в корне проекта, как это было и осталось в архивах.

Пример структуры проекта:

  project/
  ├─ core/
  ├─ libraries/
  ├─ modules/
  ├─ profiles/
  ├─ themes/
  ├─ vendor/
  ├─ index.php
  └─ composer.json

Если вы знакомы с drupal-composer/drupal-project, то становится ясно, что новый шаблон drupal/recommended-project является его аналогом. Их основная цель, управление Drupal через Composer, а также, вынесение корня сайта на уровень ниже.

У меня есть материал о двух вариантах установки Drupal. Я также везде где можно рекомендовал использовать drupal-composer/drupal-project для своих проектов. И вот, мы теперь имеем официальный шаблон.

drupal-composer/drupal-project никуда не девается, более того, он также обновлён на использование официальных пакетов (но распространится это только на новые проекты), но что если вы хотите перейти на официальный вариант? Тогда этот материал для вас. Это достаточно простая, пошаговая операция, где нужно лишь немного принять решений и всё будет работать дальше!

В чем отличие drupal/recommended-project от drupal-composer/drupal-project?¶

drupal/recommended-project является официальным темплейтом. Это подразумевает что он будет поддерживаться сообществом и проблемы, если такие будут возникать, будут исправляться намного быстрее.
drupal/recommended-project породил ряд других официальных Composer проектов, которые решают проблемы, которые раньше пытался решить drupal-composer/drupal-project своими силами и, возможно, костылями. Теперь всё подготавливается автоматически в экосистеме Drupal.
drupal/recommended-project практически не имеет никаких зависимостей по умолчанию. Он намного легковестнее, его структура и начальный проект не имееют «мусора» (если не считать приветственного пакета). Например, там нету ни Drush, ни Drupal Console, ни прочих подобных заметных зависимостей, и это хорошо! Вам ничего не навязывают и за вас ничего не решают.
drupal/recommended-project лучше подходит в качестве основны для создания своих собственных Composer шаблонов. Опять же, это связано с тем, что он «чище».
drupal/recommended-project нельзя использовать для проектов младше Drupal 8.8.0. Переходя на него, вы уже должны быть обновлены, либо сделать это в процессе.

В остальном, они не сильно отличаются и переходить сломя голову нет никакого смысла.

Я бы рекомендовал производить данную миграцию только если есть желание и возможности, в процессе обновления проекта до Drupal 8.8.0+ или же когда настанет момент обновляться на Drupal 9.

Миграция¶

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

Это значит, что миграция сводится к тому, что мы заменяем пакеты, которые ранее использовались и устанавливались drupal-composer/drupal-project на те, что используются drupal/recommended-project.

По факту, вся миграция является опциональной, вы сами решаете что мигрировать, а что нет, что заменять, а что оставить как было. Мы пройдемся по всем значимым отличиям, и вы сами примите решение. Лично я, произвожу замену сразу всех пунктов.

Некоторые зависимости появились в drupal-composer/drupal-project раньше, или наоборот позже, чем вы могли создать проект. Если их нету — просто пропускайте.

Подготовка проекта¶

Прежде всего, я бы рекомендовал вам обновиться до Drupal 8.8.0+, прежде чем продолжать идти по миграции.

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

drupal/core¶

С релизом новых шаблонов проектов, появились новые официальные мета-пакеты. Один из них — drupal/core-recommended.

drupal/core-recommended — полный аналог drupal/core, с тем лишь отличием, что в нём версии для зависимостей ядра фиксированы. Это значит, что они будут обновляться только с новыми релизами Drupal. В drupal/core версии указаны минимальные, это значит, что как только у зависимостей выйдет новая версия, она будет обновлена сразу же, как только вы совершите очередное обновление.

Это сделано для того, чтобы вы были уверены, что с конкретными версиями ядро покрыто тестами и прошло их успешно на момент релиза, а значит, они не станут причиной проблем. Например у нас уже был случай, когда новая версия Twig поломала Drupal.

Для миграции вам необходимо в composer.json файле, заменить свою текущую завиcимость, например "drupal/core": "^8.8.0", на новую "drupal/core-recommended": "^8.8".

drupal-composer/drupal-scaffold¶

drupal-composer/drupal-scaffold предназначен для загрузки скафолд файлов (index.php, robots.txt, .htaccess и т.д.). Для него также появилась замена в виде drupal/core-composer-scaffold.

Для миграции вам необходимо заменить в своём composer.json файле текущую зависимость, например "drupal-composer/drupal-scaffold": "^8.8.0", на новую "drupal/core-composer-scaffold": "^8.8",.

Затем, вам необходимо добавить новые настройки в extra.drupal-scaffold. Если они уже там имеются — это от старого пакета. Их необходимо временно куда-то скопировать, и вставить новые, от нового пакета.

По умолчанию в drupal/recommended-project они имеют вид:

        …
        "drupal-scaffold": {
            "locations": {
                "web-root": "web/"
            }
        },
        …

Затем перенесите все старые настройки в новый раздел. Только не забывайте, что у них разные настройки. Для того чтобы корректно перенести читайте документации для данных пакетов:

Пример моей новой настройки:

        …
        "drupal-scaffold": {
            "locations": {
                "web-root": "web/"
            },
            "file-mapping": {
                "[web-root]/sites/development.services.yml": false,
                "[web-root]/robots.txt": false
            }
        },
        …

webmozart/path-util¶

Данный пакет используется скриптом (scripts/composer/ScriptHandler.php), который поставляется с drupal-composer/drupal-project.

Он не потребуется — удаляем.

webflo/drupal-finder¶

Данный пакет используется скриптом (scripts/composer/ScriptHandler.php), который поставляется с drupal-composer/drupal-project.

Он не потребуется — удаляем.

vlucas/phpdotenv¶

vlucas/phpdotenv — предназначен для поддержки .env файлов.

Если на вашем проекте никак не используется .env файл на уровне веб-сервера и приложения, смело можно удалять зависимость. Если используется, оставляйте.

Если решили удалить, то не забудьте также удалить:

load.environment.php файл в корне проекта.
Загрузку данного файла в composer.json файле по пути autoload.files.

    …
    "autoload": {
        …
        "files": ["load.environment.php"]
    },
    …

drupal/console¶

Если не пользуетесь — удаляйте.

drush/drush¶

Если не пользуетесь — удаляйте.

Если решили удалить, не забудьте удалить папку drush в корне проекта.

Если drush оставили, но не используете его конфигурационные файлы и возможности (drush.yml, self.site.yml) и не указываете ему что прод, что стейдж, что дев — можно также удалить папку drush в корне. Если же вы обращаетесь через drush к продакшену, стейджу или другим инстансам проекта — оставьте.

wikimedia/composer-merge-plugin¶

wikimedia/composer-merge-plugin — позволяет импортировать содержимое composer.json файлов из других директорий внутри проекта и мерджить (виртуально) в один основной composer.json.

Данный пакет используется, в основном, только для кастомных модулей и тем. С релизом официальных шаблонов предлагается использовать штатное решение Composer, которое производительнее, не требует зависимостей и работает более «естественно».

Стоит ли удалять? Если у вас Composer версии 1.9.1+ (composer --version) — удаляйте, если меньше и нет возможности обновить — не трогайте.

Если у вас композер версии меньше 1.9.1 — обновите его при помощи composer self-update, в противном случае вы будете получать ошибку «Package cannot install to inside its source at…» при следовании советам ниже.

Ранее вы могли иметь следующие настройки:

        …
        "merge-plugin": {
            "include": [
                "web/modules/custom/*/composer.json",
                "web/themes/custom/*/composer.json"
            ],
            "recurse": true,
            "replace": false,
            "merge-extra": false
        },
        …

Теперь это делается иначе, при помощи раздела repositories composer.json файла.

Вы можете указать конкретный путь до папки с composer.json файлом.

    …
    "repositories": [
        …
        {
            "type": "path",
            "url": "web/modules/custom/example"
        }
    ],
    …

Либо вы можете указать все папки внутри определенной:

    …
    "repositories": [
        …
        {
            "type": "path",
            "url": "web/modules/custom/*"
        },
        {
            "type": "path",
            "url": "web/themes/custom/*"
        }
    ],
    …

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

После данного изменения не забудьте также удалить старые настройки из extra.merge-plugin.

Важный момент в том, что все composer.json файлы, найденные таким способом воспринимаются Composer как полноценные пакеты. Это значит, что автоматически данные файлы не подхватятся, эти пути трактуются как репозитории пакетов и обрабатываются только в процессе обновлений или запросов новых пакетов.

Во всех composer.json файлах что вы хотите так использовать, обязательно должен быть указан "name" и "type". Это было совершенно ненужно со старым плагином. Теперь обязательно. Придется дать название всем кастомным пакетам в модулях.

Пример такого файла из кастом модуля «example»:

{
    "name": "example/example",
    "type": "drupal-custom-module",
    "description": "The custom code for example.",
    "keywords": [
        "Drupal"
    ],
    "require": {
        "npm-asset/swiper": "^5.0.0"
    }
}

Например, если у вас несколько модулей, и, допустим, есть «example_node», то давайте название example/example_node.

Вы можете указывать какие угодно зависимости, как и раньше, но репозитории здесь уже не поддерживаются. Вы не сможете здесь объявить https://asset-packagist.org, но можете это сделать в основном, а зависимости уже указывать модулям.

После чего вам необходимо запросить пакет через Composer. Если отталкиваться от примера выше, то composer require example/example. И так для каждого «пакета».

Фактически вы создаете свои пакеты, которые хостятся локально. А репозиторием выступает файловая система.

В результате данных действий у вас появятся соответствующие зависимости в composer.json файле проекта, что-то вроде "example/example": "dev-master", где вместо dev-master, может быть название вашей ветки git проекта.

webflo/drupal-core-require-dev¶

webflo/drupal-core-require-dev аналог drupal/core. В нём прописаны зависимости Drupal, необходимые исключительно для разработки, но бесполезные на продакшене и живом проекте. Для него также появился официальный аналог — drupal/core-dev.

Для миграции вам необходимо в composer.json файле, заменить свою текущую зависимость, например "webflo/drupal-core-require-dev": "^8.8", на новую "drupal/core-dev": "^8.8".