# Описание класса VersionInfo

## Информация о версии

Версия класса: 1.1

Впервые введено в пакет с версии: 1.0.24
Последнее обновление в версии: 1.0.27

Описание класса: Класс, описывающий информацию о версии.

## Публичные свойства и константы класса

В классе определены следующие константы:

* `array StagesNames` - имена стадий сборки.
* `string DefaultTemplate` - шаблон вывода по умолчанию.

В классе определены следующе свойства:

* `int $Major` - мажорная версия (**только чтение**).
* `int $Minor` - минорная версия (**только чтение**).
* `int $Release` - номер релиза (**только чтение**).
* `int $Build` - номер сборки (**только чтение**).
* `VersionInfoStage $Stage` - стадия сборки (**только чтение**).
* `int $StageNumber` - номер стадии сборки (**только чтение**).

## Методы и функции

### Конструктор.

Конструктор принимает **4 обязательных** и **2 дополнительных параметра**:

* `int $Major` - мажорная версия (**обязательный**);
* `int $Minor` - минорная версия (**обязательный**);
* `int $Release` - номер релиза (**обязательный**);
* `int $Build` - номер сборки (**обязательный**);
* `VersionInfoStage` $Stage - стадия сборки (по умолчанию, `VersionInfoStage::Undefined`);
* `int $StageNumber` - номер стадии сборки (по умолчанию, `0`).

В результате создаётся новый класс `VersionInfo`.

Пример:

    $version = new VersionInfo (1, 0, 0, 0, VersionInfoStage::Beta, 1);

Создаст класс `VersionInfo` для версии `1.0.0.0 Beta 1`.

### Преобразование в строку.

За преобразование в строку отвечает 2 метода: `ToString` и `__toString ()`.

#### Метод `ToString`

Этот метод возвращает строковое представление версии. Он содержит **2 необязательных параметра**:

* `string $template` - шаблон вывода (по умолчанию, `DefaultTemplate`);
* `array $stagesNames` - имена стадий сборки (по умолчанию, `StagesNames`).

Метод возвращает `string` - строковое представление версии.

В шаблоне должны присутствовать маркеры:

|     Маркер     | Описание            | Обязательный |
|:--------------:|:--------------------|:------------:|
|    #{Major}    | Мажорная версия     |      ДА      |
|    #{Minor}    | Минорная версия     |      ДА      |
|   #{Release}   | Номер релиза        |      ДА      |
|    #{Build}    | Номер сборки        |      ДА      |
|    #{Stage}    | Стадия сборки       |     НЕТ      |
| #{StageNumber} | Номер стадии сборки |     НЕТ      |

Эти маркеры в шаблоне заменяются на значения соответствующих свойств.

Синтаксис:

    public function ToString (string $template, array $stagesNames): string

Пример,

    // Создаю объект
    $version = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);

    // Задаю шаблон
    $template = #{Major}.#{Minor}.#{Release} (сборка #{Build});

    // Вывожу
    echo $version->ToString($template);

В результате на экране появится:

    1.2.3 (сборка 4)

#### Метод `__toString`

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

Этот метод необходим для вывода корректной информации при попытке привести объект класса `VersionInfo` к типу `string`.

Метод возвращает `string` - строковое представление версии.

Синтаксис:

    public function __toString (): string

Пример,

    // Создаю объект
    $version = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);

    // Вывожу
    echo $version;

В результате на экране появится:

    1.2.3.4 Beta 5

### Сравнение версий

Для сравнения версий используется две аналогичные друг другу (но различающиеся по способу вызова) функции: `Compare` и
`CompareWith`.

#### Метод `Compare`

Это статический метод, который сравнивает две версии, заданные в **2 обязательных параметрах**:

* `VersionInfo $version1` - версия 1;
* `VersionInfo $version2` - версия 2.

Этот метод возвращает `int`:

| version1  | version2  | Результат |
|:---------:|:---------:|:---------:|
|  Младше   |  Старше   |    -1     |
| Совпадает | Совпадает |     0     |
|  Старше   |  Младше   |     1     |

Синтаксис:

    public static function Compare (VersionInfo $version1, VersionInfo $version2): int

