20250712 1.1.1 Beta 4
This commit is contained in:
179
sources/extensions/TypeExtension.md
Normal file
179
sources/extensions/TypeExtension.md
Normal file
@@ -0,0 +1,179 @@
|
||||
# Описание класса TypeExtension
|
||||
|
||||
## Информация о версии
|
||||
|
||||
Версия класса: 1.0
|
||||
|
||||
Впервые введено в пакет с версии: 1.1.1
|
||||
|
||||
Описание класса: Расширение для любого типа.
|
||||
|
||||
## Публичные свойства и константы класса
|
||||
|
||||
К публичным свойствам можно отнести следующие статичные функции: `DEFAULT_TO_ARRAY_ON_CLASS` и
|
||||
`DEFAULT_FROM_ARRAY_ON_CLASS`. Они описывают методы обработки классов по умолчанию для методов `ToArray` и `FromArray`
|
||||
соответственно.
|
||||
|
||||
### Метод `DEFAULT_TO_ARRAY_ON_CLASS`
|
||||
|
||||
Этот метод возвращает `Closure`, который можно использовать (и он используется при значении параметра `null`) во втором
|
||||
параметре метода `ToArray`.
|
||||
|
||||
### Метод `DEFAULT_FROM_ARRAY_ON_CLASS`
|
||||
|
||||
Этот метод возвращает `Closure`, который можно использовать (и он используется при значении параметра `null`) во втором
|
||||
параметре метода `FromArray`.
|
||||
|
||||
## Методы и функции
|
||||
|
||||
### Метод `ToArray`
|
||||
|
||||
Этот _статический_ метод переводит класс в массив. Он содержит **1 обязательный параметр**:
|
||||
|
||||
* `object $class` - класс, который нужно перевести в массив
|
||||
|
||||
и **1 необязательный параметр**:
|
||||
|
||||
* `?callable $onClass = null` - метод обработки классов. Если передаётся `null`, то используется
|
||||
`DEFAULT_TO_ARRAY_ON_CLASS`. По умолчанию, `null`.
|
||||
|
||||
В качестве метода обработки классов `onClass` подойдет любое `Closure` вида
|
||||
|
||||
fn (object $class): array => <ДЕЙСТВИЕ>;
|
||||
|
||||
Метод возвращает `array` - массив публичных свойств.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public static function ToArray (object $class, ?callable $onClass = null): array
|
||||
|
||||
Пример,
|
||||
|
||||
// Создаём тестовый класс (см. TypeExtensionTest)
|
||||
$class = new D (
|
||||
'test_string',
|
||||
12345,
|
||||
true,
|
||||
new A("test_string_A", 6789, false),
|
||||
new B("test_string_B", 9876, "false"),
|
||||
new C("test_string_C", 54321, true)
|
||||
);
|
||||
|
||||
// Создаём метод обработки классов
|
||||
// - воспользуемся тем, что класс C реализует интерфейс ISerialize
|
||||
$c_closure = fn (C $class): array =>
|
||||
[
|
||||
"type_class" => C::class,
|
||||
"type_value" => $class->Serialize()
|
||||
];
|
||||
|
||||
// - зададим метод обработки
|
||||
$closure = fn (object $class): array => $class instanceof C
|
||||
? $c_closure($class)
|
||||
: TypeExtension::ToArray($class);
|
||||
|
||||
// Преобразуем в массив
|
||||
try {
|
||||
$array = TypeExtension::ToArray($class, $closure);
|
||||
}
|
||||
catch (TypeException $e) {
|
||||
// - если ошибка, то выводим её и завершаем работу
|
||||
die($e->getMessage());
|
||||
}
|
||||
|
||||
// Вывожу в файл
|
||||
file_put_contents(__DIR__ . "/class.txt", json_encode($array, JSON_PRETTY_PRINT));
|
||||
|
||||
В результате содержимое файла:
|
||||
|
||||
{
|
||||
"type_class": "goodboyalex\\php_components_pack\\tests\\data\\D",
|
||||
"stringD": "test_string",
|
||||
"intD": 12345,
|
||||
"boolD": true,
|
||||
"a": {
|
||||
"type_class": "goodboyalex\\php_components_pack\\tests\\data\\A",
|
||||
"a": "test_string_A",
|
||||
"b": 6789,
|
||||
"c": false
|
||||
},
|
||||
"b": {
|
||||
"type_class": "goodboyalex\\php_components_pack\\tests\\data\\B",
|
||||
"a": "test_string_B",
|
||||
"b": 9876,
|
||||
"d": "false"
|
||||
},
|
||||
"c": {
|
||||
"type_class": "goodboyalex\\php_components_pack\\tests\\data\\C",
|
||||
"type_value": "{\"string\":\"test_string_C\",\"int\":54321,\"bool\":true}"
|
||||
}
|
||||
}
|
||||
|
||||
#### Выбрасываемые исключения
|
||||
|
||||
Этот метод выбрасывает исключение типа `TypeException` в случае, если объект `$class` (обязательный параметр метода) не является классом.
|
||||
|
||||
### Метод `FromArray`
|
||||
|
||||
Этот _статический_ метод переводит массив в класс. Он содержит **1 обязательный параметр**:
|
||||
|
||||
* `array $array` - массив публичных свойств
|
||||
|
||||
и **1 необязательный параметр**:
|
||||
|
||||
* `?callable $onClass = null` - метод обработки классов. Если передаётся `null`, то используется
|
||||
`DEFAULT_FROM_ARRAY_ON_CLASS`. По умолчанию, `null`.
|
||||
|
||||
В качестве метода обработки классов `onClass` подойдет любое `Closure` вида
|
||||
|
||||
fn (array $classArray): object => <ДЕЙСТВИЕ>;
|
||||
|
||||
Метод возвращает `object` - экземпляр класса.
|
||||
|
||||
Синтаксис:
|
||||
|
||||
public static function FromArray (array $array, ?callable $onClass = null): object
|
||||
|
||||
Пример,
|
||||
|
||||
// Считываем данные из файла и преобразуем в массив
|
||||
$array = json_decode(file_get_contents(__DIR__ . "/class.txt"), true);
|
||||
|
||||
// Создаём метод обработки классов
|
||||
// - воспользуемся тем, что класс C реализует интерфейс ISerialize
|
||||
$c_closure = function (string $serializedC): C
|
||||
{
|
||||
$classC = new C();
|
||||
$classC->UnSerialize($serializedC);
|
||||
return $classC;
|
||||
};
|
||||
|
||||
// - зададим метод обработки
|
||||
$closure = fn (array $classArray): object =>
|
||||
$classArray['type_class'] == C::class
|
||||
? $c_closure($classArray["type_value"])
|
||||
: TypeExtension::FromArray($classArray);
|
||||
|
||||
// Преобразуем в объект
|
||||
try {
|
||||
$class = TypeExtension::FromArray($array, D::CLOSURE_FROM_ARRAY());
|
||||
} catch (TypeException $e) {
|
||||
// - если ошибка, то выводим её и завершаем работу
|
||||
die($e->getMessage());
|
||||
}
|
||||
|
||||
// Вывожу тестовую строку
|
||||
echo $class->c->stringC;
|
||||
|
||||
В результате на экране отобразится:
|
||||
|
||||
test_string_C
|
||||
|
||||
#### Выбрасываемые исключения
|
||||
|
||||
Этот метод выбрасывает исключение типа `TypeException` в случаях, если:
|
||||
|
||||
* массив `$array` не создан через метод `ToArray`;
|
||||
* при попытке создать объект, он не создаётся;
|
||||
* дата передана не корректного формата;
|
||||
* пытается передать `null` не `nullable` типу.
|
||||
@@ -28,20 +28,24 @@ final class TypeExtension
|
||||
*/
|
||||
public static function DEFAULT_TO_ARRAY_ON_CLASS (): Closure
|
||||
{
|
||||
return fn (object $class) => self::ToArray($class, self::DEFAULT_TO_ARRAY_ON_CLASS());
|
||||
return fn (object $class): array => self::ToArray($class);
|
||||
}
|
||||
|
||||
/**
|
||||
* Переводит объект в массив.
|
||||
*
|
||||
* @param object $class Объект.
|
||||
* @param callable $onClass Метод обработки классов.
|
||||
* @param callable|null $onClass Метод обработки классов. Если передаётся null, то используется
|
||||
* <code>DEFAULT_TO_ARRAY_ON_CLASS</code>. По умолчанию, null.
|
||||
*
|
||||
* @return array Массив свойств типа.
|
||||
* @throws TypeException Исключение, если объект не является классом.
|
||||
*/
|
||||
public static function ToArray (object $class, callable $onClass): array
|
||||
public static function ToArray (object $class, ?callable $onClass = null): array
|
||||
{
|
||||
// Проверяю, что метод обработки классов не null и если null, то присваиваю дефолтный метод
|
||||
$onClass ??= self::DEFAULT_TO_ARRAY_ON_CLASS();
|
||||
|
||||
// Создаю массив результата
|
||||
$result = [];
|
||||
|
||||
@@ -102,16 +106,28 @@ final class TypeExtension
|
||||
return $result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Дефолтный метод обработки классов для FromArray.
|
||||
*
|
||||
* @return Closure Метод обработки классов для FromArray.
|
||||
*/
|
||||
public static function DEFAULT_FROM_ARRAY_ON_CLASS (): Closure
|
||||
{
|
||||
return fn (array $classArray): object => self::FromArray($classArray);
|
||||
}
|
||||
|
||||
/**
|
||||
* Переводит массив в объект.
|
||||
*
|
||||
* @param array $array Массив свойств.
|
||||
* @param callable|null $onClass Метод обработки классов. Если передаётся null, то используется
|
||||
* <code>DEFAULT_FROM_ARRAY_ON_CLASS</code>. По умолчанию, null.
|
||||
*
|
||||
* @return mixed Объект типа $className.
|
||||
* @return mixed Восстановленный объект.
|
||||
* @throws TypeException Исключение, если массив не создан через ToArray, объект не создан, дата не корректного
|
||||
* формата или пытается передать null не nullable типу.
|
||||
*/
|
||||
public function FromArray (array $array): object
|
||||
public static function FromArray (array $array, ?callable $onClass = null): object
|
||||
{
|
||||
// Проверяю, что массив является массивом, созданным через ToArray, то есть содержит ключ type_class
|
||||
if (!array_key_exists("type_class", $array))
|
||||
@@ -186,7 +202,7 @@ final class TypeExtension
|
||||
}
|
||||
|
||||
// - если значение является NULL
|
||||
if ($value = "null") {
|
||||
if (is_string($value) && $value == "null") {
|
||||
// -- присваиваю NULL
|
||||
try {
|
||||
$instance->$key = null;
|
||||
@@ -203,7 +219,7 @@ final class TypeExtension
|
||||
// - если значение является классом
|
||||
if (is_object($instance->$key) && is_array($array[$key]) && array_key_exists("type_class", $array[$key])) {
|
||||
// -- добавляю в массив через рекурсию
|
||||
$instance->$key = self::FromArray($array[$key]);
|
||||
$instance->$key = $onClass($array[$key]);
|
||||
|
||||
// -- следующий элемент
|
||||
continue;
|
||||
|
||||
Reference in New Issue
Block a user