Версии и ограничения. Объяснение работы с версиями в Composer.

1. Версии Composer или версии VCS
2. Теги и ветви VCS
   
   1. Теги VCS
   2. Ветви VCS
   3. Стабильность VCS
   4. Минимальная стабильность VCS
3. Запись ограничений версий в Composer
   
   1. Точное ограничение версии
   2. Диапазон версий
   3. Диапазон версий через дефис (-)
   4. Диапазон версий с обозначением (.*)
4. Операторы следующего релиза новой версии в Composer
   1. Тильда для обозначение диапазона версий (~)
   2. Диапазон версий с символом каретки (^)
5. Ограничения стабильности версий в Composer
6. Краткие выводы по версионированию в Composer
7. Тестирование ограничений версии в Composer

Версии Composer или версии VCS

Поскольку Composer в значительной степени ориентирован на использование систем контроля версий, таких как git, термин "версия" может быть немного двусмысленным. В смысле системы контроля версий, "версия" - это определённый набор файлов, содержащих определённые данные. В терминологии git это "ref", или конкретный коммит, который может быть представлен веткой HEAD или тегом. Когда вы проверяете эту версию в вашей VCS - например, тег v1.1 или коммит e35fa0d, - вы запрашиваете один-единственный, известный набор файлов, и всегда получаете в ответ одни и те же файлы.

В Composer то, что часто называют версией - это строка, которая следует за именем пакета в строке require (например, ~1.1 или 1.2.*) - на самом деле является ограничением версии. Composer использует ограничения версии, чтобы определить, какие ссылки в VCS ему следует проверить (или чтобы убедиться, что данная библиотека является приемлемой в случае статически поддерживаемой библиотеки со спецификацией version в composer.json).

Теги и ветви VCS

Для дальнейшего обсуждения рассмотрим следующий пример репозитория библиотек:

~/my-library$ git branch

v1
v2
my-feature
another-feature

~/my-library$ git tag

v1.0
v1.0.1
v1.0.2
v1.1-BETA
v1.1-RC1
v1.1-RC2
v1.1
v1.1.1
v2.0-BETA
v2.0-RC1
v2.0
v2.0.1
v2.0.2

Теги VCS

Обычно Composer работает с тегами (в отличие от веток - если вы не знаете, что это значит, почитайте о системах контроля версий). Когда вы пишете ограничение версии, оно может ссылаться на конкретный тег (например, 1.1) или на допустимый диапазон тегов (например, >=1.1 <2.0 или ~4.0). Чтобы разрешить эти ограничения, Composer сначала запрашивает у VCS список всех доступных тегов, а затем создает внутренний список доступных версий на основе этих тегов. В приведенном выше примере внутренний список Composer включает версии 1.0, 1.0.1, 1.0.2, бета-версию 1.1, первый и второй релиз-кандидаты 1.1, финальную версию 1.1 и т. д...... (Обратите внимание, что Composer автоматически удаляет префикс 'v' в фактическом названии, чтобы получить действительный номер финальной версии).

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

Ветви VCS

Если требуется, чтобы Composer проверял ветку, а не тег, нужно указать ему на ветку с помощью специального префикса dev-* (или иногда суффикса; см. ниже). Если вы проверяете ветку, предполагается, что вы хотите работать с ней, и Composer фактически клонирует репозиторий в нужное место в вашей директории vendor. Для тегов он копирует нужные файлы без фактического клонирования репозитория. (Вы можете изменить это поведение с помощью --prefer-source и --prefer-dist, см. настройки установки).

В приведенном выше примере, если бы вы хотели проверить ветку my-feature, вы бы указали dev-my-feature в качестве ограничения версии в предложении require. В результате Composer клонирует репозиторий my-library в мой каталог vendor и проверит ветку my-feature.

