20250612
* Добавлено перечисление стадий в информации о версии VersionInfoStage. * Добавлен новый класс, описывающий информацию о версии, VersionInfo (подробнее см. VersionInfo.md).
This commit is contained in:
272
sources/classes/VersionInfo.md
Normal file
272
sources/classes/VersionInfo.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# Описание класса 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
|
||||
Reference in New Issue
Block a user