Skip to content

Latest commit

 

History

History
executable file
·
306 lines (239 loc) · 21.9 KB

01-basic-usage.md

File metadata and controls

executable file
·
306 lines (239 loc) · 21.9 KB
Raw

Основы использования

Подготовка

В качестве примера для демонстрации основ использования Composer, мы будем устанавливать библиотеку логирования 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 ниже, либо узнайте больше о репозиториях здесь).

Названия пакетов

Название пакета состоит из имени разработчика (vendor) и собственно имени проекта. Зачастую они будут совпадать — имя разработчика нужно только для предотвращения коллизий названий пакетов. К примеру, данная возможность позволит двум разным людям создать библиотеку с названием json: один определит пакет с названием igorw/json, в то время как другой может создать пакет, имя которого seldaek/json.

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

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

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

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

Как Composer загружает нужные файлы? Когда вы указываете зависимость в composer.json, Composer сначала возьмёт имя запрашиваемого пакета и ищет его в любых репозиториях, которые вы зарегистрировали, используя поле repositories. Если вы не зарегистрировали никаких дополнительных репозиториев, либо пакет пакет с данным именем не найден в указанных репозиториях, Composer возвратится к поиске пакета на 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. Ведь в реальности вы не хотите добавлять весь сторонний код пакетов в ваш репозиторий, отслеживаемый CVS.

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

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

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

В любом случае, при выполении команды install при существовании файла composer.lock, Composer разрешает и устанавливает все зависимости, перечисленные в файле 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 стремится стать центральным хранилищем, который будут все использовать. В данном случае это означает, что вы можете автоматически запросить (установить через require) любой пакет, доступный в этом хранилище, без дополнительного указания, где Composer должен искать пакет.

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

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

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

Composer поддерживает пакеты платформы, которые на самом деле являются виртуальными пакетами для всего того, что установлено в системе, но в реальности не устанавливаются с помощью Composer. Сюда входят непосредственно сам 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->addWarning('Foo');

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

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

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

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

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

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

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

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

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

Смотрите также статью по оптимизации автозагрузчика.

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

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