Когда имена ветвей выглядят как версии, мы должны уточнить для Composer, что мы пытаемся проверить ветвь, а не тег. В приведенном выше примере у нас есть две ветки версий: v1 и v2. Чтобы заставить Composer проверить одну из этих веток, нужно указать ограничение версии, которое выглядит так: v1.x-dev. .x — это произвольная строка, которая нужна Composer, чтобы указать ему, что мы говорим о ветке v1, а не о теге v1 (в качестве альтернативы можно назвать ветку v1.x вместо v1). В случае ветки с именем, похожим на версию (v1, в данном случае), вы добавляете -dev в качестве суффикса, а не используете dev- в качестве префикса.

Стабильность VCS

Composer распознает следующие виды стабильности (в порядке убывания стабильности): dev, alpha, beta, RC и stable, где RC означает release candidate. Стабильность версии определяется ее суффиксом, например, версия v1.1-BETA имеет стабильность beta, а v1.1-RC1 — RC. Если такой суффикс отсутствует, например, версия v1.1, то Composer считает эту версию стабильной. Кроме того, Composer автоматически добавляет суффикс -dev ко всем числовым веткам и префиксирует dev- все остальные ветки, импортированные из VCS-репозитория. В обоих случаях присваивается стабильность dev.

Помните об этом, и это поможет вам в следующем разделе.

Минимальная стабильность VCS

Есть еще один момент, который повлияет на то, какие файлы будут извлечены из VCS библиотеки и добавлены в ваш проект: Composer позволяет указать ограничения стабильности, чтобы указать, какие теги считаются действительными. В примере выше обратите внимание, что библиотека выпустила бета-версию и два релиз-кандидата для версии 1.1 до окончательного официального релиза. Чтобы получить эти версии при запуске composer install или composer update, мы должны явно указать Composer, что мы не против релиз-кандидатов и бета-версий (и альфа-версий, если они нам нужны). Это можно сделать либо с помощью общепроектного значения minimum-stability в composer.json, либо с помощью "флагов стабильности" в ограничениях версий. Подробнее можно узнать на странице схемы.

Запись ограничений версий в Composer

Теперь, когда вы имеете представление о том, как Composer видит версии, давайте поговорим о том, как задать ограничения версий для зависимостей вашего проекта.

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

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

Пример: 1.0.2

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

С помощью операторов сравнения можно задать диапазоны допустимых версий. Допустимыми операторами являются >, >=, <, <=, !=.

Вы можете задать несколько диапазонов. Диапазоны, разделенные пробелом ( ) или запятой (,), будут рассматриваться как логическое AND. Двойная черта (||) будет рассматриваться как логическое OR. AND имеет более высокий приоритет, чем OR.

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

Примечание: В старых версиях Composer одинарная черта (|) была рекомендуемой альтернативой логическому OR. Поэтому для обратной совместимости одинарная черта (|) по-прежнему будет рассматриваться как логическое OR.

Примеры:

• >=1.0
• >=1.0 <2.0
• >=1.0 <1.1 || >=1.2

Диапазон версий через дефис (-)

Включающий набор версий. Частичные версии, включенные справа, дополняются подстановочным знаком. Например, 1.0 - 2.0 эквивалентно >=1.0.0 <2.1, так как 2.0 становится 2.0.*. С другой стороны, 1.0.0 - 2.1.0 эквивалентно >=1.0.0 <=2.1.0.

Пример: 1.0 - 2.0

Диапазон версий с обозначением (.*)

Вы можете задать шаблон с помощью подстановочного знака *. 1.0.* эквивалентно >=1.0 <1.1.

Пример: 1.0.*

Операторы следующего релиза новой версии в Composer

Тильда для обозначение диапазона версий (~)

Оператор ~ лучше всего объяснить на примере: ~1.2 эквивалентно >=1.2 <2.0.0, а ~1.2.3 эквивалентно >=1.2.3 <1.3.0. Как видите, это полезно в основном для проектов, соблюдающих семантическое версионирование. Обычное использование — это отметить минимальную минорную версию, от которой вы зависите, например ~1.2 (что позволяет использовать все, вплоть до 2.0, но не включая ее). Поскольку в теории не должно быть никаких нарушений обратной совместимости до 2.0, это хорошо работает. Другой способ взглянуть на это заключается в том, что использование ~ указывает минимальную версию, но позволяет увеличить последнюю цифру.

