Команды Composer

Если вы используете composer.phar локально, то приведённые команды необходимо соответственно изменить в зависимости от того как настроено ваше окружение. Например, если файл composer.phar находится в текущем каталоге и интерпретатор PHP доступен без указания пути к нему, то установка пакета будет осуществляться так:

php composer.phar require vendor/package

При глобальной установке:

composer require vendor/package

Проект на основе пакета

Чаще всего вы будете разворачивать проекты Composer на основе уже существующих пакетов. В этом случае утилита берёт пакет из репозитория и просто распаковывает его в текущую папку, все зависимости помещаются в папку vendor. Для этого используется команда create-project:

composer create-project laravel/laravel ./

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

Установка пакета

Установка пакета через Composer осуществляется посредством выполнения следующей команды, где vendor это имя поставщика php пакета, а package это его название:

composer require vendor/package

Например, добавление в проект пакета twig через Composer будет осуществляться так:

composer require "twig/twig:^2.0"

Команда require не только загрузит требуемую библиотеку в проект, но и пропишет её ещё в файле composer.json, обнавив его. Если устанавливаемый пакет зависит от других библиотек, то они также будут установлены или обновлены. Кроме этого ещё будет обновлён файл composer.lock.

Бывают случаи, когда пакет не хочет устанавливаться из-за несовместимости с платформой. В первую очередь надо убедится, что все необходимые ему расширения PHP в системе установлены.

Если же ваша консольная версия PHP использует другие расширения, а сам пакет будет использоваться только с веб-сервером, можно отключить проверку системных требований пакета с помощью опции --ignore-platform-reqs:

composer require --ignore-platform-reqs vendor/package

Ещё одна ошибка, которую вы можете получить - это не соответствие минимальной стабильности пакета. Все пакеты Composer могут иметь два уровня стабильности:

stable стабильный
dev находится в разработке

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

nano composer.json

Под имеющийся строчкой License добавьте следующую строчку:

"minimum-stability": "dev",

Если в файле уже есть строчка minimum-stability, необходимо заменить её значения со stable на dev. После этого вы сможете установить пакет composer, который вам необходим.

Установка всех пакетов из файла composer.json

Установка сразу всех пакетов в проект осуществляется посредством команды:

composer install

Эта команда работает следующим образом:

Проверяет, имеется ли файл composer.lock
Если файл composer.lock существует, устанавливает версии указанные в нём
Если файла composer.lock нет, тогда выполняется composer.json, создаётся файл composer.lock

Возьмем для примера вот такой файл:

composer.json{
  "name": "laravel/laravel",
  "description": "The Laravel Framework.",
  "keywords": ["framework", "laravel"],
  "license": "MIT",
  "type": "project",
  "require": {
      "php": ">=5.6.4",
      "laravel/framework": "5.3.*"
  },
  "require-dev": {
      "fzaninotto/faker": "~1.4",
      "mockery/mockery": "0.9.*",
      "phpunit/phpunit": "~5.0",
      "symfony/css-selector": "3.1.*",
      "symfony/dom-crawler": "3.1.*"
  },
  "autoload": {
      "classmap": [
          "database"
      ],
      "psr-4": {
          "App\\": "app/"
      }
  },
  "autoload-dev": {
      "classmap": [
          "tests/TestCase.php"
      ]
  },
  "scripts": {
      "post-root-package-install": [
          "php -r \"file_exists('.env') || copy('.env.example', '.env');\""
      ],
      "post-create-project-cmd": [
          "php artisan key:generate"
      ],
      "post-install-cmd": [
          "Illuminate\\Foundation\\ComposerScripts::postInstall",
          "php artisan optimize"
      ],
      "post-update-cmd": [
          "Illuminate\\Foundation\\ComposerScripts::postUpdate",
          "php artisan optimize"
      ]
  },
  "config": {
      "preferred-install": "dist"
  }
}

Пакеты, которые Composer должен установить перечислены в секциях:

require указываются пакеты, которые необходимы для работы проекта
require-dev указывают пакеты, необходимые только для разработки и не влияющие на работу самого проекта

В секциях указаны, так называемые зависимости. Для каждого пакета указана версия. Composer последовательно устанавливает указанные пакеты и разрешает зависимости уже самих пакетов. У пакетов есть свои зависимости и эти зависимости указываются также в composer.json самого пакета. Например, посмотрим на исходник пакета fzaninotto/faker, указанного в секции require-dev. У него в корне можно найти файл composer.json, в котором указаны зависимости для этого пакета.

После того, как все пакеты будут установлены, Composer сформирует файл composer.lock, в котором зафиксирует установленные версии пакетов. Для чего это нужно? Если вы ведёте коллективную разработку, то ваш коллега скачав pull проект с гит-репозитория должен получить тоже окружение и версии всех пакетов, если у вас в composer.json версия для пакета жёстко не зафиксирована, а указана через маску:

{
  "require": {
      "vendor/somepackage": "1.*"
  }
}

Например, на момент разработки у вас установлена версия 1.1, в composer.lock будет указана версия 1.1. Тогда ваш коллега при установке получит ту же версию пакета, которая установлена у вас, даже если вышла новая версия 1.2. Именно поэтому практически всегда проекты имеют файл composer.lock в репозитории.

Обновление пакетов

