Понимание версий в composer.json: символы ^ и ~, диапазоны версий

# Версии пакетов в composer.json

Вы, вероятно, видели символы вроде "^3.2" и "~3.2" в файле composer.json. Давайте разберёмся, что эти символы означают и какие версии пакетов они поддерживают.

## Пример файла composer.json

Вот общий пример файла composer.json:

```json
{
  "require": {
    "author/package": ">=5.6",
    "author/package": "~2.0.14",
    "author/package": "~2.0.0",
    "author/package": "~2.0.0 || ~2.1.0",
    "author/package": "dev-master",
    "author/package": "*",
    "author/package": "2.4.1"
  },
  "require-dev": {
    "author/package": "~2.1.0",
    "author/package": "~2.1.0",
    "author/package": "~2.0.0",
    "author/package": "^4.0",
    "author/package": "^1.0",
    "author/package": "^1.0",
    "author/package": "^1.0",
    "author/package": "~0.5.0 || ~1.1.0",
    "author/package": ">=2.7 <=4.2.4"
  }
}

Содержание

• Точная версия
• Диапазоны версий
• Комбинирование диапазонов
• Диапазон версий с помощью -
• Ограничения стабильности
• Общая информация

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

Определяет только указанную версию пакета. Задаётся без каких-либо символов:

"erusev/parsedown": "1.7"

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

Позволяет обновлять пакет в пределах заданного диапазона версий.

• dev-master — позволяет использовать все версии, включая последние коммиты основной ветки.
• > — например, ">1.7" позволяет использовать версии больше указанной.
• >= — например, ">=1.7" позволяет использовать версии больше или равные указанной.
• < — например, "<1.7" позволяет использовать версии меньше указанной.
• <= — например, "<=1.7" позволяет использовать версии меньше или равные указанной.
• != — например, "!=1.7" позволяет использовать любые версии, кроме указанной.
• **** — например, "1.1." (это подстановочный знак). Используется для указания шаблона версии.
  Например, "1.0.*" включает все версии 1.0, 1.0.1, 1.0.2 и так далее.

~ — например, "~1.2.3".
Оператор тильда. Позволяет увеличивать последнюю указанную цифру. Обычно используется для обозначения минимальной минорной версии, на которой зависит ваш код.

• ~1.2 соответствует как ">=1.2 <2.0.0" (все версии до 2.0, но исключая 2.0).
• ~1.2.3 соответствует как ">=1.2.3 <1.3.0" (все версии до 1.3, но исключая 1.3).

Пример:

"erusev/parsedown": "~2.0.14"

^ — например, "^1.2.3".
Оператор карет. Похож на тильду, но позволяет увеличивать все числа, кроме первого (основного). Обычно используется для обозначения минимальной осн��вной версии.

• ^1.2.3 соответствует ">=1.2.3 <2.0.0" (все версии до 2.0, но исключая 2.0).
• Если основная версия начинается с 0, он позволяет все обновления до второго числа. Для версий до 1.0, также учитывается безопасность обновлений и рассматривается как "^0.3" = ">=0.3.0 <0.4.0".

Рекомендуется использовать этот оператор для обеспечения совместимости при написании/использовании библиотеки.

Пример:

"erusev/parsedown": "^4.0"

Комбинирование диапазонов

Несколько диапазонов можно указывать одновременно:

• Пример: ">2.7 <4.2.4" — логическое "И". Пробел или запятая между версиями означает "И".
• || — Пример: "2.0.0 || 2.1.0" — логическое "ИЛИ". Двойная вертикальная черта означает "ИЛИ".

Примечание: В старых версиях Composer для логического "ИЛИ" рекомендовали использовать одиночную вертикальную черту |. Поэтому для обратной совместимости | все еще рассматривается как логическое "ИЛИ".

"И" имеет приоритет над "ИЛИ".

Примеры:

// Более или равно версии 2.6
"erusev/parsedown": ">=2.6"

// Более 2.7 И меньше 4.2.4
"erusev/parsedown": ">2.7 <4.2.4"

// Версия 2.0.0 ИЛИ версия 2.1.0
"erusev/parsedown": "2.0.0 || 2.1.0"

Диапазон версий с помощью -

Дефис (-) указывает, какой набор версий подходит: от версии - до версии. Правое неуказанное число в версии дополняется *.

Например, 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".

Пример:

// Более или равно 2.0, но меньше 3.1
"erusev/parsedown": "2.0 - 3.0"

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

Добавьте суффикс -stable, если вам нужно загружать только стабильные версии.

Если суффикс не указан, Composer под капотом будет использовать -dev или -stable в зависимости от указанного оператора:

Общая информация

Сводная информация о версиях:

"require": {
  // только версия 1.3.2
  "author/package": "1.3.2",

  // >, <, >=, <= | задают верхние / нижние границы
  "author/package": ">=1.3.2", // все, что больше или равно 1.3.2
  "author/package": "<1.3.2",  // меньше 1.3.2

  // * | подстановочный знак
  "author/package": "1.3.*", // >=1.3.0 <1.4.0

  // ~ | позволяет увеличивать последнюю указанную цифру
  "author/package": "~1.3.2", // >=1.3.2 <1.4.0
  "author/package": "~1.3", // >=1.3.0 <2.0.0

  // ^ | не позволяет критические изменения
  "author/package": "^1.3.2", // >=1.3.2 <2.0.0
  "author/package": "^0.3.2", // >=0.3.2 <0.4.0

  // ИЛИ
  "phpunit/phpunit": "^3||^4||^5||^6||^7||^8||^9",
  // старая версия
  "phpunit/phpunit": "^3|^4|^5|^6|^7|^8|^9"
}