Compare commits
15 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| 6e831e2650 | |||
| 52de613b0f | |||
| 58b3b74d99 | |||
| f5420ce2c0 | |||
| e9118609b6 | |||
| 1290a567de | |||
| df660676d0 | |||
| 3e199fc460 | |||
| a58b6f1358 | |||
| a439c0d2c9 | |||
| ef0f2ff54d | |||
| 28dbf773f1 | |||
| 0730509096 | |||
| e9333e8624 | |||
| 71958482c5 |
composer.jsoncomposer.lock
sources
attributes
classes
enums
exceptions
operators
traits/JsonReWriter
JsonReWriterDeleteTrait.phpJsonReWriterKeyTrait.phpJsonReWriterLoadSaveTrait.phpJsonReWriterReadTrait.phpJsonReWriterWriteTrait.php
types
tests
@ -20,7 +20,7 @@
|
||||
"ext-mbstring": "*"
|
||||
},
|
||||
"require-dev": {
|
||||
"phpunit/phpunit": "^12.1.6"
|
||||
"phpunit/phpunit": "^12.2.1"
|
||||
},
|
||||
"autoload": {
|
||||
"psr-4": {
|
||||
|
||||
76
composer.lock
generated
76
composer.lock
generated
@ -4,7 +4,7 @@
|
||||
"Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
|
||||
"This file is @generated automatically"
|
||||
],
|
||||
"content-hash": "0c5a35b9c8987ac3fd0f7480fea87d4c",
|
||||
"content-hash": "f5bf0ec4042cb12fb3a702cad65f099d",
|
||||
"packages": [],
|
||||
"packages-dev": [
|
||||
{
|
||||
@ -69,16 +69,16 @@
|
||||
},
|
||||
{
|
||||
"name": "nikic/php-parser",
|
||||
"version": "v5.4.0",
|
||||
"version": "v5.5.0",
|
||||
"source": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/nikic/PHP-Parser.git",
|
||||
"reference": "447a020a1f875a434d62f2a401f53b82a396e494"
|
||||
"reference": "ae59794362fe85e051a58ad36b289443f57be7a9"
|
||||
},
|
||||
"dist": {
|
||||
"type": "zip",
|
||||
"url": "https://api.github.com/repos/nikic/PHP-Parser/zipball/447a020a1f875a434d62f2a401f53b82a396e494",
|
||||
"reference": "447a020a1f875a434d62f2a401f53b82a396e494",
|
||||
"url": "https://api.github.com/repos/nikic/PHP-Parser/zipball/ae59794362fe85e051a58ad36b289443f57be7a9",
|
||||
"reference": "ae59794362fe85e051a58ad36b289443f57be7a9",
|
||||
"shasum": ""
|
||||
},
|
||||
"require": {
|
||||
@ -121,9 +121,9 @@
|
||||
],
|
||||
"support": {
|
||||
"issues": "https://github.com/nikic/PHP-Parser/issues",
|
||||
"source": "https://github.com/nikic/PHP-Parser/tree/v5.4.0"
|
||||
"source": "https://github.com/nikic/PHP-Parser/tree/v5.5.0"
|
||||
},
|
||||
"time": "2024-12-30T11:07:19+00:00"
|
||||
"time": "2025-05-31T08:24:38+00:00"
|
||||
},
|
||||
{
|
||||
"name": "phar-io/manifest",
|
||||
@ -245,16 +245,16 @@
|
||||
},
|
||||
{
|
||||
"name": "phpunit/php-code-coverage",
|
||||
"version": "12.3.0",
|
||||
"version": "12.3.1",
|
||||
"source": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/sebastianbergmann/php-code-coverage.git",
|
||||
"reference": "9075a8efc66e11bc55c319062e147bdb06777267"
|
||||
"reference": "ddec29dfc128eba9c204389960f2063f3b7fa170"
|
||||
},
|
||||
"dist": {
|
||||
"type": "zip",
|
||||
"url": "https://api.github.com/repos/sebastianbergmann/php-code-coverage/zipball/9075a8efc66e11bc55c319062e147bdb06777267",
|
||||
"reference": "9075a8efc66e11bc55c319062e147bdb06777267",
|
||||
"url": "https://api.github.com/repos/sebastianbergmann/php-code-coverage/zipball/ddec29dfc128eba9c204389960f2063f3b7fa170",
|
||||
"reference": "ddec29dfc128eba9c204389960f2063f3b7fa170",
|
||||
"shasum": ""
|
||||
},
|
||||
"require": {
|
||||
@ -310,7 +310,7 @@
|
||||
"support": {
|
||||
"issues": "https://github.com/sebastianbergmann/php-code-coverage/issues",
|
||||
"security": "https://github.com/sebastianbergmann/php-code-coverage/security/policy",
|
||||
"source": "https://github.com/sebastianbergmann/php-code-coverage/tree/12.3.0"
|
||||
"source": "https://github.com/sebastianbergmann/php-code-coverage/tree/12.3.1"
|
||||
},
|
||||
"funding": [
|
||||
{
|
||||
@ -330,7 +330,7 @@
|
||||
"type": "tidelift"
|
||||
}
|
||||
],
|
||||
"time": "2025-05-23T15:49:03+00:00"
|
||||
"time": "2025-06-18T08:58:13+00:00"
|
||||
},
|
||||
{
|
||||
"name": "phpunit/php-file-iterator",
|
||||
@ -579,16 +579,16 @@
|
||||
},
|
||||
{
|
||||
"name": "phpunit/phpunit",
|
||||
"version": "12.1.6",
|
||||
"version": "12.2.5",
|
||||
"source": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/sebastianbergmann/phpunit.git",
|
||||
"reference": "2fdf0056c673c8f0f1eed00030be5f8243c1e6e0"
|
||||
"reference": "b71849b29f7a8d7574e4401873cb8b539896613f"
|
||||
},
|
||||
"dist": {
|
||||
"type": "zip",
|
||||
"url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/2fdf0056c673c8f0f1eed00030be5f8243c1e6e0",
|
||||
"reference": "2fdf0056c673c8f0f1eed00030be5f8243c1e6e0",
|
||||
"url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/b71849b29f7a8d7574e4401873cb8b539896613f",
|
||||
"reference": "b71849b29f7a8d7574e4401873cb8b539896613f",
|
||||
"shasum": ""
|
||||
},
|
||||
"require": {
|
||||
@ -602,15 +602,15 @@
|
||||
"phar-io/manifest": "^2.0.4",
|
||||
"phar-io/version": "^3.2.1",
|
||||
"php": ">=8.3",
|
||||
"phpunit/php-code-coverage": "^12.2.1",
|
||||
"phpunit/php-code-coverage": "^12.3.1",
|
||||
"phpunit/php-file-iterator": "^6.0.0",
|
||||
"phpunit/php-invoker": "^6.0.0",
|
||||
"phpunit/php-text-template": "^5.0.0",
|
||||
"phpunit/php-timer": "^8.0.0",
|
||||
"sebastian/cli-parser": "^4.0.0",
|
||||
"sebastian/comparator": "^7.0.1",
|
||||
"sebastian/comparator": "^7.1.0",
|
||||
"sebastian/diff": "^7.0.0",
|
||||
"sebastian/environment": "^8.0.1",
|
||||
"sebastian/environment": "^8.0.2",
|
||||
"sebastian/exporter": "^7.0.0",
|
||||
"sebastian/global-state": "^8.0.0",
|
||||
"sebastian/object-enumerator": "^7.0.0",
|
||||
@ -624,7 +624,7 @@
|
||||
"type": "library",
|
||||
"extra": {
|
||||
"branch-alias": {
|
||||
"dev-main": "12.1-dev"
|
||||
"dev-main": "12.2-dev"
|
||||
}
|
||||
},
|
||||
"autoload": {
|
||||
@ -656,7 +656,7 @@
|
||||
"support": {
|
||||
"issues": "https://github.com/sebastianbergmann/phpunit/issues",
|
||||
"security": "https://github.com/sebastianbergmann/phpunit/security/policy",
|
||||
"source": "https://github.com/sebastianbergmann/phpunit/tree/12.1.6"
|
||||
"source": "https://github.com/sebastianbergmann/phpunit/tree/12.2.5"
|
||||
},
|
||||
"funding": [
|
||||
{
|
||||
@ -680,7 +680,7 @@
|
||||
"type": "tidelift"
|
||||
}
|
||||
],
|
||||
"time": "2025-05-21T12:36:31+00:00"
|
||||
"time": "2025-06-27T04:37:55+00:00"
|
||||
},
|
||||
{
|
||||
"name": "sebastian/cli-parser",
|
||||
@ -741,16 +741,16 @@
|
||||
},
|
||||
{
|
||||
"name": "sebastian/comparator",
|
||||
"version": "7.0.1",
|
||||
"version": "7.1.0",
|
||||
"source": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/sebastianbergmann/comparator.git",
|
||||
"reference": "b478f34614f934e0291598d0c08cbaba9644bee5"
|
||||
"reference": "03d905327dccc0851c9a08d6a979dfc683826b6f"
|
||||
},
|
||||
"dist": {
|
||||
"type": "zip",
|
||||
"url": "https://api.github.com/repos/sebastianbergmann/comparator/zipball/b478f34614f934e0291598d0c08cbaba9644bee5",
|
||||
"reference": "b478f34614f934e0291598d0c08cbaba9644bee5",
|
||||
"url": "https://api.github.com/repos/sebastianbergmann/comparator/zipball/03d905327dccc0851c9a08d6a979dfc683826b6f",
|
||||
"reference": "03d905327dccc0851c9a08d6a979dfc683826b6f",
|
||||
"shasum": ""
|
||||
},
|
||||
"require": {
|
||||
@ -761,7 +761,7 @@
|
||||
"sebastian/exporter": "^7.0"
|
||||
},
|
||||
"require-dev": {
|
||||
"phpunit/phpunit": "^12.0"
|
||||
"phpunit/phpunit": "^12.2"
|
||||
},
|
||||
"suggest": {
|
||||
"ext-bcmath": "For comparing BcMath\\Number objects"
|
||||
@ -769,7 +769,7 @@
|
||||
"type": "library",
|
||||
"extra": {
|
||||
"branch-alias": {
|
||||
"dev-main": "7.0-dev"
|
||||
"dev-main": "7.1-dev"
|
||||
}
|
||||
},
|
||||
"autoload": {
|
||||
@ -809,15 +809,27 @@
|
||||
"support": {
|
||||
"issues": "https://github.com/sebastianbergmann/comparator/issues",
|
||||
"security": "https://github.com/sebastianbergmann/comparator/security/policy",
|
||||
"source": "https://github.com/sebastianbergmann/comparator/tree/7.0.1"
|
||||
"source": "https://github.com/sebastianbergmann/comparator/tree/7.1.0"
|
||||
},
|
||||
"funding": [
|
||||
{
|
||||
"url": "https://github.com/sebastianbergmann",
|
||||
"type": "github"
|
||||
},
|
||||
{
|
||||
"url": "https://liberapay.com/sebastianbergmann",
|
||||
"type": "liberapay"
|
||||
},
|
||||
{
|
||||
"url": "https://thanks.dev/u/gh/sebastianbergmann",
|
||||
"type": "thanks_dev"
|
||||
},
|
||||
{
|
||||
"url": "https://tidelift.com/funding/github/packagist/sebastian/comparator",
|
||||
"type": "tidelift"
|
||||
}
|
||||
],
|
||||
"time": "2025-03-07T07:00:32+00:00"
|
||||
"time": "2025-06-17T07:41:58+00:00"
|
||||
},
|
||||
{
|
||||
"name": "sebastian/complexity",
|
||||
@ -1621,4 +1633,4 @@
|
||||
},
|
||||
"platform-dev": {},
|
||||
"plugin-api-version": "2.6.0"
|
||||
}
|
||||
}
|
||||
|
||||
29
sources/attributes/GetOnly.php
Normal file
29
sources/attributes/GetOnly.php
Normal file
@ -0,0 +1,29 @@
|
||||
<?php
|
||||
/**
|
||||
* Отключаю несущественные инспекции (из-за Attribute)
|
||||
*
|
||||
* @noinspection PhpMultipleClassDeclarationsInspection
|
||||
*/
|
||||
|
||||
namespace goodboyalex\php_components_pack\attributes;
|
||||
|
||||
use Attribute;
|
||||
|
||||
/**
|
||||
* Атрибут указания, что параметр является параметром только для чтения и не подлежит маппингу.
|
||||
*
|
||||
* @author Александр Бабаев
|
||||
* @package php_components_pack
|
||||
* @version 1.0
|
||||
* @since 1.0.25
|
||||
*/
|
||||
#[Attribute(flags: Attribute::TARGET_PROPERTY)]
|
||||
final readonly class GetOnly
|
||||
{
|
||||
/**
|
||||
* Конструктор
|
||||
*/
|
||||
public function __construct ()
|
||||
{
|
||||
}
|
||||
}
|
||||
@ -5,8 +5,10 @@ namespace goodboyalex\php_components_pack\classes;
|
||||
use DateTimeImmutable;
|
||||
use DateTimeInterface;
|
||||
use Exception;
|
||||
use goodboyalex\php_components_pack\attributes\GetOnly;
|
||||
use ReflectionClass;
|
||||
use ReflectionException;
|
||||
use ReflectionProperty;
|
||||
use stdClass;
|
||||
use UnitEnum;
|
||||
|
||||
@ -15,7 +17,7 @@ use UnitEnum;
|
||||
*
|
||||
* @author Александр Бабаев
|
||||
* @package php_components_pack
|
||||
* @version 1.0
|
||||
* @version 1.0.1
|
||||
* @since 1.0
|
||||
*/
|
||||
final class ClassMapper
|
||||
@ -59,6 +61,11 @@ final class ClassMapper
|
||||
// -- пропускаю
|
||||
continue;
|
||||
|
||||
// - если свойство маркируется как GetOnly
|
||||
if (self::HasGetOnlyAttributes($from, $name))
|
||||
// -- пропускаю
|
||||
continue;
|
||||
|
||||
// - если свойство не разрешено
|
||||
if (count($options['allowed']) > 0 && !in_array($name, $options['allowed']))
|
||||
// -- пропускаю
|
||||
@ -71,6 +78,32 @@ final class ClassMapper
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Проверяет, есть ли у свойства класса $class атрибуты GetOnly.
|
||||
*
|
||||
* @param object $class Объект класса.
|
||||
* @param string $propertyName Имя свойства.
|
||||
*
|
||||
* @return bool true если у свойства есть атрибут GetOnly, иначе false.
|
||||
*/
|
||||
private static function HasGetOnlyAttributes (object $class, string $propertyName): bool
|
||||
{
|
||||
// Создаем отражение свойства класса
|
||||
try {
|
||||
$reflectionProperty = new ReflectionProperty(get_class($class), $propertyName);
|
||||
}
|
||||
catch (ReflectionException) {
|
||||
// - возвращаю false, если произошла ошибка создания отражения свойства класса
|
||||
return false;
|
||||
}
|
||||
|
||||
// Получаем список атрибутов у данного свойства
|
||||
$attributes = $reflectionProperty->getAttributes(GetOnly::class);
|
||||
|
||||
// Возвращаем true, если атрибут найден, иначе false
|
||||
return !empty($attributes);
|
||||
}
|
||||
|
||||
/**
|
||||
* Подготавливает значения свойств класса.
|
||||
*
|
||||
|
||||
351
sources/classes/File.php
Normal file
351
sources/classes/File.php
Normal file
@ -0,0 +1,351 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_components_pack\classes;
|
||||
|
||||
use Exception;
|
||||
use RecursiveDirectoryIterator;
|
||||
use RecursiveIteratorIterator;
|
||||
|
||||
/**
|
||||
* Класс, реализующий функционал работы с файлами и выполнение операций над файлами одной командой.
|
||||
*
|
||||
* @author Александр Бабаев
|
||||
* @package php_components_pack
|
||||
* @version 1.0.2
|
||||
* @since 1.0.21
|
||||
*/
|
||||
final class File
|
||||
{
|
||||
/**
|
||||
* @var array Массив сообщений об ошибках при удалении директории.
|
||||
*/
|
||||
public const array REMOVE_DIRECTORY_ERROR_MESSAGES = [
|
||||
'directory_not_exist' => "Директория не существует или нет доступа на запись!",
|
||||
'error_deleting_file_or_link' => 'Ошибка удаления файла или ссылки: %s!',
|
||||
'error_deleting_directory' => 'Ошибка удаления каталога: %s. Код возврата: %d!',
|
||||
'unhandled_error' => 'Ошибка удаления директории %s: %s!'
|
||||
];
|
||||
|
||||
/**
|
||||
* @var array Массив сообщений об ошибках при получении размера файла.
|
||||
*/
|
||||
public const array FILE_SIZE_ERROR_MESSAGES = [
|
||||
'file_not_exist' => 'Файл не существует!',
|
||||
'not_a_file' => 'Указанный путь не является файлом!',
|
||||
'cannot_get_size' => 'Не удалось получить размер файла!'
|
||||
];
|
||||
|
||||
/**
|
||||
* @var array Массив локализации размеров файлов.
|
||||
*/
|
||||
public const array FILE_SIZE_UNITS = ['байт', 'КБ', 'МБ', 'ГБ', 'ТБ'];
|
||||
|
||||
/**
|
||||
* Получает список файлов в директории и поддиректориях, соответствующей шаблону $pattern.
|
||||
*
|
||||
* @param string $dir Родительская директория
|
||||
* @param string $pattern Шаблон имени файла
|
||||
*
|
||||
* @return false|array Список файлов или false в случае ошибки
|
||||
*/
|
||||
public static function FindFiles (string $dir, string $pattern = '*.php'): false|array
|
||||
{
|
||||
// Получаем список файлов и каталогов в текущей директории
|
||||
$files = glob("$dir/$pattern");
|
||||
|
||||
// Если произошла ошибка
|
||||
if ($files === false)
|
||||
// - то возвращаем false
|
||||
return false;
|
||||
|
||||
// Перебираем поддиректории
|
||||
foreach (glob("$dir/*", GLOB_ONLYDIR | GLOB_NOSORT) as $subDir) {
|
||||
// - если ошибка
|
||||
if ($subDir === false)
|
||||
// - то пропускаем
|
||||
continue;
|
||||
|
||||
// - рекурсивный вызов для каждой поддиректории
|
||||
$files = array_merge($files, self::FindFiles($subDir, $pattern));
|
||||
}
|
||||
|
||||
// Возвращаем список файлов
|
||||
return $files;
|
||||
}
|
||||
|
||||
/**
|
||||
* Получает имя файла без пути к нему и расширения.
|
||||
*
|
||||
* @param string $fileName Полное имя файла с путем к нему.
|
||||
*
|
||||
* @return string Имя файла без пути к нему и расширения.
|
||||
*/
|
||||
public static function ExtractFileNameWithoutExtension (string $fileName): string
|
||||
{
|
||||
// Имя файла без пути к нему
|
||||
$fileNameOnly = self::ExtractFileName($fileName);
|
||||
|
||||
// Расширение файла
|
||||
$fileExtension = self::ExtractFileExtension($fileName);
|
||||
|
||||
// Возвращаем имя файла без пути к нему и расширения.
|
||||
return substr($fileNameOnly, 0, -strlen($fileExtension) - 1);
|
||||
}
|
||||
|
||||
/**
|
||||
* Получает имя файла без пути к нему, но с расширением.
|
||||
*
|
||||
* @param string $fileName Полное имя файла с путем к нему.
|
||||
*
|
||||
* @return string Имя файла без пути к нему, но с расширением.
|
||||
*/
|
||||
public static function ExtractFileName (string $fileName): string
|
||||
{
|
||||
return basename($fileName);
|
||||
}
|
||||
|
||||
/**
|
||||
* Получает расширение файла.
|
||||
*
|
||||
* @param string $fileName Имя файла с путем к нему.
|
||||
*
|
||||
* @return string Расширение файла.
|
||||
*/
|
||||
public static function ExtractFileExtension (string $fileName): string
|
||||
{
|
||||
|
||||
return pathinfo($fileName, PATHINFO_EXTENSION);
|
||||
}
|
||||
|
||||
/**
|
||||
* Получает относительный путь к файлу, относительно заданной папки
|
||||
*
|
||||
* @param string $fullPath Полный путь к файлу
|
||||
* @param string $basePath Вырезаемый путь (с начала)
|
||||
*
|
||||
* @return false|string Относительный путь к файлу
|
||||
*/
|
||||
public static function GetRelativePath (string $fullPath, string $basePath): false|string
|
||||
{
|
||||
return stripos($fullPath, $basePath) !== false ? str_replace($basePath, "", $fullPath) : false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Удаляет директорию вместе со всеми файлами и поддиректориями.
|
||||
*
|
||||
* @param string $directory Полный путь к директории.
|
||||
* @param array $errorMessages Сообщения об ошибках удаления (по умолчанию, см.
|
||||
* {@link REMOVE_DIRECTORY_ERROR_MESSAGES}).
|
||||
*
|
||||
* @return ActionState Результат удаления.
|
||||
*/
|
||||
public static function RemoveDir (string $directory,
|
||||
array $errorMessages = self::REMOVE_DIRECTORY_ERROR_MESSAGES): ActionState
|
||||
{
|
||||
// Создаю результат
|
||||
$result = new ActionState(false);
|
||||
|
||||
try {
|
||||
// Проверяем наличие директории и доступ на запись
|
||||
if (!self::DirectoryExists(directory: $directory, checkWriteAccess: true)) {
|
||||
// - если нет, то добавляем ошибку
|
||||
$result->AddError($errorMessages['directory_not_exist']);
|
||||
|
||||
// - и возвращаем результат
|
||||
return $result;
|
||||
}
|
||||
|
||||
// Создаем рекурсивный итерационный объект для перебора всего дерева каталогов
|
||||
$iterator = new RecursiveIteratorIterator(
|
||||
new RecursiveDirectoryIterator($directory),
|
||||
RecursiveIteratorIterator::CHILD_FIRST
|
||||
);
|
||||
|
||||
// Проходим по каждому элементу (каталогам и файлам)
|
||||
foreach ($iterator as $item) {
|
||||
// - получаем путь к файлу
|
||||
$realPath = $item->getRealPath();
|
||||
|
||||
// - если это файл или ссылка
|
||||
if ($item->isFile() || $item->isLink())
|
||||
// -- то удаляем его
|
||||
if (!@unlink($realPath)) {
|
||||
// --- если не удалось удалить, то добавляем ошибку
|
||||
$result->AddError(sprintf($errorMessages['error_deleting_file_or_link'], $realPath));
|
||||
|
||||
// --- и возвращаем результат
|
||||
return $result;
|
||||
}
|
||||
}
|
||||
|
||||
// Определение текущей операционной системы
|
||||
$os = strtolower(PHP_OS_FAMILY);
|
||||
|
||||
// Экранируем аргумент для предотвращения инъекций
|
||||
$escapedDirectory = escapeshellarg($directory);
|
||||
|
||||
// Дальнейшие действия зависят от операционной системы
|
||||
switch ($os) {
|
||||
// - для Windows
|
||||
case 'windows':
|
||||
// -- выполняем команду Windows
|
||||
exec("rd /s /q $escapedDirectory", $output, $returnCode);
|
||||
break;
|
||||
|
||||
// - для Linux/macOS
|
||||
default:
|
||||
// -- выполняем команду Linux/macOS
|
||||
exec("rm -rf $escapedDirectory", $output, $returnCode);
|
||||
break;
|
||||
}
|
||||
|
||||
// Проверяем код возврата
|
||||
if ($returnCode !== 0) {
|
||||
// - если не удалось удалить, то добавляем ошибку
|
||||
$result->AddError(sprintf($errorMessages['error_deleting_directory'], $directory, $returnCode));
|
||||
|
||||
// --- и возвращаем результат
|
||||
return $result;
|
||||
}
|
||||
|
||||
// Если все прошло успешно (а если мы сюда попали, то все должно быть хорошо), то добавляем результат true
|
||||
$result->Value = true;
|
||||
|
||||
// - и возвращаем его
|
||||
return $result;
|
||||
}
|
||||
catch (Exception $exception) {
|
||||
// Если произошла ошибка, то добавляем ошибку
|
||||
$result->AddError(sprintf($errorMessages['unhandled_error'], $directory, $exception->getMessage()));
|
||||
|
||||
// - задаем результат false
|
||||
$result->Value = false;
|
||||
|
||||
// - и возвращаем его
|
||||
return $result;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Проверяет, существует ли директория.
|
||||
*
|
||||
* @param string $directory Путь к директории.
|
||||
* @param bool $checkReadAccess Проверять ли доступ на чтение директории (по умолчанию true).
|
||||
* @param bool $checkWriteAccess Проверять ли доступ на запись директории (по умолчанию false).
|
||||
*
|
||||
* @return bool Результат проверки.
|
||||
*/
|
||||
public static function DirectoryExists (string $directory, bool $checkReadAccess = true,
|
||||
bool $checkWriteAccess = false): bool
|
||||
{
|
||||
// Очищаем кэш
|
||||
clearstatcache();
|
||||
|
||||
// Проверяем, существует ли директория
|
||||
if (!file_exists($directory))
|
||||
// - если нет, то возвращаем false
|
||||
return false;
|
||||
|
||||
// Проверяем, является ли директория директорией, а не файлом
|
||||
if (!is_dir($directory))
|
||||
// - если нет, то возвращаем false
|
||||
return false;
|
||||
|
||||
// Проверяем, есть ли доступ на чтение директории
|
||||
if ($checkReadAccess && !is_readable($directory))
|
||||
// - если нет, то возвращаем false
|
||||
return false;
|
||||
|
||||
// Проверяем, есть ли доступ на запись директории
|
||||
if ($checkWriteAccess && !is_writable($directory))
|
||||
// - если нет, то возвращаем false
|
||||
return false;
|
||||
|
||||
// Если все проверки пройдены успешно, то возвращаем true
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Получает размер файла в байтах.
|
||||
*
|
||||
* @param string $filename Имя файла.
|
||||
* @param array $errorLocalization Массив сообщений об ошибках при получении размера файла (по умолчанию, см.
|
||||
* {@link FILE_SIZE_ERROR_MESSAGES}).
|
||||
*
|
||||
* @return ActionState Результат с размером файла в байтах.
|
||||
*/
|
||||
public static function FileSize (string $filename,
|
||||
array $errorLocalization = self::FILE_SIZE_ERROR_MESSAGES): ActionState
|
||||
{
|
||||
// Очищаем кэш
|
||||
clearstatcache();
|
||||
|
||||
// Создаём результат
|
||||
$result = new ActionState(-1);
|
||||
|
||||
// Проверяем, существует ли файл
|
||||
if (!file_exists($filename)) {
|
||||
// - если нет, то добавляем ошибку
|
||||
$result->AddError($errorLocalization['file_not_exist']);
|
||||
// - и возвращаем результат
|
||||
return $result;
|
||||
}
|
||||
|
||||
// Проверяем, является ли $filename файлом
|
||||
if (!is_file($filename)) {
|
||||
// - если нет, то добавляем ошибку
|
||||
$result->AddError($errorLocalization['not_a_file']);
|
||||
// - и возвращаем результат
|
||||
return $result;
|
||||
}
|
||||
|
||||
// Получаем размер файла
|
||||
$size = filesize($filename);
|
||||
|
||||
// Проверяем, получилось ли получить размер файла
|
||||
if ($size === false) {
|
||||
// - если нет, то добавляем ошибку
|
||||
$result->AddError($errorLocalization['cannot_get_size']);
|
||||
// - и возвращаем результат
|
||||
return $result;
|
||||
}
|
||||
|
||||
// Устанавливаем значение результата
|
||||
$result->Value = $size;
|
||||
|
||||
// Возвращаем результат
|
||||
return $result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Преобразует размер файла в байтах в красивое строковое представление.
|
||||
*
|
||||
* @param int $fileSize Размер файла в байтах.
|
||||
* @param array $fileSizeUnits Локализованные единицы измерения размера файла (по умолчанию, см.
|
||||
* {@link FILE_SIZE_UNITS}).
|
||||
* @param string $decimalSeparator Разделитель десятичной части (по умолчанию, запятая).
|
||||
*
|
||||
* @return string Размер файла в красивом строковом представлении. Например, если размер файла составляет 1500
|
||||
* байт, вывод будет «1.46 КБ».
|
||||
*/
|
||||
public static function FileSizeToString (int $fileSize, array $fileSizeUnits = self::FILE_SIZE_UNITS,
|
||||
string $decimalSeparator = ','): string
|
||||
{
|
||||
/**
|
||||
* Вычисление степени для преобразования: берём минимум из 4 и результата округления до ближайшего целого числа
|
||||
* в меньшую сторону логарифма размера файла в байтах по основанию 1024 (это показывает, сколько раз нужно
|
||||
* разделить размер файла на 1024, чтобы получить значение в более крупных единицах измерения). Ограничение в 4
|
||||
* необходимо для того, чтобы соответствовать единице измерения ТБ (терабайт).
|
||||
*/
|
||||
$power = min(4, floor(log($fileSize, 1024)));
|
||||
|
||||
/**
|
||||
* Преобразование размера файла: размер файла делим на 1024 в степени, равной степени $power,
|
||||
* затем округляем полученное до 2 цифр после запятой.
|
||||
*/
|
||||
$size = number_format(round($fileSize / pow(1024, $power), 2), 2, $decimalSeparator);
|
||||
|
||||
// Возвращаем преобразованное значение вместе с единицей измерения
|
||||
return "$size $fileSizeUnits[$power]";
|
||||
}
|
||||
}
|
||||
710
sources/classes/JsonReWriter.md
Normal file
710
sources/classes/JsonReWriter.md
Normal file
@ -0,0 +1,710 @@
|
||||
# Описание класса JsonReWriter
|
||||
|
||||
## Информация о версии
|
||||
|
||||
Версия класса: 1.0
|
||||
|
||||
Впервые введено в пакет с версии: 1.1.0
|
||||
|
||||
Описание класса: Класс для работы с JSON-файлами.
|
||||
|
||||
## Публичные свойства и константы класса
|
||||
|
||||
В классе определены следующие свойства:
|
||||
|
||||
- `string $JsonString` - строка JSON (чтение/запись).
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
### Правила формирования ключей.
|
||||
|
||||
Ключ для чтения/записи данных класса формируется следующим образом: `ключ/подключ/подключ подключа` .
|
||||
|
||||
Например, если дан json-файл:
|
||||
|
||||
{
|
||||
"test": {
|
||||
"subtest": {
|
||||
"AAA": "123",
|
||||
"BBB": 1.23
|
||||
}
|
||||
},
|
||||
"test1": {
|
||||
"test": 123
|
||||
},
|
||||
"test2": {
|
||||
"test": true
|
||||
},
|
||||
"test3": {
|
||||
"test": {
|
||||
"res": "[1,2,3]"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Пусть требуется получить значение `BBB`, тогда ключ должен быть `test/subtest/BBB`.
|
||||
|
||||
### Чтение.
|
||||
|
||||
1. Создайте элемент класса `$json = new JsonReWriter ();`
|
||||
2. Если у вас требуется загрузить json из файла `$fileName`, то воспользуйтесь методом `LoadFromFile`:
|
||||
`$json->LoadFromFile($fileName);`, если же json представлен строкой `$jsonStr`, то загрузите её в свойство
|
||||
`$JsonString`: `$json->JsonString = $jsonStr;`
|
||||
3. Далее можно пользоваться любым методом для чтения `Read*`, в том числе и общим `$json->Read(...)`.
|
||||
|
||||
**Пример:**
|
||||
|
||||
// Имя файла
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
// Создаю класс
|
||||
$json = new JsonReWriter();
|
||||
// Загшружаю данные из файла
|
||||
$json->LoadFromFile($fileName);
|
||||
// Получаю число
|
||||
$float = $json->ReadFloat("test/subtest/BBB", 0.2);
|
||||
|
||||
В итоге в `$float` будет `1.23`.
|
||||
|
||||
### Запись.
|
||||
|
||||
1. Создайте элемент класса `$json = new JsonReWriter ();`
|
||||
2. Далее можно пользоваться любым методом для записи `Write*`, в том числе и общим `$json->Write(...)`.
|
||||
3. Если вам требуется создать json файл с именем `$fileName`, то воспользуйтесь методом `SaveToFile`:
|
||||
`$json->SaveToFile($fileName);`, если же json должен быть представлен строкой `$jsonStr`, то загрузите её из свойства
|
||||
`$JsonString`: `$jsonStr = $json->JsonString;`
|
||||
|
||||
**Пример:**
|
||||
|
||||
// Имя файла
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
// Создаю класс
|
||||
$json = new JsonReWriter();
|
||||
// Загшружаю данные из файла
|
||||
$json->LoadFromFile($fileName);
|
||||
// Получаю число
|
||||
try {
|
||||
$json->Write("test/subtest/BBB", 0.2);
|
||||
}
|
||||
catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
В итоге в `test/subtest/BBB` вместо `1.23` будет `0.2`.
|
||||
|
||||
## Коды ошибок JsonErrorCode
|
||||
|
||||
Ниже представлена таблица основных кодов ошибки:
|
||||
|
||||
| Ошибка | Описание | Введено с версии |
|
||||
|:-------------------:|:---------------------------------------------------------------------------:|:----------------:|
|
||||
| Unknown | Неизвестная ошибка | 1.0 |
|
||||
| None | Ошибок нет | 1.0 |
|
||||
| Depth | Достигнута максимальная глубина стека | 1.0 |
|
||||
| StateMismatch | Неверный или некорректный JSON | 1.0 |
|
||||
| CTRLChar | Ошибка управляющего символа, возможно, неверная кодировка | 1.0 |
|
||||
| Syntax | Синтаксическая ошибка | 1.0 |
|
||||
| UTF8 | Некорректные для кодировки UTF-8 символы, возможно, неверная кодировка | 1.0 |
|
||||
| Recursion | Одна или несколько зацикленных ссылок в кодируемом значении | 1.0 |
|
||||
| InfOrNan | Одно или несколько значений NAN или INF в кодируемом значении | 1.0 |
|
||||
| UnsupportedType | Передали значение с неподдерживаемым типом | 1.0 |
|
||||
| InvalidPropertyName | Имя свойства не может быть закодировано | 1.0 |
|
||||
| UTF16 | Некорректный для кодировки UTF-16 символ, возможно, некорректно закодирован | 1.0 |
|
||||
| KeyIsNotArray | Ключ не содержит вложений, хотя от него требуется обратное | 1.0 |
|
||||
| NotISerializable | Класс не реализует интерфейс ISerializable | 1.0 |
|
||||
|
||||
### Методы и функции перечисления JsonErrorCode
|
||||
|
||||
Перечисление содержит **статический метод** `static function FromLastError (): JsonErrorCode`, который получает код
|
||||
ошибки из последней JSON ошибки.
|
||||
|
||||
Например, при успешной загрузке, можем проверить ошибки:
|
||||
|
||||
$errors = JsonErrorCode::FromLastError ();
|
||||
|
||||
После того, как мы выведем `$errors`, мы получим `JsonErrorCode::None`.
|
||||
|
||||
## Исключение JsonException
|
||||
|
||||
Исключение расширяет класс `Exception`, поэтому может выбрасываться через `throw`.
|
||||
|
||||
### Свойства
|
||||
|
||||
Исключение содержит следующие свойства:
|
||||
|
||||
- `?string $JsonString` - строка JSON (или null);
|
||||
- `JsonErrorCode $ErrorCode` - код ошибки JSON;
|
||||
- `?string $ErrorMessage` - сообщение об ошибке JSON (в отличие от функции json_last_error_msg(), данная переменная при
|
||||
отсутствии ошибок выводит null, а не "No error").
|
||||
|
||||
### Методы и функции
|
||||
|
||||
#### Конструктор.
|
||||
|
||||
Конструктор принимает **3 необязательных параметра**:
|
||||
|
||||
* `?string $json` - строка JSON (по умолчанию, `null`);
|
||||
* `JsonErrorCode $errorCode` - код ошибки (по умолчанию, `JsonErrorCode::Unknown`);
|
||||
* `?string $errorMessage` - сообщение об ошибке (по умолчанию, `null`).
|
||||
|
||||
В результате создаётся новое исключение `JsonException`.
|
||||
|
||||
Пример:
|
||||
|
||||
throw new JsonException("{}", JsonErrorCode::Depth, "Пример");
|
||||
|
||||
Создаст исключение `JsonException`.
|
||||
|
||||
## Методы и функции
|
||||
|
||||
### Конструктор и деструктор.
|
||||
|
||||
Конструктор не принимает никаких параметров.
|
||||
|
||||
В результате создаётся новый класс `JsonReWriter`.
|
||||
|
||||
**Пример:**
|
||||
|
||||
// Контсуктор
|
||||
$json = new JsonReWriter ();
|
||||
// Деструктор
|
||||
unset($json);
|
||||
|
||||
Создаст и уничтожит класс `JsonReWriter`.
|
||||
|
||||
### Сохранение и загрузка из файла.
|
||||
|
||||
За сохранение и загрузку отвечают 2 метода: `SaveToFile` и `LoadFromFile`.
|
||||
|
||||
#### Сохранение в файл (метод `SaveToFile`)
|
||||
|
||||
Этот метод сохраняет содержимое JSON в файл. Он содержит **1 обязательный параметр**:
|
||||
|
||||
* `string $fileName` - имя файла на диске.
|
||||
|
||||
Метод возвращает `bool` - сохранены ли данные в файл: `true` - да, `false` - нет.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function SaveToFile (string $fileName): bool
|
||||
|
||||
**Пример:**
|
||||
|
||||
// Имя файла
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
// Сохраняем созданный JSON файл
|
||||
$json->SaveToFile($fileName);
|
||||
|
||||
Содержимое файла `test.json` представлено далее:
|
||||
|
||||
{
|
||||
"test": {
|
||||
"subtest": {
|
||||
"AAA": "123",
|
||||
"BBB": 1.23
|
||||
}
|
||||
},
|
||||
"test1": {
|
||||
"test": 123
|
||||
},
|
||||
"test2": {
|
||||
"test": true
|
||||
},
|
||||
"test3": {
|
||||
"test": {
|
||||
"res": "[1,2,3]"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#### Загрузка файла (метод `LoadFromFile`)
|
||||
|
||||
Этот метод загружает содержимое файла в класс. Он содержит **1 обязательный параметр**:
|
||||
|
||||
* `string $fileName` - имя файла на диске.
|
||||
|
||||
Метод возвращает `bool` - загружены ли данные из файла: `true` - да, `false` - нет.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function LoadFromFile (string $fileName): bool
|
||||
|
||||
**Пример:**
|
||||
Пусть дан файл `test.json`, содержимое которого представлено далее:
|
||||
|
||||
{
|
||||
"test": {
|
||||
"subtest": {
|
||||
"AAA": "123",
|
||||
"BBB": 1.23
|
||||
}
|
||||
},
|
||||
"test1": {
|
||||
"test": 123
|
||||
},
|
||||
"test2": {
|
||||
"test": true
|
||||
},
|
||||
"test3": {
|
||||
"test": {
|
||||
"res": "[1,2,3]"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Следующий код загрузит это содержимое в класс:
|
||||
|
||||
// Имя файла
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Загружаю данные
|
||||
$json->LoadFromFile($fileName);
|
||||
|
||||
### Чтение данных
|
||||
|
||||
Для чтения данных используется один общий метод `Read` и 7 его производных метода: `ReadString`, `ReadInt`, `ReadFloat`,
|
||||
`ReadBool`, `ReadArray`, `ReadObject` и `ReadSerializable`.
|
||||
|
||||
#### Метод `Read`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **1 обязательный параметр** `string $key` (ключ) и **1
|
||||
необязательный параметр** `mixed $default` (значение по умолчанию, задан по умолчанию в `null`).
|
||||
|
||||
Этот метод возвращает `mixed`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function Read (string $key, mixed $default = null): mixed
|
||||
|
||||
**Пример,**
|
||||
|
||||
// Создаю класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполняю данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->Write("test3/test/res", json_encode([1, 2, 3]));
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
// Получаю значение
|
||||
$float = (float)$json->Read("test/subtest/BBB"));
|
||||
|
||||
В результате, переменная `$float` будет иметь значение `1.23`.
|
||||
|
||||
#### Метод `ReadString`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **1 обязательный параметр** `string $key` (ключ) и **1
|
||||
необязательный параметр** `string $default` (значение по умолчанию, задан по умолчанию в `""`).
|
||||
|
||||
Этот метод возвращает `string`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadString (string $key, string $default = ""): string
|
||||
|
||||
#### Метод `ReadInt`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **1 обязательный параметр** `string $key` (ключ) и **1
|
||||
необязательный параметр** `int $default` (значение по умолчанию, задан по умолчанию в `0`).
|
||||
|
||||
Этот метод возвращает `int`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadInt (string $key, int $default = 0): int
|
||||
|
||||
#### Метод `ReadFloat`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **1 обязательный параметр** `string $key` (ключ) и **1
|
||||
необязательный параметр** `float $default` (значение по умолчанию, задан по умолчанию в `0.0`).
|
||||
|
||||
Этот метод возвращает `float`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadFloat (string $key, float $default = 0.0): float
|
||||
|
||||
#### Метод `ReadBool`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **1 обязательный параметр** `string $key` (ключ) и **1
|
||||
необязательный параметр** `bool $default` (значение по умолчанию, задан по умолчанию в `false`).
|
||||
|
||||
Этот метод возвращает `bool`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadBool (string $key, bool $default = false): bool
|
||||
|
||||
#### Метод `ReadArray`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **1 обязательный параметр** `string $key` (ключ) и **1
|
||||
необязательный параметр** `array $default` (значение по умолчанию, задан по умолчанию в `[]`).
|
||||
|
||||
Этот метод возвращает `array`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadArray (string $key, array $default = []): array
|
||||
|
||||
#### Метод `ReadObject`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **2 обязательных параметра**:
|
||||
|
||||
- `string $key` (ключ);
|
||||
- `object $default` (значение по умолчанию).
|
||||
|
||||
Этот метод возвращает `object`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadObject (string $key, object $default): object
|
||||
|
||||
#### Метод `ReadSerializable`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **2 обязательных параметра**:
|
||||
|
||||
- `string $key` (ключ);
|
||||
- `string $serializableClassName` (имя класса, реализующего интерфейс ISerializable, с namespace).
|
||||
|
||||
Этот метод возвращает класс, реализующий интерфейс `ISerializable`.
|
||||
|
||||
**Важно!** Этот метод может выбросить исключение `JsonException`, если класс, заданный в `$serializableClassName` не
|
||||
реализует интерфейс `ISerializable`.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadSerializable (string $key, string $serializableClassName): ISerializable
|
||||
|
||||
**Пример,**
|
||||
|
||||
Пусть для примера, класс `Demo` из namespace `iam\namespace` реализует интерфейс `ISerializable`.
|
||||
|
||||
// Создаю класс
|
||||
$json = new JsonReWriter();
|
||||
// ... Здесь где-то загрузка данных
|
||||
// Получаю класс
|
||||
try {
|
||||
/**
|
||||
* @var Demo $unSerializableClass
|
||||
*/
|
||||
$unSerializableClass = $json->ReadSerializable("test", "iam\\namespace\\Demo");
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
В результате, переменная `$unSerializableClass` будет содержать данные класса `Demo`.
|
||||
|
||||
### Запись данных
|
||||
|
||||
Для чтения данных используется один общий метод `Write` и 3 его производных метода: `WriteArray`, `WriteObject` и
|
||||
`WriteSerializable`.
|
||||
|
||||
**Важно!** Лобой из вышеуказанных методов может выбросить исключение `JsonException`, если ключ не содержит вложений,
|
||||
хотя от него требуется обратное.
|
||||
|
||||
#### Метод `Write`
|
||||
|
||||
Это метод, который записывает значение в ключ JSON. Он имеет **2 обязательных параметра**:
|
||||
|
||||
- `string $key` (ключ);
|
||||
- `mixed $value` (записываемое значение).
|
||||
|
||||
Этот метод ничего не возвращает.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function Write (string $key, mixed $value): void
|
||||
|
||||
**Пример,**
|
||||
|
||||
// Имя файла
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
// Сохраняем созданный JSON файл
|
||||
$json->SaveToFile($fileName);
|
||||
|
||||
Содержимое файла `test.json` представлено далее:
|
||||
|
||||
{
|
||||
"test": {
|
||||
"subtest": {
|
||||
"AAA": "123",
|
||||
"BBB": 1.23
|
||||
}
|
||||
},
|
||||
"test1": {
|
||||
"test": 123
|
||||
},
|
||||
"test2": {
|
||||
"test": true
|
||||
},
|
||||
"test3": {
|
||||
"test": {
|
||||
"res": "[1,2,3]"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#### Метод `WriteArray`
|
||||
|
||||
Это метод, который записывает значение в ключ JSON. Он имеет **2 обязательных параметра**:
|
||||
|
||||
- `string $key` (ключ);
|
||||
- `array $array` (записываемое значение).
|
||||
|
||||
Этот метод ничего не возвращает.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function WriteArray (string $key, array $array): void
|
||||
|
||||
#### Метод `WriteObject`
|
||||
|
||||
Это метод, который записывает значение в ключ JSON. Он имеет **2 обязательных параметра**:
|
||||
|
||||
- `string $key` (ключ);
|
||||
- `object $value` (записываемое значение).
|
||||
|
||||
Этот метод ничего не возвращает.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function WriteObject (string $key, object $value): void
|
||||
|
||||
#### Метод `WriteSerializable`
|
||||
|
||||
Это метод, который записывает значение в ключ JSON. Он имеет **2 обязательных параметра**:
|
||||
|
||||
- `string $key` (ключ);
|
||||
- `ISerializable $serializableValue` (записываемое значение).
|
||||
|
||||
Этот метод ничего не возвращает.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function WriteSerializable (string $key, ISerializable $serializableValue): void
|
||||
|
||||
**Пример,**
|
||||
Пусть для примера, класс `Demo` из namespace `iam\namespace` реализует интерфейс `ISerializable`.
|
||||
|
||||
// Имя файла
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Создаём класс Demo
|
||||
$serializableClass = new Demo(...);
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->WriteSerializable("test", $serializableClass);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
...
|
||||
|
||||
### Работа с ключами JSON
|
||||
|
||||
Для работы с ключами JSON есть 2 метода: `IsKeyExists` и `GetKeys`.
|
||||
|
||||
#### Метод `IsKeyExists`
|
||||
|
||||
Это метод проверяем наличие ключа в JSON. Он имеет **1 обязательный параметр** - `string $key` (ключ).
|
||||
|
||||
Этот метод возвращает `bool`: `true` если ключ найден и `false` в противном случае.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function IsKeyExists (string $key): bool
|
||||
|
||||
**Пример,**
|
||||
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
// Проверяем ключи
|
||||
$check1 = $json->IsKeyExists("test/subtest/AAA");
|
||||
$check2 = $json->IsKeyExists("test/subtest/ССС");
|
||||
|
||||
В результате, `$check1` будет `true`, а `$check2` - `false`.
|
||||
|
||||
#### Метод `GetKeys`
|
||||
|
||||
Это метод получает список ключей. Он имеет **2 необязательных параметра**:
|
||||
|
||||
- `string $parentKey` (ключ родителя (или "" (установлено по умолчанию) для всех);
|
||||
- `bool $includeChildren` (нужно ли включать дочерние ключи (по умолчанию, да)).
|
||||
|
||||
Этот метод возвращает `array`: список ключей.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function GetKeys (string $parentKey = "", bool $includeChildren = true): array
|
||||
|
||||
**Пример,**
|
||||
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
// Получаем ключи
|
||||
$keys1 = $json->GetKeys("test");
|
||||
$keys2 = $json->GetKeys("test", false);
|
||||
$keys3 = $json->GetKeys();
|
||||
|
||||
В результате, `$key1` будет следующим массивом:
|
||||
|
||||
[
|
||||
"test/subtest",
|
||||
"test/subtest/AAA",
|
||||
"test/subtest/BBB"
|
||||
]
|
||||
|
||||
`$key2` будет следующим массивом:
|
||||
|
||||
[
|
||||
"subtest"
|
||||
]
|
||||
|
||||
`$key3` будет следующим массивом:
|
||||
|
||||
[
|
||||
"test",
|
||||
"test/subtest",
|
||||
"test/subtest/AAA",
|
||||
"test/subtest/BBB",
|
||||
"test1",
|
||||
"test1/test",
|
||||
"test2",
|
||||
"test2/test",
|
||||
"test3",
|
||||
"test3/test",
|
||||
"test3/test/res"
|
||||
]
|
||||
|
||||
### Удаление ключей JSON
|
||||
|
||||
Для удаления ключей JSON есть 2 метода: `DeleteKey`, который удаляет только определённый ключ и `Clear`, который удаляет
|
||||
**все ключи** из json-файла.
|
||||
|
||||
#### Метод `DeleteKey`
|
||||
|
||||
Это метод удаляет только определённый ключ в JSON. Он имеет **1 обязательный параметр** - `string $key` (ключ).
|
||||
|
||||
Этот метод возвращает `bool` - результат удаления ключа: `true` - удаление прошло успешно, `false` - произошла ошибка
|
||||
при удалении.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function DeleteKey (string $key): bool
|
||||
|
||||
**Пример,**
|
||||
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
// Получаемем ключи до удаления
|
||||
$check1 = $json->GetKeys("test/subtest");
|
||||
// Удаляем ключ
|
||||
$this->DeleteKey("test/subtest/BBB");
|
||||
// Получаемем ключи после удаления
|
||||
$check2 = $json->GetKeys("test/subtest");
|
||||
|
||||
В результате, `$check1` будет
|
||||
|
||||
[
|
||||
"test/subtest",
|
||||
"test/subtest/AAA",
|
||||
"test/subtest/BBB"
|
||||
]
|
||||
|
||||
а `$check2`:
|
||||
|
||||
[
|
||||
"test/subtest",
|
||||
"test/subtest/AAA"
|
||||
]
|
||||
|
||||
#### Метод `Clear`
|
||||
|
||||
Это метод удаляет **все ключи** из json-файла. Он не имеет никаких параметров и ничего не возвращает.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function Clear (): void
|
||||
|
||||
**Пример,**
|
||||
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
// Очищаем
|
||||
$json->Clear();
|
||||
// Получаем ключи
|
||||
$keys = $json->GetKeys();
|
||||
|
||||
В результате, `$key` будет следующим массивом:
|
||||
|
||||
[
|
||||
]
|
||||
90
sources/classes/JsonReWriter.php
Normal file
90
sources/classes/JsonReWriter.php
Normal file
@ -0,0 +1,90 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_components_pack\classes;
|
||||
|
||||
use goodboyalex\php_components_pack\enums\JsonErrorCode;
|
||||
use goodboyalex\php_components_pack\exceptions\JsonException;
|
||||
use goodboyalex\php_components_pack\traits\JsonReWriter\JsonReWriterDeleteTrait;
|
||||
use goodboyalex\php_components_pack\traits\JsonReWriter\JsonReWriterKeyTrait;
|
||||
use goodboyalex\php_components_pack\traits\JsonReWriter\JsonReWriterLoadSaveTrait;
|
||||
use goodboyalex\php_components_pack\traits\JsonReWriter\JsonReWriterReadTrait;
|
||||
use goodboyalex\php_components_pack\traits\JsonReWriter\JsonReWriterWriteTrait;
|
||||
|
||||
/**
|
||||
* Класс для работы с JSON-файлами.
|
||||
*
|
||||
* @author Александр Бабаев
|
||||
* @package php_components_pack
|
||||
* @version 1.0
|
||||
* @since 1.1.0
|
||||
*/
|
||||
final class JsonReWriter
|
||||
{
|
||||
/**
|
||||
* @var string $JsonString Строка JSON.
|
||||
*/
|
||||
public string $JsonString {
|
||||
get {
|
||||
// Проверка на пустоту
|
||||
if (count($this->JsonData) === 0)
|
||||
// - если массив пуст, возвращаем пустой JSON
|
||||
return '{}';
|
||||
|
||||
// Преобразую данные в JSON
|
||||
$json = json_encode($this->JsonData, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
|
||||
|
||||
// Проверка на ошибки
|
||||
if (json_last_error() !== JSON_ERROR_NONE)
|
||||
// - если есть ошибки, выбрасываем исключение
|
||||
throw new JsonException(null, JsonErrorCode::FromLastError(), json_last_error_msg());
|
||||
|
||||
// Возвращаем JSON
|
||||
return $json;
|
||||
}
|
||||
set {
|
||||
// Чтение содержимого файла и преобразование JSON в объект
|
||||
$this->JsonData = json_decode($value, true);
|
||||
|
||||
// Проверка на ошибки
|
||||
if ($this->JsonData === null && json_last_error() !== JSON_ERROR_NONE)
|
||||
// - если есть ошибки, выбрасываем исключение
|
||||
throw new JsonException($value, JsonErrorCode::FromLastError(), json_last_error_msg());
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @var array $JsonData Массив данных.
|
||||
*/
|
||||
private array $JsonData;
|
||||
|
||||
/**
|
||||
* Конструктор класса.
|
||||
*/
|
||||
public function __construct ()
|
||||
{
|
||||
$this->JsonData = [];
|
||||
}
|
||||
|
||||
/**
|
||||
* Деструктор класса.
|
||||
*/
|
||||
public function __destruct ()
|
||||
{
|
||||
unset($this->JsonData);
|
||||
}
|
||||
|
||||
// Подключаем методы чтения JSON
|
||||
use JsonReWriterReadTrait;
|
||||
|
||||
// Подключаем методы записи JSON
|
||||
use JsonReWriterWriteTrait;
|
||||
|
||||
// Подключаем методы сохранения и загрузки JSON
|
||||
use JsonReWriterLoadSaveTrait;
|
||||
|
||||
// Подключаем методы работы с ключами
|
||||
use JsonReWriterKeyTrait;
|
||||
|
||||
// Подключаем методы удаления данных из JSON
|
||||
use JsonReWriterDeleteTrait;
|
||||
}
|
||||
419
sources/classes/VersionInfo.md
Normal file
419
sources/classes/VersionInfo.md
Normal file
@ -0,0 +1,419 @@
|
||||
# Описание класса 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
|
||||
391
sources/classes/VersionInfo.php
Normal file
391
sources/classes/VersionInfo.php
Normal file
@ -0,0 +1,391 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_components_pack\classes;
|
||||
|
||||
use goodboyalex\php_components_pack\enums\VersionCompareRangeOption;
|
||||
use goodboyalex\php_components_pack\enums\VersionInfoStage;
|
||||
use goodboyalex\php_components_pack\extensions\StringExtension;
|
||||
|
||||
/**
|
||||
* Класс, описывающий информацию о версии.
|
||||
*
|
||||
* @author Александр Бабаев
|
||||
* @package php_components_pack
|
||||
* @version 1.2
|
||||
* @since 1.0.24
|
||||
*/
|
||||
final class VersionInfo
|
||||
{
|
||||
/**
|
||||
* @var array $StagesNames Имена стадий сборки.
|
||||
*/
|
||||
public const array StagesNames = [
|
||||
VersionInfoStage::PreAlpha->value => 'PreAlpha',
|
||||
VersionInfoStage::Alpha->value => 'Alpha',
|
||||
VersionInfoStage::Beta->value => 'Beta',
|
||||
VersionInfoStage::ReleaseCandidate->value => 'rc',
|
||||
VersionInfoStage::Stable->value => 'Stable'
|
||||
];
|
||||
|
||||
/**
|
||||
* @var string $DefaultTemplate Шаблон вывода по умолчанию.
|
||||
*/
|
||||
public const string DefaultTemplate = '#{Major}.#{Minor}.#{Release}.#{Build} #{Stage} #{StageNumber}';
|
||||
|
||||
/**
|
||||
* @var int $Major Мажорная версия.
|
||||
*/
|
||||
private(set) int $Major = 0;
|
||||
|
||||
/**
|
||||
* @var int $Minor Минорная версия.
|
||||
*/
|
||||
private(set) int $Minor = 0;
|
||||
|
||||
/**
|
||||
* @var int $Release Номер релиза.
|
||||
*/
|
||||
private(set) int $Release = 0;
|
||||
|
||||
/**
|
||||
* @var int $Build Номер сборки.
|
||||
*/
|
||||
private(set) int $Build = 0;
|
||||
|
||||
/**
|
||||
* @var VersionInfoStage $Stage Стадия сборки.
|
||||
*/
|
||||
private(set) VersionInfoStage $Stage = VersionInfoStage::Undefined;
|
||||
|
||||
/**
|
||||
* @var int $StageNumber Номер стадии сборки.
|
||||
*/
|
||||
private(set) int $StageNumber = 0;
|
||||
|
||||
/**
|
||||
* Конструктор.
|
||||
*
|
||||
* @param int $Major Мажорная версия.
|
||||
* @param int $Minor Минорная версия.
|
||||
* @param int $Release Номер релиза.
|
||||
* @param int $Build Номер сборки.
|
||||
* @param VersionInfoStage $Stage Стадия сборки.
|
||||
* @param int $StageNumber Номер стадии сборки.
|
||||
*/
|
||||
public function __construct (int $Major, int $Minor, int $Release, int $Build,
|
||||
VersionInfoStage $Stage = VersionInfoStage::Undefined, int $StageNumber = 0)
|
||||
{
|
||||
$this->Major = $Major;
|
||||
$this->Minor = $Minor;
|
||||
$this->Release = $Release;
|
||||
$this->Build = $Build;
|
||||
$this->Stage = $Stage;
|
||||
$this->StageNumber = $StageNumber;
|
||||
}
|
||||
|
||||
/**
|
||||
* Сравнивает две версии.
|
||||
*
|
||||
* @param VersionInfo $version1 Версия 1.
|
||||
* @param VersionInfo $version2 Версия 2.
|
||||
*
|
||||
* @return int Возвращает 1, если версия 1 больше версии 2, 0, если равны, -1, если версия 1 меньше версии 2.
|
||||
*/
|
||||
public static function Compare (VersionInfo $version1, VersionInfo $version2): int
|
||||
{
|
||||
return $version1->CompareWith($version2);
|
||||
}
|
||||
|
||||
/**
|
||||
* Сравнивает текущую версию с переданной.
|
||||
*
|
||||
* @param VersionInfo $version Переданная версия.
|
||||
*
|
||||
* @return int Возвращает 1, если текущая версия больше переданной, 0, если равны, -1, если текущая версия меньше
|
||||
* переданной.
|
||||
*/
|
||||
public function CompareWith (VersionInfo $version): int
|
||||
{
|
||||
// Задаем шаблон вывода
|
||||
$toStringTemplate = '#{Major}.#{Minor}.#{Release}.#{Build}';
|
||||
|
||||
// Сначала сравним числа (мажорную, минорную версии, номер релиза и сборки):
|
||||
$compareResult = version_compare(
|
||||
$this->ToString($toStringTemplate),
|
||||
$version->ToString($toStringTemplate)
|
||||
);
|
||||
|
||||
// Если численные части совпадают, проверяем стадии сборки
|
||||
if ($compareResult === 0) {
|
||||
// - особый случай: стабильная версия всегда больше любых промежуточных стадий
|
||||
if ($this->Stage === VersionInfoStage::Stable && self::IsNotUndefinedOrStable($version->Stage))
|
||||
// - считаем нашу старшей
|
||||
return 1;
|
||||
|
||||
// - особый случай: если наша версия не stable, а другая stable
|
||||
if ($version->Stage === VersionInfoStage::Stable && self::IsNotUndefinedOrStable($this->Stage))
|
||||
// - считаем нашу младшей
|
||||
return -1;
|
||||
|
||||
// - преобразуем стадии в целые числа для прямого сравнения
|
||||
$currentStageValue = $this->Stage->ToInt();
|
||||
$otherStageValue = $version->Stage->ToInt();
|
||||
|
||||
// - если стадии отличаются
|
||||
if ($currentStageValue !== $otherStageValue)
|
||||
// - сравниваем их
|
||||
return $currentStageValue <=> $otherStageValue;
|
||||
|
||||
// - если стадии одинаковые
|
||||
if (self::IsNotUndefinedOrStable($this->Stage) && self::IsNotUndefinedOrStable($version->Stage)
|
||||
&& $this->StageNumber !== $version->StageNumber)
|
||||
return $this->StageNumber <=> $version->StageNumber;
|
||||
|
||||
// - если все совпадает, то вернём 0
|
||||
return 0;
|
||||
}
|
||||
|
||||
// Возврат результата сравнения
|
||||
return $compareResult;
|
||||
}
|
||||
|
||||
/**
|
||||
* Возвращает строковое представление версии.
|
||||
*
|
||||
* @param string $template Шаблон вывода. В шаблоне маркеры #{Major}, #{Minor}, #{Release}, #{Build}, #{Stage} и
|
||||
* #{StageNumber} заменяются на значения соответствующих свойств. По умолчанию используется
|
||||
* {@link DefaultTemplate}.
|
||||
* @param array $stagesNames Имена стадий сборки (по умолчанию из константы {@link StagesNames}).
|
||||
*
|
||||
* @return string Строковое представление версии.
|
||||
*/
|
||||
public function ToString (string $template = self::DefaultTemplate, array $stagesNames = self::StagesNames): string
|
||||
{
|
||||
// Получаем строковое представление стадии сборки
|
||||
$stage = match ($this->Stage) {
|
||||
// - для неопределенной стадии сборки и релиза возвращаем пустую строку
|
||||
VersionInfoStage::Undefined, VersionInfoStage::Stable => '',
|
||||
|
||||
// - для остальных стадий сборки возвращаем строковое представление стадии сборки
|
||||
VersionInfoStage::PreAlpha => $stagesNames[VersionInfoStage::PreAlpha->value],
|
||||
VersionInfoStage::Alpha => $stagesNames[VersionInfoStage::Alpha->value],
|
||||
VersionInfoStage::Beta => $stagesNames[VersionInfoStage::Beta->value],
|
||||
VersionInfoStage::ReleaseCandidate => $stagesNames[VersionInfoStage::ReleaseCandidate->value]
|
||||
};
|
||||
|
||||
// Возвращаем строковое представление номера стадии сборки, если конечно стадия определена и она не релиз
|
||||
// и номер сборки должен быть задан (больше 0)
|
||||
$stageNum = self::IsNotUndefinedOrStable($this->Stage) && $this->StageNumber > 0
|
||||
? "$this->StageNumber" : '';
|
||||
|
||||
// Создаём массив для замены
|
||||
$replaceData = [
|
||||
'#{Major}' => "$this->Major",
|
||||
'#{Minor}' => "$this->Minor",
|
||||
'#{Release}' => "$this->Release",
|
||||
'#{Build}' => "$this->Build",
|
||||
'#{Stage}' => $stage,
|
||||
'#{StageNumber}' => $stageNum
|
||||
];
|
||||
|
||||
// Заменяем все в шаблоне
|
||||
$result = StringExtension::ReplaceAll($replaceData, $template);
|
||||
|
||||
// Возвращаем результат, удаляя лишние пробелы в конце
|
||||
return rtrim($result, ' ');
|
||||
}
|
||||
|
||||
/**
|
||||
* Проверяет, является ли версия неопределённой или релизом.
|
||||
*
|
||||
* @param VersionInfoStage $versionStage Стадия сборки.
|
||||
*
|
||||
* @return bool Возвращает true, если стадия сборки определена и не является релизом.
|
||||
*/
|
||||
public static function IsNotUndefinedOrStable (VersionInfoStage $versionStage): bool
|
||||
{
|
||||
return $versionStage !== VersionInfoStage::Undefined && $versionStage !== VersionInfoStage::Stable;
|
||||
}
|
||||
|
||||
/**
|
||||
* Преобразует строку с версией в объект {@link VersionInfo}.
|
||||
*
|
||||
* @param string $version Строка с версией (она должна быть в формате {@link DefaultTemplate}).
|
||||
* @param array $stagesNames Имена стадий сборки (по умолчанию из константы {@link StagesNames}).
|
||||
*
|
||||
* @return VersionInfo Возвращает объект {@link VersionInfo} с данными о версии.
|
||||
*/
|
||||
public static function Parse (string $version, array $stagesNames = self::StagesNames): VersionInfo
|
||||
{
|
||||
// Убираем пробелы в начале и конце строки
|
||||
$version = trim($version);
|
||||
|
||||
// Разбиваем строку на части по пробелам (1 часть - основная - мажор, минор, релиз, сборка,
|
||||
// 2 часть - стадия и 3 - номер стадии)
|
||||
$versionParts = explode(' ', $version);
|
||||
|
||||
// Проверяем, что строка содержит хотя бы 1 часть
|
||||
if (count($versionParts) < 1)
|
||||
// - если нет, то возвращаем пустую версию
|
||||
return new VersionInfo(0, 0, 0, 0);
|
||||
|
||||
// Составим регулярное выражение для парсинга базовой информации о версии
|
||||
$pattern = '/^(\d+)\.(\d+)\.(\d+)\.(\d+)/';
|
||||
|
||||
// Парсим базовую информацию о версии
|
||||
if (!preg_match($pattern, $versionParts[0], $matches))
|
||||
// - если не удалось, то возвращаем пустую версию
|
||||
return new VersionInfo(0, 0, 0, 0);
|
||||
|
||||
// Проверяем, что найдены все 4 части
|
||||
if (!$matches || count($matches) < 5)
|
||||
// - если нет, то возвращаем пустую версию
|
||||
return new VersionInfo(0, 0, 0, 0);
|
||||
|
||||
// Получаем значения
|
||||
[, $major, $minor, $release, $build] = $matches;
|
||||
|
||||
// Парсим обязательные цифры
|
||||
// - мажорная версия
|
||||
$major = intval($major);
|
||||
// - минорная версия
|
||||
$minor = intval($minor);
|
||||
// - номер релиза
|
||||
$release = intval($release);
|
||||
// - номер сборки
|
||||
$build = intval($build);
|
||||
|
||||
// Если частей версии больше 1
|
||||
if (count($versionParts) > 1) {
|
||||
// - получаем массив для перевода строковых имен стадий в числа
|
||||
$stageEnumMap = array_flip($stagesNames);
|
||||
|
||||
// - получаем стадию
|
||||
$stage = VersionInfoStage::FromInt(intval($stageEnumMap[$versionParts[1]] ?? 0));
|
||||
|
||||
// - если стадия определена и не релиз, и кроме того, есть номер стадии
|
||||
if (self::IsNotUndefinedOrStable($stage) && count($versionParts) > 2)
|
||||
// -- получаем номер стадии
|
||||
$stageNumber = intval($versionParts[2]);
|
||||
else
|
||||
// -- иначе, устанавливаем номер стадии 0
|
||||
$stageNumber = 0;
|
||||
}
|
||||
else {
|
||||
// - иначе, устанавливаем стадию неопределённой
|
||||
$stage = VersionInfoStage::Undefined;
|
||||
// - и номер стадии 0
|
||||
$stageNumber = 0;
|
||||
}
|
||||
|
||||
// Создание объекта VersionInfo
|
||||
return new VersionInfo($major, $minor, $release, $build, $stage, $stageNumber);
|
||||
}
|
||||
|
||||
/**
|
||||
* Выводит строковое представление версии (упрощённая версия ToString() с шаблоном по умолчанию, необходимая для
|
||||
* вывода при попытке привести объект к типу string).
|
||||
*
|
||||
* @return string Строковое представление версии.
|
||||
*/
|
||||
public function __toString (): string
|
||||
{
|
||||
// Получаем строковое представление версии и возвращаем его
|
||||
return $this->ToString();
|
||||
}
|
||||
|
||||
/**
|
||||
* Проверяет, находится ли текущая версия в заданном диапазоне.
|
||||
*
|
||||
* @param VersionInfo|null $left Левая граница диапазона или null, если граница не задана (будет использована
|
||||
* минимальная версия).
|
||||
* @param VersionInfo|null $right Правая граница диапазона или null, если граница не задана (будет использована
|
||||
* максимальная версия).
|
||||
* @param ObjectArray|null $options Опции проверки (по умолчанию массив, который разрешает включать границы).
|
||||
*
|
||||
* @return int Возвращает 1, если текущая версия старше интервала, 0, если находится в интервале, -1, если текущая
|
||||
* версия младше интервала.
|
||||
*
|
||||
* @version 1.1
|
||||
* @since 1.0.27
|
||||
*/
|
||||
public function CompareWithRange (?VersionInfo $left = null, ?VersionInfo $right = null,
|
||||
?ObjectArray $options = null): int
|
||||
{
|
||||
// Подготавливаем опции, если они не переданы
|
||||
$options ??= new ObjectArray([
|
||||
VersionCompareRangeOption::LeftBorderIncluded,
|
||||
VersionCompareRangeOption::RightBorderIncluded
|
||||
]);
|
||||
|
||||
// Устанавливаем левую границу
|
||||
$leftBorder = $left ?? self::MinVersion();
|
||||
|
||||
// Устанавливаем правую границу
|
||||
$rightBorder = $right ?? self::MaxVersion();
|
||||
|
||||
// Проверяем, что границы не перепутаны
|
||||
if ($leftBorder->CompareWith($rightBorder) == 0)
|
||||
// - если границы перепутаны, то меняем их местами
|
||||
[$leftBorder, $rightBorder] = [$rightBorder, $leftBorder];
|
||||
|
||||
// Проверяем текущую версию относительно границ
|
||||
$compareLeft = $this->CompareWith($leftBorder);
|
||||
$compareRight = $this->CompareWith($rightBorder);
|
||||
|
||||
// Проверяем, что границы включены
|
||||
// - левая
|
||||
$leftBorderIncluded = $options->IsExist(fn (VersionCompareRangeOption $option)
|
||||
=> $option === VersionCompareRangeOption::LeftBorderIncluded);
|
||||
// - правая
|
||||
$rightBorderIncluded = $options->IsExist(fn (VersionCompareRangeOption $option)
|
||||
=> $option === VersionCompareRangeOption::RightBorderIncluded);
|
||||
|
||||
// Проверяем включение границ
|
||||
$isInInterval =
|
||||
(
|
||||
($compareLeft >= 0 && $leftBorderIncluded)
|
||||
|| ($compareLeft > 0)
|
||||
)
|
||||
&& (
|
||||
($compareRight <= 0 && $rightBorderIncluded)
|
||||
|| ($compareRight < 0)
|
||||
);
|
||||
|
||||
// Итоговая обработка результатов
|
||||
if ($isInInterval)
|
||||
// - версия в пределах диапазона
|
||||
return 0;
|
||||
else // - версия не в пределах диапазона, и если она младше левой границы (или равна ей при не включении границы)
|
||||
if ($compareLeft <= 0)
|
||||
// -- то возвращаем -1
|
||||
return -1;
|
||||
else
|
||||
// -- в противном случае, версия старше правой границы (или равна ей при не включении границы)
|
||||
return 1;
|
||||
}
|
||||
|
||||
/**
|
||||
* Возвращает минимальную версию.
|
||||
*
|
||||
* @return VersionInfo Минимальная версия.
|
||||
*
|
||||
* @since 1.0.28
|
||||
*/
|
||||
public static function MinVersion (): VersionInfo
|
||||
{
|
||||
return new VersionInfo(0, 0, 0, 0, VersionInfoStage::PreAlpha, 0);
|
||||
}
|
||||
|
||||
/**
|
||||
* Возвращает максимальную версию.
|
||||
*
|
||||
* @return VersionInfo Максимальная версия.
|
||||
*
|
||||
* @since 1.0.28
|
||||
*/
|
||||
public static function MaxVersion (): VersionInfo
|
||||
{
|
||||
return new VersionInfo(PHP_INT_MAX, PHP_INT_MAX, PHP_INT_MAX, PHP_INT_MAX, VersionInfoStage::Stable);
|
||||
}
|
||||
}
|
||||
108
sources/enums/JsonErrorCode.php
Normal file
108
sources/enums/JsonErrorCode.php
Normal file
@ -0,0 +1,108 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_components_pack\enums;
|
||||
|
||||
use goodboyalex\php_components_pack\traits\EnumExtensionsTrait;
|
||||
|
||||
/**
|
||||
* Перечисление известных ошибок при работе с JSON файлами.
|
||||
*
|
||||
* @author Александр Бабаев
|
||||
* @package php_components_pack
|
||||
* @version 1.0
|
||||
* @since 1.1.0
|
||||
*/
|
||||
enum JsonErrorCode: int
|
||||
{
|
||||
// Подключаю расширение для Enum
|
||||
use EnumExtensionsTrait;
|
||||
|
||||
/**
|
||||
* Неизвестная ошибка.
|
||||
*/
|
||||
case Unknown = -1;
|
||||
|
||||
/**
|
||||
* Ошибок нет.
|
||||
*/
|
||||
case None = 0;
|
||||
|
||||
/**
|
||||
* Достигнута максимальная глубина стека.
|
||||
*/
|
||||
case Depth = 1;
|
||||
|
||||
/**
|
||||
* Неверный или некорректный JSON.
|
||||
*/
|
||||
case StateMismatch = 2;
|
||||
|
||||
/**
|
||||
* Ошибка управляющего символа, возможно, неверная кодировка.
|
||||
*/
|
||||
case CTRLChar = 3;
|
||||
|
||||
/**
|
||||
* Синтаксическая ошибка.
|
||||
*/
|
||||
case Syntax = 4;
|
||||
|
||||
/**
|
||||
* Некорректные для кодировки UTF-8 символы, возможно, неверная кодировка.
|
||||
*/
|
||||
case UTF8 = 5;
|
||||
|
||||
/**
|
||||
* Одна или несколько зацикленных ссылок в кодируемом значении.
|
||||
*/
|
||||
case Recursion = 6;
|
||||
|
||||
/**
|
||||
* Одно или несколько значений NAN или INF в кодируемом значении.
|
||||
*/
|
||||
case InfOrNan = 7;
|
||||
|
||||
/**
|
||||
* Передали значение с неподдерживаемым типом.
|
||||
*/
|
||||
case UnsupportedType = 8;
|
||||
|
||||
/**
|
||||
* Имя свойства не может быть закодировано.
|
||||
*/
|
||||
case InvalidPropertyName = 9;
|
||||
|
||||
/**
|
||||
* Некорректный для кодировки UTF-16 символ, возможно, некорректно закодирован.
|
||||
*/
|
||||
case UTF16 = 10;
|
||||
|
||||
/**
|
||||
* Ключ не содержит вложений, хотя от него требуется обратное.
|
||||
*/
|
||||
case KeyIsNotArray = 11;
|
||||
|
||||
/**
|
||||
* Класс не реализует интерфейс ISerializable.
|
||||
*/
|
||||
case NotISerializable = 12;
|
||||
|
||||
/**
|
||||
* Получает код ошибки из последней JSON ошибки.
|
||||
*
|
||||
* @return JsonErrorCode Код ошибки.
|
||||
*/
|
||||
public static function FromLastError (): JsonErrorCode
|
||||
{
|
||||
// Получаю код ошибки
|
||||
$error = json_last_error();
|
||||
|
||||
// Проверяю, что код ошибки в диапазоне [0; 10]
|
||||
if ($error < 0 || $error > 10)
|
||||
// - верну неизвестную ошибку, если код не в диапазоне
|
||||
return self::Unknown;
|
||||
|
||||
// Перевожу код в Enum
|
||||
return self::FromInt($error);
|
||||
}
|
||||
}
|
||||
29
sources/enums/VersionCompareRangeOption.php
Normal file
29
sources/enums/VersionCompareRangeOption.php
Normal file
@ -0,0 +1,29 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_components_pack\enums;
|
||||
|
||||
use goodboyalex\php_components_pack\traits\EnumExtensionsTrait;
|
||||
|
||||
/**
|
||||
* Перечисление параметров для сравнения версий на промежутке.
|
||||
*
|
||||
* @author Александр Бабаев
|
||||
* @package php_components_pack
|
||||
* @version 1.0
|
||||
* @since 1.0.27
|
||||
*/
|
||||
enum VersionCompareRangeOption: int
|
||||
{
|
||||
// Подключаю расширение для Enum
|
||||
use EnumExtensionsTrait;
|
||||
|
||||
/**
|
||||
* Левая граница включается в диапазон.
|
||||
*/
|
||||
case LeftBorderIncluded = 0;
|
||||
|
||||
/**
|
||||
* Правая граница включается в диапазон.
|
||||
*/
|
||||
case RightBorderIncluded = 1;
|
||||
}
|
||||
49
sources/enums/VersionInfoStage.php
Normal file
49
sources/enums/VersionInfoStage.php
Normal file
@ -0,0 +1,49 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_components_pack\enums;
|
||||
|
||||
use goodboyalex\php_components_pack\traits\EnumExtensionsTrait;
|
||||
|
||||
/**
|
||||
* Перечисление стадий в информации о версии.
|
||||
*
|
||||
* @author Александр Бабаев
|
||||
* @package php_components_pack
|
||||
* @version 1.0
|
||||
* @since 1.0.24
|
||||
*/
|
||||
enum VersionInfoStage: int
|
||||
{
|
||||
// Подключаю расширение для Enum
|
||||
use EnumExtensionsTrait;
|
||||
|
||||
/**
|
||||
* Не определена или не задана стадия.
|
||||
*/
|
||||
case Undefined = 0;
|
||||
|
||||
/**
|
||||
* Пре-алфа.
|
||||
*/
|
||||
case PreAlpha = 1;
|
||||
|
||||
/**
|
||||
* Альфа.
|
||||
*/
|
||||
case Alpha = 2;
|
||||
|
||||
/**
|
||||
* Бета.
|
||||
*/
|
||||
case Beta = 3;
|
||||
|
||||
/**
|
||||
* Кандидат в релиз.
|
||||
*/
|
||||
case ReleaseCandidate = 4;
|
||||
|
||||
/**
|
||||
* Релиз.
|
||||
*/
|
||||
case Stable = 5;
|
||||
}
|
||||
67
sources/exceptions/JsonException.php
Normal file
67
sources/exceptions/JsonException.php
Normal file
@ -0,0 +1,67 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_components_pack\exceptions;
|
||||
|
||||
use Exception;
|
||||
use goodboyalex\php_components_pack\enums\JsonErrorCode;
|
||||
|
||||
/**
|
||||
* Ошибка работы с JSON.
|
||||
*
|
||||
* @author Александр Бабаев
|
||||
* @package php_components_pack
|
||||
* @version 1.0
|
||||
* @since 1.1.0
|
||||
*/
|
||||
final class JsonException extends Exception
|
||||
{
|
||||
/**
|
||||
* @var string|null $JsonString Строка JSON.
|
||||
*/
|
||||
public ?string $JsonString;
|
||||
|
||||
/**
|
||||
* @var JsonErrorCode $ErrorCode Код ошибки JSON.
|
||||
*/
|
||||
public JsonErrorCode $ErrorCode;
|
||||
|
||||
/**
|
||||
* @link https://www.php.net/manual/ru/function.json-last-error-msg.php
|
||||
* @var string|null $ErrorMessage Сообщение об ошибке JSON.
|
||||
*
|
||||
* Внимание! В отличие от функции json_last_error_msg(), данная переменная при отсутствии ошибок выводит null, а не
|
||||
* "No error".
|
||||
*/
|
||||
public ?string $ErrorMessage;
|
||||
|
||||
/**
|
||||
* Конструктор.
|
||||
*
|
||||
* @param string|null $json Строка JSON.
|
||||
* @param JsonErrorCode $errorCode Код ошибки JSON.
|
||||
* @param string|null $errorMessage Сообщение об ошибке JSON.
|
||||
*/
|
||||
public function __construct (?string $json = null, JsonErrorCode $errorCode = JsonErrorCode::Unknown,
|
||||
?string $errorMessage = null)
|
||||
{
|
||||
// Если код ошибки JSON равен 0
|
||||
if ($errorMessage === "No error")
|
||||
// - то присваиваем ему null для совместимости
|
||||
$errorMessage = null;
|
||||
|
||||
// Сохраняем сообщение об ошибке
|
||||
$this->ErrorMessage = $errorMessage;
|
||||
|
||||
// Если сообщение пусто, то присваиваем ему "" для совместимости
|
||||
$errorMessage = $errorMessage ?? "";
|
||||
|
||||
// Запускаем базовый конструктор
|
||||
parent::__construct($errorMessage);
|
||||
|
||||
// Присваиваем имя файла
|
||||
$this->JsonString = $json;
|
||||
|
||||
// Присваиваем код ошибки
|
||||
$this->ErrorCode = $errorCode;
|
||||
}
|
||||
}
|
||||
710
sources/operators/JsonReWriter.md
Normal file
710
sources/operators/JsonReWriter.md
Normal file
@ -0,0 +1,710 @@
|
||||
# Описание класса JsonReWriter
|
||||
|
||||
## Информация о версии
|
||||
|
||||
Версия класса: 1.0
|
||||
|
||||
Впервые введено в пакет с версии: 1.1.0
|
||||
|
||||
Описание класса: Класс для работы с JSON-файлами.
|
||||
|
||||
## Публичные свойства и константы класса
|
||||
|
||||
В классе определены следующие свойства:
|
||||
|
||||
- `string $JsonString` - строка JSON (чтение/запись).
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
### Правила формирования ключей.
|
||||
|
||||
Ключ для чтения/записи данных класса формируется следующим образом: `ключ/подключ/подключ подключа` .
|
||||
|
||||
Например, если дан json-файл:
|
||||
|
||||
{
|
||||
"test": {
|
||||
"subtest": {
|
||||
"AAA": "123",
|
||||
"BBB": 1.23
|
||||
}
|
||||
},
|
||||
"test1": {
|
||||
"test": 123
|
||||
},
|
||||
"test2": {
|
||||
"test": true
|
||||
},
|
||||
"test3": {
|
||||
"test": {
|
||||
"res": "[1,2,3]"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Пусть требуется получить значение `BBB`, тогда ключ должен быть `test/subtest/BBB`.
|
||||
|
||||
### Чтение.
|
||||
|
||||
1. Создайте элемент класса `$json = new JsonReWriter ();`
|
||||
2. Если у вас требуется загрузить json из файла `$fileName`, то воспользуйтесь методом `LoadFromFile`:
|
||||
`$json->LoadFromFile($fileName);`, если же json представлен строкой `$jsonStr`, то загрузите её в свойство
|
||||
`$JsonString`: `$json->JsonString = $jsonStr;`
|
||||
3. Далее можно пользоваться любым методом для чтения `Read*`, в том числе и общим `$json->Read(...)`.
|
||||
|
||||
**Пример:**
|
||||
|
||||
// Имя файла
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
// Создаю класс
|
||||
$json = new JsonReWriter();
|
||||
// Загшружаю данные из файла
|
||||
$json->LoadFromFile($fileName);
|
||||
// Получаю число
|
||||
$float = $json->ReadFloat("test/subtest/BBB", 0.2);
|
||||
|
||||
В итоге в `$float` будет `1.23`.
|
||||
|
||||
### Запись.
|
||||
|
||||
1. Создайте элемент класса `$json = new JsonReWriter ();`
|
||||
2. Далее можно пользоваться любым методом для записи `Write*`, в том числе и общим `$json->Write(...)`.
|
||||
3. Если вам требуется создать json файл с именем `$fileName`, то воспользуйтесь методом `SaveToFile`:
|
||||
`$json->SaveToFile($fileName);`, если же json должен быть представлен строкой `$jsonStr`, то загрузите её из свойства
|
||||
`$JsonString`: `$jsonStr = $json->JsonString;`
|
||||
|
||||
**Пример:**
|
||||
|
||||
// Имя файла
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
// Создаю класс
|
||||
$json = new JsonReWriter();
|
||||
// Загшружаю данные из файла
|
||||
$json->LoadFromFile($fileName);
|
||||
// Получаю число
|
||||
try {
|
||||
$json->Write("test/subtest/BBB", 0.2);
|
||||
}
|
||||
catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
В итоге в `test/subtest/BBB` вместо `1.23` будет `0.2`.
|
||||
|
||||
## Коды ошибок JsonErrorCode
|
||||
|
||||
Ниже представлена таблица основных кодов ошибки:
|
||||
|
||||
| Ошибка | Описание | Введено с версии |
|
||||
|:-------------------:|:---------------------------------------------------------------------------:|:----------------:|
|
||||
| Unknown | Неизвестная ошибка | 1.0 |
|
||||
| None | Ошибок нет | 1.0 |
|
||||
| Depth | Достигнута максимальная глубина стека | 1.0 |
|
||||
| StateMismatch | Неверный или некорректный JSON | 1.0 |
|
||||
| CTRLChar | Ошибка управляющего символа, возможно, неверная кодировка | 1.0 |
|
||||
| Syntax | Синтаксическая ошибка | 1.0 |
|
||||
| UTF8 | Некорректные для кодировки UTF-8 символы, возможно, неверная кодировка | 1.0 |
|
||||
| Recursion | Одна или несколько зацикленных ссылок в кодируемом значении | 1.0 |
|
||||
| InfOrNan | Одно или несколько значений NAN или INF в кодируемом значении | 1.0 |
|
||||
| UnsupportedType | Передали значение с неподдерживаемым типом | 1.0 |
|
||||
| InvalidPropertyName | Имя свойства не может быть закодировано | 1.0 |
|
||||
| UTF16 | Некорректный для кодировки UTF-16 символ, возможно, некорректно закодирован | 1.0 |
|
||||
| KeyIsNotArray | Ключ не содержит вложений, хотя от него требуется обратное | 1.0 |
|
||||
| NotISerializable | Класс не реализует интерфейс ISerializable | 1.0 |
|
||||
|
||||
### Методы и функции перечисления JsonErrorCode
|
||||
|
||||
Перечисление содержит **статический метод** `static function FromLastError (): JsonErrorCode`, который получает код
|
||||
ошибки из последней JSON ошибки.
|
||||
|
||||
Например, при успешной загрузке, можем проверить ошибки:
|
||||
|
||||
$errors = JsonErrorCode::FromLastError ();
|
||||
|
||||
После того, как мы выведем `$errors`, мы получим `JsonErrorCode::None`.
|
||||
|
||||
## Исключение JsonException
|
||||
|
||||
Исключение расширяет класс `Exception`, поэтому может выбрасываться через `throw`.
|
||||
|
||||
### Свойства
|
||||
|
||||
Исключение содержит следующие свойства:
|
||||
|
||||
- `?string $JsonString` - строка JSON (или null);
|
||||
- `JsonErrorCode $ErrorCode` - код ошибки JSON;
|
||||
- `?string $ErrorMessage` - сообщение об ошибке JSON (в отличие от функции json_last_error_msg(), данная переменная при
|
||||
отсутствии ошибок выводит null, а не "No error").
|
||||
|
||||
### Методы и функции
|
||||
|
||||
#### Конструктор.
|
||||
|
||||
Конструктор принимает **3 необязательных параметра**:
|
||||
|
||||
* `?string $json` - строка JSON (по умолчанию, `null`);
|
||||
* `JsonErrorCode $errorCode` - код ошибки (по умолчанию, `JsonErrorCode::Unknown`);
|
||||
* `?string $errorMessage` - сообщение об ошибке (по умолчанию, `null`).
|
||||
|
||||
В результате создаётся новое исключение `JsonException`.
|
||||
|
||||
Пример:
|
||||
|
||||
throw new JsonException("{}", JsonErrorCode::Depth, "Пример");
|
||||
|
||||
Создаст исключение `JsonException`.
|
||||
|
||||
## Методы и функции
|
||||
|
||||
### Конструктор и деструктор.
|
||||
|
||||
Конструктор не принимает никаких параметров.
|
||||
|
||||
В результате создаётся новый класс `JsonReWriter`.
|
||||
|
||||
**Пример:**
|
||||
|
||||
// Контсуктор
|
||||
$json = new JsonReWriter ();
|
||||
// Деструктор
|
||||
unset($json);
|
||||
|
||||
Создаст и уничтожит класс `JsonReWriter`.
|
||||
|
||||
### Сохранение и загрузка из файла.
|
||||
|
||||
За сохранение и загрузку отвечают 2 метода: `SaveToFile` и `LoadFromFile`.
|
||||
|
||||
#### Сохранение в файл (метод `SaveToFile`)
|
||||
|
||||
Этот метод сохраняет содержимое JSON в файл. Он содержит **1 обязательный параметр**:
|
||||
|
||||
* `string $fileName` - имя файла на диске.
|
||||
|
||||
Метод возвращает `bool` - сохранены ли данные в файл: `true` - да, `false` - нет.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function SaveToFile (string $fileName): bool
|
||||
|
||||
**Пример:**
|
||||
|
||||
// Имя файла
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
// Сохраняем созданный JSON файл
|
||||
$json->SaveToFile($fileName);
|
||||
|
||||
Содержимое файла `test.json` представлено далее:
|
||||
|
||||
{
|
||||
"test": {
|
||||
"subtest": {
|
||||
"AAA": "123",
|
||||
"BBB": 1.23
|
||||
}
|
||||
},
|
||||
"test1": {
|
||||
"test": 123
|
||||
},
|
||||
"test2": {
|
||||
"test": true
|
||||
},
|
||||
"test3": {
|
||||
"test": {
|
||||
"res": "[1,2,3]"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#### Загрузка файла (метод `LoadFromFile`)
|
||||
|
||||
Этот метод загружает содержимое файла в класс. Он содержит **1 обязательный параметр**:
|
||||
|
||||
* `string $fileName` - имя файла на диске.
|
||||
|
||||
Метод возвращает `bool` - загружены ли данные из файла: `true` - да, `false` - нет.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function LoadFromFile (string $fileName): bool
|
||||
|
||||
**Пример:**
|
||||
Пусть дан файл `test.json`, содержимое которого представлено далее:
|
||||
|
||||
{
|
||||
"test": {
|
||||
"subtest": {
|
||||
"AAA": "123",
|
||||
"BBB": 1.23
|
||||
}
|
||||
},
|
||||
"test1": {
|
||||
"test": 123
|
||||
},
|
||||
"test2": {
|
||||
"test": true
|
||||
},
|
||||
"test3": {
|
||||
"test": {
|
||||
"res": "[1,2,3]"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Следующий код загрузит это содержимое в класс:
|
||||
|
||||
// Имя файла
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Загружаю данные
|
||||
$json->LoadFromFile($fileName);
|
||||
|
||||
### Чтение данных
|
||||
|
||||
Для чтения данных используется один общий метод `Read` и 7 его производных метода: `ReadString`, `ReadInt`, `ReadFloat`,
|
||||
`ReadBool`, `ReadArray`, `ReadObject` и `ReadSerializable`.
|
||||
|
||||
#### Метод `Read`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **1 обязательный параметр** `string $key` (ключ) и **1
|
||||
необязательный параметр** `mixed $default` (значение по умолчанию, задан по умолчанию в `null`).
|
||||
|
||||
Этот метод возвращает `mixed`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function Read (string $key, mixed $default = null): mixed
|
||||
|
||||
**Пример,**
|
||||
|
||||
// Создаю класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполняю данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->Write("test3/test/res", json_encode([1, 2, 3]));
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
// Получаю значение
|
||||
$float = (float)$json->Read("test/subtest/BBB"));
|
||||
|
||||
В результате, переменная `$float` будет иметь значение `1.23`.
|
||||
|
||||
#### Метод `ReadString`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **1 обязательный параметр** `string $key` (ключ) и **1
|
||||
необязательный параметр** `string $default` (значение по умолчанию, задан по умолчанию в `""`).
|
||||
|
||||
Этот метод возвращает `string`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadString (string $key, string $default = ""): string
|
||||
|
||||
#### Метод `ReadInt`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **1 обязательный параметр** `string $key` (ключ) и **1
|
||||
необязательный параметр** `int $default` (значение по умолчанию, задан по умолчанию в `0`).
|
||||
|
||||
Этот метод возвращает `int`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadInt (string $key, int $default = 0): int
|
||||
|
||||
#### Метод `ReadFloat`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **1 обязательный параметр** `string $key` (ключ) и **1
|
||||
необязательный параметр** `float $default` (значение по умолчанию, задан по умолчанию в `0.0`).
|
||||
|
||||
Этот метод возвращает `float`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadFloat (string $key, float $default = 0.0): float
|
||||
|
||||
#### Метод `ReadBool`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **1 обязательный параметр** `string $key` (ключ) и **1
|
||||
необязательный параметр** `bool $default` (значение по умолчанию, задан по умолчанию в `false`).
|
||||
|
||||
Этот метод возвращает `bool`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadBool (string $key, bool $default = false): bool
|
||||
|
||||
#### Метод `ReadArray`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **1 обязательный параметр** `string $key` (ключ) и **1
|
||||
необязательный параметр** `array $default` (значение по умолчанию, задан по умолчанию в `[]`).
|
||||
|
||||
Этот метод возвращает `array`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadArray (string $key, array $default = []): array
|
||||
|
||||
#### Метод `ReadObject`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **2 обязательных параметра**:
|
||||
|
||||
- `string $key` (ключ);
|
||||
- `object $default` (значение по умолчанию).
|
||||
|
||||
Этот метод возвращает `object`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadObject (string $key, object $default): object
|
||||
|
||||
#### Метод `ReadSerializable`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **2 обязательных параметра**:
|
||||
|
||||
- `string $key` (ключ);
|
||||
- `string $serializableClassName` (имя класса, реализующего интерфейс ISerializable, с namespace).
|
||||
|
||||
Этот метод возвращает класс, реализующий интерфейс `ISerializable`.
|
||||
|
||||
**Важно!** Этот метод может выбросить исключение `JsonException`, если класс, заданный в `$serializableClassName` не
|
||||
реализует интерфейс `ISerializable`.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadSerializable (string $key, string $serializableClassName): ISerializable
|
||||
|
||||
**Пример,**
|
||||
|
||||
Пусть для примера, класс `Demo` из namespace `iam\namespace` реализует интерфейс `ISerializable`.
|
||||
|
||||
// Создаю класс
|
||||
$json = new JsonReWriter();
|
||||
// ... Здесь где-то загрузка данных
|
||||
// Получаю класс
|
||||
try {
|
||||
/**
|
||||
* @var Demo $unSerializableClass
|
||||
*/
|
||||
$unSerializableClass = $json->ReadSerializable("test", "iam\\namespace\\Demo");
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
В результате, переменная `$unSerializableClass` будет содержать данные класса `Demo`.
|
||||
|
||||
### Запись данных
|
||||
|
||||
Для чтения данных используется один общий метод `Write` и 3 его производных метода: `WriteArray`, `WriteObject` и
|
||||
`WriteSerializable`.
|
||||
|
||||
**Важно!** Лобой из вышеуказанных методов может выбросить исключение `JsonException`, если ключ не содержит вложений,
|
||||
хотя от него требуется обратное.
|
||||
|
||||
#### Метод `Write`
|
||||
|
||||
Это метод, который записывает значение в ключ JSON. Он имеет **2 обязательных параметра**:
|
||||
|
||||
- `string $key` (ключ);
|
||||
- `mixed $value` (записываемое значение).
|
||||
|
||||
Этот метод ничего не возвращает.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function Write (string $key, mixed $value): void
|
||||
|
||||
**Пример,**
|
||||
|
||||
// Имя файла
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
// Сохраняем созданный JSON файл
|
||||
$json->SaveToFile($fileName);
|
||||
|
||||
Содержимое файла `test.json` представлено далее:
|
||||
|
||||
{
|
||||
"test": {
|
||||
"subtest": {
|
||||
"AAA": "123",
|
||||
"BBB": 1.23
|
||||
}
|
||||
},
|
||||
"test1": {
|
||||
"test": 123
|
||||
},
|
||||
"test2": {
|
||||
"test": true
|
||||
},
|
||||
"test3": {
|
||||
"test": {
|
||||
"res": "[1,2,3]"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#### Метод `WriteArray`
|
||||
|
||||
Это метод, который записывает значение в ключ JSON. Он имеет **2 обязательных параметра**:
|
||||
|
||||
- `string $key` (ключ);
|
||||
- `array $array` (записываемое значение).
|
||||
|
||||
Этот метод ничего не возвращает.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function WriteArray (string $key, array $array): void
|
||||
|
||||
#### Метод `WriteObject`
|
||||
|
||||
Это метод, который записывает значение в ключ JSON. Он имеет **2 обязательных параметра**:
|
||||
|
||||
- `string $key` (ключ);
|
||||
- `object $value` (записываемое значение).
|
||||
|
||||
Этот метод ничего не возвращает.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function WriteObject (string $key, object $value): void
|
||||
|
||||
#### Метод `WriteSerializable`
|
||||
|
||||
Это метод, который записывает значение в ключ JSON. Он имеет **2 обязательных параметра**:
|
||||
|
||||
- `string $key` (ключ);
|
||||
- `ISerializable $serializableValue` (записываемое значение).
|
||||
|
||||
Этот метод ничего не возвращает.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function WriteSerializable (string $key, ISerializable $serializableValue): void
|
||||
|
||||
**Пример,**
|
||||
Пусть для примера, класс `Demo` из namespace `iam\namespace` реализует интерфейс `ISerializable`.
|
||||
|
||||
// Имя файла
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Создаём класс Demo
|
||||
$serializableClass = new Demo(...);
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->WriteSerializable("test", $serializableClass);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
...
|
||||
|
||||
### Работа с ключами JSON
|
||||
|
||||
Для работы с ключами JSON есть 2 метода: `IsKeyExists` и `GetKeys`.
|
||||
|
||||
#### Метод `IsKeyExists`
|
||||
|
||||
Это метод проверяем наличие ключа в JSON. Он имеет **1 обязательный параметр** - `string $key` (ключ).
|
||||
|
||||
Этот метод возвращает `bool`: `true` если ключ найден и `false` в противном случае.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function IsKeyExists (string $key): bool
|
||||
|
||||
**Пример,**
|
||||
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
// Проверяем ключи
|
||||
$check1 = $json->IsKeyExists("test/subtest/AAA");
|
||||
$check2 = $json->IsKeyExists("test/subtest/ССС");
|
||||
|
||||
В результате, `$check1` будет `true`, а `$check2` - `false`.
|
||||
|
||||
#### Метод `GetKeys`
|
||||
|
||||
Это метод получает список ключей. Он имеет **2 необязательных параметра**:
|
||||
|
||||
- `string $parentKey` (ключ родителя (или "" (установлено по умолчанию) для всех);
|
||||
- `bool $includeChildren` (нужно ли включать дочерние ключи (по умолчанию, да)).
|
||||
|
||||
Этот метод возвращает `array`: список ключей.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function GetKeys (string $parentKey = "", bool $includeChildren = true): array
|
||||
|
||||
**Пример,**
|
||||
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
// Получаем ключи
|
||||
$keys1 = $json->GetKeys("test");
|
||||
$keys2 = $json->GetKeys("test", false);
|
||||
$keys3 = $json->GetKeys();
|
||||
|
||||
В результате, `$key1` будет следующим массивом:
|
||||
|
||||
[
|
||||
"test/subtest",
|
||||
"test/subtest/AAA",
|
||||
"test/subtest/BBB"
|
||||
]
|
||||
|
||||
`$key2` будет следующим массивом:
|
||||
|
||||
[
|
||||
"subtest"
|
||||
]
|
||||
|
||||
`$key3` будет следующим массивом:
|
||||
|
||||
[
|
||||
"test",
|
||||
"test/subtest",
|
||||
"test/subtest/AAA",
|
||||
"test/subtest/BBB",
|
||||
"test1",
|
||||
"test1/test",
|
||||
"test2",
|
||||
"test2/test",
|
||||
"test3",
|
||||
"test3/test",
|
||||
"test3/test/res"
|
||||
]
|
||||
|
||||
### Удаление ключей JSON
|
||||
|
||||
Для удаления ключей JSON есть 2 метода: `DeleteKey`, который удаляет только определённый ключ и `Clear`, который удаляет
|
||||
**все ключи** из json-файла.
|
||||
|
||||
#### Метод `DeleteKey`
|
||||
|
||||
Это метод удаляет только определённый ключ в JSON. Он имеет **1 обязательный параметр** - `string $key` (ключ).
|
||||
|
||||
Этот метод возвращает `bool` - результат удаления ключа: `true` - удаление прошло успешно, `false` - произошла ошибка
|
||||
при удалении.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function DeleteKey (string $key): bool
|
||||
|
||||
**Пример,**
|
||||
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
// Получаемем ключи до удаления
|
||||
$check1 = $json->GetKeys("test/subtest");
|
||||
// Удаляем ключ
|
||||
$this->DeleteKey("test/subtest/BBB");
|
||||
// Получаемем ключи после удаления
|
||||
$check2 = $json->GetKeys("test/subtest");
|
||||
|
||||
В результате, `$check1` будет
|
||||
|
||||
[
|
||||
"test/subtest",
|
||||
"test/subtest/AAA",
|
||||
"test/subtest/BBB"
|
||||
]
|
||||
|
||||
а `$check2`:
|
||||
|
||||
[
|
||||
"test/subtest",
|
||||
"test/subtest/AAA"
|
||||
]
|
||||
|
||||
#### Метод `Clear`
|
||||
|
||||
Это метод удаляет **все ключи** из json-файла. Он не имеет никаких параметров и ничего не возвращает.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function Clear (): void
|
||||
|
||||
**Пример,**
|
||||
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
// Очищаем
|
||||
$json->Clear();
|
||||
// Получаем ключи
|
||||
$keys = $json->GetKeys();
|
||||
|
||||
В результате, `$key` будет следующим массивом:
|
||||
|
||||
[
|
||||
]
|
||||
46
sources/operators/Operators.php
Normal file
46
sources/operators/Operators.php
Normal file
@ -0,0 +1,46 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_components_pack\operators;
|
||||
|
||||
/**
|
||||
* Полезные операторы.
|
||||
*
|
||||
* @author Александр Бабаев
|
||||
* @package php_components_pack
|
||||
* @version 1.0
|
||||
* @since 1.1.1
|
||||
*/
|
||||
final class Operators
|
||||
{
|
||||
/**
|
||||
* Проверяет, что значение <code>$value</code> равно одному из значений <code>$values</code>.
|
||||
*
|
||||
* @param mixed $value Искомое значение.
|
||||
* @param mixed ...$values Массив значений.
|
||||
*
|
||||
* @return bool Возвращает <code>true</code>, если значение <code>$value</code> равно одному из значений
|
||||
* <code>$values</code>, иначе <code>false</code>.
|
||||
*/
|
||||
public static function Is (mixed $value, mixed ...$values): bool
|
||||
{
|
||||
// Проверяем, что хотя бы одно из значений равно искомому и возвращаем результат
|
||||
return array_any($values, fn ($curValue) => $curValue === $value);
|
||||
}
|
||||
|
||||
/**
|
||||
* Проверяет, сколько раз значение <code>$value</code> встречается в массиве <code>$values</code>.
|
||||
*
|
||||
* @param mixed $value Искомое значение.
|
||||
* @param mixed ...$values Массив значений.
|
||||
*
|
||||
* @return int Возвращает количество значений <code>$values</code>, которые равны <code>$value</code>.
|
||||
*/
|
||||
public static function IsCount (mixed $value, mixed ...$values): int
|
||||
{
|
||||
// Получаем массив значений повторений
|
||||
$result = array_count_values($values);
|
||||
|
||||
// Возвращаем результат
|
||||
return $result[$value] ?? 0;
|
||||
}
|
||||
}
|
||||
69
sources/traits/JsonReWriter/JsonReWriterDeleteTrait.php
Normal file
69
sources/traits/JsonReWriter/JsonReWriterDeleteTrait.php
Normal file
@ -0,0 +1,69 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_components_pack\traits\JsonReWriter;
|
||||
|
||||
/**
|
||||
* Часть кода класса JsonReWriter, отвечающая за методы удаления ключей JSON.
|
||||
*
|
||||
* @author Александр Бабаев
|
||||
* @package php_components_pack
|
||||
* @version 1.0
|
||||
* @since 1.1.0
|
||||
*/
|
||||
trait JsonReWriterDeleteTrait
|
||||
{
|
||||
/**
|
||||
* Очистка данных JSON.
|
||||
*
|
||||
* @return void
|
||||
*/
|
||||
public function Clear (): void
|
||||
{
|
||||
// Очистка данных
|
||||
unset($this->JsonData);
|
||||
|
||||
// Создание пустого массива
|
||||
$this->JsonData = [];
|
||||
}
|
||||
|
||||
/**
|
||||
* Удаление ключа JSON.
|
||||
*
|
||||
* @param string $key Требуемый ключ JSON для удаления.
|
||||
*
|
||||
* @return bool Результат удаления ключа: <code>true</code> - удаление прошло успешно, <code>false</code> -
|
||||
* произошла ошибка при удалении.
|
||||
*/
|
||||
public function DeleteKey (string $key): bool
|
||||
{
|
||||
// Очищаем ключ
|
||||
$preparedKey = $this->PrepareKey($key);
|
||||
|
||||
// Проверка ключа
|
||||
if (!$this->IsKeyExists($preparedKey))
|
||||
// - ключ не существует
|
||||
return false;
|
||||
|
||||
// Разбиваем ключ на части
|
||||
$keys = $this->ParseKey($preparedKey);
|
||||
|
||||
// Получаем текущий массив данных
|
||||
$current = &$this->JsonData;
|
||||
|
||||
// Если ключ не является корневым
|
||||
if (count($keys) > 0)
|
||||
// - переходим к вложенному массиву
|
||||
for ($i = 0; $i < count($keys) - 1; $i++)
|
||||
// -- и добавляем массив данных
|
||||
$current = &$current[$keys[$i]];
|
||||
|
||||
// Получаем удаляемый ключ
|
||||
$deleteKey = $keys[count($keys) - 1];
|
||||
|
||||
// Удаляем ключ
|
||||
unset($current[$deleteKey]);
|
||||
|
||||
// Проверяем удаление
|
||||
return $this->IsKeyExists($key);
|
||||
}
|
||||
}
|
||||
129
sources/traits/JsonReWriter/JsonReWriterKeyTrait.php
Normal file
129
sources/traits/JsonReWriter/JsonReWriterKeyTrait.php
Normal file
@ -0,0 +1,129 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_components_pack\traits\JsonReWriter;
|
||||
|
||||
use goodboyalex\php_components_pack\extensions\StringExtension;
|
||||
|
||||
/**
|
||||
* Часть кода класса JsonReWriter, отвечающая за методы работы с ключами JSON.
|
||||
*
|
||||
* @author Александр Бабаев
|
||||
* @package php_components_pack
|
||||
* @version 1.0
|
||||
* @since 1.1.0
|
||||
*/
|
||||
trait JsonReWriterKeyTrait
|
||||
{
|
||||
/**
|
||||
* Проверяем наличие ключа в JSON.
|
||||
*
|
||||
* @param string $key Ключ.
|
||||
*
|
||||
* @return bool true если ключ найден, false если нет.
|
||||
*/
|
||||
public function IsKeyExists (string $key): bool
|
||||
{
|
||||
// Получаем массив ключей по вложенности
|
||||
$keys = $this->ParseKey($key);
|
||||
|
||||
// Получаем текущий массив данных
|
||||
$current = $this->JsonData;
|
||||
|
||||
// Для каждого ключа
|
||||
foreach ($keys as $key) {
|
||||
// - проверяем наличие ключа в текущем массиве
|
||||
if (!array_key_exists($key, $current))
|
||||
// - нет? Возвращаем false
|
||||
return false;
|
||||
|
||||
// Переходим ко вложенному массиву
|
||||
$current = $current[$key];
|
||||
}
|
||||
|
||||
// Возвращаем true, если все ключи найдены
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Получение ключей по вложенности. Т.е., ключи вида <code>"key1/key2/key3" => ["key1", "key2", "key3"]</code>.
|
||||
*
|
||||
* @param string $key Ключ.
|
||||
*
|
||||
* @return array Ключи по вложенности.
|
||||
*/
|
||||
private function ParseKey (string $key): array
|
||||
{
|
||||
// Очищаем ключ
|
||||
$key = $this->PrepareKey($key);
|
||||
|
||||
// Разбиваем ключ на части
|
||||
return explode('/', $key);
|
||||
}
|
||||
|
||||
/**
|
||||
* Подготавливает ключ к использованию внутри методов.
|
||||
*
|
||||
* @param string $key Неочищенный ключ.
|
||||
*
|
||||
* @return string Очищенный ключ.
|
||||
*/
|
||||
private function PrepareKey (string $key): string
|
||||
{
|
||||
return trim($key, "/ ");
|
||||
}
|
||||
|
||||
/**
|
||||
* Получение списка ключей.
|
||||
*
|
||||
* @param string $parentKey Ключ родителя (или "" (установлено по умолчанию) для всех).
|
||||
* @param bool $includeChildren Нужно ли включать дочерние ключи (по умолчанию, да).
|
||||
*
|
||||
* @return array Список ключей.
|
||||
*/
|
||||
public function GetKeys (string $parentKey = "", bool $includeChildren = true): array
|
||||
{
|
||||
// Очищаем ключ
|
||||
$parentKey = $this->PrepareKey($parentKey);
|
||||
|
||||
// Разбиваем ключ на части
|
||||
$keys = StringExtension::IsNullOrWhitespace($parentKey) ? [] : $this->ParseKey($parentKey);
|
||||
|
||||
// Получаем текущий массив данных
|
||||
$current = $this->JsonData;
|
||||
|
||||
// Если ключ не является корневым
|
||||
if (count($keys) > 0)
|
||||
// - переходим к вложенному массиву
|
||||
for ($i = 0; $i < count($keys); $i++)
|
||||
// -- и добавляем массив данных
|
||||
$current = $current[$keys[$i]];
|
||||
|
||||
// Получаем список ключей родителя
|
||||
$parentKeysList = array_keys($current);
|
||||
|
||||
// Если не нужно включать дочерние ключи
|
||||
if (!$includeChildren)
|
||||
// - возвращаем список родительских ключей
|
||||
return $parentKeysList;
|
||||
|
||||
// Создаем результирующий массив
|
||||
$result = [];
|
||||
|
||||
// Для каждого ключа
|
||||
foreach ($parentKeysList as $key) {
|
||||
// - очищаем текущий ключ
|
||||
$currentKey = $this->PrepareKey($parentKey . "/" . $key);
|
||||
|
||||
// - добавляем его в результирующий массив
|
||||
$result[] = $currentKey;
|
||||
|
||||
// - если у текущего ключа есть дочерние ключи
|
||||
if (is_array($current[$key]))
|
||||
// -- добавляем их в результирующий массив
|
||||
$result = array_merge($result, $this->GetKeys($currentKey));
|
||||
}
|
||||
|
||||
// Возвращаем результирующий массив
|
||||
return $result;
|
||||
}
|
||||
}
|
||||
56
sources/traits/JsonReWriter/JsonReWriterLoadSaveTrait.php
Normal file
56
sources/traits/JsonReWriter/JsonReWriterLoadSaveTrait.php
Normal file
@ -0,0 +1,56 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_components_pack\traits\JsonReWriter;
|
||||
|
||||
/**
|
||||
* Часть кода класса JsonReWriter, отвечающая за методы загрузки и сохранения JSON.
|
||||
*
|
||||
* @author Александр Бабаев
|
||||
* @package php_components_pack
|
||||
* @version 1.0
|
||||
* @since 1.1.0
|
||||
*/
|
||||
trait JsonReWriterLoadSaveTrait
|
||||
{
|
||||
/**
|
||||
* Сохраняем JSON в файл.
|
||||
*
|
||||
* @param string $fileName Имя файла.
|
||||
*
|
||||
* @return bool Сохранены ли данные в файл: <code>true</code> - да, <code>false</code> - нет.
|
||||
*/
|
||||
public function SaveToFile (string $fileName): bool
|
||||
{
|
||||
// Запись данных в файл
|
||||
return file_put_contents($fileName, $this->JsonString) !== false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Загрузка данных из JSON-файла.
|
||||
*
|
||||
* @param string $fileName Имя файла.
|
||||
*
|
||||
* @return bool Загрузились ли данные из файла: <code>true</code> - да, <code>false</code> - нет.
|
||||
*/
|
||||
public function LoadFromFile (string $fileName): bool
|
||||
{
|
||||
// Проверка существования файла
|
||||
if (!is_file($fileName))
|
||||
// - если нет, возвращаем false
|
||||
return false;
|
||||
|
||||
// Чтение содержимого файла
|
||||
$result = file_get_contents($fileName);
|
||||
|
||||
// Проверка на ошибки
|
||||
if ($result === false)
|
||||
// - если есть ошибки, возвращаем false
|
||||
return false;
|
||||
|
||||
// Записываем результат
|
||||
$this->JsonString = $result;
|
||||
|
||||
// Возвращаем true, если все хорошо
|
||||
return true;
|
||||
}
|
||||
}
|
||||
173
sources/traits/JsonReWriter/JsonReWriterReadTrait.php
Normal file
173
sources/traits/JsonReWriter/JsonReWriterReadTrait.php
Normal file
@ -0,0 +1,173 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_components_pack\traits\JsonReWriter;
|
||||
|
||||
use goodboyalex\php_components_pack\enums\JsonErrorCode;
|
||||
use goodboyalex\php_components_pack\exceptions\JsonException;
|
||||
use goodboyalex\php_components_pack\interfaces\ISerializable;
|
||||
|
||||
/**
|
||||
* Часть кода класса JsonReWriter, отвечающая за методы чтения ключей и значений JSON.
|
||||
*
|
||||
* @author Александр Бабаев
|
||||
* @package php_components_pack
|
||||
* @version 1.0
|
||||
* @since 1.1.0
|
||||
*/
|
||||
trait JsonReWriterReadTrait
|
||||
{
|
||||
/**
|
||||
* Читает значение ключа JSON как целое число.
|
||||
*
|
||||
* @param string $key Ключ JSON.
|
||||
* @param int $default Значение по умолчанию.
|
||||
*
|
||||
* @return int Значение ключа JSON или значение по умолчанию.
|
||||
*/
|
||||
public function ReadInt (string $key, int $default = 0): int
|
||||
{
|
||||
return (int)$this->Read($key, $default);
|
||||
}
|
||||
|
||||
/**
|
||||
* Читает значение ключа JSON.
|
||||
*
|
||||
* @param string $key Ключ JSON.
|
||||
* @param mixed $default Значение по умолчанию.
|
||||
*
|
||||
* @return mixed Значение ключа JSON или значение по умолчанию.
|
||||
*/
|
||||
public function Read (string $key, mixed $default = null): mixed
|
||||
{
|
||||
// Подготавливаем ключ
|
||||
$key = $this->PrepareKey($key);
|
||||
|
||||
// Проверяем, существует ли ключ
|
||||
if (!$this->IsKeyExists($key))
|
||||
// - если нет, то возвращаем значение по умолчанию
|
||||
return $default;
|
||||
|
||||
// Разбиваем ключ на массив ключей
|
||||
$keys = $this->ParseKey($key);
|
||||
|
||||
// Получаем текущий массив данных
|
||||
$current = $this->JsonData;
|
||||
|
||||
// Для каждого ключа до предпоследнего
|
||||
for ($i = 0; $i < count($keys) - 1; $i++)
|
||||
// - переходим ко вложенному массиву
|
||||
$current = $current[$keys[$i]];
|
||||
|
||||
// Возвращаем значение последнего ключа и если его нет, то возвращаем значение по умолчанию
|
||||
return $current[$keys[count($keys) - 1]] ?? $default;
|
||||
}
|
||||
|
||||
/**
|
||||
* Читает значение ключа JSON как вещественное число.
|
||||
*
|
||||
* @param string $key Ключ JSON.
|
||||
* @param float $default Значение по умолчанию.
|
||||
*
|
||||
* @return float Значение ключа JSON или значение по умолчанию.
|
||||
*/
|
||||
public function ReadFloat (string $key, float $default = 0.0): float
|
||||
{
|
||||
return (float)$this->Read($key, $default);
|
||||
}
|
||||
|
||||
/**
|
||||
* Читает значение ключа JSON как логическое значение.
|
||||
*
|
||||
* @param string $key Ключ JSON.
|
||||
* @param bool $default Значение по умолчанию.
|
||||
*
|
||||
* @return bool Значение ключа JSON или значение по умолчанию.
|
||||
*/
|
||||
public function ReadBool (string $key, bool $default = false): bool
|
||||
{
|
||||
return (bool)$this->Read($key, $default);
|
||||
}
|
||||
|
||||
/**
|
||||
* Читает значение ключа JSON как массив.
|
||||
*
|
||||
* @param string $key Ключ JSON.
|
||||
* @param array $default Значение по умолчанию.
|
||||
*
|
||||
* @return array Значение ключа JSON или значение по умолчанию.
|
||||
*/
|
||||
public function ReadArray (string $key, array $default = []): array
|
||||
{
|
||||
// Получаем значение ключа JSON
|
||||
$serializedDef = json_encode($default);
|
||||
|
||||
// Читаем значение ключа JSON
|
||||
$value = $this->ReadString($key, $serializedDef);
|
||||
|
||||
// Десериализуем значение ключа JSON
|
||||
return json_decode($value, true);
|
||||
}
|
||||
|
||||
/**
|
||||
* Читает значение ключа JSON как строку.
|
||||
*
|
||||
* @param string $key Ключ JSON.
|
||||
* @param string $default Значение по умолчанию.
|
||||
*
|
||||
* @return string Значение ключа JSON или значение по умолчанию.
|
||||
*/
|
||||
public function ReadString (string $key, string $default = ""): string
|
||||
{
|
||||
return (string)$this->Read($key, $default);
|
||||
}
|
||||
|
||||
/**
|
||||
* Читает значение ключа JSON как объект.
|
||||
*
|
||||
* @param string $key Ключ JSON.
|
||||
* @param object $default Значение по умолчанию.
|
||||
*
|
||||
* @return object Значение ключа JSON или значение по умолчанию.
|
||||
*/
|
||||
public function ReadObject (string $key, object $default): object
|
||||
{
|
||||
// Получаем значение ключа JSON
|
||||
$serializedDef = json_encode($default);
|
||||
|
||||
// Читаем значение ключа JSON
|
||||
$value = $this->ReadString($key, $serializedDef);
|
||||
|
||||
// Десериализуем значение ключа JSON
|
||||
return json_decode($value);
|
||||
}
|
||||
|
||||
/**
|
||||
* Читает значение ключа JSON как объект, реализующий интерфейс ISerializable.
|
||||
*
|
||||
* @param string $key Ключ JSON.
|
||||
* @param string $serializableClassName Имя класса, реализующего интерфейс ISerializable, с namespace.
|
||||
*
|
||||
* @return ISerializable Инициализированный объект
|
||||
* @throws JsonException Если класс не реализует интерфейс ISerializable
|
||||
*/
|
||||
public function ReadSerializable (string $key, string $serializableClassName): ISerializable
|
||||
{
|
||||
// Создаем объект
|
||||
$instance = new $serializableClassName();
|
||||
|
||||
// Проверяем, что он реализует интерфейс ISerializable
|
||||
if (!$instance instanceof ISerializable)
|
||||
// - если нет, то выбрасываем исключение
|
||||
throw new JsonException(errorCode: JsonErrorCode::NotISerializable,
|
||||
errorMessage: "Class $serializableClassName is not implements ISerializable interface / Класс $serializableClassName не реализует интерфейс ISerializable");
|
||||
|
||||
// Получаем строку JSON из ключа
|
||||
$json = $this->ReadString($key, $instance->Serialize());
|
||||
|
||||
// Десериализуем строку JSON в объект
|
||||
$instance->UnSerialize($json);
|
||||
|
||||
// Возвращаем объект
|
||||
return $instance;
|
||||
}
|
||||
}
|
||||
109
sources/traits/JsonReWriter/JsonReWriterWriteTrait.php
Normal file
109
sources/traits/JsonReWriter/JsonReWriterWriteTrait.php
Normal file
@ -0,0 +1,109 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_components_pack\traits\JsonReWriter;
|
||||
|
||||
use goodboyalex\php_components_pack\enums\JsonErrorCode;
|
||||
use goodboyalex\php_components_pack\exceptions\JsonException;
|
||||
use goodboyalex\php_components_pack\interfaces\ISerializable;
|
||||
|
||||
/**
|
||||
* Часть кода класса JsonReWriter, отвечающая за методы записи ключей и значений JSON.
|
||||
*
|
||||
* @author Александр Бабаев
|
||||
* @package php_components_pack
|
||||
* @version 1.0
|
||||
* @since 1.1.0
|
||||
*/
|
||||
trait JsonReWriterWriteTrait
|
||||
{
|
||||
/**
|
||||
* Записывает объект в ключ JSON.
|
||||
*
|
||||
* @param string $key Ключ JSON.
|
||||
* @param object $value Записываемое значение.
|
||||
*
|
||||
* @return void
|
||||
* @throws JsonException Ключ не содержит вложений, хотя от него требуется обратное.
|
||||
*/
|
||||
public function WriteObject (string $key, object $value): void
|
||||
{
|
||||
$this->Write($key, json_encode($value));
|
||||
}
|
||||
|
||||
/**
|
||||
* Записывает значение в ключ JSON.
|
||||
*
|
||||
* @param string $key Ключ JSON.
|
||||
* @param mixed $value Записываемое значение.
|
||||
*
|
||||
* @return void
|
||||
* @throws JsonException Ключ не содержит вложений, хотя от него требуется обратное.
|
||||
*/
|
||||
public function Write (string $key, mixed $value): void
|
||||
{
|
||||
// Подготавливаем ключ
|
||||
$key = $this->PrepareKey($key);
|
||||
|
||||
// Получаем массив ключей по вложенности
|
||||
$keys = $this->ParseKey($key);
|
||||
|
||||
// Получаем текущий массив данных
|
||||
$current = &$this->JsonData;
|
||||
|
||||
// Для каждого ключа до предпоследнего
|
||||
for ($i = 0; $i < count($keys) - 1; $i++) {
|
||||
// - проверяем наличие ключа в текущем массиве
|
||||
if (!isset($current[$keys[$i]]))
|
||||
// - нет? Создаем ключ (массив)
|
||||
$current[$keys[$i]] = [];
|
||||
|
||||
// - проверяем, что ключ является массивом
|
||||
if (!is_array($current[$keys[$i]]))
|
||||
// - нет? Выбрасываем исключение
|
||||
throw new JsonException(errorCode: JsonErrorCode::KeyIsNotArray,
|
||||
errorMessage: "The key does not contain attachments, although it is required to do the opposite / Ключ не содержит вложений, хотя от него требуется обратное!");
|
||||
|
||||
// - переходим ко вложенному массиву
|
||||
$current = &$current[$keys[$i]];
|
||||
}
|
||||
|
||||
// Создаем ключ (значение)
|
||||
$current[$keys[count($keys) - 1]] = $value;
|
||||
}
|
||||
|
||||
/**
|
||||
* Записывает объект, реализующий интерфейс ISerializable, в ключ JSON.
|
||||
*
|
||||
* @param string $key Ключ JSON.
|
||||
* @param ISerializable $serializableValue Записываемый объект, реализующий интерфейс ISerializable.
|
||||
*
|
||||
* @return void
|
||||
* @throws JsonException Ключ не содержит вложений, хотя от него требуется обратное.
|
||||
*/
|
||||
public function WriteSerializable (string $key, ISerializable $serializableValue): void
|
||||
{
|
||||
// Сериализуем объект
|
||||
$serialized = $serializableValue->Serialize();
|
||||
|
||||
// Записываем в ключ
|
||||
$this->Write($key, $serialized);
|
||||
}
|
||||
|
||||
/**
|
||||
* Записывает массив в ключ JSON.
|
||||
*
|
||||
* @param string $key Ключ JSON.
|
||||
* @param array $array Массив для записи.
|
||||
*
|
||||
* @return void
|
||||
* @throws JsonException Ключ не содержит вложений, хотя от него требуется обратное.
|
||||
*/
|
||||
public function WriteArray (string $key, array $array): void
|
||||
{
|
||||
// Сериализуем массив
|
||||
$serialized = json_encode($array);
|
||||
|
||||
// Записываем в ключ
|
||||
$this->Write($key, $serialized);
|
||||
}
|
||||
}
|
||||
119
sources/types/BoolEx.php
Normal file
119
sources/types/BoolEx.php
Normal file
@ -0,0 +1,119 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_components_pack\types;
|
||||
|
||||
/**
|
||||
* Тип-расширение для типа bool.
|
||||
*
|
||||
* @author Александр Бабаев
|
||||
* @package php_components_pack
|
||||
* @version 1.0
|
||||
* @since 1.1.1
|
||||
*/
|
||||
final class BoolEx
|
||||
{
|
||||
/**
|
||||
* @var int $False Значение "ложь".
|
||||
*/
|
||||
public const int False = -1;
|
||||
|
||||
/**
|
||||
* @var int $Null Значение не установлено (и не истина, и не ложь).
|
||||
*/
|
||||
public const int Null = 0;
|
||||
|
||||
/**
|
||||
* @var int $True Значение "истина".
|
||||
*/
|
||||
public const int True = 1;
|
||||
|
||||
/**
|
||||
* @var int $Value Хранимое значение.
|
||||
*/
|
||||
private int $Value;
|
||||
|
||||
public function __construct (?bool $value = null)
|
||||
{
|
||||
// Присваиваем значение
|
||||
$this->Value = $value === null ? self::Null : ($value ? self::True : self::False);
|
||||
}
|
||||
|
||||
/**
|
||||
* Преобразует значение в экземпляр типа.
|
||||
*
|
||||
* ВАЖНО: при преобразовании в тип будет использована следующая логика:
|
||||
*
|
||||
* - <code>'true'</code>, <code>'1'</code>, <code>'on'</code>, <code>'yes'</code>, <code>'y'</code>,
|
||||
* <code>'t'</code>, <code>true</code>, <code>1</code>, <code>1.0</code> считаются как истина;
|
||||
* - <code>'false'</code>, <code>'0'</code>, <code>'off'</code>, <code>'no'</code>, <code>'n'</code>,
|
||||
* <code>'f'</code>, <code>false</code>, <code>-1</code>, <code>-1.0</code> считаются как ложь;
|
||||
* - все остальные значения считаются как неустановленною (и не истина, и не ложь).
|
||||
*
|
||||
* @param mixed $value Значение.
|
||||
*
|
||||
* @return BoolEx Возвращает экземпляр типа.
|
||||
*/
|
||||
public static function Parse (mixed $value): BoolEx
|
||||
{
|
||||
// Преобразуем значение в тип
|
||||
$value = match ($value) {
|
||||
'true', '1', 'on', 'yes', 'y', 't', true, 1, 1.0 => self::True,
|
||||
'false', '0', 'off', 'no', 'n', 'f', false, -1, -1.0 => self::False,
|
||||
default => self::Null
|
||||
};
|
||||
|
||||
// Создаем экземпляр типа
|
||||
return new BoolEx($value);
|
||||
}
|
||||
|
||||
/**
|
||||
* Проверяет, является ли значение ложью.
|
||||
*
|
||||
* @return bool Возвращает, является ли значение ложью.
|
||||
*/
|
||||
public function IsFalse (): bool
|
||||
{
|
||||
return $this->Value === self::False;
|
||||
}
|
||||
|
||||
/**
|
||||
* Проверяет, является ли значение истиной.
|
||||
*
|
||||
* @return bool Возвращает, является ли значение истиной.
|
||||
*/
|
||||
public function IsTrue (): bool
|
||||
{
|
||||
return $this->Value === self::True;
|
||||
}
|
||||
|
||||
/**
|
||||
* Возвращает строковое представление значения.
|
||||
*
|
||||
* @return string Возвращает строковое представление значения.
|
||||
*/
|
||||
public function __toString (): string
|
||||
{
|
||||
// Преобразуем значение в строку
|
||||
return match ($this->Value) {
|
||||
self::True => "true",
|
||||
self::False => "false",
|
||||
self::Null => "null"
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Конвертирует значение в bool.
|
||||
*
|
||||
* @param bool $onNull Значение, возвращаемое при неустановленном значении.
|
||||
*
|
||||
* @return bool Возвращает значение, конвертированное в bool.
|
||||
*/
|
||||
public function AsBool (bool $onNull = false): bool
|
||||
{
|
||||
return match ($this->Value) {
|
||||
self::True => true,
|
||||
self::False => false,
|
||||
default => $onNull
|
||||
};
|
||||
}
|
||||
}
|
||||
710
sources/types/JsonReWriter.md
Normal file
710
sources/types/JsonReWriter.md
Normal file
@ -0,0 +1,710 @@
|
||||
# Описание класса JsonReWriter
|
||||
|
||||
## Информация о версии
|
||||
|
||||
Версия класса: 1.0
|
||||
|
||||
Впервые введено в пакет с версии: 1.1.0
|
||||
|
||||
Описание класса: Класс для работы с JSON-файлами.
|
||||
|
||||
## Публичные свойства и константы класса
|
||||
|
||||
В классе определены следующие свойства:
|
||||
|
||||
- `string $JsonString` - строка JSON (чтение/запись).
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
### Правила формирования ключей.
|
||||
|
||||
Ключ для чтения/записи данных класса формируется следующим образом: `ключ/подключ/подключ подключа` .
|
||||
|
||||
Например, если дан json-файл:
|
||||
|
||||
{
|
||||
"test": {
|
||||
"subtest": {
|
||||
"AAA": "123",
|
||||
"BBB": 1.23
|
||||
}
|
||||
},
|
||||
"test1": {
|
||||
"test": 123
|
||||
},
|
||||
"test2": {
|
||||
"test": true
|
||||
},
|
||||
"test3": {
|
||||
"test": {
|
||||
"res": "[1,2,3]"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Пусть требуется получить значение `BBB`, тогда ключ должен быть `test/subtest/BBB`.
|
||||
|
||||
### Чтение.
|
||||
|
||||
1. Создайте элемент класса `$json = new JsonReWriter ();`
|
||||
2. Если у вас требуется загрузить json из файла `$fileName`, то воспользуйтесь методом `LoadFromFile`:
|
||||
`$json->LoadFromFile($fileName);`, если же json представлен строкой `$jsonStr`, то загрузите её в свойство
|
||||
`$JsonString`: `$json->JsonString = $jsonStr;`
|
||||
3. Далее можно пользоваться любым методом для чтения `Read*`, в том числе и общим `$json->Read(...)`.
|
||||
|
||||
**Пример:**
|
||||
|
||||
// Имя файла
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
// Создаю класс
|
||||
$json = new JsonReWriter();
|
||||
// Загшружаю данные из файла
|
||||
$json->LoadFromFile($fileName);
|
||||
// Получаю число
|
||||
$float = $json->ReadFloat("test/subtest/BBB", 0.2);
|
||||
|
||||
В итоге в `$float` будет `1.23`.
|
||||
|
||||
### Запись.
|
||||
|
||||
1. Создайте элемент класса `$json = new JsonReWriter ();`
|
||||
2. Далее можно пользоваться любым методом для записи `Write*`, в том числе и общим `$json->Write(...)`.
|
||||
3. Если вам требуется создать json файл с именем `$fileName`, то воспользуйтесь методом `SaveToFile`:
|
||||
`$json->SaveToFile($fileName);`, если же json должен быть представлен строкой `$jsonStr`, то загрузите её из свойства
|
||||
`$JsonString`: `$jsonStr = $json->JsonString;`
|
||||
|
||||
**Пример:**
|
||||
|
||||
// Имя файла
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
// Создаю класс
|
||||
$json = new JsonReWriter();
|
||||
// Загшружаю данные из файла
|
||||
$json->LoadFromFile($fileName);
|
||||
// Получаю число
|
||||
try {
|
||||
$json->Write("test/subtest/BBB", 0.2);
|
||||
}
|
||||
catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
В итоге в `test/subtest/BBB` вместо `1.23` будет `0.2`.
|
||||
|
||||
## Коды ошибок JsonErrorCode
|
||||
|
||||
Ниже представлена таблица основных кодов ошибки:
|
||||
|
||||
| Ошибка | Описание | Введено с версии |
|
||||
|:-------------------:|:---------------------------------------------------------------------------:|:----------------:|
|
||||
| Unknown | Неизвестная ошибка | 1.0 |
|
||||
| None | Ошибок нет | 1.0 |
|
||||
| Depth | Достигнута максимальная глубина стека | 1.0 |
|
||||
| StateMismatch | Неверный или некорректный JSON | 1.0 |
|
||||
| CTRLChar | Ошибка управляющего символа, возможно, неверная кодировка | 1.0 |
|
||||
| Syntax | Синтаксическая ошибка | 1.0 |
|
||||
| UTF8 | Некорректные для кодировки UTF-8 символы, возможно, неверная кодировка | 1.0 |
|
||||
| Recursion | Одна или несколько зацикленных ссылок в кодируемом значении | 1.0 |
|
||||
| InfOrNan | Одно или несколько значений NAN или INF в кодируемом значении | 1.0 |
|
||||
| UnsupportedType | Передали значение с неподдерживаемым типом | 1.0 |
|
||||
| InvalidPropertyName | Имя свойства не может быть закодировано | 1.0 |
|
||||
| UTF16 | Некорректный для кодировки UTF-16 символ, возможно, некорректно закодирован | 1.0 |
|
||||
| KeyIsNotArray | Ключ не содержит вложений, хотя от него требуется обратное | 1.0 |
|
||||
| NotISerializable | Класс не реализует интерфейс ISerializable | 1.0 |
|
||||
|
||||
### Методы и функции перечисления JsonErrorCode
|
||||
|
||||
Перечисление содержит **статический метод** `static function FromLastError (): JsonErrorCode`, который получает код
|
||||
ошибки из последней JSON ошибки.
|
||||
|
||||
Например, при успешной загрузке, можем проверить ошибки:
|
||||
|
||||
$errors = JsonErrorCode::FromLastError ();
|
||||
|
||||
После того, как мы выведем `$errors`, мы получим `JsonErrorCode::None`.
|
||||
|
||||
## Исключение JsonException
|
||||
|
||||
Исключение расширяет класс `Exception`, поэтому может выбрасываться через `throw`.
|
||||
|
||||
### Свойства
|
||||
|
||||
Исключение содержит следующие свойства:
|
||||
|
||||
- `?string $JsonString` - строка JSON (или null);
|
||||
- `JsonErrorCode $ErrorCode` - код ошибки JSON;
|
||||
- `?string $ErrorMessage` - сообщение об ошибке JSON (в отличие от функции json_last_error_msg(), данная переменная при
|
||||
отсутствии ошибок выводит null, а не "No error").
|
||||
|
||||
### Методы и функции
|
||||
|
||||
#### Конструктор.
|
||||
|
||||
Конструктор принимает **3 необязательных параметра**:
|
||||
|
||||
* `?string $json` - строка JSON (по умолчанию, `null`);
|
||||
* `JsonErrorCode $errorCode` - код ошибки (по умолчанию, `JsonErrorCode::Unknown`);
|
||||
* `?string $errorMessage` - сообщение об ошибке (по умолчанию, `null`).
|
||||
|
||||
В результате создаётся новое исключение `JsonException`.
|
||||
|
||||
Пример:
|
||||
|
||||
throw new JsonException("{}", JsonErrorCode::Depth, "Пример");
|
||||
|
||||
Создаст исключение `JsonException`.
|
||||
|
||||
## Методы и функции
|
||||
|
||||
### Конструктор и деструктор.
|
||||
|
||||
Конструктор не принимает никаких параметров.
|
||||
|
||||
В результате создаётся новый класс `JsonReWriter`.
|
||||
|
||||
**Пример:**
|
||||
|
||||
// Контсуктор
|
||||
$json = new JsonReWriter ();
|
||||
// Деструктор
|
||||
unset($json);
|
||||
|
||||
Создаст и уничтожит класс `JsonReWriter`.
|
||||
|
||||
### Сохранение и загрузка из файла.
|
||||
|
||||
За сохранение и загрузку отвечают 2 метода: `SaveToFile` и `LoadFromFile`.
|
||||
|
||||
#### Сохранение в файл (метод `SaveToFile`)
|
||||
|
||||
Этот метод сохраняет содержимое JSON в файл. Он содержит **1 обязательный параметр**:
|
||||
|
||||
* `string $fileName` - имя файла на диске.
|
||||
|
||||
Метод возвращает `bool` - сохранены ли данные в файл: `true` - да, `false` - нет.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function SaveToFile (string $fileName): bool
|
||||
|
||||
**Пример:**
|
||||
|
||||
// Имя файла
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
// Сохраняем созданный JSON файл
|
||||
$json->SaveToFile($fileName);
|
||||
|
||||
Содержимое файла `test.json` представлено далее:
|
||||
|
||||
{
|
||||
"test": {
|
||||
"subtest": {
|
||||
"AAA": "123",
|
||||
"BBB": 1.23
|
||||
}
|
||||
},
|
||||
"test1": {
|
||||
"test": 123
|
||||
},
|
||||
"test2": {
|
||||
"test": true
|
||||
},
|
||||
"test3": {
|
||||
"test": {
|
||||
"res": "[1,2,3]"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#### Загрузка файла (метод `LoadFromFile`)
|
||||
|
||||
Этот метод загружает содержимое файла в класс. Он содержит **1 обязательный параметр**:
|
||||
|
||||
* `string $fileName` - имя файла на диске.
|
||||
|
||||
Метод возвращает `bool` - загружены ли данные из файла: `true` - да, `false` - нет.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function LoadFromFile (string $fileName): bool
|
||||
|
||||
**Пример:**
|
||||
Пусть дан файл `test.json`, содержимое которого представлено далее:
|
||||
|
||||
{
|
||||
"test": {
|
||||
"subtest": {
|
||||
"AAA": "123",
|
||||
"BBB": 1.23
|
||||
}
|
||||
},
|
||||
"test1": {
|
||||
"test": 123
|
||||
},
|
||||
"test2": {
|
||||
"test": true
|
||||
},
|
||||
"test3": {
|
||||
"test": {
|
||||
"res": "[1,2,3]"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Следующий код загрузит это содержимое в класс:
|
||||
|
||||
// Имя файла
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Загружаю данные
|
||||
$json->LoadFromFile($fileName);
|
||||
|
||||
### Чтение данных
|
||||
|
||||
Для чтения данных используется один общий метод `Read` и 7 его производных метода: `ReadString`, `ReadInt`, `ReadFloat`,
|
||||
`ReadBool`, `ReadArray`, `ReadObject` и `ReadSerializable`.
|
||||
|
||||
#### Метод `Read`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **1 обязательный параметр** `string $key` (ключ) и **1
|
||||
необязательный параметр** `mixed $default` (значение по умолчанию, задан по умолчанию в `null`).
|
||||
|
||||
Этот метод возвращает `mixed`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function Read (string $key, mixed $default = null): mixed
|
||||
|
||||
**Пример,**
|
||||
|
||||
// Создаю класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполняю данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->Write("test3/test/res", json_encode([1, 2, 3]));
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
// Получаю значение
|
||||
$float = (float)$json->Read("test/subtest/BBB"));
|
||||
|
||||
В результате, переменная `$float` будет иметь значение `1.23`.
|
||||
|
||||
#### Метод `ReadString`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **1 обязательный параметр** `string $key` (ключ) и **1
|
||||
необязательный параметр** `string $default` (значение по умолчанию, задан по умолчанию в `""`).
|
||||
|
||||
Этот метод возвращает `string`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadString (string $key, string $default = ""): string
|
||||
|
||||
#### Метод `ReadInt`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **1 обязательный параметр** `string $key` (ключ) и **1
|
||||
необязательный параметр** `int $default` (значение по умолчанию, задан по умолчанию в `0`).
|
||||
|
||||
Этот метод возвращает `int`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadInt (string $key, int $default = 0): int
|
||||
|
||||
#### Метод `ReadFloat`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **1 обязательный параметр** `string $key` (ключ) и **1
|
||||
необязательный параметр** `float $default` (значение по умолчанию, задан по умолчанию в `0.0`).
|
||||
|
||||
Этот метод возвращает `float`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadFloat (string $key, float $default = 0.0): float
|
||||
|
||||
#### Метод `ReadBool`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **1 обязательный параметр** `string $key` (ключ) и **1
|
||||
необязательный параметр** `bool $default` (значение по умолчанию, задан по умолчанию в `false`).
|
||||
|
||||
Этот метод возвращает `bool`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadBool (string $key, bool $default = false): bool
|
||||
|
||||
#### Метод `ReadArray`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **1 обязательный параметр** `string $key` (ключ) и **1
|
||||
необязательный параметр** `array $default` (значение по умолчанию, задан по умолчанию в `[]`).
|
||||
|
||||
Этот метод возвращает `array`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadArray (string $key, array $default = []): array
|
||||
|
||||
#### Метод `ReadObject`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **2 обязательных параметра**:
|
||||
|
||||
- `string $key` (ключ);
|
||||
- `object $default` (значение по умолчанию).
|
||||
|
||||
Этот метод возвращает `object`: значение ключа JSON или значение по умолчанию.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadObject (string $key, object $default): object
|
||||
|
||||
#### Метод `ReadSerializable`
|
||||
|
||||
Это метод, который читает значение ключа JSON. Он имеет **2 обязательных параметра**:
|
||||
|
||||
- `string $key` (ключ);
|
||||
- `string $serializableClassName` (имя класса, реализующего интерфейс ISerializable, с namespace).
|
||||
|
||||
Этот метод возвращает класс, реализующий интерфейс `ISerializable`.
|
||||
|
||||
**Важно!** Этот метод может выбросить исключение `JsonException`, если класс, заданный в `$serializableClassName` не
|
||||
реализует интерфейс `ISerializable`.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function ReadSerializable (string $key, string $serializableClassName): ISerializable
|
||||
|
||||
**Пример,**
|
||||
|
||||
Пусть для примера, класс `Demo` из namespace `iam\namespace` реализует интерфейс `ISerializable`.
|
||||
|
||||
// Создаю класс
|
||||
$json = new JsonReWriter();
|
||||
// ... Здесь где-то загрузка данных
|
||||
// Получаю класс
|
||||
try {
|
||||
/**
|
||||
* @var Demo $unSerializableClass
|
||||
*/
|
||||
$unSerializableClass = $json->ReadSerializable("test", "iam\\namespace\\Demo");
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
В результате, переменная `$unSerializableClass` будет содержать данные класса `Demo`.
|
||||
|
||||
### Запись данных
|
||||
|
||||
Для чтения данных используется один общий метод `Write` и 3 его производных метода: `WriteArray`, `WriteObject` и
|
||||
`WriteSerializable`.
|
||||
|
||||
**Важно!** Лобой из вышеуказанных методов может выбросить исключение `JsonException`, если ключ не содержит вложений,
|
||||
хотя от него требуется обратное.
|
||||
|
||||
#### Метод `Write`
|
||||
|
||||
Это метод, который записывает значение в ключ JSON. Он имеет **2 обязательных параметра**:
|
||||
|
||||
- `string $key` (ключ);
|
||||
- `mixed $value` (записываемое значение).
|
||||
|
||||
Этот метод ничего не возвращает.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function Write (string $key, mixed $value): void
|
||||
|
||||
**Пример,**
|
||||
|
||||
// Имя файла
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
// Сохраняем созданный JSON файл
|
||||
$json->SaveToFile($fileName);
|
||||
|
||||
Содержимое файла `test.json` представлено далее:
|
||||
|
||||
{
|
||||
"test": {
|
||||
"subtest": {
|
||||
"AAA": "123",
|
||||
"BBB": 1.23
|
||||
}
|
||||
},
|
||||
"test1": {
|
||||
"test": 123
|
||||
},
|
||||
"test2": {
|
||||
"test": true
|
||||
},
|
||||
"test3": {
|
||||
"test": {
|
||||
"res": "[1,2,3]"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#### Метод `WriteArray`
|
||||
|
||||
Это метод, который записывает значение в ключ JSON. Он имеет **2 обязательных параметра**:
|
||||
|
||||
- `string $key` (ключ);
|
||||
- `array $array` (записываемое значение).
|
||||
|
||||
Этот метод ничего не возвращает.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function WriteArray (string $key, array $array): void
|
||||
|
||||
#### Метод `WriteObject`
|
||||
|
||||
Это метод, который записывает значение в ключ JSON. Он имеет **2 обязательных параметра**:
|
||||
|
||||
- `string $key` (ключ);
|
||||
- `object $value` (записываемое значение).
|
||||
|
||||
Этот метод ничего не возвращает.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function WriteObject (string $key, object $value): void
|
||||
|
||||
#### Метод `WriteSerializable`
|
||||
|
||||
Это метод, который записывает значение в ключ JSON. Он имеет **2 обязательных параметра**:
|
||||
|
||||
- `string $key` (ключ);
|
||||
- `ISerializable $serializableValue` (записываемое значение).
|
||||
|
||||
Этот метод ничего не возвращает.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function WriteSerializable (string $key, ISerializable $serializableValue): void
|
||||
|
||||
**Пример,**
|
||||
Пусть для примера, класс `Demo` из namespace `iam\namespace` реализует интерфейс `ISerializable`.
|
||||
|
||||
// Имя файла
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Создаём класс Demo
|
||||
$serializableClass = new Demo(...);
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->WriteSerializable("test", $serializableClass);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
...
|
||||
|
||||
### Работа с ключами JSON
|
||||
|
||||
Для работы с ключами JSON есть 2 метода: `IsKeyExists` и `GetKeys`.
|
||||
|
||||
#### Метод `IsKeyExists`
|
||||
|
||||
Это метод проверяем наличие ключа в JSON. Он имеет **1 обязательный параметр** - `string $key` (ключ).
|
||||
|
||||
Этот метод возвращает `bool`: `true` если ключ найден и `false` в противном случае.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function IsKeyExists (string $key): bool
|
||||
|
||||
**Пример,**
|
||||
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
// Проверяем ключи
|
||||
$check1 = $json->IsKeyExists("test/subtest/AAA");
|
||||
$check2 = $json->IsKeyExists("test/subtest/ССС");
|
||||
|
||||
В результате, `$check1` будет `true`, а `$check2` - `false`.
|
||||
|
||||
#### Метод `GetKeys`
|
||||
|
||||
Это метод получает список ключей. Он имеет **2 необязательных параметра**:
|
||||
|
||||
- `string $parentKey` (ключ родителя (или "" (установлено по умолчанию) для всех);
|
||||
- `bool $includeChildren` (нужно ли включать дочерние ключи (по умолчанию, да)).
|
||||
|
||||
Этот метод возвращает `array`: список ключей.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function GetKeys (string $parentKey = "", bool $includeChildren = true): array
|
||||
|
||||
**Пример,**
|
||||
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
// Получаем ключи
|
||||
$keys1 = $json->GetKeys("test");
|
||||
$keys2 = $json->GetKeys("test", false);
|
||||
$keys3 = $json->GetKeys();
|
||||
|
||||
В результате, `$key1` будет следующим массивом:
|
||||
|
||||
[
|
||||
"test/subtest",
|
||||
"test/subtest/AAA",
|
||||
"test/subtest/BBB"
|
||||
]
|
||||
|
||||
`$key2` будет следующим массивом:
|
||||
|
||||
[
|
||||
"subtest"
|
||||
]
|
||||
|
||||
`$key3` будет следующим массивом:
|
||||
|
||||
[
|
||||
"test",
|
||||
"test/subtest",
|
||||
"test/subtest/AAA",
|
||||
"test/subtest/BBB",
|
||||
"test1",
|
||||
"test1/test",
|
||||
"test2",
|
||||
"test2/test",
|
||||
"test3",
|
||||
"test3/test",
|
||||
"test3/test/res"
|
||||
]
|
||||
|
||||
### Удаление ключей JSON
|
||||
|
||||
Для удаления ключей JSON есть 2 метода: `DeleteKey`, который удаляет только определённый ключ и `Clear`, который удаляет
|
||||
**все ключи** из json-файла.
|
||||
|
||||
#### Метод `DeleteKey`
|
||||
|
||||
Это метод удаляет только определённый ключ в JSON. Он имеет **1 обязательный параметр** - `string $key` (ключ).
|
||||
|
||||
Этот метод возвращает `bool` - результат удаления ключа: `true` - удаление прошло успешно, `false` - произошла ошибка
|
||||
при удалении.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function DeleteKey (string $key): bool
|
||||
|
||||
**Пример,**
|
||||
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
// Получаемем ключи до удаления
|
||||
$check1 = $json->GetKeys("test/subtest");
|
||||
// Удаляем ключ
|
||||
$this->DeleteKey("test/subtest/BBB");
|
||||
// Получаемем ключи после удаления
|
||||
$check2 = $json->GetKeys("test/subtest");
|
||||
|
||||
В результате, `$check1` будет
|
||||
|
||||
[
|
||||
"test/subtest",
|
||||
"test/subtest/AAA",
|
||||
"test/subtest/BBB"
|
||||
]
|
||||
|
||||
а `$check2`:
|
||||
|
||||
[
|
||||
"test/subtest",
|
||||
"test/subtest/AAA"
|
||||
]
|
||||
|
||||
#### Метод `Clear`
|
||||
|
||||
Это метод удаляет **все ключи** из json-файла. Он не имеет никаких параметров и ничего не возвращает.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public function Clear (): void
|
||||
|
||||
**Пример,**
|
||||
|
||||
// Создаём класс
|
||||
$json = new JsonReWriter();
|
||||
// Заполним данными
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
} catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
// Очищаем
|
||||
$json->Clear();
|
||||
// Получаем ключи
|
||||
$keys = $json->GetKeys();
|
||||
|
||||
В результате, `$key` будет следующим массивом:
|
||||
|
||||
[
|
||||
]
|
||||
@ -27,6 +27,7 @@ class ClassMapperTest extends TestCase
|
||||
{
|
||||
require_once __DIR__ . '/../data/A.php';
|
||||
require_once __DIR__ . '/../data/B.php';
|
||||
require_once __DIR__ . '/../../sources/attributes/GetOnly.php';
|
||||
require_once __DIR__ . '/../../sources/classes/classMapper.php';
|
||||
}
|
||||
}
|
||||
94
tests/classes/FileTest.php
Normal file
94
tests/classes/FileTest.php
Normal file
@ -0,0 +1,94 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_components_pack\tests\classes;
|
||||
|
||||
use goodboyalex\php_components_pack\classes\File;
|
||||
use PHPUnit\Framework\TestCase;
|
||||
|
||||
class FileTest extends TestCase
|
||||
{
|
||||
public function testExtractFileName ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$this->assertEquals("test.txt", File::ExtractFileName("c:\\tmp\\test.txt"));
|
||||
$this->assertEquals("test.txt", File::ExtractFileName("c:/tmp/test.txt"));
|
||||
$this->assertEquals("test.txt", File::ExtractFileName("\\tmp\\test.txt"));
|
||||
}
|
||||
|
||||
private function PrepareForTest (): void
|
||||
{
|
||||
require_once __DIR__ . '/../../sources/classes/File.php';
|
||||
}
|
||||
|
||||
public function testFindFiles ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$result = File::FindFiles(__DIR__);
|
||||
|
||||
$this->assertIsArray($result);
|
||||
$this->assertCount(8, $result);
|
||||
}
|
||||
|
||||
public function testGetRelativePath ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$fullPath = "c:\\source\\tmp\\test.txt";
|
||||
|
||||
$basePath = "c:\\source\\";
|
||||
|
||||
$this->assertEquals("tmp\\test.txt", File::GetRelativePath($fullPath, $basePath));
|
||||
}
|
||||
|
||||
public function testExtractFileExtension ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$this->assertEquals("txt", File::ExtractFileExtension("c:\\tmp\\test.txt"));
|
||||
$this->assertEquals("txt", File::ExtractFileExtension("c:/tmp/test.txt"));
|
||||
$this->assertEquals("txt", File::ExtractFileExtension("\\tmp\\test.txt"));
|
||||
}
|
||||
|
||||
public function testExtractFileNameWithoutExtension ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$this->assertEquals("test", File::ExtractFileNameWithoutExtension("c:\\tmp\\test.txt"));
|
||||
$this->assertEquals("test", File::ExtractFileNameWithoutExtension("c:/tmp/test.txt"));
|
||||
$this->assertEquals("test", File::ExtractFileNameWithoutExtension("\\tmp\\test.txt"));
|
||||
}
|
||||
|
||||
public function testRemoveDir ()
|
||||
{
|
||||
/**
|
||||
* ВАЖНО! Перед запуском теста необходимо создать директорию D:\TestDelete и наполнить её ненужными файлами
|
||||
*/
|
||||
|
||||
$this->PrepareForTest();
|
||||
|
||||
$result = File::RemoveDir("D:/TestDelete");
|
||||
|
||||
$this->assertTrue($result->Value);
|
||||
$this->assertFalse(File::DirectoryExists("D:\\TestDelete"));
|
||||
}
|
||||
|
||||
public function testFileSize ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$size = File::FileSize("C:\\Windows/explorer.exe");
|
||||
|
||||
$this->assertEquals(2774080, $size->Value);
|
||||
}
|
||||
|
||||
public function testFileSizeString ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$size = File::FileSizeToString(2774080);
|
||||
|
||||
$this->assertEquals("2,65 МБ", $size);
|
||||
}
|
||||
}
|
||||
319
tests/classes/JsonReWriterTest.php
Normal file
319
tests/classes/JsonReWriterTest.php
Normal file
@ -0,0 +1,319 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_components_pack\tests\classes;
|
||||
|
||||
use goodboyalex\php_components_pack\classes\File;
|
||||
use goodboyalex\php_components_pack\classes\BoolEx;
|
||||
use goodboyalex\php_components_pack\exceptions\JsonException;
|
||||
use goodboyalex\php_components_pack\tests\data\A;
|
||||
use goodboyalex\php_components_pack\tests\data\C;
|
||||
use PHPUnit\Framework\TestCase;
|
||||
|
||||
class JsonReWriterTest extends TestCase
|
||||
{
|
||||
public function testIsKeyExists ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$json = new BoolEx();
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
}
|
||||
catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
$this->assertTrue($json->IsKeyExists("test/subtest/AAA"));
|
||||
}
|
||||
|
||||
private function PrepareForTest (): void
|
||||
{
|
||||
require_once __DIR__ . '/../../sources/exceptions/JsonException.php';
|
||||
require_once __DIR__ . '/../../sources/traits/JsonReWriter/JsonReWriterDeleteTrait.php';
|
||||
require_once __DIR__ . '/../../sources/traits/JsonReWriter/JsonReWriterKeyTrait.php';
|
||||
require_once __DIR__ . '/../../sources/traits/JsonReWriter/JsonReWriterLoadSaveTrait.php';
|
||||
require_once __DIR__ . '/../../sources/traits/JsonReWriter/JsonReWriterReadTrait.php';
|
||||
require_once __DIR__ . '/../../sources/traits/JsonReWriter/JsonReWriterWriteTrait.php';
|
||||
require_once __DIR__ . '/../../sources/classes/JsonReWriter.php';
|
||||
require_once __DIR__ . '/../data/A.php';
|
||||
require_once __DIR__ . '/../data/C.php';
|
||||
}
|
||||
|
||||
public function testReadWriteInt ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$json = new BoolEx();
|
||||
try {
|
||||
$json->Write("test/test", 123);
|
||||
}
|
||||
catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
$this->assertEquals(123, $json->ReadInt("test/test"));
|
||||
}
|
||||
|
||||
public function testReadWriteBool ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$json = new BoolEx();
|
||||
try {
|
||||
$json->Write("test/test1", false);
|
||||
$json->Write("test/test2", true);
|
||||
}
|
||||
catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
$this->assertTrue($json->ReadBool("test/test2"));
|
||||
$this->assertFalse($json->ReadBool("test/test1"));
|
||||
}
|
||||
|
||||
public function testReadWriteString ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$json = new BoolEx();
|
||||
try {
|
||||
$json->Write("test/test", "test string");
|
||||
}
|
||||
catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
$this->assertEquals("test string", $json->ReadString("test/test", "test this"));
|
||||
}
|
||||
|
||||
public function testSaveToFile ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
|
||||
if (file_exists($fileName))
|
||||
unlink($fileName);
|
||||
|
||||
$json = new BoolEx();
|
||||
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
}
|
||||
catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
$json->SaveToFile($fileName);
|
||||
|
||||
$this->assertFileExists($fileName);
|
||||
|
||||
$size = File::FileSize($fileName)->Value;
|
||||
|
||||
$this->assertEquals(268, $size);
|
||||
|
||||
unlink($fileName);
|
||||
}
|
||||
|
||||
public function testReadWriteArray ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$json = new BoolEx();
|
||||
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
}
|
||||
catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
$this->assertArrayIsEqualToArrayIgnoringListOfKeys([1, 2, 3], $json->ReadArray("test3/test/res"), []);
|
||||
}
|
||||
|
||||
public function testClear ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$json = new BoolEx();
|
||||
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
}
|
||||
catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
$json->Clear();
|
||||
|
||||
$this->assertCount(0, $json->GetKeys());
|
||||
}
|
||||
|
||||
public function testReadWriteObject ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$json = new BoolEx();
|
||||
|
||||
$class = new A("test", 123, true);
|
||||
|
||||
try {
|
||||
$json->WriteObject("test", $class);
|
||||
}
|
||||
catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
$this->assertEquals("test", $json->ReadObject("test", new A())->a);
|
||||
}
|
||||
|
||||
public function testLoadFromFile ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$fileName = __DIR__ . "/test.json";
|
||||
|
||||
if (file_exists($fileName))
|
||||
unlink($fileName);
|
||||
|
||||
$json = new BoolEx();
|
||||
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
}
|
||||
catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
$json->SaveToFile($fileName);
|
||||
|
||||
unset($json);
|
||||
|
||||
$json = new BoolEx();
|
||||
|
||||
$json->LoadFromFile($fileName);
|
||||
|
||||
unlink($fileName);
|
||||
|
||||
$this->assertEquals(123, $json->ReadInt("test1/test"));
|
||||
}
|
||||
|
||||
public function testDeleteKey ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$json = new BoolEx();
|
||||
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
}
|
||||
catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
$json->DeleteKey("test3/test/res");
|
||||
|
||||
$this->assertFalse($json->IsKeyExists("test3/test/res"));
|
||||
}
|
||||
|
||||
public function testReadWrite ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$json = new BoolEx();
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->Write("test3/test/res", json_encode([1, 2, 3]));
|
||||
}
|
||||
catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
$this->assertTrue($json->IsKeyExists("test/subtest/AAA"));
|
||||
$this->assertTrue($json->IsKeyExists("test1/test"));
|
||||
$this->assertEquals(1.23, (float)$json->Read("test/subtest/BBB"));
|
||||
}
|
||||
|
||||
public function testGetKeys ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$json = new BoolEx();
|
||||
try {
|
||||
$json->Write("test/subtest/AAA", "123");
|
||||
$json->Write("test/subtest/BBB", 1.23);
|
||||
$json->Write("test1/test", 123);
|
||||
$json->Write("test2/test", true);
|
||||
$json->WriteArray("test3/test/res", [1, 2, 3]);
|
||||
}
|
||||
catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
$this->assertCount(11, $json->GetKeys());
|
||||
$this->assertCount(2, $json->GetKeys("test/subtest"));
|
||||
}
|
||||
|
||||
public function testReadWriteSerializable ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$serializableClass = new C("test", 123, true);
|
||||
|
||||
$json = new BoolEx();
|
||||
try {
|
||||
$json->WriteSerializable("test", $serializableClass);
|
||||
|
||||
/**
|
||||
* @var C $unSerializableClass Получаем объект из файла
|
||||
*/
|
||||
$unSerializableClass = $json->ReadSerializable("test", "goodboyalex\\php_components_pack\\tests\\data\\C");
|
||||
}
|
||||
catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
return;
|
||||
}
|
||||
|
||||
$this->assertEquals($serializableClass->stringC, $unSerializableClass->stringC);
|
||||
$this->assertEquals($serializableClass->intC, $unSerializableClass->intC);
|
||||
$this->assertEquals($serializableClass->boolC, $unSerializableClass->boolC);
|
||||
}
|
||||
|
||||
public function testReadWriteFloat ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$json = new BoolEx();
|
||||
try {
|
||||
$json->Write("test", 1.23);
|
||||
}
|
||||
catch (JsonException $e) {
|
||||
echo $e->getMessage();
|
||||
}
|
||||
|
||||
$this->assertEquals(1.23, $json->ReadFloat("test", 0.2));
|
||||
}
|
||||
}
|
||||
134
tests/classes/VersionInfoTest.php
Normal file
134
tests/classes/VersionInfoTest.php
Normal file
@ -0,0 +1,134 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_components_pack\tests\classes;
|
||||
|
||||
use goodboyalex\php_components_pack\classes\ObjectArray;
|
||||
use goodboyalex\php_components_pack\classes\VersionInfo;
|
||||
use goodboyalex\php_components_pack\enums\VersionInfoStage;
|
||||
use PHPUnit\Framework\TestCase;
|
||||
|
||||
class VersionInfoTest extends TestCase
|
||||
{
|
||||
public function testCompareWith ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$versionInfo1 = new VersionInfo(1, 2, 3, 4, VersionInfoStage::Beta, 1);
|
||||
$versionInfo2 = new VersionInfo(1, 1, 3, 4, VersionInfoStage::Alpha, 2);
|
||||
|
||||
$this->assertEquals(1, $versionInfo1->CompareWith($versionInfo2));
|
||||
|
||||
}
|
||||
|
||||
private function PrepareForTest (): void
|
||||
{
|
||||
require_once __DIR__ . '/../../sources/enums/VersionInfoStage.php';
|
||||
require_once __DIR__ . '/../../sources/classes/VersionInfo.php';
|
||||
}
|
||||
|
||||
public function test__toString ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
$versionInfo = new VersionInfo(1, 2, 3, 4, VersionInfoStage::Beta, 1);
|
||||
$this->assertEquals('1.2.3.4 Beta 1', $versionInfo->__toString());
|
||||
}
|
||||
|
||||
public function testToString ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
$versionInfo = new VersionInfo(1, 2, 3, 4, VersionInfoStage::Beta, 1);
|
||||
|
||||
$template = "Это #{Stage} #{StageNumber} версии #{Major}.#{Minor}.#{Release}.#{Build}";
|
||||
|
||||
$stageNames = [
|
||||
VersionInfoStage::PreAlpha->value => 'рано',
|
||||
VersionInfoStage::Alpha->value => 'начало',
|
||||
VersionInfoStage::Beta->value => 'середнячок',
|
||||
VersionInfoStage::ReleaseCandidate->value => 'почти',
|
||||
VersionInfoStage::Stable->value => 'это релиз, детка!'
|
||||
];
|
||||
|
||||
$this->assertEquals('Это середнячок 1 версии 1.2.3.4', $versionInfo->ToString($template, $stageNames));
|
||||
}
|
||||
|
||||
public function testParse ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$stageNames = [
|
||||
VersionInfoStage::PreAlpha->value => 'pre',
|
||||
VersionInfoStage::Alpha->value => 'alpha',
|
||||
VersionInfoStage::Beta->value => 'beta',
|
||||
VersionInfoStage::ReleaseCandidate->value => 'rc',
|
||||
VersionInfoStage::Stable->value => 'stable'
|
||||
];
|
||||
|
||||
$version = VersionInfo::Parse('1.2.3.4 beta 1', $stageNames);
|
||||
|
||||
$this->assertEquals(1, $version->Major);
|
||||
$this->assertEquals(2, $version->Minor);
|
||||
$this->assertEquals(3, $version->Release);
|
||||
$this->assertEquals(4, $version->Build);
|
||||
$this->assertEquals(VersionInfoStage::Beta, $version->Stage);
|
||||
$this->assertEquals(1, $version->StageNumber);
|
||||
}
|
||||
|
||||
public function test__construct ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$version = new VersionInfo(1, 2, 3, 4, VersionInfoStage::Beta, 1);
|
||||
|
||||
$this->assertEquals(2, $version->Minor);
|
||||
}
|
||||
|
||||
public function testCompare ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$versionInfo1 = new VersionInfo(1, 2, 3, 4, VersionInfoStage::Beta, 1);
|
||||
$versionInfo2 = new VersionInfo(1, 1, 3, 4, VersionInfoStage::Alpha, 2);
|
||||
|
||||
$this->assertEquals(1, VersionInfo::Compare($versionInfo1, $versionInfo2));
|
||||
}
|
||||
|
||||
public function testCompareWithRange ()
|
||||
{
|
||||
$this->PrepareForTest();
|
||||
|
||||
$versionInfo1 = new VersionInfo(1, 2, 3, 4, VersionInfoStage::Beta, 1);
|
||||
|
||||
$versionInfo2 = new VersionInfo(1, 1, 3, 4, VersionInfoStage::Alpha, 2);
|
||||
|
||||
$versionInfo3 = new VersionInfo(1, 1, 1, 1, VersionInfoStage::Alpha, 2);
|
||||
|
||||
$versionInfo4 = new VersionInfo(5, 5, 5, 5, VersionInfoStage::Stable);
|
||||
|
||||
$optionNotBorder = new ObjectArray();
|
||||
|
||||
// Для начала простое сравнение
|
||||
$this->assertEquals(0, $versionInfo1->CompareWithRange($versionInfo3, $versionInfo4));
|
||||
$this->assertEquals(-1, $versionInfo2->CompareWithRange($versionInfo1, $versionInfo4));
|
||||
$this->assertEquals(1, $versionInfo4->CompareWithRange($versionInfo2, $versionInfo1));
|
||||
|
||||
// Немного перепутаем границы =)
|
||||
$this->assertEquals(1, $versionInfo4->CompareWithRange($versionInfo1, $versionInfo2));
|
||||
|
||||
// А теперь с границами
|
||||
// - значение равно левой границе
|
||||
$this->assertEquals(0, $versionInfo2->CompareWithRange($versionInfo2, $versionInfo1));
|
||||
// - значение равно правой границе
|
||||
$this->assertEquals(0, $versionInfo1->CompareWithRange($versionInfo2, $versionInfo1));
|
||||
// - а теперь с выключением границ
|
||||
// -- для левой
|
||||
$this->assertEquals(-1, $versionInfo2->CompareWithRange($versionInfo2, $versionInfo1, $optionNotBorder));
|
||||
// -- для правой
|
||||
$this->assertEquals(1, $versionInfo1->CompareWithRange($versionInfo2, $versionInfo1, $optionNotBorder));
|
||||
|
||||
// А что если границы равны и значение равно
|
||||
// - для включённых границ
|
||||
$this->assertEquals(0, $versionInfo1->CompareWithRange($versionInfo1, $versionInfo1));
|
||||
// - для выключённых границ
|
||||
$this->assertEquals(-1, $versionInfo1->CompareWithRange($versionInfo1, $versionInfo1, $optionNotBorder));
|
||||
}
|
||||
}
|
||||
36
tests/data/C.php
Normal file
36
tests/data/C.php
Normal file
@ -0,0 +1,36 @@
|
||||
<?php
|
||||
|
||||
namespace goodboyalex\php_components_pack\tests\data;
|
||||
|
||||
use goodboyalex\php_components_pack\interfaces\ISerializable;
|
||||
|
||||
class C implements ISerializable
|
||||
{
|
||||
public string $stringC;
|
||||
public int $intC;
|
||||
public bool $boolC;
|
||||
|
||||
public function __construct (string $string = "", int $int = 0, bool $bool = false)
|
||||
{
|
||||
$this->stringC = $string;
|
||||
$this->intC = $int;
|
||||
$this->boolC = $bool;
|
||||
}
|
||||
|
||||
public function Serialize (): string
|
||||
{
|
||||
$array = [];
|
||||
$array["string"] = $this->stringC;
|
||||
$array["int"] = $this->intC;
|
||||
$array["bool"] = $this->boolC;
|
||||
return json_encode($array);
|
||||
}
|
||||
|
||||
public function UnSerialize (string $serialized): void
|
||||
{
|
||||
$array = json_decode($serialized, true);
|
||||
$this->stringC = $array["string"];
|
||||
$this->intC = $array["int"];
|
||||
$this->boolC = $array["bool"];
|
||||
}
|
||||
}
|
||||
Loading…
x
Reference in New Issue
Block a user