php_components_pack/sources/classes/VersionInfo.md

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

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

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

Впервые введено в пакет с версии: 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

Метод MinVersion

Введено в версии 1.0.28.

Этот статический метод без параметров возвращает минимальную версию (объект класса VersionInfo).

Синтаксис:

public static function MinVersion (): VersionInfo

Пример,

// Создаю объекты
$version = VersionInfo::MinVersion();

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

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

0.0.0.0 PreAlpha 0

Метод MaxVersion

Введено в версии 1.0.28.

Этот статический метод без параметров возвращает максимальную версию (объект класса VersionInfo).

Синтаксис:

public static function MaxVersion (): VersionInfo

Пример,

// Создаю объекты
$version = VersionInfo::MaxVersion();

// В этом примере считается, что константа PHP_INT_MAX равна 9223372036854775807

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

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

9223372036854775807.9223372036854775807.9223372036854775807.9223372036854775807