Основы использования Composer в своих проектах

1. Введение в использование Composer
2. composer.json: Настройка проекта в Composer
   1. Ключ require
   2. Имена пакетов
   3. Ограничения версии пакета
3. Установка зависимостей в Composer
   1. Добавление файла composer.lock в систему контроля версий
   2. Установка из composer.lock
4. Обновление зависимостей до последних версий
5. Packagist
6. Программные пакеты Composer
7. Автозагрузка в Composer

Введение в использование Composer.

Для ознакомления с базовым использованием мы установим monolog/monolog, библиотеку протоколирования. Если вы еще не установили Composer, обратитесь к главе Введение.

Примечание:

Для простоты в этом введении предполагается, что Composer был установлен локально.

composer.json: Настройка проекта в Composer.

Чтобы начать использовать Composer в своем проекте, все, что нужно, - это файл composer.json. Этот файл описывает зависимости вашего проекта и может содержать другие метаданные. Обычно он должен находиться в самой верхней директории вашего проекта/VCS-репозитория. Технически можно запустить Composer в любом месте, но если вы хотите опубликовать пакет на Packagist.org, он должен найти этот файл в верхней части вашего VCS-репозитория.

Ключ require.

Первое, что необходимо указать в composer.json, - это ключ require. Этим вы сообщаете Composer, от каких пакетов зависит ваш проект.

{
    "require": {
        "monolog/monolog": "2.0.*"
    }
}

Как показано выше в коде, require принимает объект, который сопоставляет имена пакетов (например, monolog/monolog) с ограничениями версии (например, 2.0.*).

Composer использует эту информацию для поиска нужного набора файлов в "репозиториях" пакетов, которые вы регистрируете с помощью ключа repositories, или в Packagist.org, репозитории пакетов по умолчанию. В приведенном выше примере, поскольку в файле composer.json не было зарегистрировано никакого другого репозитория, предполагается, что пакет monolog/monolog зарегистрирован на Packagist.org. (Подробнее о Packagist и о репозиториях).

Имена пакетов.

Имя пакета состоит из имени разработчика и имени проекта. Часто они будут идентичны - имя разработчика существует только для того, чтобы предотвратить конфликты имен. Например, это позволит двум разным людям создать библиотеку с именем json. Одна из них может называться igorw/json, а другая - seldaek/json.

Читайте подробнее о публикации пакетов и именовании пакетов. (Обратите внимание, что можно также указать "платформенные пакеты" в качестве зависимостей, что позволит запрашивать определенные версии серверного программного обеспечения. См. раздел "Пакеты платформы" ниже).

Ограничения версии пакета.

В нашем примере мы запрашиваем пакет Monolog с ограничением версии 2.0.*. Это означает любую версию в ветке разработки 2.0 или любую версию, которая больше или равна 2.0 и меньше 2.1 (>=2.0 <2.1).

Для получения более подробной информации о версиях, о том, как версии связаны друг с другом, и об ограничениях версий, пожалуйста, прочитайте раздел "Версии".

Как Composer загружает нужные файлы?

Когда вы указываете зависимость в composer.json, Composer сначала берет имя пакета, который был запрошен, и ищет его во всех репозиториях, которые были зарегистрированы с помощью ключа repositories. Если никаких дополнительных репозиториев не регистрировалось, или он не находит пакет с таким именем в указанных репозиториях, он обращается к Packagist.org (подробнее ниже).

Когда Composer находит нужный пакет либо на Packagist.org, либо в указанном репозитории, он использует функции управления версиями VCS пакета (т.е. ветви и теги), чтобы подобрать наилучшее соответствие заданному ограничению версии. Обязательно прочитайте о версиях и о разрешениях пакетов в статье о версиях.

Примечание:

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

Вы можете столкнуться с этим, если пытаетесь запросить dev, alpha, beta или RC версии пакета. Подробнее о флагах стабильности и ключе minimum-stability читайте на странице с описанием схемы.

Установка зависимостей в Composer.

Чтобы первоначально установить определенные зависимости для вашего проекта, необходимо выполнить команду update.

php composer.phar update

Это заставит Composer сделать две вещи:

1. Он разрешает все зависимости, перечисленные в вашем файле composer.json, и записывает все пакеты и их точные версии в файл composer.lock, фиксируя проект на этих конкретных версиях. Вы должны сохранить файл composer.lock в репозитории проекта, чтобы все работающие над проектом лица были привязаны к одним и тем же версиям зависимостей (подробнее об этом ниже). В этом заключается основная роль команды update.
2. Затем автоматически запускается команда install. Она загрузит файлы зависимостей в каталог vendor вашего проекта. (Каталог vendor - это обычное местоположение для всего стороннего кода в проекте). В нашем примере, приведенном выше, исходные файлы Monolog будут находиться в каталоге vendor/monolog/monolog/. Поскольку Monolog зависит от psr/log, файлы этого пакета также можно найти в vendor/.

Совет:

Если вы используете git для своего проекта, вы, вероятно, захотите добавить vendor в .gitignore. В действительности не стоит добавлять весь этот сторонний код в ваш репозитарий файлов.

Добавление файла composer.lock в систему контроля версий.

