Composer. Дружим битрикс с менеджером пакетов

bitrix-loves-composer

Как много различных интересных инструментов нас окружает, и как много разработчиков по каким-то причинам боится их использовать. Сегодня речь пойдет о composer, о том, как «по быстрому» его поставить и заставить работать в унисон с битриксом.

Пара  слов о том, что это за зверь, и зачем он вам вообще нужен (если вы до сих пор не в курсе).
Composer — это отличный менеджер зависимостей для php. Это значит, что с его помощью вы можете управлять зависимостями вашего проекта буквально в «пару кликов». Например, досконально известно, что ваш проект зависит от php 5.4 (т.к. использует, например, трейты), а также в коде компонентов вашего проекта используется замечательная библиотека Guzzle. С помощью composer эти 2 зависимости можно напрямую связать с вашим проектом, и они будут поддерживаться при переносе всей системы в целом на другую машину, например. Или при обновлении библиотек, использующихся в проекте.
Обо всем — по порядку.

Ставим Composer

Установить composer = скачать php скрипт. Сам  composer представляет из себя .phar архив (это такой php архив, который можно запустить как скрипт). Качаем его любым доступным вам способом из официального источника — https://getcomposer.org/download/. Можно просто ручками скачать по этой ссылке.

Дальше нужно этот файлик куда-то положить. Есть как минимум 2 варианта:

  1. Положить файлик в директорию проекта
  2. Зашить его в операционку (если у вас unix-like) или сделать батник (ежели win). Как это сделать, читаем тут.

Не знаю, почему, но я предпочитаю первый вариант. Видимо из-за его простоты. Кладем composer.phar в директорию /local вашего проекта (можно положить его куда угодно в принципе, я обычно кладу в local)

Далее, нам нужно создать файлик, в котором будут описаны все зависимости для нашего проекта. Этот файлик именуется composer.json. В его недрах нужно в формате json описать, что у вас за проект и какими зависимостями этот проект обладает. Ниже — пример такого файлика:

Файл достаточно читабелен человеком. Из него можно четко и ясно выявить всю необходимую информацию. Самое главное здесь — секция require. Именно она описывает все зависимости проекта. В данном случае я указал, что проект может выполняться на php версии 5.4 и старше, а также код проекта использует такие библиотеки, как  mmjurov/yandex-inflector и dts/ebay-sdk-trading.
Перечень всех доступных библиотек в режиме реального времени можно просмотреть на https://packagist.org/.  Это такой репозиторий готовых решений.

Итак, у нас есть 2 файла:
/local/composer.phar
/local/composer.json

Следующий шаг — это разрешение зависимостей. Под этим процессом понимается набор действий, который позволит удовлетворить всем зависимостям, которые указаны в composer.json. Для этого, нужно запустить на выполнение сам composer через командную строку с командой install вот так в нашем случае (предварительно нужно зайти в директорию local при помощи командной строки):

В результате выполнения этой команды вы увидите лог выполнения операций, примерно такой:

Лог composer

В логе видно, какие библиотеки были установлены, и какие проблемы произошли при установке. В моем случае сказано, что была установлена библиотека Guzzle 3, которая помечена как deprecated. Видимо библиотека dts/ebay-sdk требует наличия именно этой версии библиотеки.

В процессе выполнения этой операции будет создана директория /local/vendor , в которой будут расположены все скачанные библиотеки, а также файлы, необходимые для работы composer.

Остался последний шаг установки — автозагрузка. Сам Composer всегда генерирует файл автозагрузки для всех библиотек. Лежит он по адресу /local/vendor/autoload.php. Просто включите этот файл в свой проект через init.php и наслаждайтесь использованием новых библиотек!

Интеграция в проект

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

Не спешите все их добавлять в систему контроля версий. Это будет излишним. Из всех файлов, которые были созданы, под версионный контроль потребуется добавить только 2 файла — composer.json и composer.lock. Про первый я уже подробно писал, а вот второй появился как раз после установки всех зависимостей.
Если кратко — то этот файл содержит «снимок» вашей текущей рабочей копии. Проще говоря — в нем перечислены библиотеки, которые у вас установлены, а также их точные версии. Этот файл нужен как раз для версионного контроля. При переносе всего проекта с одной машины на другую нужно будет лишь запустить команду

