♻️ UPDATE Добавлена документация для KinopoiskDev

docs/dev/.nav.yml

@@ -1,29 +1,30 @@
 title: Разработки
 nav:
   - Инструкции:
-    - Composer: composer.md
-    - Crowdin: crowdin.md
-    - Инструкция по установке: install_instructions.md
-    - Инструкция по установке PHP intl: php_intl.md
+      - Composer: composer.md
+      - Crowdin: crowdin.md
+      - Инструкция по установке: install_instructions.md
+      - Инструкция по установке PHP intl: php_intl.md
   - API Wrappers:
-    - KinopoiskUnoffical PHP: notkinopoiskphp/
+      - KinopoiskUnoffical PHP: notkinopoiskphp/
+      - KinopoiskDev PHP: kinopoiskdev/
   - Бесплатные разработки:
-    - DB Manager: db_manager/
-    - "Re: Post": repost/
-    - DLE Faker: dle_faker/
-    - Telegram Posting: telegramposting/
-    - MH Admin: mhadmin/
-    - MyStatus: mystatus.md
-    - Release Status: releasestatus.md
-    - Schema.Org: schema.md
-    - Пользовательские теги: usertags.md
-    - Webmaster Verification: webmaster-verification.md
-    - XF Lists: xflist.md
-    - XF Select: xfselect.md
+      - DB Manager: db_manager/
+      - "Re: Post": repost/
+      - DLE Faker: dle_faker/
+      - Telegram Posting: telegramposting/
+      - MH Admin: mhadmin/
+      - MyStatus: mystatus.md
+      - Release Status: releasestatus.md
+      - Schema.Org: schema.md
+      - Пользовательские теги: usertags.md
+      - Webmaster Verification: webmaster-verification.md
+      - XF Lists: xflist.md
+      - XF Select: xfselect.md
   - Хаки:
-    - Страницы как на КиноПоиске: hook-pages-like-kp.md
-    - Подсчёт символов в короткой новости: hook-shortstory-signs-count.md
+      - Страницы как на КиноПоиске: hook-pages-like-kp.md
+      - Подсчёт символов в короткой новости: hook-shortstory-signs-count.md
   - Платные разработки:
-    - Шаблон SeasonVar: paid-seasonvar/
-    - Курс валют: paid-currencies_rate.md
-    - Последние новости списком: paid-lastnews.md 
+      - Шаблон SeasonVar: paid-seasonvar/
+      - Курс валют: paid-currencies_rate.md
+      - Последние новости списком: paid-lastnews.md

docs/dev/kinopoiskdev/.nav.yml

@@ -0,0 +1,15 @@
+title: KinopoiskDev PHP Wrapper
+nav:
+  - Главная: README.md
+  - Основной класс / клиент: Kinopoisk.md
+  - Сравнение с KinopoiskUnofficialTech: notkinopoiskphp-compare.md
+  - Атрибуты: Attributes/
+  - Контракты: Contracts/
+  - Перечисления: Enums/
+  - Исключения: Exceptions/
+  - Фильтры: Filter/
+  - HTTP запросы: Http/
+  - Модели: Models/
+  - Ответы API: Responses/
+  - Сервисы: Services/
+  - Утилиты: Utils/

docs/dev/kinopoiskdev/Attributes/.nav.yml

@@ -0,0 +1,5 @@
+title: Атрибуты
+nav:
+  - ApiField: ApiField.md
+  - Sensitive: Sensitive.md
+  - Validation: Validation.md 

docs/dev/kinopoiskdev/Attributes/ApiField.md

@@ -0,0 +1,29 @@
+# ApiField
+
+**Описание:** Атрибут для указания источника поля в API
+Позволяет настроить маппинг между свойствами модели и полями API.
+Поддерживает указание имени поля в API, возможность null значений
+и значения по умолчанию.
+
+**С версии:** 1.0.0
+
+**Версия:** 1.0.0
+
+**Пример:**
+```php
+#[ApiField(name: 'movie_title', nullable: false, default: 'Unknown')]
+public string $title;
+#[ApiField(name: 'release_year', nullable: true)]
+public ?int $year;
+```
+
+## `__construct()`
+
+**Описание:** Конструктор атрибута API поля
+
+**Параметры:**
+
+* `$name` (string|null): Имя поля в API (если null, используется имя свойства)
+* `$nullable` (bool): Разрешены ли null значения (по умолчанию true)
+* `$default` (mixed): Значение по умолчанию при отсутствии данных
+

docs/dev/kinopoiskdev/Attributes/Sensitive.md

@@ -0,0 +1,27 @@
+# Sensitive
+
+**Описание:** Атрибут для конфиденциальных полей
+Позволяет пометить поля как конфиденциальные для контроля
+их отображения в различных контекстах (JSON, массивы, логи).
+
+**С версии:** 1.0.0
+
+**Версия:** 1.0.0
+
+**Пример:**
+```php
+#[Sensitive(hideInJson: true, hideInArray: false)]
+public string $apiToken;
+#[Sensitive(hideInJson: true, hideInArray: true)]
+public string $password;
+```
+
+## `__construct()`
+
+**Описание:** Конструктор атрибута конфиденциального поля
+
+**Параметры:**
+
+* `$hideInJson` (bool): Скрывать ли поле в JSON сериализации (по умолчанию true)
+* `$hideInArray` (bool): Скрывать ли поле в массивах (по умолчанию false)
+

