babaev-an
a439c0d2c9
* Добавлено перечисление стадий в информации о версии VersionInfoStage. * Добавлен новый класс, описывающий информацию о версии, VersionInfo (подробнее см. VersionInfo.md).
272 lines
11 KiB
Markdown
272 lines
11 KiB
Markdown
# Описание класса VersionInfo
|
||
|
||
## Информация о версии
|
||
|
||
Версия класса: 1.0
|
||
|
||
Впервые введено в пакет с версии: 1.0.24
|
||
|
||
Описание класса: Класс, описывающий информацию о версии.
|
||
|
||
## Публичные свойства и константы класса
|
||
|
||
В классе определены следующие константы:
|
||
|
||
* `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
|
||
|
||
### Парсинг версий
|
||
|
||
Для преобразования строки с версией в объект `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 |