Передача этого файла в систему контроля версий важна потому, что это приведет к тому, что все, кто устанавливает проект, будут использовать точно такие же версии зависимостей, которые используете вы. Ваш CI-сервер, рабочие машины, другие разработчики в вашей команде - все и каждый работает на одних и тех же зависимостях, что уменьшает вероятность возникновения ошибок, затрагивающих только некоторые части развертывания. Даже если вы разрабатываете в одиночку, через шесть месяцев при переустановке проекта вы можете быть уверены, что установленные зависимости все еще работают, даже если ваши зависимости выпустили много новых версий с тех пор. (См. примечание ниже об использовании команды update).

Примечание:

Для библиотек нет необходимости регистрировать файл блокировки, см. также: Библиотеки - Файл блокировки.

Установка из composer.lock.

Если в папке проекта уже есть файл composer.lock, это означает, что либо вы выполнили команду update раньше, либо кто-то другой в проекте выполнил команду update и сохранил файл composer.lock в проекте (что хорошо).

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

Поэтому после получения новых изменений из репозитория VCS рекомендуется выполнить команду install в Composer, чтобы убедиться, что каталог vendor синхронизирован с файлом composer.lock.

php composer.phar install

Обновление зависимостей до последних версий.

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

php composer.phar update

Примечание:

Composer выдаст предупреждение при выполнении команды установки install, если composer.lock не был обновлен после внесения изменений в composer.json, которые могут повлиять на разрешение зависимостей.

Если вы хотите установить, обновить или удалить только одну зависимость, ее можно явно указать в качестве аргумента:

php composer.phar update monolog/monolog [...]

Packagist.

Packagist.org является основным репозиторием Composer. Репозиторий Composer - это, по сути, хранилище пакетов: место, откуда вы можете получать пакеты. Packagist нацелен на то, чтобы стать центральным репозиторием, который используют все. Это означает, что вы можете автоматически потребовать любой пакет, который доступен там, не указывая, где Composer должен искать пакет.

На сайте Packagist.org можно просматривать и искать пакеты.

Любому проекту с открытым исходным кодом, использующему Composer, рекомендуется публиковать свои пакеты на Packagist. Библиотека не обязательно должна быть на Packagist, чтобы использоваться Composer, но это позволяет быстрее ее найти и внедрить другим разработчикам.

Программные пакеты Composer.

Composer имеет пакеты платформы, которые являются виртуальными пакетами для элементов, установленных в системе, но фактически не устанавливаемых Composer. Сюда входит сам PHP, расширения PHP и некоторые системные библиотеки.

• php
  • представляет версию PHP для пользователя, что позволяет применять ограничения, например, ^7.1. Чтобы установить 64-битную версию php, вы можете запросить пакет php-64bit.
• hhvm
  • представляет версию среды выполнения HHVM и позволяет применить ограничение, например, ^2.3.
• ext-<name>
  • позволяет запрашивать расширения PHP (включая расширения ядра). Версионность здесь может быть весьма непоследовательной, поэтому часто целесообразно установить ограничение на *. Примером имени пакета расширения является ext-gd.
• lib-<name>
  • позволяет установить ограничения на версии библиотек, используемых PHP. Доступны следующие: curl, iconv, icu, libxml, openssl, pcre, uuid, xsl.

Можно использовать show --platform, чтобы получить список пакетов для вашей локально доступной платформы.

Автозагрузка в Composer.

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

require __DIR__ . '/vendor/autoload.php';

$log = new Monolog\Logger('name');
$log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
$log->warning('Foo');

Вы даже можете добавить свой собственный код в автозагрузку, добавив поле autoload в composer.json.

{
    "autoload": {
        "psr-4": {"Acme\\": "src/"}
    }
}

Composer зарегистрирует автозагрузчик PSR-4 для пространства имен Acme.

Вы определяете соответствие между пространствами имен и каталогами. Каталог src будет находиться в корне проекта, на том же уровне, что и каталог vendor. В качестве примера можно привести файл src/Foo.php, содержащий класс Acme\Foo.

После добавления поля autoload необходимо повторно выполнить эту команду:

php composer.phar dump-autoload

Эта команда заново создаст файл vendor/autoload.php. Более подробную информацию смотрите в разделе dump-autoload.

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

$loader = require __DIR__ . '/vendor/autoload.php';
$loader->addPsr4('Acme\\Test\\', __DIR__);

Помимо автозагрузки PSR-4, Composer также поддерживает PSR-0, classmap и файлы автозагрузки. Более подробную информацию смотрите в справочнике по autoload.

Смотрите также документацию по оптимизации автозагрузки.

Примечание:

Composer предоставляет свой собственный автозагрузчик. Если вы не хотите использовать его, можно включить файлы vendor/composer/autoload_*.php, которые возвращают ассоциативные массивы, позволяющие настроить собственный автозагрузчик.

Перевод с английского официальной документации Composer:
https://getcomposer.org/doc/01-basic-usage.md

Заберите ссылку на статью к себе, чтобы потом легко её найти!
Раз уж досюда дочитали, то может может есть желание рассказать об этом месте своим друзьям, знакомым и просто мимо проходящим?
Не надо себя сдерживать! ;)