Пример: ~1.2

Примечание: Хотя 2.0-beta.1 строго предшествует 2.0, ограничение версии ~1.2 не будет его устанавливать. Как было сказано выше, ~1.2 означает, что может измениться только .2, но часть 1. остается неизменной.

Примечание: Оператор ~ имеет исключение в своем поведении для номера основного выпуска. Это означает, что, например, ~1 - это то же самое, что и ~1.0, так как он не позволит увеличить основной номер, пытаясь сохранить обратную совместимость.

Диапазон версий с символом каретки (^)

Оператор ^ ведет себя очень похоже, но он ближе к семантической версионности и всегда допускает не разрывные обновления. Например, ^1.2.3 эквивалентен >=1.2.3 <2.0.0, поскольку ни один из релизов до 2.0 не должен нарушать обратную совместимость. Для версий до 1.0 он также действует с учетом безопасности и рассматривает ^0.3 как >=0.3.0 <0.4.0, а ^0.0.3 как >=0.0.3 <0.0.4.

Это рекомендуемый оператор для максимальной совместимости при написании библиотечного кода.

Пример: ^1.2.3

Примечание: Если вы используете PowerShell в Windows, то при использовании символов в качестве аргументов в CLI, например, при использовании команды composer require, необходимо избегать символа каретки. Вы должны использовать четыре последующих оператора каретки, например ^^^^1.2.3, чтобы оператор каретки был правильно передан в Composer.

Ограничения стабильности версий в Composer

Если вы используете ограничение, которое явно не определяет стабильность, Composer по умолчанию будет использовать -dev или -stable, в зависимости от используемого оператора (операторов). Это происходит автоматически.

Если вы хотите явно учитывать в сравнении только стабильный релиз, добавьте суффикс -stable.

Примеры:

Ограничения	Изнутри
1.2.3	=1.2.3.0-stable
>1.2	>1.2.0.0-stable
>=1.2	>=1.2.0.0-dev
>=1.2-stable	>=1.2.0.0-stable
<1.3	<1.3.0.0-dev
<=1.3	<=1.3.0.0-stable
1 - 2	>=1.0.0.0-dev <3.0.0.0-dev
~1.3	>=1.3.0.0-dev <2.0.0.0-dev
1.4.*	>=1.4.0.0-dev <1.5.0.0-dev

Однако, чтобы разрешить различные варианты стабильности без принудительной установки на уровне ограничений, вы можете использовать stability-flags типа @<стабильность> (например, @dev), чтобы сообщить Composer, что данный пакет может быть установлен в той стабильности, которая отличается от минимальной стабильности, установленной по умолчанию. Все доступные флаги стабильности перечислены в разделе minimum-stability на странице схемы.

Краткие выводы по версионированию в Composer

"require": {
    "vendor/package": "1.3.2", // exactly 1.3.2

    // >, <, >=, <= | specify upper / lower bounds
    "vendor/package": ">=1.3.2", // anything above or equal to 1.3.2
    "vendor/package": "<1.3.2", // anything below 1.3.2

    // * | wildcard
    "vendor/package": "1.3.*", // >=1.3.0 <1.4.0

    // ~ | allows last digit specified to go up
    "vendor/package": "~1.3.2", // >=1.3.2 <1.4.0
    "vendor/package": "~1.3", // >=1.3.0 <2.0.0

    // ^ | doesn't allow breaking changes (major version fixed - following semver)
    "vendor/package": "^1.3.2", // >=1.3.2 <2.0.0
    "vendor/package": "^0.3.2", // >=0.3.2 <0.4.0 // except if major version is 0
}

Тестирование ограничений версии в Composer

Вы можете проверить ограничения версии с помощью сайта semver.madewithlove.com. Введите имя пакета, и он автоматически заполнит ограничение версии по умолчанию, которое Composer добавит в ваш файл composer.json. Вы можете настроить ограничение версии, и инструмент выделит все релизы, которые соответствуют ему.

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