Команда update используется для обновления зависимостей. Она использует только composer.json. Например, если для пакета указана версия с маской 1.* или ~2.3.0 или dev-master Composer проверит есть ли более новая версия в репозитории для установленного пакета и если есть, установит её. И так для каждого пакета. После этого Composer обновит файл composer.lock.

При установке проекта в случае, если файл composer.lock отсутствует, команды install и update действуют одинаково. Запомните, при первой установке, а также когда вы загрузили из репозитория новую версию вашего проекта, всегда используйте комманду install, которая проверит изменения в файле composer.lock. Когда в рабочем проекте нужно установить новые пакеты, обновить установленные или удалить ненужные, понадобится команда update. Можно использовать альтернативные команды require и remove, которые будут рассмотрены ниже.

Обновление всех пакетов, если удалили пакет из composer.json, значит он будет деинсталирован:

composer update

Обновление или установка указанных пакетов, если укажите пакет который удалили из composer.json, значит он будет деинсталирован:

composer update vendor/package

Обновление пакетов разработчика:

composer update --dev

Удаление пакета

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

composer remove vendor/package

Никогда не удаляйте пакеты вручную из директории vendor, это сломает зависимости Composer.

Очистка внутреннего кэша пакетов

Бывает, что вы создали новый класс или установили пакет, но классы из него всё ещё не видны, и при попытке обратится к ним вы получаете ошибку. В таком случае следует обновить кэш автозагрузки с помощью команды:

composer clear-cache

Зависимости require и require-dev

В секции require указываются пакеты, которые необходимы для работы проекта. Это могут быть комментарии, админка, функции для работы с датами и т.п. В секции require-dev указывают пакеты, необходимые только для разработки и не влияющие на работу самого проекта.

Можно заметить, что при установке или обновлении Composer устанавливает пакеты из обоих секций. Тогда возникает вопрос, зачем их делить? Это разделение условное и им управляете вы сами. Composer сам не может определить, где он запускается — на сервере разработки или продакшене. Поэтому, при разворачивании проекта на продакшене, нужно указать Composer чтобы он, не устанавливал пакеты для разработки из секции require-dev.

composer install --no-dev

При обновлении также указывать ключ --no-dev:

composer update --no-dev

Версии

При указании зависимостей в файле composer.json необходимо указать версию пакета. Давайте рассмотрим варианты определения этих версий.

Точная версия

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

"vendor/package": "1.0.2"

Диапазон версий

С помощью операторов сравнения вы можете указать диапазоны допустимых версий. Для этого можно использовать следующие операторы:

>
>=
<
<=
!=

Можно определить несколько диапазонов. Диапазоны, разделенные пробелом или запятой, будут рассматриваться как логические И. Две вертикальные черты || будут рассматриваться как логическое ИЛИ. И имеет более высокий приоритет чем ИЛИ:

"vendor/package1": ">1.0"
"vendor/package2": ">=1.0 <2.0"
"vendor/package3": ">=1.0 <1.1 || >=1.2"

Диапазон через дефис

Определяется диапазон с минимальной и максимальной границей версий. Если в правой части указать неполную версию, то она будет дополнена подстановочным знаком *:

"vendor/package": "1.0.0 - 2.0.0" // эквивалентно ">=1.0.0 <=2.0.0"
# Неполная версия
"vendor/package": "1.0.0 - 2.0"  //эквивалентно ">=1.0.0 <2.1"  так как 2.0 превращается в 2.0.*

Подстановка

Для определения любых значений можно использовать шаблон со знаком *:

"vendor/package": "1.0.*" // Эквивалентно ">=1.0.0 <1.1"
"vendor/package": "*" // Устанавливает последнюю версию. Данный вариант использовать не рекомендуется!

Тильда

Тильда ~ похожа на подстановку, но имеет одно отличие. Можно указать нижнюю границу версии, последняя цифра указанной версии может быть любой, не не ниже указанной:

"vendor/package": "~1.2.3" // Эквивалентно ">=1.2.3 <1.3.0"
"vendor/package": "~1.2" // Эквивалентно ">=1.2 <2.0.0"

Каретка

Каретку ^ часто используют при семантическом версионировании и для разрешения непрерывных обновлений. Её указывают для ограничения мажорной версии, чтобы гарантировать обратную совместимость:

"vendor/package": "^1.2.3" // Эквивалентно ">=1.2.3 <2.0.0"

Сопутствующие команды

Создание базового варианта файла composer.json

Создание базового варианта файла composer.json с помощью мастера, посредством ответов на вопросы:

composer init

Обновление Composer

Команда для обновления Сomposer до последней версии:

composer self-update

Обновление lock файла без обновления пакетов

Для обновления файла composer.lock без обновления самих пакетов:

composer update --lock

Проверка валидности файла composer.json

Команда с помощью которой можно проверить валидность файла composer.json:

composer validate

Вывести зависимости для указанного пакета

Вывести все зависимости указанного пакета от других можно с помощью команды:

composer depends vendor/package

Вывод всех установленных библиотек

Команда для отображения всех установленных PHP пакетов:

composer show

Вывод списка всех доступных команд

Вывести на экран все доступные команды Composer можно так:

composer list

Получение подробной справки по команде

Вывод подробной справки по команде:

composer help имя_команды

Например, вывести подробную инструкцию по использованию команды require можно следующим образом:

composer help require