php_components_pack/sources/classes/VersionInfo.md

Описание класса 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