Пример,

    // Создаю объекты
    // - $version11 младше $version12
    $version11 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);
    $version12 = new VersionInfo (1, 2, 3, 5, VersionInfoStage::Beta, 6);

    // $version21 совпадает с $version22
    $version21 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);
    $version22 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);

    // $version31 старше $version32
    $version31 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Stable);
    $version32 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);

    // Сравниваю
    $verCompare1 = VersionInfo::Compare($version11, $version12);
    $verCompare2 = VersionInfo::Compare($version21, $version22);
    $verCompare3 = VersionInfo::Compare($version31, $version32);

    // Вывожу
    echo $verCompare1 . '|' . $verCompare2 . '|' . $verCompare3;

В результате на экране появится:

    -1|0|1

#### Метод `CompareWith`

Этот метод полностью аналогичен методу `Compare`. Он отличается лишь только тем, что **не статичен** и вызывается из
ранее созданного экземпляра класса. Он сравнивает текущую версию с переданной. Этот метод имеет только **1 обязательный
параметр**: `VersionInfo $version` - переданная версия.

Этот метод возвращает `int`: `1`, если текущая версия старше переданной, `0`, если совпадает и `-1`, если текущая версия
младше переданной.

Синтаксис:

    public function CompareWith (VersionInfo $version): int

Пример,

    // Создаю объекты
    // - $version11 младше $version12
    $version11 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);
    $version12 = new VersionInfo (1, 2, 3, 5, VersionInfoStage::Beta, 6);

    // $version21 совпадает с $version22
    $version21 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);
    $version22 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);

    // $version31 старше $version32
    $version31 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Stable);
    $version32 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);

    // Сравниваю
    $verCompare1 = $version11->CompareWith($version12);
    $verCompare2 = $version21->CompareWith($version22);
    $verCompare3 = $version31->CompareWith($version32);

    // Вывожу
    echo $verCompare1 . '|' . $verCompare2 . '|' . $verCompare3;

В результате на экране появится:

    -1|0|1

#### Метод `CompareWithRange`

Введено в версии `1.0.27`.

Это метод, который проверяет, находится ли текущая версия в заданном диапазоне, указанном в **2 необязательных
параметрах**:

* `VersionInfo (или null) $left` - левая граница, по умолчанию, `null`;
* `VersionInfo (или null) $right` - правая граница, по умолчанию, `null`.

В случае, если будет передан `null` вместо левой границы, то метод создаст класс `VersionInfo` с минимально возможной
версией `0.0.0.0 PreAlpha 0`, а вместо правой - `VersionInfo` с максимально возможной версией
`9223372036854775807.9223372036854775807.9223372036854775807.9223372036854775807 Stable` (здесь `9223372036854775807` -
максимальное число INT по умолчанию - у вас может быть другое).

Границы могут совпадать, тогда поведение будет совпадать с методом `CompareWith` (при условии, что границы включены).
Кроме того, работает защита "от дурака" и если границы перепутаны, то метод автоматически поменяет их местами.

**3-й необязательный параметр** отвечает за параметры сравнения. Это `ObjectArray` из перечисления
`VersionCompareRangeOption`, который может содержать следующие настройки:

|      Настройка      |               Описание                | Включена по умолчанию |
|:-------------------:|:-------------------------------------:|:---------------------:|
| LeftBorderIncluded  | Включена ли левая граница в диапазон  |          ДА           |
| RightBorderIncluded | Включена ли правая граница в диапазон |          ДА           |

Этот метод возвращает `int`:

|          Текущая версия           | Результат |
|:---------------------------------:|:---------:|
|         Младше диапазона          |    -1     |
| Внутри диапазона (или на границе) |     0     |
|         Старше диапазона          |     1     |

Синтаксис:

    public function CompareWithRange (?VersionInfo $left = null, ?VersionInfo $right = null, ?ObjectArray $options = null): int