и все зависимости будут разрешены с учетом тех версий, которые указаны в lock файле. Это важно, т.к. необдуманное обновление версий тех или иных библиотек может привести к печальным последствиям. Поэтому за зависимостями нужно следить.
Кстати, для того, чтобы обновить зависимости согласно тем ограничениям, которые указаны в composer.json (проще говоря — обновить все библиотеки, которые перечислены в этом файле), можно простой командой

Все остальные файлы добавляем в gitignore и создаем коммит со сделанными изменениями.

Остается последний вопрос — перенос библиотек на другую машину. Для того, чтобы перенести библиотеки, вам нужно выполнить команду install на том компе, где нужно развернуть все эти библиотеки. Сделать это можно либо вручную, либо повесить на какой-то хук гита, либо с помощью вашей системы развертывания проектов (хотя если у вас таковая имеется, то наверно эта статья не для вас 😉 )

Composer + PHPStorm

Ну и конечно-же, нельзя обойти стороной интеграцию Composer с Phpstorm.
После того, как вы создали composer.json файл и залили файл с самим composer в директорию проекта, идем в шторм, там жмем Tools -> Composer -> Init composer…
В этом диалоговом окне вас попросят указать путь до composer.phar, путь до composer.json, а также путь до php интерпретатора. Жмем Ок.
После этого можно с помощью PhpStorm управлять зависимостями composer с помощью диалогового окна, которое можно вызвать из меню Tools -> Composer -> Add dependency …
В этом диалоговом окне он покажет перечень доступных на packagist библиотек с возможностью поиска по ним и быстрой установки.

Вот так то! Пользуйтесь правильными инструментами, будьте грамотными разработчиками.
В качестве самообучения предлагаю ознакомиться с документацией на composer — https://getcomposer.org/doc/01-basic-usage.md

  • Gorodetskiy Ilya

    Ошибка в JSON: используются одинарные кавычки в разделе «keywords».

  • для того что бы использовать композер в битрикс по полной: https://github.com/composer/installers/

    так же советую добавить в json
    «config»: {«vendor-dir»: «local/lib»},

    для инсталлера:
    «extra»: {«installer-paths»: {«local/modules/{$name}/»: [«type:bitrix-module»]}},

    помогает при работе с собственным репозиторием при разработке компонентов, модулей, и темплейтов.

    • Спасибо, Ян, за ваше важное дополнение.
      Да, действительно, есть отличный модуль composer-installers, который позволяет устанавливать в том числе и модули битрикса. Только главное не забыть из версионного контроля исключить все модули, которые будут установлены таким способом. По умолчанию composer-installers будет ставить модули, компоненты и шаблоны в директорию /bitrix (спасибо одному из коллег из сообщества битрикс разработчиков). Там им и место.
      В случае, который описан в моей статье, нужно переписать пути для установки т.к. сам composer установлен не в корень проекта. Сделать это можно примерно так:

      «extra»: {
      «installer-paths»: {
      «../bitrix/modules/{$name}/»: [«type:bitrix-module»],
      «./bitrix/components/{$name}/»: [«type:bitrix-component»],
      «./bitrix/templates/{$name}/»: [«type:bitrix-theme»]
      }
      }

      • не рекомендуется работать с директорией /bitrix/
        нынче модули, компоненты и темплейты предпочтительнее устанавливать непосредственно в папку /local/ как я написал выше.
        битриксовые модули можно загрузить через админку, и они встанут куда надо, а при разработке собственных, в extra правильнее, на мой взгляд, было бы прописать директории именно для local.

        • Ян, похоже вы не очень внимательно прочитали мой комментарий.

          Я прекрасно понимаю, что разработчику не рекомендуется работать с директорией /bitrix. Весь свой версионируемый код должен находиться в директории /local. Но внешние модули и библиотеки не должны находиться в /local. Это же очевидно. Внешние библиотеки не должны версионироваться вашей системой контроля версий. Управлением версиями и зависимостями внешними библиотеками берет на себя composer в данном случае

          Изначально composer-installers благополучно ставил все модули/компоненты/шаблоны в директорию local по-умолчанию. Однако этот «баг», точнее недочет, был исправлен нашим коллегой, и в актуальных версиях composer-installers ставит битриксовые зависимости в /bitrix. Вот его статья на эту тему — http://samokhvalov.info/blog/all/ispravlenie-kompozera-dlya-bitriksa/. Там подробно описано, что было добавлено, а также ясно сказано — почему.