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

    [
    ]