Пример,

    // Создаю объекты
    // - 1.2.3.4 Beta 1
    $versionInfo1 = new VersionInfo(1, 2, 3, 4, VersionInfoStage::Beta, 1);

    // - 1.1.3.4 Alpha 2
    $versionInfo2 = new VersionInfo(1, 1, 3, 4, VersionInfoStage::Alpha, 2);

    // - 1.1.1.1 Alpha 2
    $versionInfo3 = new VersionInfo(1, 1, 1, 1, VersionInfoStage::Alpha, 2);
    
    // - 5.5.5.5 Stable
    $versionInfo4 = new VersionInfo(5, 5, 5, 5, VersionInfoStage::Stable);

    // Сравниваю
    echo "Для начала простое сравнение: ";
    $ver1d1 = $versionInfo1->CompareWithRange($versionInfo3, $versionInfo4);
    $ver1d2 = $versionInfo2->CompareWithRange($versionInfo1, $versionInfo4);
    $ver1d2 = $versionInfo4->CompareWithRange($versionInfo2, $versionInfo1);
    echo "$ver1d1|$ver1d2|$ver1d3 \r\n"

    echo "Немного перепутаем границы =) ";
    $ver2d1 = $versionInfo4->CompareWithRange($versionInfo1, $versionInfo2);
    echo "И получим: $ver2d1\r\n";

    echo "А теперь с границами!\r\n";
    echo "- значение равно левой границе: ";
    $ver3d1 = $versionInfo2->CompareWithRange($versionInfo2, $versionInfo1);
    echo " $ver3d1\r\n";
    echo "- значение равно правой границе: ";
    $ver3d2 = $versionInfo1->CompareWithRange($versionInfo2, $versionInfo1);
    echo " $ver3d2\r\n";
    echo "- а теперь с выключением границ:\r\n";
    echo "-- для левой: ";
    $ver3d3 = $versionInfo2->CompareWithRange($versionInfo2, $versionInfo1, $optionNotBorder);
    echo " $ver3d3\r\n";
    echo "-- для правой: ";
    $ver3d4 = $versionInfo1->CompareWithRange($versionInfo2, $versionInfo1, $optionNotBorder);
    echo " $ver3d4\r\n";
    echo "А что если границы равны и значение равно?\r\n";
    echo "- для включённых границ: ";
    $ver4d1 = $versionInfo1->CompareWithRange($versionInfo1, $versionInfo1);
    echo " $ver4d1\r\n";
    echo "- для выключённых границ: ";
    $ver4d2 = $versionInfo1->CompareWithRange($versionInfo1, $versionInfo1, $optionNotBorder);
    echo " $ver4d2";

В результате на экране появится:

    Для начала простое сравнение: 0|-1|1
    Немного перепутаем границы =) И получим: 1
    А теперь с границами!
    - значение равно левой границе: 0
    - значение равно правой границе: 0
    - а теперь с выключением границ:
    -- для левой: -1
    -- для правой: 1
    А что если границы равны и значение равно?
    - для включённых границ: 0
    - для выключённых границ: -1

### Парсинг версий

Для преобразования строки с версией в объект `VersionInfo` используется статичный метод `Parse`.

Он требует **1 обязательный параметр** и **1 необязательный**:

* `string $version` - строка с версией (она должна быть в формате
  `#{Major}.#{Minor}.#{Release}.#{Build} #{Stage} #{StageNumber}`, причём `#{Stage}` и `#{StageNumber}` можно не
  указывать);
* `array $stagesNames` - имена стадий сборки (по умолчанию, `StagesNames`).

Этот метод возвращает объект {@link VersionInfo} с данными о версии или `new VersionInfo(0, 0, 0, 0)` в случае ошибки.

Синтаксис:

    public static function Parse (string $version, array $stagesNames = self::StagesNames): VersionInfo

Пример,

    // Создаю текст
    $verText = '1.2.3.4 Beta 2';    
    
    // Преобразую
    $version = VersionInfo::Parse($verText);

    // Вывожу
    echo $version;

В результате на экране появится:

    1.2.3.4 Beta 2

### Вспомогательные методы

#### Метод `IsNotUndefinedOrStable`

Этот **статический** метод проверяет, является ли версия в неопределённой стадии или уже релизом.

Он имеет только **1 обязательный параметр**: `VersionInfoStage $versionStage` - стадия сборки.

Этот метод возвращает `bool`: `true`, если стадия сборки определена и не является релизом и `false` в противном случае.

Синтаксис:

    public static function IsNotUndefinedOrStable (VersionInfoStage $versionStage): bool

Пример,

    // Создаю объекты
    $version1 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Undefined, 5);
    $version2 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Beta, 5);
    $version3 = new VersionInfo (1, 2, 3, 4, VersionInfoStage::Stable);

    // Сравниваю
    $res1 = VersionInfo::IsNotUndefinedOrStabl($version1->Stage);
    $res2 = VersionInfo::IsNotUndefinedOrStabl($version2->Stage);
    $res3 = VersionInfo::IsNotUndefinedOrStabl($version3->Stage);

    // Вывожу
    echo $res1 . '|' . $res2 . '|' . $res3;

В результате на экране появится:

    false|true|false