Базовое использование

Введение

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

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

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

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

Ключ `require`

Первое, что вы указываете в файле composer.json — это ключ require. Вы сообщаете Composer, от каких пакетов зависит ваш проект.

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

Как вы видите, require принимает объект, который сопоставляет имена пакетов (например, monolog/monolog) с ограничениями версий (например, 1.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 см. на странице схемы.

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

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

php composer.phar update

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

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

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

Сохранение файла `composer.lock` в системе управления версиями

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

Примечание: Для библиотек сохранение файла lock не требуется, см. также: Библиотеки — Файл lock.

Установка из файла `composer.lock`

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

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

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

php composer.phar install

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

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

php composer.phar update

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

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

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

Packagist

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

Если вы перейдёте на сайт Packagist.org, вы можете просмотреть и найти пакеты.

Любой открытый проект, использующий Composer, рекомендуется публиковать свои пакеты на Packagist. Библиотека не обязана быть на Packagist, чтобы её использовал 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 генерирует файл 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, которые возвращают ассоциативные массивы, позволяющие настроить собственный автозагрузчик.

← Введение | Библиотеки →