babaev-an/php_components_pack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 30 Wiki Activity
php_components_pack/sources/classes/JsonReWriter.md
babaev-an 52de613b0f 20250629 1.1 Stable
2025-06-29 20:29:52 +03:00

26 KiB
Raw Blame History

Описание класса 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 будет следующим массивом:

[
]