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

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

Введение #

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

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

composer.json: настройка проекта #

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

Ключ require #

Первой (и часто единственной) вещью, которую вы указываете в composer.json, является ключ require. Вы просто говорите Composer, от чего зависит ваш пакет.

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

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

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

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

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

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

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

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

Ознакомьтесь с версиями для получения более подробной информации о версиях, связях версий и ограничениях версий.

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

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

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

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

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

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

php composer.phar install

Когда вы запускаете эту команду, может произойти одно из двух:

Установка без composer.lock #

Если вы никогда не запускали команду раньше, а также не было файла composer.lock, Composer просто решает все зависимости, перечисленные в вашем файле composer.json, и загружает последнюю версию своих файлов в каталог vendor вашего проекта. (Каталог vendor является обычным местоположением для всего стороннего кода в проекте). В нашем примере, приведенном выше, вы получите исходные файлы Monolog в vendor/monolog/monolog/. Если Monolog перечислял какие-либо зависимости, они также были бы в папках, находящихся под vendor/.

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

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

Установка с помощью composer.lock #

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

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

Фиксируйте свой файл composer.lock для управления версиями #

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

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

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

php composer.phar update
Примечание: Composer будет отображать предупреждение при выполнении команды install, если composer.lock и composer.json не синхронизированы.

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

php composer.phar update monolog/monolog [...]
Примечание. Для библиотек нет необходимости фиксировать файл блокировки, см. также "Библиотеки - файл блокировки".

Packagist #

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

Если вы заходите на сайт Packagist (packagist.org), вы можете искать и искать пакеты.

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

Пакеты платформ #

Composer имеет пакеты платформы, которые являются виртуальными пакетами для вещей, которые установлены в системе, но фактически не могут быть установлены Composer. Это включает сам PHP, расширения PHP и некоторые системные библиотеки.

  • php представляет версию пользователя PHP, позволяющую применять ограничения, например. >=5.4.0. Чтобы потребовать 64-битную версию php, вы можете потребовать пакет php-64bit.
  • hhvm представляет версию среды исполнения HHVM и позволяет применять ограничение, например '>=2.3.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->addWarning('Foo');

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

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

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

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

После добавления поля autoload в composer.json необходимо повторно выполнить команду dump-autoload для повторной генерации файла vendor/autoload.php.

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

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

В дополнение к автозагрузке PSR-4, Composer также поддерживает PSR-0, classmap и автозагрузку файлов. См. autoload для получения дополнительной информации.

См. Также документы optimizing the autoloader.

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

← Начало работы Библиотеки →