docs/dev/kinopoiskdev/Attributes/Validation.md

@@ -0,0 +1,63 @@
+# Validation
+
+**Описание:** Атрибут для валидации свойств модели
+Предоставляет декларативный способ задания правил валидации
+для свойств моделей с использованием PHP 8.3 Attributes.
+Поддерживает различные типы валидации: обязательные поля,
+ограничения длины, диапазоны значений, регулярные выражения.
+
+**С версии:** 1.0.0
+
+**Версия:** 1.0.0
+
+**Пример:**
+```php
+class Movie {
+#[Validation(required: true, minLength: 1, maxLength: 255)]
+public string $title;
+#[Validation(min: 1900, max: 2030)]
+public int $year;
+#[Validation(pattern: '/^[a-zA-Z0-9\s]+$/')]
+public string $genre;
+}
+```
+
+**См. также:**
+
+* `\KinopoiskDev\Services\ValidationService`: Сервис валидации
+* `\KinopoiskDev\Exceptions\ValidationException`: Исключения валидации
+
+## `__construct()`
+
+**Описание:** Конструктор атрибута валидации
+Создает новый экземпляр атрибута валидации с указанными правилами.
+Все параметры являются опциональными и могут быть настроены
+в зависимости от требований к конкретному полю.
+
+**Параметры:**
+
+* `$required` (bool): Обязательное ли поле (по умолчанию false)
+* `$minLength` (int|null): Минимальная длина строки (для строковых полей)
+* `$maxLength` (int|null): Максимальная длина строки (для строковых полей)
+* `$min` (float|null): Минимальное значение (для числовых полей)
+* `$max` (float|null): Максимальное значение (для числовых полей)
+* `$pattern` (string|null): Регулярное выражение для проверки формата
+* `$allowedValues` (array<string>): Допустимые значения (для enum-подобных полей)
+* `$customMessage` (string|null): Кастомное сообщение об ошибке валидации
+
+**Пример:**
+```php
+// Обязательное поле с ограничением длины
+#[Validation(required: true, minLength: 1, maxLength: 100)]
+public string $name;
+// Числовое поле с диапазоном
+#[Validation(min: 0, max: 10)]
+public float $rating;
+// Поле с регулярным выражением
+#[Validation(pattern: '/^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$/i')]
+public string $email;
+// Поле с допустимыми значениями
+#[Validation(allowedValues: ['movie', 'series', 'cartoon'])]
+public string $type;
+```
+

docs/dev/kinopoiskdev/Contracts/.nav.yml

@@ -0,0 +1,4 @@
+title: Контракты
+nav:
+  - CacheInterface: CacheInterface.md
+  - LoggerInterface: LoggerInterface.md 

docs/dev/kinopoiskdev/Contracts/CacheInterface.md

@@ -0,0 +1,78 @@
+# CacheInterface
+
+**Описание:** Интерфейс для сервиса кэширования
+Определяет контракт для работы с различными системами кэширования
+в приложении. Поддерживает базовые операции CRUD для кэша.
+
+**С версии:** 1.0.0
+
+**Версия:** 1.0.0
+
+## `get()`
+
+**Описание:** Получает значение из кэша по ключу
+
+**Параметры:**
+
+* `$key` (string): Ключ кэша
+
+**Возвращает:** `mixed|null` Значение из кэша или null если не найдено
+
+## `set()`
+
+**Описание:** Сохраняет значение в кэш
+
+**Параметры:**
+
+* `$key` (string): Ключ кэша
+* `$value` (mixed): Значение для сохранения
+* `$ttl` (int): Время жизни в секундах
+
+**Возвращает:** `bool True` при успешном сохранении
+
+## `delete()`
+
+**Описание:** Удаляет значение из кэша
+
+**Параметры:**
+
+* `$key` (string): Ключ кэша
+
+**Возвращает:** `bool True` при успешном удалении
+
+## `has()`
+
+**Описание:** Проверяет наличие ключа в кэше
+
+**Параметры:**
+
+* `$key` (string): Ключ кэша
+
+**Возвращает:** `bool True` если ключ существует
+
+## `clear()`
+
+**Описание:** Очищает весь кэш
+
+**Возвращает:** `bool True` при успешной очистке
+
+## `getMultiple()`
+
+**Описание:** Получает множественные значения по ключам
+
+**Параметры:**
+
+* `$keys` (array<string>): Массив ключей
+
+**Возвращает:** `array<string, mixed>` Ассоциативный массив ключ => значение
+
+## `setMultiple()`
+
+**Описание:** Сохраняет множественные значения
+
+**Параметры:**
+
+* `$ttl` (int): Время жизни в секундах
+
+**Возвращает:** `bool True` при успешном сохранении
+