From eefaf1fc0c31e4f8b26bd0719dfcb4fa02ce78bc Mon Sep 17 00:00:00 2001 From: Maxim Harder Date: Mon, 4 Aug 2025 14:27:01 +0200 Subject: [PATCH] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20UPDATE=20=D0=94=D0=BE?= =?UTF-8?q?=D0=B1=D0=B0=D0=B2=D0=BB=D0=B5=D0=BD=D0=B0=20=D0=B4=D0=BE=D0=BA?= =?UTF-8?q?=D1=83=D0=BC=D0=B5=D0=BD=D1=82=D0=B0=D1=86=D0=B8=D1=8F=20=D0=B4?= =?UTF-8?q?=D0=BB=D1=8F=20KinopoiskDev?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Добавлен новый enum `MovieStatus` для представления статусов фильмов - Реализован базовый DTO `BaseDocsResponseDto` для пагинированных ответов API - Добавлен новый DTO `PersonDocsResponseDto` для поиска персон с пагинацией - Реализован класс `KeywordRequests` для работы с ключевыми словами API ✨ NEW Добавлен функционал для работы с ключевыми словами - Добавлен метод `getKeywordsByTitle` для поиска ключевых слов по названию - Добавлен метод `searchKeywords` для поиска ключевых слов по различным фильтрам - Добавлен метод `getKeywordsForMovie` для получения ключевых слов, связанных с фильмом 🐛 FIX Исправлены ошибки в документации - Исправлены описания методов и свойств в документации - Добавлены ссылки на связанные классы и модели - Уточнены версии и совместимость с API --- docs/dev/.nav.yml | 45 +- docs/dev/kinopoiskdev/.nav.yml | 15 + docs/dev/kinopoiskdev/Attributes/.nav.yml | 5 + docs/dev/kinopoiskdev/Attributes/ApiField.md | 29 + docs/dev/kinopoiskdev/Attributes/Sensitive.md | 27 + .../dev/kinopoiskdev/Attributes/Validation.md | 63 ++ docs/dev/kinopoiskdev/Contracts/.nav.yml | 4 + .../kinopoiskdev/Contracts/CacheInterface.md | 78 +++ .../kinopoiskdev/Contracts/LoggerInterface.md | 138 ++++ docs/dev/kinopoiskdev/Enums/.nav.yml | 16 + docs/dev/kinopoiskdev/Enums/FilterField.md | 276 ++++++++ docs/dev/kinopoiskdev/Enums/FilterOperator.md | 76 ++ docs/dev/kinopoiskdev/Enums/HttpStatusCode.md | 40 ++ docs/dev/kinopoiskdev/Enums/ImageType.md | 36 + docs/dev/kinopoiskdev/Enums/ListCategory.md | 24 + docs/dev/kinopoiskdev/Enums/MovieStatus.md | 32 + docs/dev/kinopoiskdev/Enums/MovieType.md | 36 + .../kinopoiskdev/Enums/PersonProfession.md | 68 ++ docs/dev/kinopoiskdev/Enums/PersonSex.md | 20 + docs/dev/kinopoiskdev/Enums/RatingMpaa.md | 32 + docs/dev/kinopoiskdev/Enums/ReviewType.md | 16 + docs/dev/kinopoiskdev/Enums/SortDirection.md | 98 +++ docs/dev/kinopoiskdev/Enums/SortField.md | 339 +++++++++ docs/dev/kinopoiskdev/Enums/StudioType.md | 81 +++ docs/dev/kinopoiskdev/Exceptions/.nav.yml | 5 + .../Exceptions/KinopoiskDevException.md | 48 ++ .../Exceptions/KinopoiskResponseException.md | 51 ++ .../Exceptions/ValidationException.md | 166 +++++ docs/dev/kinopoiskdev/Filter/.nav.yml | 10 + .../kinopoiskdev/Filter/ImageSearchFilter.md | 180 +++++ .../Filter/KeywordSearchFilter.md | 284 ++++++++ .../kinopoiskdev/Filter/MovieSearchFilter.md | 259 +++++++ .../kinopoiskdev/Filter/PersonSearchFilter.md | 212 ++++++ .../kinopoiskdev/Filter/ReviewSearchFilter.md | 164 +++++ .../kinopoiskdev/Filter/SeasonSearchFilter.md | 143 ++++ docs/dev/kinopoiskdev/Filter/SortCriteria.md | 146 ++++ .../kinopoiskdev/Filter/StudioSearchFilter.md | 235 +++++++ docs/dev/kinopoiskdev/Http/.nav.yml | 10 + docs/dev/kinopoiskdev/Http/ImageRequests.md | 66 ++ docs/dev/kinopoiskdev/Http/KeywordRequests.md | 90 +++ docs/dev/kinopoiskdev/Http/ListRequests.md | 84 +++ docs/dev/kinopoiskdev/Http/MovieRequests.md | 377 ++++++++++ docs/dev/kinopoiskdev/Http/PersonRequests.md | 337 +++++++++ docs/dev/kinopoiskdev/Http/ReviewRequests.md | 135 ++++ docs/dev/kinopoiskdev/Http/SeasonRequests.md | 123 ++++ docs/dev/kinopoiskdev/Http/StudioRequests.md | 198 ++++++ docs/dev/kinopoiskdev/Kinopoisk.md | 276 ++++++++ docs/dev/kinopoiskdev/Models/.nav.yml | 5 + .../kinopoiskdev/Models/AbstractBaseModel.md | 419 +++++++++++ docs/dev/kinopoiskdev/Models/ApiImage.md | 76 ++ docs/dev/kinopoiskdev/Models/Audience.md | 60 ++ docs/dev/kinopoiskdev/Models/BaseModel.md | 171 +++++ docs/dev/kinopoiskdev/Models/BirthPlace.md | 25 + docs/dev/kinopoiskdev/Models/CurrencyValue.md | 81 +++ docs/dev/kinopoiskdev/Models/DeathPlace.md | 17 + docs/dev/kinopoiskdev/Models/Episode.md | 90 +++ docs/dev/kinopoiskdev/Models/ExternalId.md | 187 +++++ docs/dev/kinopoiskdev/Models/FactInMovie.md | 93 +++ docs/dev/kinopoiskdev/Models/FactInPerson.md | 81 +++ docs/dev/kinopoiskdev/Models/Fees.md | 83 +++ docs/dev/kinopoiskdev/Models/Image.md | 140 ++++ docs/dev/kinopoiskdev/Models/ItemName.md | 74 ++ docs/dev/kinopoiskdev/Models/Keyword.md | 88 +++ docs/dev/kinopoiskdev/Models/LinkedMovie.md | 97 +++ docs/dev/kinopoiskdev/Models/Lists.md | 68 ++ docs/dev/kinopoiskdev/Models/Logo.md | 90 +++ .../kinopoiskdev/Models/MeiliPersonEntity.md | 388 +++++++++++ docs/dev/kinopoiskdev/Models/Movie.md | 220 ++++++ docs/dev/kinopoiskdev/Models/MovieAward.md | 100 +++ .../kinopoiskdev/Models/MovieFromKeyword.md | 45 ++ .../kinopoiskdev/Models/MovieFromStudio.md | 75 ++ docs/dev/kinopoiskdev/Models/MovieInPerson.md | 127 ++++ docs/dev/kinopoiskdev/Models/Name.md | 79 +++ docs/dev/kinopoiskdev/Models/NetworkItem.md | 113 +++ docs/dev/kinopoiskdev/Models/Networks.md | 114 +++ docs/dev/kinopoiskdev/Models/Nomination.md | 73 ++ .../kinopoiskdev/Models/NominationAward.md | 75 ++ docs/dev/kinopoiskdev/Models/Person.md | 115 +++ docs/dev/kinopoiskdev/Models/PersonAward.md | 108 +++ docs/dev/kinopoiskdev/Models/PersonInMovie.md | 81 +++ docs/dev/kinopoiskdev/Models/PersonPlace.md | 82 +++ docs/dev/kinopoiskdev/Models/Premiere.md | 65 ++ docs/dev/kinopoiskdev/Models/Rating.md | 201 ++++++ docs/dev/kinopoiskdev/Models/Review.md | 101 +++ docs/dev/kinopoiskdev/Models/ReviewInfo.md | 75 ++ docs/dev/kinopoiskdev/Models/SearchMovie.md | 113 +++ docs/dev/kinopoiskdev/Models/Season.md | 94 +++ docs/dev/kinopoiskdev/Models/SeasonInfo.md | 70 ++ docs/dev/kinopoiskdev/Models/ShortImage.md | 71 ++ docs/dev/kinopoiskdev/Models/Spouses.md | 88 +++ docs/dev/kinopoiskdev/Models/Studio.md | 101 +++ docs/dev/kinopoiskdev/Models/Video.md | 77 +++ docs/dev/kinopoiskdev/Models/VideoTypes.md | 74 ++ docs/dev/kinopoiskdev/Models/Votes.md | 192 +++++ docs/dev/kinopoiskdev/Models/Watchability.md | 74 ++ .../kinopoiskdev/Models/WatchabilityItem.md | 81 +++ docs/dev/kinopoiskdev/Models/YearRange.md | 72 ++ docs/dev/kinopoiskdev/README.md | 142 ++++ docs/dev/kinopoiskdev/Responses/.nav.yml | 7 + docs/dev/kinopoiskdev/Responses/Api/.nav.yml | 16 + .../Responses/Api/ImageDocsResponseDto.md | 54 ++ .../Responses/Api/KeywordDocsResponseDto.md | 80 +++ .../Responses/Api/ListDocsResponseDto.md | 48 ++ .../Api/MovieAwardDocsResponseDto.md | 44 ++ .../Responses/Api/MovieDocsResponseDto.md | 41 ++ .../Api/PersonAwardDocsResponseDto.md | 41 ++ .../Responses/Api/PersonDocsResponseDto.md | 43 ++ .../Responses/Api/PossibleValueDto.md | 58 ++ .../Responses/Api/ReviewDocsResponseDto.md | 43 ++ .../Responses/Api/SearchMovieResponseDto.md | 38 + .../Responses/Api/SearchPersonResponseDto.md | 38 + .../Responses/Api/SearchStudioResponseDto.md | 2 + .../Responses/Api/SeasonDocsResponseDto.md | 42 ++ .../Responses/Api/StudioDocsResponseDto.md | 15 + .../Responses/BaseDocsResponseDto.md | 176 +++++ .../kinopoiskdev/Responses/BaseResponseDto.md | 35 + .../Responses/ErrorResponseDto.md | 55 ++ .../kinopoiskdev/Responses/Errors/.nav.yml | 5 + .../Errors/ForbiddenErrorResponseDto.md | 53 ++ .../Errors/NotFoundErrorResponseDto.md | 56 ++ .../Errors/UnauthorizedErrorResponseDto.md | 63 ++ docs/dev/kinopoiskdev/Services/.nav.yml | 4 + .../dev/kinopoiskdev/Services/CacheService.md | 236 +++++++ .../Services/ValidationService.md | 396 +++++++++++ docs/dev/kinopoiskdev/Utils/.nav.yml | 6 + docs/dev/kinopoiskdev/Utils/DataManager.md | 211 ++++++ docs/dev/kinopoiskdev/Utils/FilterTrait.md | 128 ++++ docs/dev/kinopoiskdev/Utils/MovieFilter.md | 653 ++++++++++++++++++ docs/dev/kinopoiskdev/Utils/SortManager.md | 199 ++++++ .../kinopoiskdev/notkinopoiskphp-compare.md | 187 +++++ 130 files changed, 13675 insertions(+), 22 deletions(-) create mode 100644 docs/dev/kinopoiskdev/.nav.yml create mode 100644 docs/dev/kinopoiskdev/Attributes/.nav.yml create mode 100644 docs/dev/kinopoiskdev/Attributes/ApiField.md create mode 100644 docs/dev/kinopoiskdev/Attributes/Sensitive.md create mode 100644 docs/dev/kinopoiskdev/Attributes/Validation.md create mode 100644 docs/dev/kinopoiskdev/Contracts/.nav.yml create mode 100644 docs/dev/kinopoiskdev/Contracts/CacheInterface.md create mode 100644 docs/dev/kinopoiskdev/Contracts/LoggerInterface.md create mode 100644 docs/dev/kinopoiskdev/Enums/.nav.yml create mode 100644 docs/dev/kinopoiskdev/Enums/FilterField.md create mode 100644 docs/dev/kinopoiskdev/Enums/FilterOperator.md create mode 100644 docs/dev/kinopoiskdev/Enums/HttpStatusCode.md create mode 100644 docs/dev/kinopoiskdev/Enums/ImageType.md create mode 100644 docs/dev/kinopoiskdev/Enums/ListCategory.md create mode 100644 docs/dev/kinopoiskdev/Enums/MovieStatus.md create mode 100644 docs/dev/kinopoiskdev/Enums/MovieType.md create mode 100644 docs/dev/kinopoiskdev/Enums/PersonProfession.md create mode 100644 docs/dev/kinopoiskdev/Enums/PersonSex.md create mode 100644 docs/dev/kinopoiskdev/Enums/RatingMpaa.md create mode 100644 docs/dev/kinopoiskdev/Enums/ReviewType.md create mode 100644 docs/dev/kinopoiskdev/Enums/SortDirection.md create mode 100644 docs/dev/kinopoiskdev/Enums/SortField.md create mode 100644 docs/dev/kinopoiskdev/Enums/StudioType.md create mode 100644 docs/dev/kinopoiskdev/Exceptions/.nav.yml create mode 100644 docs/dev/kinopoiskdev/Exceptions/KinopoiskDevException.md create mode 100644 docs/dev/kinopoiskdev/Exceptions/KinopoiskResponseException.md create mode 100644 docs/dev/kinopoiskdev/Exceptions/ValidationException.md create mode 100644 docs/dev/kinopoiskdev/Filter/.nav.yml create mode 100644 docs/dev/kinopoiskdev/Filter/ImageSearchFilter.md create mode 100644 docs/dev/kinopoiskdev/Filter/KeywordSearchFilter.md create mode 100644 docs/dev/kinopoiskdev/Filter/MovieSearchFilter.md create mode 100644 docs/dev/kinopoiskdev/Filter/PersonSearchFilter.md create mode 100644 docs/dev/kinopoiskdev/Filter/ReviewSearchFilter.md create mode 100644 docs/dev/kinopoiskdev/Filter/SeasonSearchFilter.md create mode 100644 docs/dev/kinopoiskdev/Filter/SortCriteria.md create mode 100644 docs/dev/kinopoiskdev/Filter/StudioSearchFilter.md create mode 100644 docs/dev/kinopoiskdev/Http/.nav.yml create mode 100644 docs/dev/kinopoiskdev/Http/ImageRequests.md create mode 100644 docs/dev/kinopoiskdev/Http/KeywordRequests.md create mode 100644 docs/dev/kinopoiskdev/Http/ListRequests.md create mode 100644 docs/dev/kinopoiskdev/Http/MovieRequests.md create mode 100644 docs/dev/kinopoiskdev/Http/PersonRequests.md create mode 100644 docs/dev/kinopoiskdev/Http/ReviewRequests.md create mode 100644 docs/dev/kinopoiskdev/Http/SeasonRequests.md create mode 100644 docs/dev/kinopoiskdev/Http/StudioRequests.md create mode 100644 docs/dev/kinopoiskdev/Kinopoisk.md create mode 100644 docs/dev/kinopoiskdev/Models/.nav.yml create mode 100644 docs/dev/kinopoiskdev/Models/AbstractBaseModel.md create mode 100644 docs/dev/kinopoiskdev/Models/ApiImage.md create mode 100644 docs/dev/kinopoiskdev/Models/Audience.md create mode 100644 docs/dev/kinopoiskdev/Models/BaseModel.md create mode 100644 docs/dev/kinopoiskdev/Models/BirthPlace.md create mode 100644 docs/dev/kinopoiskdev/Models/CurrencyValue.md create mode 100644 docs/dev/kinopoiskdev/Models/DeathPlace.md create mode 100644 docs/dev/kinopoiskdev/Models/Episode.md create mode 100644 docs/dev/kinopoiskdev/Models/ExternalId.md create mode 100644 docs/dev/kinopoiskdev/Models/FactInMovie.md create mode 100644 docs/dev/kinopoiskdev/Models/FactInPerson.md create mode 100644 docs/dev/kinopoiskdev/Models/Fees.md create mode 100644 docs/dev/kinopoiskdev/Models/Image.md create mode 100644 docs/dev/kinopoiskdev/Models/ItemName.md create mode 100644 docs/dev/kinopoiskdev/Models/Keyword.md create mode 100644 docs/dev/kinopoiskdev/Models/LinkedMovie.md create mode 100644 docs/dev/kinopoiskdev/Models/Lists.md create mode 100644 docs/dev/kinopoiskdev/Models/Logo.md create mode 100644 docs/dev/kinopoiskdev/Models/MeiliPersonEntity.md create mode 100644 docs/dev/kinopoiskdev/Models/Movie.md create mode 100644 docs/dev/kinopoiskdev/Models/MovieAward.md create mode 100644 docs/dev/kinopoiskdev/Models/MovieFromKeyword.md create mode 100644 docs/dev/kinopoiskdev/Models/MovieFromStudio.md create mode 100644 docs/dev/kinopoiskdev/Models/MovieInPerson.md create mode 100644 docs/dev/kinopoiskdev/Models/Name.md create mode 100644 docs/dev/kinopoiskdev/Models/NetworkItem.md create mode 100644 docs/dev/kinopoiskdev/Models/Networks.md create mode 100644 docs/dev/kinopoiskdev/Models/Nomination.md create mode 100644 docs/dev/kinopoiskdev/Models/NominationAward.md create mode 100644 docs/dev/kinopoiskdev/Models/Person.md create mode 100644 docs/dev/kinopoiskdev/Models/PersonAward.md create mode 100644 docs/dev/kinopoiskdev/Models/PersonInMovie.md create mode 100644 docs/dev/kinopoiskdev/Models/PersonPlace.md create mode 100644 docs/dev/kinopoiskdev/Models/Premiere.md create mode 100644 docs/dev/kinopoiskdev/Models/Rating.md create mode 100644 docs/dev/kinopoiskdev/Models/Review.md create mode 100644 docs/dev/kinopoiskdev/Models/ReviewInfo.md create mode 100644 docs/dev/kinopoiskdev/Models/SearchMovie.md create mode 100644 docs/dev/kinopoiskdev/Models/Season.md create mode 100644 docs/dev/kinopoiskdev/Models/SeasonInfo.md create mode 100644 docs/dev/kinopoiskdev/Models/ShortImage.md create mode 100644 docs/dev/kinopoiskdev/Models/Spouses.md create mode 100644 docs/dev/kinopoiskdev/Models/Studio.md create mode 100644 docs/dev/kinopoiskdev/Models/Video.md create mode 100644 docs/dev/kinopoiskdev/Models/VideoTypes.md create mode 100644 docs/dev/kinopoiskdev/Models/Votes.md create mode 100644 docs/dev/kinopoiskdev/Models/Watchability.md create mode 100644 docs/dev/kinopoiskdev/Models/WatchabilityItem.md create mode 100644 docs/dev/kinopoiskdev/Models/YearRange.md create mode 100644 docs/dev/kinopoiskdev/README.md create mode 100644 docs/dev/kinopoiskdev/Responses/.nav.yml create mode 100644 docs/dev/kinopoiskdev/Responses/Api/.nav.yml create mode 100644 docs/dev/kinopoiskdev/Responses/Api/ImageDocsResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/Api/KeywordDocsResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/Api/ListDocsResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/Api/MovieAwardDocsResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/Api/MovieDocsResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/Api/PersonAwardDocsResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/Api/PersonDocsResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/Api/PossibleValueDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/Api/ReviewDocsResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/Api/SearchMovieResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/Api/SearchPersonResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/Api/SearchStudioResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/Api/SeasonDocsResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/Api/StudioDocsResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/BaseDocsResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/BaseResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/ErrorResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/Errors/.nav.yml create mode 100644 docs/dev/kinopoiskdev/Responses/Errors/ForbiddenErrorResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/Errors/NotFoundErrorResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Responses/Errors/UnauthorizedErrorResponseDto.md create mode 100644 docs/dev/kinopoiskdev/Services/.nav.yml create mode 100644 docs/dev/kinopoiskdev/Services/CacheService.md create mode 100644 docs/dev/kinopoiskdev/Services/ValidationService.md create mode 100644 docs/dev/kinopoiskdev/Utils/.nav.yml create mode 100644 docs/dev/kinopoiskdev/Utils/DataManager.md create mode 100644 docs/dev/kinopoiskdev/Utils/FilterTrait.md create mode 100644 docs/dev/kinopoiskdev/Utils/MovieFilter.md create mode 100644 docs/dev/kinopoiskdev/Utils/SortManager.md create mode 100644 docs/dev/kinopoiskdev/notkinopoiskphp-compare.md diff --git a/docs/dev/.nav.yml b/docs/dev/.nav.yml index c065bfa..5ea2520 100644 --- a/docs/dev/.nav.yml +++ b/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 \ No newline at end of file + - Шаблон SeasonVar: paid-seasonvar/ + - Курс валют: paid-currencies_rate.md + - Последние новости списком: paid-lastnews.md diff --git a/docs/dev/kinopoiskdev/.nav.yml b/docs/dev/kinopoiskdev/.nav.yml new file mode 100644 index 0000000..402d578 --- /dev/null +++ b/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/ diff --git a/docs/dev/kinopoiskdev/Attributes/.nav.yml b/docs/dev/kinopoiskdev/Attributes/.nav.yml new file mode 100644 index 0000000..559a2ab --- /dev/null +++ b/docs/dev/kinopoiskdev/Attributes/.nav.yml @@ -0,0 +1,5 @@ +title: Атрибуты +nav: + - ApiField: ApiField.md + - Sensitive: Sensitive.md + - Validation: Validation.md \ No newline at end of file diff --git a/docs/dev/kinopoiskdev/Attributes/ApiField.md b/docs/dev/kinopoiskdev/Attributes/ApiField.md new file mode 100644 index 0000000..915cda9 --- /dev/null +++ b/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): Значение по умолчанию при отсутствии данных + diff --git a/docs/dev/kinopoiskdev/Attributes/Sensitive.md b/docs/dev/kinopoiskdev/Attributes/Sensitive.md new file mode 100644 index 0000000..0ac9707 --- /dev/null +++ b/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) + diff --git a/docs/dev/kinopoiskdev/Attributes/Validation.md b/docs/dev/kinopoiskdev/Attributes/Validation.md new file mode 100644 index 0000000..c3c22f4 --- /dev/null +++ b/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): Допустимые значения (для 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; +``` + diff --git a/docs/dev/kinopoiskdev/Contracts/.nav.yml b/docs/dev/kinopoiskdev/Contracts/.nav.yml new file mode 100644 index 0000000..75e7f35 --- /dev/null +++ b/docs/dev/kinopoiskdev/Contracts/.nav.yml @@ -0,0 +1,4 @@ +title: Контракты +nav: + - CacheInterface: CacheInterface.md + - LoggerInterface: LoggerInterface.md \ No newline at end of file diff --git a/docs/dev/kinopoiskdev/Contracts/CacheInterface.md b/docs/dev/kinopoiskdev/Contracts/CacheInterface.md new file mode 100644 index 0000000..698fa18 --- /dev/null +++ b/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): Массив ключей + +**Возвращает:** `array` Ассоциативный массив ключ => значение + +## `setMultiple()` + +**Описание:** Сохраняет множественные значения + +**Параметры:** + +* `$ttl` (int): Время жизни в секундах + +**Возвращает:** `bool True` при успешном сохранении + diff --git a/docs/dev/kinopoiskdev/Contracts/LoggerInterface.md b/docs/dev/kinopoiskdev/Contracts/LoggerInterface.md new file mode 100644 index 0000000..d712cec --- /dev/null +++ b/docs/dev/kinopoiskdev/Contracts/LoggerInterface.md @@ -0,0 +1,138 @@ +# LoggerInterface + +**Описание:** Интерфейс для логирования +Определяет контракт для ведения журнала событий +с поддержкой различных уровней логирования. Основан на +стандартах PSR-3 Logger Interface для обеспечения совместимости +с различными системами логирования. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**Пример:** +```php +class CustomLogger implements LoggerInterface { +public function debug(string $message, array $context = []): void { +echo "[DEBUG] {$message}\n"; +} +public function info(string $message, array $context = []): void { +echo "[INFO] {$message}\n"; +} +// ... остальные методы +} +$kinopoisk = new Kinopoisk(apiToken: 'token', logger: new CustomLogger()); +``` + +**См. также:** + +* `https:`: //www.php-fig.org/psr/psr-3/ PSR-3 Logger Interface + +## `debug()` + +**Описание:** Записывает сообщение уровня DEBUG +Используется для детальной отладочной информации, +которая полезна при разработке и диагностике проблем. +Эти сообщения обычно не записываются в продакшене. + +**Параметры:** + +* `$message` (string): Сообщение для записи в лог + +**Возвращает:** `void` + +**Пример:** +```php +$logger->debug('HTTP request started', [ +'method' => 'GET', +'url' => '/api/movie/123', +'user_id' => 456 +]); +``` + +## `info()` + +**Описание:** Записывает информационное сообщение +Используется для записи общей информации о работе приложения, +такой как инициализация, успешные операции, статистика. + +**Параметры:** + +* `$message` (string): Сообщение для записи в лог + +**Возвращает:** `void` + +**Пример:** +```php +$logger->info('Movie retrieved successfully', [ +'movie_id' => 123, +'response_time' => 0.15 +]); +``` + +## `warning()` + +**Описание:** Записывает предупреждение +Используется для записи предупреждений, которые не являются +критическими ошибками, но требуют внимания. Например, +устаревшие API вызовы, неоптимальные запросы. + +**Параметры:** + +* `$message` (string): Сообщение для записи в лог + +**Возвращает:** `void` + +**Пример:** +```php +$logger->warning('API rate limit approaching', [ +'current_requests' => 95, +'limit' => 100, +'reset_time' => '2024-01-01T00:00:00Z' +]); +``` + +## `error()` + +**Описание:** Записывает сообщение об ошибке +Используется для записи ошибок, которые не позволяют +выполнить запрошенную операцию, но не приводят к +полной остановке приложения. + +**Параметры:** + +* `$message` (string): Сообщение для записи в лог + +**Возвращает:** `void` + +**Пример:** +```php +$logger->error('Failed to retrieve movie', [ +'movie_id' => 123, +'error_code' => 404, +'error_message' => 'Movie not found' +]); +``` + +## `critical()` + +**Описание:** Записывает критическое сообщение +Используется для записи критических ошибок, которые +могут привести к нестабильной работе приложения +или требуют немедленного вмешательства. + +**Параметры:** + +* `$message` (string): Сообщение для записи в лог + +**Возвращает:** `void` + +**Пример:** +```php +$logger->critical('Database connection failed', [ +'host' => 'localhost', +'port' => 3306, +'error' => 'Connection refused' +]); +``` + diff --git a/docs/dev/kinopoiskdev/Enums/.nav.yml b/docs/dev/kinopoiskdev/Enums/.nav.yml new file mode 100644 index 0000000..0cec844 --- /dev/null +++ b/docs/dev/kinopoiskdev/Enums/.nav.yml @@ -0,0 +1,16 @@ +title: Перечисления +nav: + - FilterField: FilterField.md + - FilterOperator: FilterOperator.md + - HttpStatusCode: HttpStatusCode.md + - ImageType: ImageType.md + - ListCategory: ListCategory.md + - MovieStatus: MovieStatus.md + - MovieType: MovieType.md + - PersonProfession: PersonProfession.md + - PersonSex: PersonSex.md + - RatingMpaa: RatingMpaa.md + - ReviewType: ReviewType.md + - SortDirection: SortDirection.md + - SortField: SortField.md + - StudioType: StudioType.md \ No newline at end of file diff --git a/docs/dev/kinopoiskdev/Enums/FilterField.md b/docs/dev/kinopoiskdev/Enums/FilterField.md new file mode 100644 index 0000000..3e7fb74 --- /dev/null +++ b/docs/dev/kinopoiskdev/Enums/FilterField.md @@ -0,0 +1,276 @@ +# FilterField + +**Описание:** Enum для полей фильтрации +Этот enum содержит все возможные поля, которые можно использовать +при фильтрации данных через API Kinopoisk.dev + +## `getFieldType()` + +**Описание:** Возвращает тип поля + +## `supportsIncludeExclude()` + +**Описание:** Проверяет, поддерживает ли поле операторы включения/исключения + +## `supportsRange()` + +**Описание:** Проверяет, поддерживает ли поле диапазоны + +## `getDefaultOperator()` + +**Описание:** Возвращает оператор по умолчанию для поля + +## `getBaseField()` + +**Описание:** Возвращает базовое поле для составных полей (например, rating.kp -> rating) + +## `getSubField()` + +**Описание:** Возвращает подполе для составных полей (например, rating.kp -> kp) + +## Cases + +### `ID` + +**Значение:** `'id'` + +### `EXTERNAL_ID` + +**Значение:** `'externalId'` + +### `NAME` + +**Значение:** `'name'` + +### `EN_NAME` + +**Значение:** `'enName'` + +### `ALTERNATIVE_NAME` + +**Значение:** `'alternativeName'` + +### `NAMES` + +**Значение:** `'names.name'` + +### `DESCRIPTION` + +**Значение:** `'description'` + +### `SHORT_DESCRIPTION` + +**Значение:** `'shortDescription'` + +### `SLOGAN` + +**Значение:** `'slogan'` + +### `TYPE` + +**Значение:** `'type'` + +### `TYPE_NUMBER` + +**Значение:** `'typeNumber'` + +### `IS_SERIES` + +**Значение:** `'isSeries'` + +### `STATUS` + +**Значение:** `'status'` + +### `YEAR` + +**Значение:** `'year'` + +### `RELEASE_YEARS` + +**Значение:** `'releaseYears'` + +### `UPDATED_AT` + +**Значение:** `'updatedAt'` + +### `CREATED_AT` + +**Значение:** `'createdAt'` + +### `RATING_KP` + +**Значение:** `'rating.kp'` + +### `RATING_IMDB` + +**Значение:** `'rating.imdb'` + +### `RATING_TMDB` + +**Значение:** `'rating.tmdb'` + +### `RATING_FILM_CRITICS` + +**Значение:** `'rating.filmCritics'` + +### `RATING_RUSSIAN_FILM_CRITICS` + +**Значение:** `'rating.russianFilmCritics'` + +### `RATING_AWAIT` + +**Значение:** `'rating.await'` + +### `RATING_MPAA` + +**Значение:** `'ratingMpaa'` + +### `AGE_RATING` + +**Значение:** `'ageRating'` + +### `VOTES_KP` + +**Значение:** `'votes.kp'` + +### `VOTES_IMDB` + +**Значение:** `'votes.imdb'` + +### `VOTES_TMDB` + +**Значение:** `'votes.tmdb'` + +### `VOTES_FILM_CRITICS` + +**Значение:** `'votes.filmCritics'` + +### `VOTES_RUSSIAN_FILM_CRITICS` + +**Значение:** `'votes.russianFilmCritics'` + +### `VOTES_AWAIT` + +**Значение:** `'votes.await'` + +### `MOVIE_LENGTH` + +**Значение:** `'movieLength'` + +### `SERIES_LENGTH` + +**Значение:** `'seriesLength'` + +### `TOTAL_SERIES_LENGTH` + +**Значение:** `'totalSeriesLength'` + +### `GENRES` + +**Значение:** `'genres.name'` + +### `COUNTRIES` + +**Значение:** `'countries.name'` + +### `POSTER` + +**Значение:** `'poster'` + +### `BACKDROP` + +**Значение:** `'backdrop'` + +### `LOGO` + +**Значение:** `'logo'` + +### `TICKETS_ON_SALE` + +**Значение:** `'ticketsOnSale'` + +### `VIDEOS` + +**Значение:** `'videos'` + +### `NETWORKS` + +**Значение:** `'networks'` + +### `PERSONS` + +**Значение:** `'persons'` + +### `PERSONS_NAME` + +**Значение:** `'persons.name'` + +### `PERSONS_ID` + +**Значение:** `'persons.id'` + +### `PERSONS_PROFESSION` + +**Значение:** `'persons.profession'` + +### `FACTS` + +**Значение:** `'facts'` + +### `FEES` + +**Значение:** `'fees'` + +### `PREMIERE` + +**Значение:** `'premiere'` + +### `PREMIERE_WORLD` + +**Значение:** `'premiere.world'` + +### `PREMIERE_RUSSIA` + +**Значение:** `'premiere.russia'` + +### `PREMIERE_USA` + +**Значение:** `'premiere.usa'` + +### `SIMILAR_MOVIES` + +**Значение:** `'similarMovies'` + +### `SEQUELS_AND_PREQUELS` + +**Значение:** `'sequelsAndPrequels'` + +### `WATCHABILITY` + +**Значение:** `'watchability'` + +### `LISTS` + +**Значение:** `'lists'` + +### `TOP_10` + +**Значение:** `'top10'` + +### `TOP_250` + +**Значение:** `'top250'` + +### `SEASONS_INFO` + +**Значение:** `'seasonsInfo'` + +### `BUDGET` + +**Значение:** `'budget'` + +### `AUDIENCE` + +**Значение:** `'audience'` + diff --git a/docs/dev/kinopoiskdev/Enums/FilterOperator.md b/docs/dev/kinopoiskdev/Enums/FilterOperator.md new file mode 100644 index 0000000..b56e4d0 --- /dev/null +++ b/docs/dev/kinopoiskdev/Enums/FilterOperator.md @@ -0,0 +1,76 @@ +# FilterOperator + +**Описание:** Enum для операторов фильтрации +Этот enum содержит все возможные операторы, которые можно использовать +при фильтрации данных через API Kinopoisk.dev + +## `getDefaultForFieldType()` + +**Описание:** Возвращает оператор по умолчанию для указанного типа поля + +## `getPrefix()` + +**Описание:** Возвращает префикс для операторов включения/исключения + +## `isRangeOperator()` + +**Описание:** Проверяет, является ли оператор оператором диапазона + +## `isIncludeExcludeOperator()` + +**Описание:** Проверяет, является ли оператор оператором включения/исключения + +## Cases + +### `EQUALS` + +**Значение:** `'eq'` + +### `NOT_EQUALS` + +**Значение:** `'ne'` + +### `GREATER_THAN` + +**Значение:** `'gt'` + +### `GREATER_THAN_EQUALS` + +**Значение:** `'gte'` + +### `LESS_THAN` + +**Значение:** `'lt'` + +### `LESS_THAN_EQUALS` + +**Значение:** `'lte'` + +### `IN` + +**Значение:** `'in'` + +### `NOT_IN` + +**Значение:** `'nin'` + +### `ALL` + +**Значение:** `'all'` + +### `REGEX` + +**Значение:** `'regex'` + +### `RANGE` + +**Значение:** `'range'` + +### `INCLUDE` + +**Значение:** `'include'` + +### `EXCLUDE` + +**Значение:** `'exclude'` + diff --git a/docs/dev/kinopoiskdev/Enums/HttpStatusCode.md b/docs/dev/kinopoiskdev/Enums/HttpStatusCode.md new file mode 100644 index 0000000..94fbac3 --- /dev/null +++ b/docs/dev/kinopoiskdev/Enums/HttpStatusCode.md @@ -0,0 +1,40 @@ +# HttpStatusCode + +**Описание:** Enum для HTTP статус кодов +Предоставляет типизированные константы для основных HTTP статус кодов, +используемых в API Kinopoisk.dev + +## `getDescription()` + +**Описание:** Возвращает описание статус кода на русском языке + +## `isError()` + +**Описание:** Проверяет, является ли статус кодом ошибки + +## `isSuccess()` + +**Описание:** Проверяет, является ли статус кодом успеха + +## Cases + +### `OK` + +**Значение:** `200` + +### `UNAUTHORIZED` + +**Значение:** `401` + +### `FORBIDDEN` + +**Значение:** `403` + +### `NOT_FOUND` + +**Значение:** `404` + +### `INTERNAL_SERVER_ERROR` + +**Значение:** `500` + diff --git a/docs/dev/kinopoiskdev/Enums/ImageType.md b/docs/dev/kinopoiskdev/Enums/ImageType.md new file mode 100644 index 0000000..a2564f1 --- /dev/null +++ b/docs/dev/kinopoiskdev/Enums/ImageType.md @@ -0,0 +1,36 @@ +# ImageType + +## Cases + +### `BACKDROP` + +**Значение:** `'backdrops'` + +### `COVER` + +**Значение:** `'cover'` + +### `FRAME` + +**Значение:** `'frame'` + +### `PROMO` + +**Значение:** `'promo'` + +### `SCREENSHOT` + +**Значение:** `'screenshot'` + +### `SHOOTING` + +**Значение:** `'shooting'` + +### `STILL` + +**Значение:** `'still'` + +### `WALLPAPER` + +**Значение:** `'wallpaper'` + diff --git a/docs/dev/kinopoiskdev/Enums/ListCategory.md b/docs/dev/kinopoiskdev/Enums/ListCategory.md new file mode 100644 index 0000000..1fb9138 --- /dev/null +++ b/docs/dev/kinopoiskdev/Enums/ListCategory.md @@ -0,0 +1,24 @@ +# ListCategory + +## Cases + +### `ONLINE` + +**Значение:** `'Онлайн-кинотеатр'` + +### `AWARD` + +**Значение:** `'Премии'` + +### `FEE` + +**Значение:** `'Сборы'` + +### `SERIES` + +**Значение:** `'Сериалы'` + +### `MOVIE` + +**Значение:** `'Фильмы'` + diff --git a/docs/dev/kinopoiskdev/Enums/MovieStatus.md b/docs/dev/kinopoiskdev/Enums/MovieStatus.md new file mode 100644 index 0000000..1dde474 --- /dev/null +++ b/docs/dev/kinopoiskdev/Enums/MovieStatus.md @@ -0,0 +1,32 @@ +# MovieStatus + +**Описание:** Enum для статусов фильмов +Этот enum содержит все возможные статусы фильмов, которые могут быть +возвращены API Kinopoisk.dev + +## `getLabel()` + +**Описание:** Возвращает человекочитаемое название статуса фильма + +## Cases + +### `FILMING` + +**Значение:** `'filming'` + +### `PRE_PRODUCTION` + +**Значение:** `'pre-production'` + +### `COMPLETED` + +**Значение:** `'completed'` + +### `ANNOUNCED` + +**Значение:** `'announced'` + +### `POST_PRODUCTION` + +**Значение:** `'post-production'` + diff --git a/docs/dev/kinopoiskdev/Enums/MovieType.md b/docs/dev/kinopoiskdev/Enums/MovieType.md new file mode 100644 index 0000000..961cfd5 --- /dev/null +++ b/docs/dev/kinopoiskdev/Enums/MovieType.md @@ -0,0 +1,36 @@ +# MovieType + +**Описание:** Enum для типов фильмов +Этот enum содержит все возможные типы фильмов, которые могут быть +возвращены API Kinopoisk.dev + +## `getLabel()` + +**Описание:** Возвращает человекочитаемое название типа фильма + +## Cases + +### `MOVIE` + +**Значение:** `'movie'` + +### `TV_SERIES` + +**Значение:** `'tv-series'` + +### `CARTOON` + +**Значение:** `'cartoon'` + +### `ANIME` + +**Значение:** `'anime'` + +### `ANIMATED_SERIES` + +**Значение:** `'animated-series'` + +### `TV_SHOW` + +**Значение:** `'tv-show'` + diff --git a/docs/dev/kinopoiskdev/Enums/PersonProfession.md b/docs/dev/kinopoiskdev/Enums/PersonProfession.md new file mode 100644 index 0000000..93f8475 --- /dev/null +++ b/docs/dev/kinopoiskdev/Enums/PersonProfession.md @@ -0,0 +1,68 @@ +# PersonProfession + +**Описание:** Enum для профессий персон +Этот enum содержит все возможные профессии персон, которые могут быть +возвращены API Kinopoisk.dev + +## `fromRussianName()` + +**Описание:** Создает экземпляр enum из русского названия профессии + +## `getRussianName()` + +**Описание:** Возвращает название профессии на русском языке + +## `getRussianPluralName()` + +**Описание:** Возвращает множественное название профессии на русском языке + +## `getEnglishName()` + +**Описание:** Возвращает название профессии на английском языке + +## `getEnglishPluralName()` + +**Описание:** Возвращает множественное название профессии на английском языке + +## Cases + +### `ACTOR` + +**Значение:** `'actor'` + +### `DIRECTOR` + +**Значение:** `'director'` + +### `WRITER` + +**Значение:** `'writer'` + +### `PRODUCER` + +**Значение:** `'producer'` + +### `COMPOSER` + +**Значение:** `'composer'` + +### `OPERATOR` + +**Значение:** `'operator'` + +### `DESIGN` + +**Значение:** `'design'` + +### `EDITOR` + +**Значение:** `'editor'` + +### `VOICE_ACTOR` + +**Значение:** `'voice_actor'` + +### `OTHER` + +**Значение:** `'other'` + diff --git a/docs/dev/kinopoiskdev/Enums/PersonSex.md b/docs/dev/kinopoiskdev/Enums/PersonSex.md new file mode 100644 index 0000000..a14df59 --- /dev/null +++ b/docs/dev/kinopoiskdev/Enums/PersonSex.md @@ -0,0 +1,20 @@ +# PersonSex + +**Описание:** Enum для пола персон +Этот enum содержит все возможные значения пола персон, которые могут быть +возвращены API Kinopoisk.dev + +## `getRussianName()` + +**Описание:** Возвращает название пола на русском языке + +## Cases + +### `MALE` + +**Значение:** `'male'` + +### `FEMALE` + +**Значение:** `'female'` + diff --git a/docs/dev/kinopoiskdev/Enums/RatingMpaa.md b/docs/dev/kinopoiskdev/Enums/RatingMpaa.md new file mode 100644 index 0000000..b77a442 --- /dev/null +++ b/docs/dev/kinopoiskdev/Enums/RatingMpaa.md @@ -0,0 +1,32 @@ +# RatingMpaa + +**Описание:** Enum для рейтингов MPAA +Этот enum содержит все возможные рейтинги MPAA, которые могут быть +возвращены API Kinopoisk.dev + +## `getDescription()` + +**Описание:** Возвращает описание рейтинга MPAA + +## Cases + +### `G` + +**Значение:** `'g'` + +### `PG` + +**Значение:** `'pg'` + +### `PG13` + +**Значение:** `'pg13'` + +### `R` + +**Значение:** `'r'` + +### `NC17` + +**Значение:** `'nc17'` + diff --git a/docs/dev/kinopoiskdev/Enums/ReviewType.md b/docs/dev/kinopoiskdev/Enums/ReviewType.md new file mode 100644 index 0000000..1ae031e --- /dev/null +++ b/docs/dev/kinopoiskdev/Enums/ReviewType.md @@ -0,0 +1,16 @@ +# ReviewType + +## Cases + +### `POSITIVE` + +**Значение:** `'Позитивный'` + +### `NEGATIVE` + +**Значение:** `'Негативный'` + +### `NEUTRAL` + +**Значение:** `'Нейтральный'` + diff --git a/docs/dev/kinopoiskdev/Enums/SortDirection.md b/docs/dev/kinopoiskdev/Enums/SortDirection.md new file mode 100644 index 0000000..caa7a76 --- /dev/null +++ b/docs/dev/kinopoiskdev/Enums/SortDirection.md @@ -0,0 +1,98 @@ +# SortDirection + +**Описание:** Enum для направления сортировки результатов поиска +Этот enum определяет возможные направления сортировки данных +при выполнении запросов к API Kinopoisk.dev + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +## `reverse()` + +**Описание:** Возвращает противоположное направление сортировки +Полезно для переключения направления сортировки в пользовательских интерфейсах +или для реализации логики "toggle" сортировки. + +**Возвращает:** `SortDirection` Противоположное направление сортировки + +## `getSymbol()` + +**Описание:** Возвращает символьное представление направления +Предоставляет краткое символьное представление направления сортировки +для использования в пользовательских интерфейсах. + +**Возвращает:** `string` Символ направления сортировки ('↑' для ASC, '↓' для DESC) + +## `getDescription()` + +**Описание:** Возвращает описательное название направления на русском языке +Предоставляет человекочитаемое описание направления сортировки +для отображения в русскоязычных интерфейсах. + +**Возвращает:** `string` Описание направления сортировки на русском языке + +## `getShortDescription()` + +**Описание:** Возвращает краткое описание направления +Предоставляет сокращенное описание направления сортировки +для использования в компактных интерфейсах. + +**Возвращает:** `string` Краткое описание направления + +## `isAscending()` + +**Описание:** Проверяет, является ли направление возрастающим + +**Возвращает:** `bool true,` если направление ASC, false в противном случае + +## `isDescending()` + +**Описание:** Проверяет, является ли направление убывающим + +**Возвращает:** `bool true,` если направление DESC, false в противном случае + +## `fromString()` + +**Описание:** Создает направление из строкового значения с fallback +Безопасно создает экземпляр SortDirection из строки с возможностью +указания значения по умолчанию при неудачном преобразовании. + +**Параметры:** + +* `$value` (string): Строковое значение направления +* `$default` (SortDirection|null): Значение по умолчанию (ASC если не указано) + +**Возвращает:** `SortDirection` Экземпляр SortDirection + +## `getAllDirections()` + +**Описание:** Возвращает все доступные направления сортировки +Статический метод для получения всех возможных направлений сортировки. +Используется для создания интерфейсов выбора направления. + +**Возвращает:** `array` Массив всех направлений SortDirection + +## `getConvertedValue()` + +**Описание:** Возвращает конвертированное значение направления сортировки +Преобразует направление сортировки в числовое строковое представление, +которое может использоваться для сортировки в базах данных или внешних API. +Возрастающее направление (ASC) преобразуется в "1", убывающее (DESC) - в "-1". + +**Возвращает:** `string` Строковое числовое представление направления ("1" для ASC, "-1" для DESC) + +## Cases + +### `ASC` + +**Значение:** `'asc'` + +**Описание:** Сортировка по возрастанию (от меньшего к большему, от А до Я) + +### `DESC` + +**Значение:** `'desc'` + +**Описание:** Сортировка по убыванию (от большего к меньшему, от Я до А) + diff --git a/docs/dev/kinopoiskdev/Enums/SortField.md b/docs/dev/kinopoiskdev/Enums/SortField.md new file mode 100644 index 0000000..9b95709 --- /dev/null +++ b/docs/dev/kinopoiskdev/Enums/SortField.md @@ -0,0 +1,339 @@ +# SortField + +**Описание:** Enum для полей сортировки при поиске фильмов +Этот enum содержит все возможные поля, которые можно использовать +для сортировки результатов поиска через API Kinopoisk.dev + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +## `getPersonFields()` + +**Описание:** Возвращает массив полей персон для выбора +Предоставляет статически кэшируемый список всех доступных полей персон, +которые могут быть использованы при запросах к API для получения информации +о персонах. Включает основные данные персоны, информацию о супругах, +фильмографию и дополнительные метаданные. +Возвращаемые поля включают: +- Базовую информацию: ID, имя, год рождения, пол, рост +- Даты: дата создания/обновления записи, день рождения, дата смерти +- Профессиональную информацию: профессия, количество наград, возраст +- Места: место рождения и смерти +- Фото и факты +- Информацию о супругах: ID, имя, пол, развод и причины, дети, тип отношений +- Фильмографию: ID фильмов, названия, альтернативные названия, рейтинги, +общую информацию, описания, английские профессии +Метод использует статическое кэширование для оптимизации производительности +при множественных вызовах в рамках одного запроса. + +**С версии:** 1.0.0 + +**Возвращает:** `array` Массив строковых значений полей персон + +**Пример:** +```php +$fields = PersonField::getPersonFields(); +$selectFields = implode(',', $fields); // Для API запроса +// Использование в запросе +$filter->selectFields($fields); +``` + +## `getRatingFields()` + +**Описание:** Возвращает все поля рейтингов +Статический метод для получения всех доступных полей рейтингов. +Используется для создания интерфейсов выбора рейтинговых полей. + +**Возвращает:** `array` Массив всех рейтинговых полей SortField + +## `getVotesFields()` + +**Описание:** Возвращает все поля голосов +Статический метод для получения всех доступных полей голосов. +Используется для создания интерфейсов выбора полей голосов. + +**Возвращает:** `array` Массив всех полей голосов SortField + +## `getDescription()` + +**Описание:** Возвращает человекочитаемое описание поля +Предоставляет описательное название поля сортировки на русском языке +для использования в пользовательских интерфейсах и документации. + +**Возвращает:** `string` Описательное название поля на русском языке + +## `isRatingField()` + +**Описание:** Проверяет, является ли поле рейтинговым +Определяет, относится ли поле сортировки к категории рейтингов. +Используется для группировки и специальной обработки рейтинговых полей. + +**Возвращает:** `bool true,` если поле является рейтинговым, false в противном случае + +## `isVotesField()` + +**Описание:** Проверяет, является ли поле полем голосов +Определяет, относится ли поле сортировки к категории голосов. +Используется для группировки и специальной обработки полей голосов. + +**Возвращает:** `bool true,` если поле является полем голосов, false в противном случае + +## `isDateField()` + +**Описание:** Проверяет, является ли поле полем даты +Определяет, относится ли поле сортировки к категории дат. +Используется для валидации и специальной обработки временных полей. + +**Возвращает:** `bool true,` если поле является полем даты, false в противном случае + +## `getDataType()` + +**Описание:** Возвращает тип данных поля для валидации +Определяет тип данных поля сортировки для обеспечения корректной +валидации и обработки параметров сортировки. + +**Возвращает:** `string` Тип данных поля ('number', 'string', 'date') + +## `isNumericField()` + +**Описание:** Проверяет, является ли поле числовым +Определяет, относится ли поле сортировки к числовому типу данных. +Используется для валидации и обработки числовых значений. + +**Возвращает:** `bool true,` если поле является числовым, false в противном случае + +## `getDefaultDirection()` + +**Описание:** Возвращает рекомендуемое направление сортировки по умолчанию +Определяет наиболее логичное направление сортировки для каждого поля +на основе его семантики и обычных пользовательских ожиданий. + +**Возвращает:** `SortDirection` Рекомендуемое направление сортировки + +## Cases + +### `ID` + +**Значение:** `'id'` + +### `NAME` + +**Значение:** `'name'` + +### `EN_NAME` + +**Значение:** `'enName'` + +### `ALTERNATIVE_NAME` + +**Значение:** `'alternativeName'` + +### `YEAR` + +**Значение:** `'year'` + +### `CREATED_AT` + +**Значение:** `'createdAt'` + +### `UPDATED_AT` + +**Значение:** `'updatedAt'` + +### `RATING_KP` + +**Значение:** `'rating.kp'` + +### `RATING_IMDB` + +**Значение:** `'rating.imdb'` + +### `RATING_TMDB` + +**Значение:** `'rating.tmdb'` + +### `RATING_FILM_CRITICS` + +**Значение:** `'rating.filmCritics'` + +### `RATING_RUSSIAN_FILM_CRITICS` + +**Значение:** `'rating.russianFilmCritics'` + +### `RATING_AWAIT` + +**Значение:** `'rating.await'` + +### `VOTES_KP` + +**Значение:** `'votes.kp'` + +### `VOTES_IMDB` + +**Значение:** `'votes.imdb'` + +### `VOTES_TMDB` + +**Значение:** `'votes.tmdb'` + +### `VOTES_FILM_CRITICS` + +**Значение:** `'votes.filmCritics'` + +### `VOTES_RUSSIAN_FILM_CRITICS` + +**Значение:** `'votes.russianFilmCritics'` + +### `VOTES_AWAIT` + +**Значение:** `'votes.await'` + +### `MOVIE_LENGTH` + +**Значение:** `'movieLength'` + +### `SERIES_LENGTH` + +**Значение:** `'seriesLength'` + +### `TOTAL_SERIES_LENGTH` + +**Значение:** `'totalSeriesLength'` + +### `AGE_RATING` + +**Значение:** `'ageRating'` + +### `TOP_10` + +**Значение:** `'top10'` + +### `TOP_250` + +**Значение:** `'top250'` + +### `PREMIERE_WORLD` + +**Значение:** `'premiere.world'` + +### `PREMIERE_RUSSIA` + +**Значение:** `'premiere.russia'` + +### `PREMIERE_USA` + +**Значение:** `'premiere.usa'` + +### `TYPE` + +**Значение:** `'type'` + +### `TITLE` + +**Значение:** `'title'` + +### `MOVIES` + +**Значение:** `'movies'` + +### `PHOTO` + +**Значение:** `'photo'` + +### `SEX` + +**Значение:** `'sex'` + +### `GROWTH` + +**Значение:** `'growth'` + +### `BIRTHDAY` + +**Значение:** `'birthday'` + +### `DEATH` + +**Значение:** `'death'` + +### `AGE` + +**Значение:** `'age'` + +### `BIRTH_PLACE` + +**Значение:** `'birthPlace.value'` + +### `DEATH_PLACE` + +**Значение:** `'deathPlace.value'` + +### `COUNT_AWARDS` + +**Значение:** `'countAwards'` + +### `PROFESSION` + +**Значение:** `'profession.value'` + +### `SPOUSES_ID` + +**Значение:** `'spouses.id'` + +### `SPOUSES_NAME` + +**Значение:** `'spouses.name'` + +### `SPOUSES_DIVORCED` + +**Значение:** `'spouses.divorced'` + +### `SPOUSES_DIVORCED_REASON` + +**Значение:** `'spouses.divorcedReason'` + +### `SPOUSES_SEX` + +**Значение:** `'spouses.sex'` + +### `SPOUSES_CHILDREN` + +**Значение:** `'spouses.children'` + +### `SPOUSES_RELATION` + +**Значение:** `'spouses.relation'` + +### `FACTS` + +**Значение:** `'facts.value'` + +### `MOVIES_ID` + +**Значение:** `'movies.id'` + +### `MOVIES_NAME` + +**Значение:** `'movies.name'` + +### `MOVIES_ALTERNATIVE_NAME` + +**Значение:** `'movies.alternativeName'` + +### `MOVIES_RATING` + +**Значение:** `'movies.rating'` + +### `MOVIES_GENERAL` + +**Значение:** `'movies.general'` + +### `MOVIES_DESCRIPTION` + +**Значение:** `'movies.description'` + +### `MOVIES_EN_PROFESSION` + +**Значение:** `'movies.enProfession'` + diff --git a/docs/dev/kinopoiskdev/Enums/StudioType.md b/docs/dev/kinopoiskdev/Enums/StudioType.md new file mode 100644 index 0000000..5a103aa --- /dev/null +++ b/docs/dev/kinopoiskdev/Enums/StudioType.md @@ -0,0 +1,81 @@ +# StudioType + +**Описание:** Перечисление типов студий +Определяет возможные типы студий в системе Kinopoisk: +- Производство: кинокомпании, занимающиеся производством фильмов +- Спецэффекты: студии, специализирующиеся на создании визуальных эффектов +- Прокат: дистрибьюторские компании +- Студия дубляжа: студии, занимающиеся озвучиванием и дубляжом + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +## `getAllTypes()` + +**Описание:** Получает все доступные типы студий + +**Возвращает:** `array` Массив всех возможных типов студий + +## `isValidType()` + +**Описание:** Проверяет, является ли переданное значение валидным типом студии + +**Параметры:** + +* `$value` (string): Значение для проверки + +**Возвращает:** `bool True,` если значение является валидным типом студии + +## `fromString()` + +**Описание:** Получает тип студии по строковому значению + +**Параметры:** + +* `$value` (string): Строковое значение типа + +**Возвращает:** `self|null` Объект enum или null, если значение не найдено + +## `getDescription()` + +**Описание:** Получает описание типа студии + +**Возвращает:** `string` Человекочитаемое описание типа студии + +## `getEnglishName()` + +**Описание:** Получает английское название типа студии + +**Возвращает:** `string` Английское название типа + +## Cases + +### `PRODUCTION` + +**Значение:** `'Производство'` + +**Описание:** Производственная студия/кинокомпания +Компании, занимающиеся непосредственно производством фильмов и сериалов + +### `SPECIAL_EFFECTS` + +**Значение:** `'Спецэффекты'` + +**Описание:** Студия спецэффектов +Компании, специализирующиеся на создании визуальных и компьютерных эффектов + +### `DISTRIBUTION` + +**Значение:** `'Прокат'` + +**Описание:** Прокатная компания +Дистрибьюторы, занимающиеся распространением и показом фильмов + +### `DUBBING_STUDIO` + +**Значение:** `'Студия дубляжа'` + +**Описание:** Студия дубляжа +Компании, занимающиеся озвучиванием, дубляжом и локализацией контента + diff --git a/docs/dev/kinopoiskdev/Exceptions/.nav.yml b/docs/dev/kinopoiskdev/Exceptions/.nav.yml new file mode 100644 index 0000000..7b41a2b --- /dev/null +++ b/docs/dev/kinopoiskdev/Exceptions/.nav.yml @@ -0,0 +1,5 @@ +title: Исключения +nav: + - KinopoiskDevException: KinopoiskDevException.md + - KinopoiskResponseException: KinopoiskResponseException.md + - ValidationException: ValidationException.md \ No newline at end of file diff --git a/docs/dev/kinopoiskdev/Exceptions/KinopoiskDevException.md b/docs/dev/kinopoiskdev/Exceptions/KinopoiskDevException.md new file mode 100644 index 0000000..de9be74 --- /dev/null +++ b/docs/dev/kinopoiskdev/Exceptions/KinopoiskDevException.md @@ -0,0 +1,48 @@ +# KinopoiskDevException + +**Описание:** Базовое исключение для всех ошибок библиотеки KinopoiskDev +Основной класс исключений, от которого наследуются все специфические +исключения библиотеки. Предоставляет единообразный интерфейс для +обработки ошибок с поддержкой цепочки исключений. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**Пример:** +```php +try { +$kinopoisk = new Kinopoisk(); +$movie = $kinopoisk->getMovieById(123); +} catch (KinopoiskDevException $e) { +echo "Ошибка: " . $e->getMessage(); +echo "Код: " . $e->getCode(); +} +``` + +**См. также:** + +* `\KinopoiskDev\Exceptions\ValidationException`: Для ошибок валидации +* `\KinopoiskDev\Exceptions\KinopoiskResponseException`: Для ошибок API + +## `__construct()` + +**Описание:** Конструктор исключения +Создает новый экземпляр исключения с указанным сообщением, +кодом ошибки и предыдущим исключением для цепочки. + +**Параметры:** + +* `$message` (string): Сообщение об ошибке +* `$code` (int): Код ошибки (по умолчанию 0) +* `$previous` (Exception|null): Предыдущее исключение в цепочке + +**Пример:** +```php +throw new KinopoiskDevException( +'Ошибка подключения к API', +500, +$previousException +); +``` + diff --git a/docs/dev/kinopoiskdev/Exceptions/KinopoiskResponseException.md b/docs/dev/kinopoiskdev/Exceptions/KinopoiskResponseException.md new file mode 100644 index 0000000..405b5e8 --- /dev/null +++ b/docs/dev/kinopoiskdev/Exceptions/KinopoiskResponseException.md @@ -0,0 +1,51 @@ +# KinopoiskResponseException + +**Описание:** Исключение для ошибок ответов API Kinopoisk.dev +Специализированное исключение для обработки ошибок HTTP ответов +от API Kinopoisk.dev. Автоматически извлекает информацию об ошибке +из объекта ответа API и формирует понятное сообщение об ошибке. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**Пример:** +```php +try { +$movie = $kinopoisk->getMovieById(999999); +} catch (KinopoiskResponseException $e) { +echo "Ошибка API: " . $e->getMessage(); +echo "Код: " . $e->getCode(); // 404 +} +``` + +**См. также:** + +* `\KinopoiskDev\Responses\Errors\UnauthorizedErrorResponseDto`: Для ошибки 401 +* `\KinopoiskDev\Responses\Errors\ForbiddenErrorResponseDto`: Для ошибки 403 +* `\KinopoiskDev\Responses\Errors\NotFoundErrorResponseDto`: Для ошибки 404 + +## `__construct()` + +**Описание:** Конструктор исключения ответа API +Создает исключение на основе класса ответа API. Автоматически +извлекает информацию об ошибке из объекта ответа и формирует +сообщение об ошибке с кодом статуса. + +**Параметры:** + +* `$rspnsCls` (string): Полное имя класса ответа API (например, UnauthorizedErrorResponseDto::class) +* `$previous` (Exception|null): Предыдущее исключение в цепочке + +**Исключения:** + +* `\Error`: При неверном имени класса ответа + +**Пример:** +```php +throw new KinopoiskResponseException( +UnauthorizedErrorResponseDto::class, +$previousException +); +``` + diff --git a/docs/dev/kinopoiskdev/Exceptions/ValidationException.md b/docs/dev/kinopoiskdev/Exceptions/ValidationException.md new file mode 100644 index 0000000..f30d952 --- /dev/null +++ b/docs/dev/kinopoiskdev/Exceptions/ValidationException.md @@ -0,0 +1,166 @@ +# ValidationException + +**Описание:** Исключение для ошибок валидации данных +Специализированное исключение для обработки ошибок валидации +с поддержкой множественных ошибок и детальной диагностики. +Используется для валидации входных данных, параметров API +и моделей данных. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**Пример:** +```php +try { +$movie = Movie::fromArray($data); +$movie->validate(); +} catch (ValidationException $e) { +foreach ($e->getErrors() as $field => $error) { +echo "Поле {$field}: {$error}\n"; +} +} +``` + +**См. также:** + +* `\KinopoiskDev\Services\ValidationService`: Сервис валидации +* `\KinopoiskDev\Attributes\Validation`: Атрибут валидации + +## `__construct()` + +**Описание:** Конструктор исключения валидации +Создает новый экземпляр исключения валидации с указанными параметрами. +Поддерживает как одиночные ошибки для конкретного поля, +так и множественные ошибки для нескольких полей. + +**Параметры:** + +* `$message` (string): Основное сообщение об ошибке +* `$field` (string|null): Поле, вызвавшее ошибку +* `$value` (mixed): Значение, не прошедшее валидацию +* `$code` (int): Код ошибки (по умолчанию 0) +* `$previous` (Throwable|null): Предыдущее исключение в цепочке + +**Пример:** +```php +throw new ValidationException( +'Ошибка валидации фильма', +['title' => 'Название обязательно', 'year' => 'Год должен быть положительным'], +'title', +null +); +``` + +## `forField()` + +**Описание:** Создает исключение для конкретного поля +Фабричный метод для создания исключения валидации +для одного конкретного поля с указанным сообщением об ошибке. + +**Параметры:** + +* `$field` (string): Название поля, вызвавшего ошибку +* `$message` (string): Сообщение об ошибке валидации +* `$value` (mixed): Значение поля, не прошедшее валидацию + +**Возвращает:** `self` Экземпляр исключения валидации + +**Пример:** +```php +throw ValidationException::forField( +'email', +'Неверный формат email адреса', +'invalid-email' +); +``` + +## `withErrors()` + +**Описание:** Создает исключение для множественных ошибок +Фабричный метод для создания исключения валидации +с множественными ошибками для разных полей. + +**Возвращает:** `self` Экземпляр исключения валидации + +**Пример:** +```php +$errors = [ +'title' => 'Название обязательно', +'year' => 'Год должен быть положительным', +'rating' => 'Рейтинг должен быть от 0 до 10' +]; +throw ValidationException::withErrors($errors); +``` + +## `getErrors()` + +**Описание:** Возвращает список всех ошибок валидации +Возвращает ассоциативный массив, где ключи - названия полей, +а значения - сообщения об ошибках валидации. + +**Возвращает:** `array` Массив ошибок в формате ['field' => 'error_message'] + +**Пример:** +```php +$errors = $exception->getErrors(); +// Результат: ['title' => 'Название обязательно', 'year' => 'Год должен быть положительным'] +``` + +## `getField()` + +**Описание:** Возвращает поле, вызвавшее ошибку +Возвращает название поля, которое не прошло валидацию. +Может быть null, если ошибка не связана с конкретным полем. + +**Возвращает:** `string|null` Название поля или null + +**Пример:** +```php +$field = $exception->getField(); +// Результат: 'title' или null +``` + +## `getValue()` + +**Описание:** Возвращает значение, не прошедшее валидацию +Возвращает значение, которое вызвало ошибку валидации. +Полезно для диагностики и отладки проблем валидации. + +**Возвращает:** `mixed` Проблемное значение + +**Пример:** +```php +$value = $exception->getValue(); +// Результат: null, пустая строка, отрицательное число и т.д. +``` + +## `getFirstError()` + +**Описание:** Возвращает первую ошибку валидации +Возвращает текст первой ошибки из списка ошибок валидации. +Полезно для быстрого отображения основной проблемы. + +**Возвращает:** `string|null` Текст первой ошибки или null, если ошибок нет + +**Пример:** +```php +$firstError = $exception->getFirstError(); +// Результат: 'Название обязательно' или null +``` + +## `hasErrors()` + +**Описание:** Проверяет, есть ли ошибки валидации +Удобный метод для проверки наличия ошибок валидации +без необходимости проверки размера массива ошибок. + +**Возвращает:** `bool True` если есть ошибки, false если ошибок нет + +**Пример:** +```php +if ($exception->hasErrors()) { +// Обработка ошибок +} +``` + diff --git a/docs/dev/kinopoiskdev/Filter/.nav.yml b/docs/dev/kinopoiskdev/Filter/.nav.yml new file mode 100644 index 0000000..ce98d92 --- /dev/null +++ b/docs/dev/kinopoiskdev/Filter/.nav.yml @@ -0,0 +1,10 @@ +title: Фильтры +nav: + - ImageSearchFilter: ImageSearchFilter.md + - KeywordSearchFilter: KeywordSearchFilter.md + - MovieSearchFilter: MovieSearchFilter.md + - PersonSearchFilter: PersonSearchFilter.md + - ReviewSearchFilter: ReviewSearchFilter.md + - SeasonSearchFilter: SeasonSearchFilter.md + - SortCriteria: SortCriteria.md + - StudioSearchFilter: StudioSearchFilter.md \ No newline at end of file diff --git a/docs/dev/kinopoiskdev/Filter/ImageSearchFilter.md b/docs/dev/kinopoiskdev/Filter/ImageSearchFilter.md new file mode 100644 index 0000000..6158a13 --- /dev/null +++ b/docs/dev/kinopoiskdev/Filter/ImageSearchFilter.md @@ -0,0 +1,180 @@ +# ImageSearchFilter + +**Описание:** Класс для фильтров при поиске изображений + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +## `language()` + +**Описание:** Добавляет фильтр по языку изображения + +**Параметры:** + +* `$language` (string): Язык изображения + +## `onlyPosters()` + +**Описание:** Фильтр только для постеров + +## `onlyStills()` + +**Описание:** Фильтр только для кадров + +## `onlyShooting()` + +**Описание:** Фильтр только для фотосессий + +## `onlyScreenshots()` + +**Описание:** Фильтр только для скриншотов + +## `onlyHighRes()` + +**Описание:** Фильтр только для изображений высокого разрешения (Full HD+) + +## `minResolution()` + +**Описание:** Добавляет фильтр по минимальному разрешению + +**Параметры:** + +* `$minWidth` (int): Минимальная ширина +* `$minHeight` (int): Минимальная высота + +## `width()` + +**Описание:** Добавляет фильтр по ширине изображения + +**Параметры:** + +* `$width` (int): Ширина изображения в пикселях +* `$operator` (string): Оператор сравнения + +## `height()` + +**Описание:** Добавляет фильтр по высоте изображения + +**Параметры:** + +* `$height` (int): Высота изображения в пикселях +* `$operator` (string): Оператор сравнения + +## `name()` + +**Описание:** Добавляет фильтр по названию + +**Параметры:** + +* `$name` (string): Название +* `$operator` (string): Оператор сравнения + +## `enName()` + +**Описание:** Добавляет фильтр по английскому названию + +**Параметры:** + +* `$enName` (string): Английское название +* `$operator` (string): Оператор сравнения + +## `type()` + +**Описание:** Добавляет фильтр по типу + +**Параметры:** + +* `$type` (string|\KinopoiskDev\Enums\ReviewType): Тип +* `$operator` (string): Оператор сравнения + +**Возвращает:** `\KinopoiskDev\Filter\MovieSearchFilter|\KinopoiskDev\Filter\ImageSearchFilter|\KinopoiskDev\Filter\KeywordSearchFilter|\KinopoiskDev\Filter\PersonSearchFilter|\KinopoiskDev\Filter\ReviewSearchFilter|\KinopoiskDev\Filter\SeasonSearchFilter|\KinopoiskDev\Filter\StudioSearchFilter|\KinopoiskDev\Utils\FilterTrait` + +## `movieId()` + +**Описание:** Добавляет фильтр по ID фильма + +**Параметры:** + +* `$movieId` (int): ID фильма + +## `searchByName()` + +**Описание:** Добавляет поисковый фильтр по названию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `searchByEnName()` + +**Описание:** Добавляет поисковый фильтр по английскому названию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `searchByDescription()` + +**Описание:** Добавляет поисковый фильтр по описанию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `withMinRating()` + +**Описание:** Добавляет фильтр по минимальному рейтингу + +**Параметры:** + +* `$minRating` (float): Минимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `withMaxRating()` + +**Описание:** Добавляет фильтр по максимальному рейтингу + +**Параметры:** + +* `$maxRating` (float): Максимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `withRatingBetween()` + +**Описание:** Добавляет фильтр по диапазону рейтинга + +**Параметры:** + +* `$minRating` (float): Минимальный рейтинг +* `$maxRating` (float): Максимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `addRangeFilter()` + +**Описание:** Добавляет фильтр по диапазону + +**Параметры:** + +* `$field` (string): Имя поля +* `$minValue` (int): Минимальное значение +* `$maxValue` (int): Максимальное значение + +## `seasonRange()` + +**Описание:** Добавляет фильтр по диапазону сезонов + +**Параметры:** + +* `$fromSeason` (int): Начальный сезон +* `$toSeason` (int): Конечный сезон + +## `ageRange()` + +**Описание:** Добавляет фильтр по возрастному диапазону + +**Параметры:** + +* `$minAge` (int): Минимальный возраст +* `$maxAge` (int): Максимальный возраст + diff --git a/docs/dev/kinopoiskdev/Filter/KeywordSearchFilter.md b/docs/dev/kinopoiskdev/Filter/KeywordSearchFilter.md new file mode 100644 index 0000000..eec4532 --- /dev/null +++ b/docs/dev/kinopoiskdev/Filter/KeywordSearchFilter.md @@ -0,0 +1,284 @@ +# KeywordSearchFilter + +**Описание:** Фильтр для поиска ключевых слов +Класс предоставляет методы для создания фильтров поиска ключевых слов +по различным критериям: ID, названию, связанным фильмам, датам и т.д. +Используется в KeywordRequests для формирования параметров запроса к API. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Http\KeywordRequests`: Для использования фильтра + +## `id()` + +**Описание:** Добавляет фильтр по ID ключевого слова + +**Параметры:** + +* `$id` (int|array): ID ключевого слова или массив ID +* `$operator` (string): Оператор сравнения (eq, ne, in, nin) + +## `title()` + +**Описание:** Добавляет фильтр по названию ключевого слова + +**Параметры:** + +* `$title` (string): Название ключевого слова +* `$operator` (string): Оператор сравнения (eq, ne, regex) + +## `movieId()` + +**Описание:** Добавляет фильтр по ID фильма +Находит все ключевые слова, связанные с указанным фильмом. + +**Параметры:** + +* `$movieId` (int|array): ID фильма или массив ID фильмов + +## `createdAt()` + +**Описание:** Добавляет фильтр по дате создания + +**Параметры:** + +* `$createdAt` (string): Дата создания в ISO формате +* `$operator` (string): Оператор сравнения (eq, ne, gt, gte, lt, lte) + +## `updatedAt()` + +**Описание:** Добавляет фильтр по дате обновления + +**Параметры:** + +* `$updatedAt` (string): Дата обновления в ISO формате +* `$operator` (string): Оператор сравнения (eq, ne, gt, gte, lt, lte) + +## `search()` + +**Описание:** Поиск ключевых слов по названию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `onlyPopular()` + +**Описание:** Фильтр для популярных ключевых слов (связанных с большим количеством фильмов) +Возвращает ключевые слова, которые встречаются в 10 и более фильмах. + +**Параметры:** + +* `$minMovieCount` (int): Минимальное количество связанных фильмов + +## `recentlyCreated()` + +**Описание:** Фильтр для недавно созданных ключевых слов + +**Параметры:** + +* `$daysAgo` (int): Количество дней назад от текущей даты + +## `recentlyUpdated()` + +**Описание:** Фильтр для недавно обновленных ключевых слов + +**Параметры:** + +* `$daysAgo` (int): Количество дней назад от текущей даты + +## `createdBetween()` + +**Описание:** Фильтр по диапазону дат создания + +**Параметры:** + +* `$startDate` (string): Начальная дата в ISO формате +* `$endDate` (string): Конечная дата в ISO формате + +## `updatedBetween()` + +**Описание:** Фильтр по диапазону дат обновления + +**Параметры:** + +* `$startDate` (string): Начальная дата в ISO формате +* `$endDate` (string): Конечная дата в ISO формате + +## `selectFields()` + +**Описание:** Выбор определенных полей для возвращения + +**Параметры:** + +* `$fields` (array): Массив названий полей + +## `notNullFields()` + +**Описание:** Исключение записей с пустыми значениями в указанных полях + +**Параметры:** + +* `$fields` (array): Массив названий полей + +## `sortById()` + +**Описание:** Сортировка по ID ключевого слова + +**Параметры:** + +* `$direction` (string): Направление сортировки ('asc' или 'desc') + +## `sortByTitle()` + +**Описание:** Сортировка по названию ключевого слова + +**Параметры:** + +* `$direction` (string): Направление сортировки ('asc' или 'desc') + +## `sortByCreatedAt()` + +**Описание:** Сортировка по дате создания + +**Параметры:** + +* `$direction` (string): Направление сортировки ('asc' или 'desc') + +## `sortByUpdatedAt()` + +**Описание:** Сортировка по дате обновления + +**Параметры:** + +* `$direction` (string): Направление сортировки ('asc' или 'desc') + +## `sortByPopularity()` + +**Описание:** Сортировка по популярности (количеству связанных фильмов) + +**Параметры:** + +* `$direction` (string): Направление сортировки ('desc' для самых популярных) + +**Возвращает:** `static` + +## `getFilters()` + +**Описание:** Возвращает массив фильтров + +**Возвращает:** `array` + +## `name()` + +**Описание:** Добавляет фильтр по названию + +**Параметры:** + +* `$name` (string): Название +* `$operator` (string): Оператор сравнения + +## `enName()` + +**Описание:** Добавляет фильтр по английскому названию + +**Параметры:** + +* `$enName` (string): Английское название +* `$operator` (string): Оператор сравнения + +## `type()` + +**Описание:** Добавляет фильтр по типу + +**Параметры:** + +* `$type` (string|\KinopoiskDev\Enums\ReviewType): Тип +* `$operator` (string): Оператор сравнения + +**Возвращает:** `\KinopoiskDev\Filter\MovieSearchFilter|\KinopoiskDev\Filter\ImageSearchFilter|\KinopoiskDev\Filter\KeywordSearchFilter|\KinopoiskDev\Filter\PersonSearchFilter|\KinopoiskDev\Filter\ReviewSearchFilter|\KinopoiskDev\Filter\SeasonSearchFilter|\KinopoiskDev\Filter\StudioSearchFilter|\KinopoiskDev\Utils\FilterTrait` + +## `searchByName()` + +**Описание:** Добавляет поисковый фильтр по названию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `searchByEnName()` + +**Описание:** Добавляет поисковый фильтр по английскому названию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `searchByDescription()` + +**Описание:** Добавляет поисковый фильтр по описанию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `withMinRating()` + +**Описание:** Добавляет фильтр по минимальному рейтингу + +**Параметры:** + +* `$minRating` (float): Минимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `withMaxRating()` + +**Описание:** Добавляет фильтр по максимальному рейтингу + +**Параметры:** + +* `$maxRating` (float): Максимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `withRatingBetween()` + +**Описание:** Добавляет фильтр по диапазону рейтинга + +**Параметры:** + +* `$minRating` (float): Минимальный рейтинг +* `$maxRating` (float): Максимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `addRangeFilter()` + +**Описание:** Добавляет фильтр по диапазону + +**Параметры:** + +* `$field` (string): Имя поля +* `$minValue` (int): Минимальное значение +* `$maxValue` (int): Максимальное значение + +## `seasonRange()` + +**Описание:** Добавляет фильтр по диапазону сезонов + +**Параметры:** + +* `$fromSeason` (int): Начальный сезон +* `$toSeason` (int): Конечный сезон + +## `ageRange()` + +**Описание:** Добавляет фильтр по возрастному диапазону + +**Параметры:** + +* `$minAge` (int): Минимальный возраст +* `$maxAge` (int): Максимальный возраст + diff --git a/docs/dev/kinopoiskdev/Filter/MovieSearchFilter.md b/docs/dev/kinopoiskdev/Filter/MovieSearchFilter.md new file mode 100644 index 0000000..aed268f --- /dev/null +++ b/docs/dev/kinopoiskdev/Filter/MovieSearchFilter.md @@ -0,0 +1,259 @@ +# MovieSearchFilter + +**Описание:** Класс для создания фильтров при поиске фильмов +Этот класс расширяет базовый MovieFilter и предоставляет +дополнительные методы для поиска фильмов + +**Ссылка:** https://kinopoiskdev.readme.io/reference/moviecontroller_findmanybyqueryv1_4 + +## `searchByAlternativeName()` + +**Описание:** Добавляет фильтр для поиска по альтернативному названию с использованием регулярного выражения + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `searchByAllNames()` + +**Описание:** Добавляет фильтр для поиска по всем названиям фильма + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `withMinVotes()` + +**Описание:** Добавляет фильтр для поиска фильмов с количеством голосов выше указанного + +**Параметры:** + +* `$minVotes` (int): Минимальное количество голосов +* `$field` (string): Поле голосов (kp, imdb, tmdb, filmCritics, russianFilmCritics, await) + +## `withVotesBetween()` + +**Описание:** Добавляет фильтр для поиска фильмов в диапазоне голосов + +**Параметры:** + +* `$minVotes` (int): Минимальное количество голосов +* `$maxVotes` (int): Максимальное количество голосов +* `$field` (string): Поле голосов (kp, imdb, tmdb, filmCritics, russianFilmCritics, await) + +## `withYearBetween()` + +**Описание:** Добавляет фильтр для поиска фильмов в диапазоне годов + +**Параметры:** + +* `$fromYear` (int): Начальный год +* `$toYear` (int): Конечный год + +## `withAllGenres()` + +**Описание:** Добавляет фильтр для поиска фильмов по нескольким жанрам (И) + +**Параметры:** + +* `$genres` (array): Массив жанров + +## `withIncludedGenres()` + +**Описание:** Добавляет фильтр для включения жанров (оператор +) + +**Параметры:** + +* `$genres` (string|array): Жанр или массив жанров для включения + +## `withExcludedGenres()` + +**Описание:** Добавляет фильтр для исключения жанров (оператор !) + +**Параметры:** + +* `$genres` (string|array): Жанр или массив жанров для исключения + +## `withAllCountries()` + +**Описание:** Добавляет фильтр для поиска фильмов по нескольким странам (И) + +**Параметры:** + +* `$countries` (array): Массив стран + +## `withIncludedCountries()` + +**Описание:** Добавляет фильтр для включения стран (оператор +) + +**Параметры:** + +* `$countries` (string|array): Страна или массив стран для включения + +## `withExcludedCountries()` + +**Описание:** Добавляет фильтр для исключения стран (оператор !) + +**Параметры:** + +* `$countries` (string|array): Страна или массив стран для исключения + +## `withActor()` + +**Описание:** Добавляет фильтр для поиска фильмов с участием указанного актера + +**Параметры:** + +* `$actor` (string|int): Имя актера или его ID + +## `withDirector()` + +**Описание:** Добавляет фильтр для поиска фильмов указанного режиссера + +**Параметры:** + +* `$director` (string|int): Имя режиссера или его ID + +## `onlyMovies()` + +**Описание:** Добавляет фильтр для поиска только фильмов (не сериалов) + +## `onlySeries()` + +**Описание:** Добавляет фильтр для поиска только сериалов + +## `inTop250()` + +**Описание:** Добавляет фильтр для поиска фильмов из топ-250 + +## `inTop10()` + +**Описание:** Добавляет фильтр для поиска фильмов из топ-10 + +## `withPremiereRange()` + +**Описание:** Добавляет фильтр по диапазону дат премьеры + +**Параметры:** + +* `$fromDate` (string): Начальная дата в формате dd.mm.yyyy +* `$toDate` (string): Конечная дата в формате dd.mm.yyyy +* `$country` (string): Страна премьеры (russia, world, usa, ...) + +## `name()` + +**Описание:** Добавляет фильтр по названию + +**Параметры:** + +* `$name` (string): Название +* `$operator` (string): Оператор сравнения + +## `enName()` + +**Описание:** Добавляет фильтр по английскому названию + +**Параметры:** + +* `$enName` (string): Английское название +* `$operator` (string): Оператор сравнения + +## `type()` + +**Описание:** Добавляет фильтр по типу + +**Параметры:** + +* `$type` (string|\KinopoiskDev\Enums\ReviewType): Тип +* `$operator` (string): Оператор сравнения + +**Возвращает:** `\KinopoiskDev\Filter\MovieSearchFilter|\KinopoiskDev\Filter\ImageSearchFilter|\KinopoiskDev\Filter\KeywordSearchFilter|\KinopoiskDev\Filter\PersonSearchFilter|\KinopoiskDev\Filter\ReviewSearchFilter|\KinopoiskDev\Filter\SeasonSearchFilter|\KinopoiskDev\Filter\StudioSearchFilter|\KinopoiskDev\Utils\FilterTrait` + +## `movieId()` + +**Описание:** Добавляет фильтр по ID фильма + +**Параметры:** + +* `$movieId` (int): ID фильма + +## `searchByName()` + +**Описание:** Добавляет поисковый фильтр по названию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `searchByEnName()` + +**Описание:** Добавляет поисковый фильтр по английскому названию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `searchByDescription()` + +**Описание:** Добавляет поисковый фильтр по описанию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `withMinRating()` + +**Описание:** Добавляет фильтр по минимальному рейтингу + +**Параметры:** + +* `$minRating` (float): Минимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `withMaxRating()` + +**Описание:** Добавляет фильтр по максимальному рейтингу + +**Параметры:** + +* `$maxRating` (float): Максимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `withRatingBetween()` + +**Описание:** Добавляет фильтр по диапазону рейтинга + +**Параметры:** + +* `$minRating` (float): Минимальный рейтинг +* `$maxRating` (float): Максимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `addRangeFilter()` + +**Описание:** Добавляет фильтр по диапазону + +**Параметры:** + +* `$field` (string): Имя поля +* `$minValue` (int): Минимальное значение +* `$maxValue` (int): Максимальное значение + +## `seasonRange()` + +**Описание:** Добавляет фильтр по диапазону сезонов + +**Параметры:** + +* `$fromSeason` (int): Начальный сезон +* `$toSeason` (int): Конечный сезон + +## `ageRange()` + +**Описание:** Добавляет фильтр по возрастному диапазону + +**Параметры:** + +* `$minAge` (int): Минимальный возраст +* `$maxAge` (int): Максимальный возраст + diff --git a/docs/dev/kinopoiskdev/Filter/PersonSearchFilter.md b/docs/dev/kinopoiskdev/Filter/PersonSearchFilter.md new file mode 100644 index 0000000..39ec8d7 --- /dev/null +++ b/docs/dev/kinopoiskdev/Filter/PersonSearchFilter.md @@ -0,0 +1,212 @@ +# PersonSearchFilter + +**Описание:** Класс для фильтров при поиске персон +Расширяет базовый фильтр методами, специфичными для персон + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +## `age()` + +**Описание:** Добавляет фильтр по возрасту + +**Параметры:** + +* `$age` (int): Возраст +* `$operator` (string): Оператор сравнения (eq, gte, lte, и т.д.) + +## `sex()` + +**Описание:** Добавляет фильтр по полу + +**Параметры:** + +* `$sex` (string): Пол (male, female) + +## `birthPlace()` + +**Описание:** Добавляет фильтр по месту рождения + +**Параметры:** + +* `$birthPlace` (string): Место рождения +* `$operator` (string): Оператор сравнения + +## `death()` + +**Описание:** Добавляет фильтр по дате смерти + +**Параметры:** + +* `$death` (string): Дата смерти +* `$operator` (string): Оператор сравнения + +## `birthday()` + +**Описание:** Добавляет фильтр по дате рождения + +**Параметры:** + +* `$birthday` (string): Дата рождения +* `$operator` (string): Оператор сравнения + +## `countAwards()` + +**Описание:** Добавляет фильтр по количеству наград + +**Параметры:** + +* `$countAwards` (int): Количество наград +* `$operator` (string): Оператор сравнения + +## `onlyActors()` + +**Описание:** Фильтр только для актеров + +## `profession()` + +**Описание:** Добавляет фильтр по профессии + +**Параметры:** + +* `$profession` (string): Профессия (актер, режиссер, сценарист, и т.д.) +* `$operator` (string): Оператор сравнения + +## `onlyDirectors()` + +**Описание:** Фильтр только для режиссеров + +## `onlyWriters()` + +**Описание:** Фильтр только для сценаристов + +## `onlyAlive()` + +**Описание:** Фильтр только для живых персон + +## `birthYear()` + +**Описание:** Фильтрация по году рождения (один год или диапазон) + +## `deathYear()` + +**Описание:** Фильтрация по году смерти + +## `name()` + +**Описание:** Добавляет фильтр по названию + +**Параметры:** + +* `$name` (string): Название +* `$operator` (string): Оператор сравнения + +## `enName()` + +**Описание:** Добавляет фильтр по английскому названию + +**Параметры:** + +* `$enName` (string): Английское название +* `$operator` (string): Оператор сравнения + +## `type()` + +**Описание:** Добавляет фильтр по типу + +**Параметры:** + +* `$type` (string|\KinopoiskDev\Enums\ReviewType): Тип +* `$operator` (string): Оператор сравнения + +**Возвращает:** `\KinopoiskDev\Filter\MovieSearchFilter|\KinopoiskDev\Filter\ImageSearchFilter|\KinopoiskDev\Filter\KeywordSearchFilter|\KinopoiskDev\Filter\PersonSearchFilter|\KinopoiskDev\Filter\ReviewSearchFilter|\KinopoiskDev\Filter\SeasonSearchFilter|\KinopoiskDev\Filter\StudioSearchFilter|\KinopoiskDev\Utils\FilterTrait` + +## `movieId()` + +**Описание:** Добавляет фильтр по ID фильма + +**Параметры:** + +* `$movieId` (int): ID фильма + +## `searchByName()` + +**Описание:** Добавляет поисковый фильтр по названию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `searchByEnName()` + +**Описание:** Добавляет поисковый фильтр по английскому названию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `searchByDescription()` + +**Описание:** Добавляет поисковый фильтр по описанию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `withMinRating()` + +**Описание:** Добавляет фильтр по минимальному рейтингу + +**Параметры:** + +* `$minRating` (float): Минимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `withMaxRating()` + +**Описание:** Добавляет фильтр по максимальному рейтингу + +**Параметры:** + +* `$maxRating` (float): Максимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `withRatingBetween()` + +**Описание:** Добавляет фильтр по диапазону рейтинга + +**Параметры:** + +* `$minRating` (float): Минимальный рейтинг +* `$maxRating` (float): Максимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `addRangeFilter()` + +**Описание:** Добавляет фильтр по диапазону + +**Параметры:** + +* `$field` (string): Имя поля +* `$minValue` (int): Минимальное значение +* `$maxValue` (int): Максимальное значение + +## `seasonRange()` + +**Описание:** Добавляет фильтр по диапазону сезонов + +**Параметры:** + +* `$fromSeason` (int): Начальный сезон +* `$toSeason` (int): Конечный сезон + +## `ageRange()` + +**Описание:** Добавляет фильтр по возрастному диапазону + +**Параметры:** + +* `$minAge` (int): Минимальный возраст +* `$maxAge` (int): Максимальный возраст + diff --git a/docs/dev/kinopoiskdev/Filter/ReviewSearchFilter.md b/docs/dev/kinopoiskdev/Filter/ReviewSearchFilter.md new file mode 100644 index 0000000..b489963 --- /dev/null +++ b/docs/dev/kinopoiskdev/Filter/ReviewSearchFilter.md @@ -0,0 +1,164 @@ +# ReviewSearchFilter + +**Описание:** Класс для фильтров при поиске отзывов + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +## `author()` + +**Описание:** Добавляет фильтр по автору + +**Параметры:** + +* `$author` (string): Автор отзыва +* `$operator` (string): Оператор сравнения + +## `review()` + +**Описание:** Добавляет фильтр по тексту отзыва + +**Параметры:** + +* `$review` (string): Текст отзыва +* `$operator` (string): Оператор сравнения + +## `title()` + +**Описание:** Добавляет фильтр по заголовку + +**Параметры:** + +* `$title` (string): Заголовок отзыва +* `$operator` (string): Оператор сравнения + +## `onlyPositive()` + +**Описание:** Фильтр только для положительных отзывов + +## `onlyNegative()` + +**Описание:** Фильтр только для отрицательных отзывов + +## `onlyNeutral()` + +**Описание:** Фильтр только для нейтральных отзывов + +## `name()` + +**Описание:** Добавляет фильтр по названию + +**Параметры:** + +* `$name` (string): Название +* `$operator` (string): Оператор сравнения + +## `enName()` + +**Описание:** Добавляет фильтр по английскому названию + +**Параметры:** + +* `$enName` (string): Английское название +* `$operator` (string): Оператор сравнения + +## `type()` + +**Описание:** Добавляет фильтр по типу + +**Параметры:** + +* `$type` (string|\KinopoiskDev\Enums\ReviewType): Тип +* `$operator` (string): Оператор сравнения + +**Возвращает:** `\KinopoiskDev\Filter\MovieSearchFilter|\KinopoiskDev\Filter\ImageSearchFilter|\KinopoiskDev\Filter\KeywordSearchFilter|\KinopoiskDev\Filter\PersonSearchFilter|\KinopoiskDev\Filter\ReviewSearchFilter|\KinopoiskDev\Filter\SeasonSearchFilter|\KinopoiskDev\Filter\StudioSearchFilter|\KinopoiskDev\Utils\FilterTrait` + +## `movieId()` + +**Описание:** Добавляет фильтр по ID фильма + +**Параметры:** + +* `$movieId` (int): ID фильма + +## `searchByName()` + +**Описание:** Добавляет поисковый фильтр по названию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `searchByEnName()` + +**Описание:** Добавляет поисковый фильтр по английскому названию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `searchByDescription()` + +**Описание:** Добавляет поисковый фильтр по описанию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `withMinRating()` + +**Описание:** Добавляет фильтр по минимальному рейтингу + +**Параметры:** + +* `$minRating` (float): Минимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `withMaxRating()` + +**Описание:** Добавляет фильтр по максимальному рейтингу + +**Параметры:** + +* `$maxRating` (float): Максимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `withRatingBetween()` + +**Описание:** Добавляет фильтр по диапазону рейтинга + +**Параметры:** + +* `$minRating` (float): Минимальный рейтинг +* `$maxRating` (float): Максимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `addRangeFilter()` + +**Описание:** Добавляет фильтр по диапазону + +**Параметры:** + +* `$field` (string): Имя поля +* `$minValue` (int): Минимальное значение +* `$maxValue` (int): Максимальное значение + +## `seasonRange()` + +**Описание:** Добавляет фильтр по диапазону сезонов + +**Параметры:** + +* `$fromSeason` (int): Начальный сезон +* `$toSeason` (int): Конечный сезон + +## `ageRange()` + +**Описание:** Добавляет фильтр по возрастному диапазону + +**Параметры:** + +* `$minAge` (int): Минимальный возраст +* `$maxAge` (int): Максимальный возраст + diff --git a/docs/dev/kinopoiskdev/Filter/SeasonSearchFilter.md b/docs/dev/kinopoiskdev/Filter/SeasonSearchFilter.md new file mode 100644 index 0000000..800fd3b --- /dev/null +++ b/docs/dev/kinopoiskdev/Filter/SeasonSearchFilter.md @@ -0,0 +1,143 @@ +# SeasonSearchFilter + +**Описание:** Класс для фильтров при поиске сезонов + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +## `number()` + +**Описание:** Добавляет фильтр по номеру сезона + +**Параметры:** + +* `$number` (int): Номер сезона +* `$operator` (string): Оператор сравнения + +## `episodesCount()` + +**Описание:** Добавляет фильтр по количеству эпизодов + +**Параметры:** + +* `$episodesCount` (int): Количество эпизодов +* `$operator` (string): Оператор сравнения + +## `name()` + +**Описание:** Добавляет фильтр по названию + +**Параметры:** + +* `$name` (string): Название +* `$operator` (string): Оператор сравнения + +## `enName()` + +**Описание:** Добавляет фильтр по английскому названию + +**Параметры:** + +* `$enName` (string): Английское название +* `$operator` (string): Оператор сравнения + +## `type()` + +**Описание:** Добавляет фильтр по типу + +**Параметры:** + +* `$type` (string|\KinopoiskDev\Enums\ReviewType): Тип +* `$operator` (string): Оператор сравнения + +**Возвращает:** `\KinopoiskDev\Filter\MovieSearchFilter|\KinopoiskDev\Filter\ImageSearchFilter|\KinopoiskDev\Filter\KeywordSearchFilter|\KinopoiskDev\Filter\PersonSearchFilter|\KinopoiskDev\Filter\ReviewSearchFilter|\KinopoiskDev\Filter\SeasonSearchFilter|\KinopoiskDev\Filter\StudioSearchFilter|\KinopoiskDev\Utils\FilterTrait` + +## `movieId()` + +**Описание:** Добавляет фильтр по ID фильма + +**Параметры:** + +* `$movieId` (int): ID фильма + +## `searchByName()` + +**Описание:** Добавляет поисковый фильтр по названию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `searchByEnName()` + +**Описание:** Добавляет поисковый фильтр по английскому названию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `searchByDescription()` + +**Описание:** Добавляет поисковый фильтр по описанию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `withMinRating()` + +**Описание:** Добавляет фильтр по минимальному рейтингу + +**Параметры:** + +* `$minRating` (float): Минимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `withMaxRating()` + +**Описание:** Добавляет фильтр по максимальному рейтингу + +**Параметры:** + +* `$maxRating` (float): Максимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `withRatingBetween()` + +**Описание:** Добавляет фильтр по диапазону рейтинга + +**Параметры:** + +* `$minRating` (float): Минимальный рейтинг +* `$maxRating` (float): Максимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `addRangeFilter()` + +**Описание:** Добавляет фильтр по диапазону + +**Параметры:** + +* `$field` (string): Имя поля +* `$minValue` (int): Минимальное значение +* `$maxValue` (int): Максимальное значение + +## `seasonRange()` + +**Описание:** Добавляет фильтр по диапазону сезонов + +**Параметры:** + +* `$fromSeason` (int): Начальный сезон +* `$toSeason` (int): Конечный сезон + +## `ageRange()` + +**Описание:** Добавляет фильтр по возрастному диапазону + +**Параметры:** + +* `$minAge` (int): Минимальный возраст +* `$maxAge` (int): Максимальный возраст + diff --git a/docs/dev/kinopoiskdev/Filter/SortCriteria.md b/docs/dev/kinopoiskdev/Filter/SortCriteria.md new file mode 100644 index 0000000..dff6b05 --- /dev/null +++ b/docs/dev/kinopoiskdev/Filter/SortCriteria.md @@ -0,0 +1,146 @@ +# SortCriteria + +**Описание:** Класс для представления критериев сортировки +Инкапсулирует информацию о поле сортировки и направлении, +предоставляя удобные методы для работы с параметрами сортировки. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +## `__construct()` + +**Описание:** Конструктор для создания критериев сортировки + +**Параметры:** + +* `$field` (SortField): Поле для сортировки +* `$direction` (SortDirection): Направление сортировки + +## `__toString()` + +**Описание:** Возвращает строковое представление критериев + +**Возвращает:** `string` Человекочитаемое описание критериев сортировки + +## `create()` + +**Описание:** Создает критерии сортировки с автоматическим направлением по умолчанию +Фабричный метод, который создает SortCriteria используя рекомендуемое +направление сортировки для указанного поля. + +**Параметры:** + +* `$field` (SortField): Поле для сортировки + +**Возвращает:** `self` Новый экземпляр SortCriteria с направлением по умолчанию + +## `ascending()` + +**Описание:** Создает критерии сортировки по возрастанию + +**Параметры:** + +* `$field` (SortField): Поле для сортировки + +**Возвращает:** `self` Новый экземпляр SortCriteria с направлением ASC + +## `descending()` + +**Описание:** Создает критерии сортировки по убыванию + +**Параметры:** + +* `$field` (SortField): Поле для сортировки + +**Возвращает:** `self` Новый экземпляр SortCriteria с направлением DESC + +## `fromArray()` + +**Описание:** Создает экземпляр SortCriteria из массива данных + +**Возвращает:** `self|null` Новый экземпляр SortCriteria или null при некорректных данных + +## `fromStrings()` + +**Описание:** Создает экземпляр SortCriteria из строковых значений + +**Параметры:** + +* `$field` (string): Строковое значение поля +* `$direction` (string|null): Строковое значение направления (опционально) + +**Возвращает:** `self|null` Новый экземпляр SortCriteria или null при неудачном преобразовании + +## `toArray()` + +**Описание:** Преобразует критерии в массив + +**Возвращает:** `array` Ассоциативный массив с ключами 'field' и 'direction' + +## `toApiString()` + +**Описание:** Преобразует критерии в массив для URL параметров API +Формирует массив с отдельными параметрами sortField и sortType +для использования в API Kinopoisk.dev. + +**Возвращает:** `array` Массив с ключами sortField и sortType + +## `reverse()` + +**Описание:** Возвращает противоположные критерии сортировки +Создает новый экземпляр SortCriteria с тем же полем, +но противоположным направлением сортировки. + +**Возвращает:** `self` Новый экземпляр с обращенным направлением + +## `hasSameField()` + +**Описание:** Проверяет, совпадают ли критерии по полю + +**Параметры:** + +* `$other` (SortCriteria): Другие критерии для сравнения + +**Возвращает:** `bool true,` если поля совпадают, false в противном случае + +## `equals()` + +**Описание:** Проверяет полное равенство критериев + +**Параметры:** + +* `$other` (SortCriteria): Другие критерии для сравнения + +**Возвращает:** `bool true,` если поле и направление совпадают, false в противном случае + +## `toShortString()` + +**Описание:** Возвращает краткое строковое представление + +**Возвращает:** `string` Краткое описание с символом направления + +## `isRatingSort()` + +**Описание:** Проверяет, является ли поле рейтинговым + +**Возвращает:** `bool true,` если поле сортировки является рейтинговым + +## `isVotesSort()` + +**Описание:** Проверяет, является ли поле полем голосов + +**Возвращает:** `bool true,` если поле сортировки является полем голосов + +## `isDateSort()` + +**Описание:** Проверяет, является ли сортировка по дате + +**Возвращает:** `bool true,` если поле сортировки является полем даты + +## `getFieldDataType()` + +**Описание:** Возвращает тип данных поля сортировки + +**Возвращает:** `string` Тип данных поля ('number', 'string', 'date') + diff --git a/docs/dev/kinopoiskdev/Filter/StudioSearchFilter.md b/docs/dev/kinopoiskdev/Filter/StudioSearchFilter.md new file mode 100644 index 0000000..9d4fdef --- /dev/null +++ b/docs/dev/kinopoiskdev/Filter/StudioSearchFilter.md @@ -0,0 +1,235 @@ +# StudioSearchFilter + +**Описание:** Фильтр для поиска студий +Класс предоставляет методы для создания фильтров поиска студий +по различным критериям: названию, типу, подтипу, связанным фильмам и т.д. +Используется в StudioRequests для формирования параметров запроса к API. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Http\StudioRequests`: Для использования фильтра +* `\KinopoiskDev\Enums\StudioType`: Для типов студий + +## `movieId()` + +**Описание:** Фильтр по идентификатору фильма +Находит студии, которые участвовали в создании указанного фильма. + +**Параметры:** + +* `$movieIds` (int|array): ID фильма или массив ID фильмов + +**Возвращает:** `self` Текущий экземпляр для цепочки методов + +## `studioType()` + +**Описание:** Фильтр по типу студии + +**Параметры:** + +* `$types` (string|StudioType|array): Тип студии, enum или массив типов + +**Возвращает:** `self` Текущий экземпляр для цепочки методов + +## `subType()` + +**Описание:** Фильтр по подтипу студии + +**Параметры:** + +* `$subTypes` (string|array): Подтип студии или массив подтипов + +**Возвращает:** `self` Текущий экземпляр для цепочки методов + +## `title()` + +**Описание:** Фильтр по названию студии +Поиск по точному или частичному совпадению названия. + +**Параметры:** + +* `$titles` (string|array): Название студии или массив названий + +**Возвращает:** `self` Текущий экземпляр для цепочки методов + +## `productionStudios()` + +**Описание:** Удобный метод для фильтрации производственных студий + +**Возвращает:** `self` Текущий экземпляр для цепочки методов + +## `specialEffectsStudios()` + +**Описание:** Удобный метод для фильтрации студий спецэффектов + +**Возвращает:** `self` Текущий экземпляр для цепочки методов + +## `distributionCompanies()` + +**Описание:** Удобный метод для фильтрации прокатных компаний + +**Возвращает:** `self` Текущий экземпляр для цепочки методов + +## `dubbingStudios()` + +**Описание:** Удобный метод для фильтрации студий дубляжа + +**Возвращает:** `self` Текущий экземпляр для цепочки методов + +## `excludeTypes()` + +**Описание:** Исключить определенные типы студий + +**Параметры:** + +* `$types` (string|StudioType|array): Типы для исключения + +**Возвращает:** `self` Текущий экземпляр для цепочки методов + +## `participatedInAllMovies()` + +**Описание:** Поиск студий, участвовавших в нескольких фильмах + +**Параметры:** + +* `$movieIds` (array): Массив ID фильмов (студия должна участвовать во всех) + +**Возвращает:** `self` Текущий экземпляр для цепочки методов + +## `sortByTitle()` + +**Описание:** Сортировка по названию студии + +**Параметры:** + +* `$direction` (string): Направление сортировки ('asc' или 'desc') + +**Возвращает:** `self` Текущий экземпляр для цепочки методов + +## `sortByType()` + +**Описание:** Сортировка по типу студии + +**Параметры:** + +* `$direction` (string): Направление сортировки ('asc' или 'desc') + +**Возвращает:** `self` Текущий экземпляр для цепочки методов + +## `country()` + +**Описание:** Фильтрация по стране + +## `name()` + +**Описание:** Добавляет фильтр по названию + +**Параметры:** + +* `$name` (string): Название +* `$operator` (string): Оператор сравнения + +## `enName()` + +**Описание:** Добавляет фильтр по английскому названию + +**Параметры:** + +* `$enName` (string): Английское название +* `$operator` (string): Оператор сравнения + +## `type()` + +**Описание:** Добавляет фильтр по типу + +**Параметры:** + +* `$type` (string|\KinopoiskDev\Enums\ReviewType): Тип +* `$operator` (string): Оператор сравнения + +**Возвращает:** `\KinopoiskDev\Filter\MovieSearchFilter|\KinopoiskDev\Filter\ImageSearchFilter|\KinopoiskDev\Filter\KeywordSearchFilter|\KinopoiskDev\Filter\PersonSearchFilter|\KinopoiskDev\Filter\ReviewSearchFilter|\KinopoiskDev\Filter\SeasonSearchFilter|\KinopoiskDev\Filter\StudioSearchFilter|\KinopoiskDev\Utils\FilterTrait` + +## `searchByName()` + +**Описание:** Добавляет поисковый фильтр по названию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `searchByEnName()` + +**Описание:** Добавляет поисковый фильтр по английскому названию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `searchByDescription()` + +**Описание:** Добавляет поисковый фильтр по описанию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `withMinRating()` + +**Описание:** Добавляет фильтр по минимальному рейтингу + +**Параметры:** + +* `$minRating` (float): Минимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `withMaxRating()` + +**Описание:** Добавляет фильтр по максимальному рейтингу + +**Параметры:** + +* `$maxRating` (float): Максимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `withRatingBetween()` + +**Описание:** Добавляет фильтр по диапазону рейтинга + +**Параметры:** + +* `$minRating` (float): Минимальный рейтинг +* `$maxRating` (float): Максимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `addRangeFilter()` + +**Описание:** Добавляет фильтр по диапазону + +**Параметры:** + +* `$field` (string): Имя поля +* `$minValue` (int): Минимальное значение +* `$maxValue` (int): Максимальное значение + +## `seasonRange()` + +**Описание:** Добавляет фильтр по диапазону сезонов + +**Параметры:** + +* `$fromSeason` (int): Начальный сезон +* `$toSeason` (int): Конечный сезон + +## `ageRange()` + +**Описание:** Добавляет фильтр по возрастному диапазону + +**Параметры:** + +* `$minAge` (int): Минимальный возраст +* `$maxAge` (int): Максимальный возраст + diff --git a/docs/dev/kinopoiskdev/Http/.nav.yml b/docs/dev/kinopoiskdev/Http/.nav.yml new file mode 100644 index 0000000..4c827f5 --- /dev/null +++ b/docs/dev/kinopoiskdev/Http/.nav.yml @@ -0,0 +1,10 @@ +title: HTTP запросы +nav: + - ImageRequests: ImageRequests.md + - KeywordRequests: KeywordRequests.md + - ListRequests: ListRequests.md + - MovieRequests: MovieRequests.md + - PersonRequests: PersonRequests.md + - ReviewRequests: ReviewRequests.md + - SeasonRequests: SeasonRequests.md + - StudioRequests: StudioRequests.md \ No newline at end of file diff --git a/docs/dev/kinopoiskdev/Http/ImageRequests.md b/docs/dev/kinopoiskdev/Http/ImageRequests.md new file mode 100644 index 0000000..8b4dcf3 --- /dev/null +++ b/docs/dev/kinopoiskdev/Http/ImageRequests.md @@ -0,0 +1,66 @@ +# ImageRequests + +**Описание:** Класс для API-запросов, связанных с изображениями фильмов +Этот класс расширяет базовый класс Kinopoisk и предоставляет специализированные +методы для работы с изображениями (постеры, кадры, задники) из API Kinopoisk.dev. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +## `getImagesByMovieId()` + +**Описание:** Получает изображения для конкретного фильма + +**Параметры:** + +* `$movieId` (int): ID фильма в Кинопоиске +* `$type` (string): Тип изображения (например: 'poster', 'frame', 'backdrop') +* `$page` (int): Номер страницы +* `$limit` (int): Количество результатов на странице + +**Возвращает:** `ImageDocsResponseDto` Изображения указанного фильма + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API +* `\JsonException`: При ошибках парсинга JSON +* `\KinopoiskDev\Exceptions\KinopoiskResponseException`: + +## `getImages()` + +**Описание:** Получает изображения с возможностью фильтрации и пагинации +Выполняет запрос к API Kinopoisk.dev для получения списка изображений фильмов +с поддержкой расширенной фильтрации и постраничной навигации. +Можно фильтровать по типу изображения, языку, размерам и ID фильма. +(тип изображения, ID фильма, язык, размеры). +При значении null создается новый экземпляр MovieSearchFilter без фильтров +250) +(общее количество, количество страниц, текущая страница) + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**API Endpoint:** `/v1.4/image` + +**Параметры:** + +* `$filters` (MovieSearchFilter|null): Объект фильтрации для поиска изображений по различным критериям +* `$page` (int): Номер запрашиваемой страницы результатов, начиная с 1 (по умолчанию 1) +* `$limit` (int): Максимальное количество результатов на одной странице (по умолчанию 10, максимум ограничен API до + +**Возвращает:** `ImageDocsResponseDto` Объект ответа, содержащий массив изображений и метаданные пагинации + +**Исключения:** + +* `KinopoiskDevException`: При ошибках валидации данных, неправильных параметрах запроса или проблемах с инициализацией объектов +* `KinopoiskResponseException`: При ошибках HTTP-запроса к API (401, 403, 404) +* `\JsonException`: При ошибках парсинга JSON-ответа от API, некорректном формате данных или повреждении ответа + +**См. также:** + +* `\KinopoiskDev\Filter\MovieSearchFilter`: Класс для настройки фильтрации изображений +* `\KinopoiskDev\Responses\Api\ImageDocsResponseDto`: Структура ответа API +* `\KinopoiskDev\Models\Image`: Модель отдельного изображения + diff --git a/docs/dev/kinopoiskdev/Http/KeywordRequests.md b/docs/dev/kinopoiskdev/Http/KeywordRequests.md new file mode 100644 index 0000000..c5420da --- /dev/null +++ b/docs/dev/kinopoiskdev/Http/KeywordRequests.md @@ -0,0 +1,90 @@ +# KeywordRequests + +**Описание:** Класс для API-запросов, связанных с ключевыми словами +Этот класс предоставляет методы для всех конечных точек ключевых слов API Kinopoisk.dev. +Позволяет получать информацию о тематических метках, которые используются для +категоризации и поиска фильмов по содержанию. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Keyword`: Для структуры данных ключевого слова +* `\KinopoiskDev\Filter\KeywordSearchFilter`: Для фильтрации запросов + +## `getKeywordsByTitle()` + +**Описание:** Получает ключевые слова по названию +Выполняет поиск ключевых слов по точному или частичному совпадению названия. +Полезно для поиска тематических категорий фильмов. + +**Параметры:** + +* `$title` (string): Название ключевого слова для поиска +* `$page` (int): Номер страницы результатов +* `$limit` (int): Количество результатов на странице + +**Возвращает:** `KeywordDocsResponseDto` Ключевые слова с подходящими названиями + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API +* `\JsonException`: При ошибках парсинга JSON + +## `searchKeywords()` + +**Описание:** Ищет ключевые слова по различным критериям +Основной метод для поиска ключевых слов с поддержкой сложных фильтров. +Позволяет искать по названию ключевого слова, связанным фильмам и другим параметрам. + +**API Endpoint:** `/v1.4/keyword` + +**Параметры:** + +* `$filters` (KeywordSearchFilter|null): Объект фильтра для поиска ключевых слов +* `$page` (int): Номер страницы результатов (по умолчанию: 1) +* `$limit` (int): Количество результатов на странице (по умолчанию: 10, максимум: 250) + +**Возвращает:** `KeywordDocsResponseDto` Результаты поиска с пагинацией + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API + +## `getKeywordsForMovie()` + +**Описание:** Получает ключевые слова для определенного фильма +Находит все ключевые слова, которые связаны с указанным фильмом. +Полезно для анализа тематики и содержания конкретного фильма. + +**Параметры:** + +* `$movieId` (int): Идентификатор фильма +* `$page` (int): Номер страницы результатов +* `$limit` (int): Количество результатов на странице + +**Возвращает:** `KeywordDocsResponseDto` Ключевые слова, связанные с фильмом + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API +* `\JsonException`: При ошибках парсинга JSON + +## `getKeywordById()` + +**Описание:** Получает ключевое слово по его ID +Выполняет поиск конкретного ключевого слова по его уникальному идентификатору. + +**Параметры:** + +* `$keywordId` (int): Уникальный идентификатор ключевого слова + +**Возвращает:** `Keyword|null` Ключевое слово или null если не найдено + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API +* `\JsonException`: При ошибках парсинга JSON + diff --git a/docs/dev/kinopoiskdev/Http/ListRequests.md b/docs/dev/kinopoiskdev/Http/ListRequests.md new file mode 100644 index 0000000..dfa875f --- /dev/null +++ b/docs/dev/kinopoiskdev/Http/ListRequests.md @@ -0,0 +1,84 @@ +# ListRequests + +**Описание:** Класс для API-запросов, связанных с коллекциями и списками фильмов +Этот класс расширяет базовый класс Kinopoisk и предоставляет специализированные +методы для работы с коллекциями фильмов (топ-250, жанровые подборки, тематические списки) из API Kinopoisk.dev. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +## `getListBySlug()` + +**Описание:** Получает конкретную коллекцию по её slug + +**API Endpoint:** `/v1.4/list/{slug}` + +**Параметры:** + +* `$slug` (string): Уникальный идентификатор коллекции (например: 'top250', 'popular-films') + +**Возвращает:** `\KinopoiskDev\Models\Lists` Коллекция фильмов со всеми доступными данными + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API или проблемах с сетью +* `\JsonException`: При ошибках парсинга JSON +* `\KinopoiskDev\Exceptions\KinopoiskResponseException`: + +**Ссылка:** https://kinopoiskdev.readme.io/reference/listcontroller_findonev1_4 + +## `getListsByCategory()` + +**Описание:** Получает коллекции по категории + +**Параметры:** + +* `$category` (\KinopoiskDev\Enums\ListCategory): Категория коллекций +* `$page` (int): Номер страницы +* `$limit` (int): Количество результатов на странице + +**Возвращает:** `ListDocsResponseDto` Коллекции указанной категории + +**Исключения:** + +* `\JsonException`: При ошибках парсинга JSON +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: При ошибках API +* `\KinopoiskDev\Exceptions\KinopoiskResponseException`: + +## `getAllLists()` + +**Описание:** Получает все доступные коллекции с возможностью фильтрации и пагинации +Выполняет запрос к API Kinopoisk.dev для получения списка всех коллекций фильмов +с поддержкой расширенной фильтрации и постраничной навигации. +Можно фильтровать по категориям, названиям и другим параметрам коллекций. +(категория, название, количество фильмов). +При значении null создается новый экземпляр MovieSearchFilter без фильтров +250) +(общее количество, количество страниц, текущая страница) + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**API Endpoint:** `/v1.4/list` + +**Параметры:** + +* `$filters` (MovieSearchFilter|null): Объект фильтрации для поиска коллекций по различным критериям +* `$page` (int): Номер запрашиваемой страницы результатов, начиная с 1 (по умолчанию 1) +* `$limit` (int): Максимальное количество результатов на одной странице (по умолчанию 10, максимум ограничен API до + +**Возвращает:** `ListDocsResponseDto` Объект ответа, содержащий массив коллекций и метаданные пагинации + +**Исключения:** + +* `KinopoiskDevException`: При ошибках валидации данных, неправильных параметрах запроса или проблемах с инициализацией объектов +* `KinopoiskResponseException`: При ошибках HTTP-запроса к API (401, 403, 404) +* `\JsonException`: При ошибках парсинга JSON-ответа от API, некорректном формате данных или повреждении ответа + +**См. также:** + +* `\KinopoiskDev\Filter\MovieSearchFilter`: Класс для настройки фильтрации коллекций +* `\KinopoiskDev\Responses\Api\ListDocsResponseDto`: Структура ответа API + diff --git a/docs/dev/kinopoiskdev/Http/MovieRequests.md b/docs/dev/kinopoiskdev/Http/MovieRequests.md new file mode 100644 index 0000000..3b37cc6 --- /dev/null +++ b/docs/dev/kinopoiskdev/Http/MovieRequests.md @@ -0,0 +1,377 @@ +# MovieRequests + +**Описание:** Класс для API-запросов, связанных с фильмами +Предоставляет полный набор методов для работы с фильмами через API Kinopoisk.dev. +Включает поиск фильмов, получение детальной информации, наград, случайных фильмов +и возможных значений для фильтрации. Поддерживает расширенную фильтрацию, +пагинацию и обработку ошибок. +Основные возможности: +- Поиск фильмов по различным критериям +- Получение детальной информации о фильме +- Работа с наградами фильмов +- Получение случайных фильмов +- Получение возможных значений для фильтров +- Специализированные методы для популярных запросов + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**Пример:** +```php +$movieRequests = new MovieRequests('your-api-token'); +// Получение фильма по ID +$movie = $movieRequests->getMovieById(123); +// Поиск фильмов +$filter = new MovieSearchFilter(); +$filter->year(2023)->rating(7.0); +$results = $movieRequests->searchMovies($filter, 1, 20); +// Получение случайного фильма +$randomMovie = $movieRequests->getRandomMovie(); +// Получение наград +$awards = $movieRequests->getMovieAwards(null, 1, 50); +``` + +**См. также:** + +* `\KinopoiskDev\Filter\MovieSearchFilter`: Для настройки фильтрации +* `\KinopoiskDev\Models\Movie`: Модель фильма +* `\KinopoiskDev\Models\MovieAward`: Модель награды фильма +* `\KinopoiskDev\Responses\Api\MovieDocsResponseDto`: Ответ с фильмами +* `\KinopoiskDev\Responses\Api\SearchMovieResponseDto`: Ответ поиска + +## `getMovieById()` + +**Описание:** Получает фильм по его ID +Выполняет запрос к API для получения полной информации о фильме +по его уникальному идентификатору. Возвращает объект Movie +со всеми доступными данными: названием, годом, рейтингами, +актерами, режиссерами, описанием и другими метаданными. + +**С версии:** 1.0.0 + +**API Endpoint:** `/v1.4/movie/{id}` + +**Параметры:** + +* `$movieId` (int): Уникальный ID фильма в базе данных Kinopoisk + +**Возвращает:** `Movie` Объект фильма со всеми доступными данными + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API или проблемах с сетью +* `KinopoiskResponseException`: При ошибках HTTP-запроса (401, 403, 404) +* `\JsonException`: При ошибках парсинга JSON-ответа + +**Пример:** +```php +$movie = $movieRequests->getMovieById(123); +echo $movie->name; // Название фильма +echo $movie->year; // Год выпуска +``` + +## `getRandomMovie()` + +**Описание:** Получает случайный фильм +Возвращает случайно выбранный фильм из базы данных Kinopoisk. +Поддерживает опциональную фильтрацию для получения случайного +фильма, соответствующего определенным критериям (год, жанр, +рейтинг и т.д.). + +**С версии:** 1.0.0 + +**API Endpoint:** `/v1.4/movie/random` + +**Параметры:** + +* `$filters` (MovieSearchFilter|null): Опциональные фильтры для ограничения выбора случайного фильма + +**Возвращает:** `Movie` Случайный фильм, соответствующий переданным фильтрам + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API или валидации +* `KinopoiskResponseException`: При ошибках HTTP-запроса +* `\JsonException`: При ошибках парсинга JSON-ответа + +**Пример:** +```php +// Получить любой случайный фильм +$randomMovie = $movieRequests->getRandomMovie(); +// Получить случайный фильм 2023 года с рейтингом выше 7.0 +$filter = new MovieSearchFilter(); +$filter->year(2023)->rating(7.0); +$randomMovie = $movieRequests->getRandomMovie($filter); +``` + +## `getPossibleValuesByField()` + +**Описание:** Получает возможные значения для указанного поля фильтрации +Возвращает список всех возможных значений для определенных полей +фильтрации, таких как жанры, страны, типы фильмов и статусы. +Полезно для создания выпадающих списков или автодополнения +в пользовательских интерфейсах. + +**С версии:** 1.0.0 + +**API Endpoint:** `/v1.4/movie/possible-values-by-field` + +**Параметры:** + +* `$field` (string): Поле для получения возможных значений (genres, countries, type, type_number, status) + +**Возвращает:** `array>` Массив возможных значений с полями name и slug + +**Исключения:** + +* `KinopoiskDevException`: При передаче неподдерживаемого поля +* `KinopoiskResponseException`: При ошибках HTTP-запроса +* `\JsonException`: При ошибках парсинга JSON-ответа + +**Пример:** +```php +// Получить все жанры +$genres = $movieRequests->getPossibleValuesByField('genres'); +// Получить все страны +$countries = $movieRequests->getPossibleValuesByField('countries'); +// Получить типы фильмов +$types = $movieRequests->getPossibleValuesByField('type'); +``` + +## `getMovieAwards()` + +**Описание:** Получает награды фильмов с возможностью фильтрации и пагинации +Выполняет запрос к API Kinopoisk.dev для получения списка наград фильмов +с поддержкой расширенной фильтрации и постраничной навигации. +Автоматически создает объект фильтра при отсутствии переданного параметра. +При значении null создается новый экземпляр MovieSearchFilter без фильтров +250) +количество страниц, текущая страница) + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**API Endpoint:** `/v1.4/movie/awards` + +**Параметры:** + +* `$filters` (MovieSearchFilter|null): Объект фильтрации для поиска наград по различным критериям (жанры, страны, годы, рейтинги и т.д.). +* `$page` (int): Номер запрашиваемой страницы результатов, начиная с 1 (по умолчанию 1) +* `$limit` (int): Максимальное количество результатов на одной странице (по умолчанию 10, максимум ограничен API до + +**Возвращает:** `MovieAwardDocsResponseDto` Объект ответа, содержащий массив наград фильмов и метаданные пагинации (общее количество, + +**Исключения:** + +* `KinopoiskDevException`: При ошибках валидации данных, неправильных параметрах запроса или проблемах с инициализацией объектов +* `KinopoiskResponseException`: При ошибках HTTP-запроса к API (401, 403, 404) +* `\JsonException`: При ошибках парсинга JSON-ответа от API, некорректном формате данных или повреждении ответа + +**См. также:** + +* `\KinopoiskDev\Filter\MovieSearchFilter`: Класс для настройки фильтрации наград +* `\KinopoiskDev\Responses\Api\MovieAwardDocsResponseDto`: Структура ответа API +* `\KinopoiskDev\Models\MovieAward`: Модель отдельной награды фильма + +## `searchByName()` + +**Описание:** Ищет фильмы только по названию (упрощенный поиск) +Выполняет поиск фильмов по названию с использованием +встроенного поискового движка API. Поддерживает частичное +совпадение и нечеткий поиск. Удобен для быстрого поиска +по названию фильма без сложной фильтрации. + +**С версии:** 1.0.0 + +**API Endpoint:** `/v1.4/movie/search` + +**Параметры:** + +* `$query` (string): Поисковый запрос (название фильма) +* `$page` (int): Номер страницы результатов (по умолчанию: 1) +* `$limit` (int): Количество результатов на странице (по умолчанию: 10) + +**Возвращает:** `SearchMovieResponseDto` Результаты поиска с пагинацией + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API или валидации +* `KinopoiskResponseException`: При ошибках HTTP-запроса +* `\JsonException`: При ошибках парсинга JSON-ответа + +**Пример:** +```php +// Поиск фильма по названию +$results = $movieRequests->searchByName('Матрица'); +// Поиск с пагинацией +$results = $movieRequests->searchByName('Терминатор', 2, 20); +``` + +## `getLatestMovies()` + +**Описание:** Получает последние фильмы +Возвращает список последних фильмов, отсортированных по дате +выхода. Поддерживает фильтрацию по году для получения +фильмов конкретного года. Удобен для отображения новинок +или актуального контента. + +**С версии:** 1.0.0 + +**API Endpoint:** `/v1.4/movie` + +**Параметры:** + +* `$year` (int|null): Год для фильтрации (по умолчанию: текущий год) +* `$page` (int): Номер страницы результатов (по умолчанию: 1) +* `$limit` (int): Количество результатов на странице (по умолчанию: 10) + +**Возвращает:** `MovieDocsResponseDto` Результаты поиска с пагинацией + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API или валидации +* `KinopoiskResponseException`: При ошибках HTTP-запроса +* `\JsonException`: При ошибках парсинга JSON-ответа + +**Пример:** +```php +// Получить последние фильмы текущего года +$latest = $movieRequests->getLatestMovies(); +// Получить фильмы 2023 года +$movies2023 = $movieRequests->getLatestMovies(2023, 1, 50); +``` + +## `getMoviesByGenre()` + +**Описание:** Получает фильмы по жанру +Возвращает список фильмов определенного жанра или жанров, +отсортированных по рейтингу Kinopoisk. Поддерживает как +одиночный жанр, так и массив жанров для более точной +фильтрации. + +**С версии:** 1.0.0 + +**Параметры:** + +* `$genres` (string|array): Жанр или массив жанров для фильтрации +* `$page` (int): Номер страницы результатов (по умолчанию: 1) +* `$limit` (int): Количество результатов на странице (по умолчанию: 10) + +**Возвращает:** `MovieDocsResponseDto` Фильмы указанного жанра с пагинацией + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API или валидации +* `KinopoiskResponseException`: При ошибках HTTP-запроса +* `\JsonException`: При ошибках парсинга JSON-ответа + +**Пример:** +```php +// Получить боевики +$actionMovies = $movieRequests->getMoviesByGenre('боевик'); +// Получить комедии и драмы +$movies = $movieRequests->getMoviesByGenre(['комедия', 'драма'], 1, 30); +``` + +## `searchMovies()` + +**Описание:** Ищет фильмы по различным критериям +Основной метод для поиска фильмов с использованием расширенной +фильтрации. Поддерживает фильтрацию по году, жанру, стране, +рейтингу, типу фильма и многим другим критериям. Включает +валидацию параметров и автоматическую пагинацию. + +**С версии:** 1.0.0 + +**API Endpoint:** `/v1.4/movie` + +**Параметры:** + +* `$filters` (MovieSearchFilter|null): Объект фильтра для настройки критериев поиска +* `$page` (int): Номер страницы результатов (по умолчанию: 1) +* `$limit` (int): Количество результатов на странице (по умолчанию: 10, максимум: 250) + +**Возвращает:** `MovieDocsResponseDto` Результаты поиска с пагинацией + +**Исключения:** + +* `KinopoiskDevException`: При ошибках валидации или превышении лимитов +* `KinopoiskResponseException`: При ошибках HTTP-запроса +* `\JsonException`: При ошибках парсинга JSON-ответа + +**Пример:** +```php +// Простой поиск всех фильмов +$results = $movieRequests->searchMovies(); +// Поиск с фильтрами +$filter = new MovieSearchFilter(); +$filter->year(2023)->rating(7.0)->genre('боевик'); +$results = $movieRequests->searchMovies($filter, 1, 50); +``` + +## `getMoviesByCountry()` + +**Описание:** Получает фильмы по стране +Возвращает список фильмов из определенной страны или стран, +отсортированных по рейтингу Kinopoisk. Поддерживает как +одиночную страну, так и массив стран для получения +фильмов из нескольких стран одновременно. + +**С версии:** 1.0.0 + +**Параметры:** + +* `$countries` (string|array): Страна или массив стран для фильтрации +* `$page` (int): Номер страницы результатов (по умолчанию: 1) +* `$limit` (int): Количество результатов на странице (по умолчанию: 10) + +**Возвращает:** `MovieDocsResponseDto` Фильмы из указанной страны с пагинацией + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API или валидации +* `KinopoiskResponseException`: При ошибках HTTP-запроса +* `\JsonException`: При ошибках парсинга JSON-ответа + +**Пример:** +```php +// Получить американские фильмы +$usMovies = $movieRequests->getMoviesByCountry('США'); +// Получить фильмы из нескольких стран +$movies = $movieRequests->getMoviesByCountry(['США', 'Великобритания'], 1, 25); +``` + +## `getMoviesByYearRange()` + +**Описание:** Получает фильмы по диапазону лет +Возвращает список фильмов, выпущенных в указанном диапазоне лет, +отсортированных по году выпуска. Полезен для получения фильмов +определенного периода или десятилетия. + +**С версии:** 1.0.0 + +**Параметры:** + +* `$fromYear` (int): Начальный год диапазона (включительно) +* `$toYear` (int): Конечный год диапазона (включительно) +* `$page` (int): Номер страницы результатов (по умолчанию: 1) +* `$limit` (int): Количество результатов на странице (по умолчанию: 10) + +**Возвращает:** `MovieDocsResponseDto` Фильмы из указанного периода с пагинацией + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API или валидации +* `KinopoiskResponseException`: При ошибках HTTP-запроса +* `\JsonException`: При ошибках парсинга JSON-ответа + +**Пример:** +```php +// Получить фильмы 90-х годов +$movies90s = $movieRequests->getMoviesByYearRange(1990, 1999); +// Получить фильмы последнего десятилетия +$recentMovies = $movieRequests->getMoviesByYearRange(2014, 2024, 1, 100); +``` + diff --git a/docs/dev/kinopoiskdev/Http/PersonRequests.md b/docs/dev/kinopoiskdev/Http/PersonRequests.md new file mode 100644 index 0000000..27b8ab0 --- /dev/null +++ b/docs/dev/kinopoiskdev/Http/PersonRequests.md @@ -0,0 +1,337 @@ +# PersonRequests + +**Описание:** Класс для API-запросов, связанных с персонами +Предоставляет полный набор методов для работы с персонами через API Kinopoisk.dev. +Включает поиск персон, получение детальной информации, наград, фильтрацию по +профессиям и другим критериям. Поддерживает расширенную фильтрацию, +пагинацию и обработку ошибок. +Основные возможности: +- Поиск персон по различным критериям +- Получение детальной информации о персоне +- Работа с наградами персон +- Фильтрация по профессиям (актеры, режиссеры и т.д.) +- Поиск по имени с поддержкой регулярных выражений +- Специализированные методы для популярных запросов + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**Пример:** +```php +$personRequests = new PersonRequests('your-api-token'); +// Получение персоны по ID +$person = $personRequests->getPersonById(123); +// Поиск персон +$filter = new PersonSearchFilter(); +$filter->profession('актер')->age(30, 50); +$results = $personRequests->searchPersons($filter, 1, 20); +// Поиск по имени +$actors = $personRequests->searchByName('Том Круз'); +// Получение актеров +$actors = $personRequests->getActors(1, 50); +``` + +**См. также:** + +* `\KinopoiskDev\Filter\PersonSearchFilter`: Для настройки фильтрации +* `\KinopoiskDev\Models\Person`: Модель персоны +* `\KinopoiskDev\Models\PersonAward`: Модель награды персоны +* `\KinopoiskDev\Responses\Api\PersonDocsResponseDto`: Ответ с персонами +* `\KinopoiskDev\Responses\Api\PersonAwardDocsResponseDto`: Ответ с наградами + +## `getPersonById()` + +**Описание:** Получает персону по её уникальному идентификатору +Выполняет запрос к API для получения полной информации о персоне, +включая биографические данные, фильмографию, награды, места +рождения и смерти, и другие доступные сведения. + +**С версии:** 1.0.0 + +**API Endpoint:** `/v1.4/person/{id}` + +**Параметры:** + +* `$personId` (int): Уникальный идентификатор персоны в системе Kinopoisk + +**Возвращает:** `Person` Объект персоны со всеми доступными данными + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API или проблемах с сетью +* `KinopoiskResponseException`: При ошибках HTTP-запроса (401, 403, 404) +* `\JsonException`: При ошибках парсинга JSON-ответа + +**Пример:** +```php +$person = $personRequests->getPersonById(123); +echo $person->name; // Имя персоны +echo $person->profession; // Профессия +``` + +## `getActors()` + +**Описание:** Получает список актёров +Удобный метод для получения списка персон с профессией "актёр". +Является обёрткой над методом getPersonsByProfession(). + +**Параметры:** + +* `$limit` (int): Количество результатов на странице (максимум 250) +* `$page` (int): Номер страницы результатов (начиная с 1) + +**Возвращает:** `PersonDocsResponseDto` Список актёров с информацией о пагинации + +**Исключения:** + +* `\JsonException`: При ошибках парсинга JSON-ответа +* `KinopoiskDevException`: При ошибках API + +**См. также:** + +* `PersonRequests::getPersonsByProfession`: () Для получения персон других профессий + +## `getPersonsByProfession()` + +**Описание:** Получает персон по профессии +Выполняет поиск персон, которые работают в указанной профессиональной области. +Поддерживает русские названия профессий из справочника Kinopoisk. + +**Параметры:** + +* `$limit` (int): Количество результатов на странице (максимум 250) +* `$profession` (string): Профессия (актёр, режиссёр, сценарист, продюсер и т.д.) +* `$page` (int): Номер страницы результатов (начиная с 1) + +**Возвращает:** `PersonDocsResponseDto` Персоны указанной профессии с информацией о пагинации + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API +* `\JsonException`: При ошибках парсинга JSON-ответа + +**См. также:** + +* `PersonRequests::getActors`: () Для получения актёров +* `PersonRequests::getDirectors`: () Для получения режиссёров + +## `searchPersons()` + +**Описание:** Выполняет поиск персон по различным критериям +Основной метод для поиска персон с поддержкой сложных фильтров. +Позволяет искать по имени, профессии, возрасту, полу, месту рождения и другим параметрам. + +**API Endpoint:** `/v1.4/person` + +**Параметры:** + +* `$filters` (PersonSearchFilter|null): Объект фильтра для поиска персон +* `$page` (int): Номер страницы результатов (по умолчанию: 1) +* `$limit` (int): Количество результатов на странице (по умолчанию: 10, максимум: 250) + +**Возвращает:** `PersonDocsResponseDto` Результаты поиска с пагинацией + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API + +## `getRandomPerson()` + +**Описание:** Получает случайную персону из базы данных API с применением случайных критериев сортировки +Метод создает случайный набор критериев сортировки, применяет их к поисковому запросу +и возвращает первую персону из результата. Если фильтры не переданы, создается +новый экземпляр PersonSearchFilter. Добавляет от 1 до (количество полей - 1) +случайных критериев сортировки для обеспечения максимальной случайности результата. +Алгоритм работы: +1. Создает пустой фильтр, если не передан +2. Получает доступные поля и направления сортировки +3. Генерирует случайное количество критериев сортировки (1 до max-1) +4. Для каждого критерия выбирает случайное поле и направление +5. Выполняет поиск с лимитом 1 запись на 1 странице +6. Возвращает первую найденную персону + +**С версии:** 1.0.0 + +**Параметры:** + +* `$filters` (PersonSearchFilter|null): Фильтры для поиска персон. Если null, создается новый экземпляр + +**Возвращает:** `Person` Случайно выбранная персона из базы данных + +**Исключения:** + +* `\Random\RandomException`: В случае ошибки генерации случайного числа +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: Если не найдено персон, соответствующих фильтрам, или при других ошибках API + +**Пример:** +```php +// Получение случайной персоны без фильтров +$randomPerson = $personRequests->getRandomPerson(); +// Получение случайной персоны только среди актеров +$filter = new PersonSearchFilter(); +$filter->onlyActors(); +$randomActor = $personRequests->getRandomPerson($filter); +// Получение случайной персоны определенного возраста +$filter = new PersonSearchFilter(); +$filter->age(30, 'gte')->age(60, 'lte'); +$randomAdultPerson = $personRequests->getRandomPerson($filter); +``` + +**См. также:** + +* `PersonSearchFilter`: Класс для настройки фильтров поиска персон +* `SortField::getPersonFields`: () Получение доступных полей для сортировки персон +* `SortDirection::getAllDirections`: () Получение всех направлений сортировки +* `SortCriteria`: Класс для создания критериев сортировки + +## `searchPersonsByName()` + +**Описание:** Выполняет поиск персон по имени (алиас для searchByName) + +**Параметры:** + +* `$name` (string): Имя для поиска +* `$page` (int): Номер страницы +* `$limit` (int): Количество результатов + +**Возвращает:** `PersonDocsResponseDto` Результаты поиска + +## `searchByName()` + +**Описание:** Выполняет поиск персон по имени +Удобный метод для поиска персон по имени с использованием регулярных выражений. +Поддерживает поиск как по русским, так и по английским именам. Полезен для +быстрого поиска персон без сложной фильтрации. + +**С версии:** 1.0.0 + +**API Endpoint:** `/v1.4/person/search` + +**Параметры:** + +* `$name` (string): Имя персоны для поиска (может быть русским или английским) +* `$page` (int): Номер страницы результатов (начиная с 1) +* `$limit` (int): Количество результатов на странице (максимум 250) + +**Возвращает:** `PersonDocsResponseDto` Результаты поиска с информацией о пагинации + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API или валидации +* `KinopoiskResponseException`: При ошибках HTTP-запроса +* `\JsonException`: При ошибках парсинга JSON-ответа + +**Пример:** +```php +// Поиск по русскому имени +$results = $personRequests->searchByName('Том Круз'); +// Поиск по английскому имени +$results = $personRequests->searchByName('Tom Cruise', 1, 20); +``` + +## `getPersonsBySex()` + +**Описание:** Получает персон по полу + +**Параметры:** + +* `$sex` (string): Пол (М, Ж) +* `$page` (int): Номер страницы +* `$limit` (int): Количество результатов + +**Возвращает:** `PersonDocsResponseDto` Результаты поиска + +## `getPersonsByBirthYear()` + +**Описание:** Получает персон по году рождения + +**Параметры:** + +* `$year` (int): Год рождения +* `$page` (int): Номер страницы +* `$limit` (int): Количество результатов + +**Возвращает:** `PersonDocsResponseDto` Результаты поиска + +## `getPersonsByBirthYearRange()` + +**Описание:** Получает персон по диапазону годов рождения + +**Параметры:** + +* `$fromYear` (int): Начальный год +* `$toYear` (int): Конечный год +* `$page` (int): Номер страницы +* `$limit` (int): Количество результатов + +**Возвращает:** `PersonDocsResponseDto` Результаты поиска + +## `getPersonsByDeathYear()` + +**Описание:** Получает персон по году смерти + +**Параметры:** + +* `$year` (int): Год смерти +* `$page` (int): Номер страницы +* `$limit` (int): Количество результатов + +**Возвращает:** `PersonDocsResponseDto` Результаты поиска + +## `getPersonAwards()` + +**Описание:** Получает награды персон с возможностью фильтрации и пагинации +Если null, создается пустой фильтр. +Поддерживает фильтрацию по возрасту, полу, +месту рождения, профессии и другим параметрам. +Значение должно быть положительным числом. +Значение не должно превышать 250. +- docs: массив объектов PersonAward с данными о наградах +- total: общее количество наград в результате +- limit: примененное ограничение на количество элементов +- page: текущая страница +- pages: общее количество страниц +- Если параметр $limit превышает 250 +- Если параметр $page меньше 1 +- При ошибках HTTP-запроса к API +- При ошибках парсинга ответа от API +- При ошибках создания объектов PersonAward из данных API + +**API Endpoint:** `/v1.4/person/awards` + +**Параметры:** + +* `$filters` (PersonSearchFilter|null): Объект фильтрации для поиска наград +* `$page` (int): Номер страницы (по умолчанию: 1) +* `$limit` (int): Количество результатов на странице (по умолчанию: 10) +* `$filters` (PersonSearchFilter|null): Фильтры для поиска наград персон. +* `$page` (int): Номер страницы для пагинации (начиная с 1). +* `$limit` (int): Максимальное количество элементов на странице. + +**Возвращает:** `PersonAwardDocsResponseDto` Объект ответа, содержащий: + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException|\KinopoiskDev\Exceptions\KinopoiskResponseException|\JsonException`: + +**Пример:** +```php +// Получение первых 10 наград персон +$awards = $kinopoisk->getPersonAwards(); +// Получение наград с фильтрацией по профессии +$filter = new PersonSearchFilter(); +$filter->profession('актер'); +$awards = $kinopoisk->getPersonAwards($filter, 1, 20); +// Получение наград живых персон с ограничением по возрасту +$filter = new PersonSearchFilter(); +$filter->onlyAlive()->age(30, 'gte'); +$awards = $kinopoisk->getPersonAwards($filter, 2, 50); +``` + +**См. также:** + +* `\KinopoiskDev\Filter\PersonSearchFilter`: Для параметров фильтрации +* `\KinopoiskDev\Models\PersonAward`: Для структуры данных наград персон +* `\KinopoiskDev\Responses\PersonAwardDocsResponseDto`: Для структуры ответа + diff --git a/docs/dev/kinopoiskdev/Http/ReviewRequests.md b/docs/dev/kinopoiskdev/Http/ReviewRequests.md new file mode 100644 index 0000000..cf5d0b4 --- /dev/null +++ b/docs/dev/kinopoiskdev/Http/ReviewRequests.md @@ -0,0 +1,135 @@ +# ReviewRequests + +**Описание:** Класс для API-запросов, связанных с рецензиями +Предоставляет методы для работы с рецензиями пользователей на фильмы и сериалы +через API Kinopoisk.dev. Включает поиск рецензий по различным критериям, +фильтрацию по типу (позитивные, негативные, нейтральные) и получение +статистики по рецензиям. +Основные возможности: +- Поиск рецензий по различным критериям +- Получение позитивных рецензий +- Получение негативных рецензий +- Фильтрация по автору, фильму, типу рецензии +- Пагинация результатов + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**Пример:** +```php +$reviewRequests = new ReviewRequests('your-api-token'); +// Поиск всех рецензий +$reviews = $reviewRequests->searchReviews(); +// Поиск с фильтрами +$filter = new ReviewSearchFilter(); +$filter->movieId(123)->type('Позитивный'); +$reviews = $reviewRequests->searchReviews($filter, 1, 20); +// Получение позитивных рецензий +$positiveReviews = $reviewRequests->getPositiveReviews(1, 50); +// Получение негативных рецензий +$negativeReviews = $reviewRequests->getNegativeReviews(1, 30); +``` + +**См. также:** + +* `\KinopoiskDev\Filter\ReviewSearchFilter`: Для настройки фильтрации +* `\KinopoiskDev\Models\Review`: Модель рецензии +* `\KinopoiskDev\Responses\Api\ReviewDocsResponseDto`: Ответ с рецензиями + +## `getPositiveReviews()` + +**Описание:** Получает положительные рецензии +Удобный метод для получения только позитивных рецензий. +Автоматически применяет фильтр по типу "Позитивный" и +возвращает рецензии с положительной оценкой фильма. + +**С версии:** 1.0.0 + +**Параметры:** + +* `$page` (int): Номер страницы результатов (по умолчанию: 1) +* `$limit` (int): Количество результатов на странице (по умолчанию: 10) + +**Возвращает:** `ReviewDocsResponseDto` Положительные рецензии с пагинацией + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API или валидации +* `KinopoiskResponseException`: При ошибках HTTP-запроса +* `\JsonException`: При ошибках парсинга JSON-ответа + +**Пример:** +```php +// Получить позитивные рецензии +$positiveReviews = $reviewRequests->getPositiveReviews(); +// Получить больше позитивных рецензий +$positiveReviews = $reviewRequests->getPositiveReviews(1, 100); +``` + +## `searchReviews()` + +**Описание:** Поиск рецензий по различным критериям +Основной метод для поиска рецензий с использованием расширенной +фильтрации. Поддерживает фильтрацию по фильму, автору, типу +рецензии, дате создания и другим критериям. Включает валидацию +параметров и автоматическую пагинацию. + +**С версии:** 1.0.0 + +**API Endpoint:** `/v1.4/review` + +**Параметры:** + +* `$filters` (ReviewSearchFilter|null): Объект фильтра для настройки критериев поиска +* `$page` (int): Номер страницы результатов (по умолчанию: 1) +* `$limit` (int): Количество результатов на странице (по умолчанию: 10, максимум: 250) + +**Возвращает:** `ReviewDocsResponseDto` Результаты поиска с пагинацией + +**Исключения:** + +* `KinopoiskDevException`: При ошибках валидации или превышении лимитов +* `KinopoiskResponseException`: При ошибках HTTP-запроса +* `\JsonException`: При ошибках парсинга JSON-ответа + +**Пример:** +```php +// Простой поиск всех рецензий +$reviews = $reviewRequests->searchReviews(); +// Поиск с фильтрами +$filter = new ReviewSearchFilter(); +$filter->movieId(123)->type('Позитивный')->author('user123'); +$reviews = $reviewRequests->searchReviews($filter, 1, 50); +``` + +## `getNegativeReviews()` + +**Описание:** Получает отрицательные рецензии +Удобный метод для получения только негативных рецензий. +Автоматически применяет фильтр по типу "Негативный" и +возвращает рецензии с отрицательной оценкой фильма. + +**С версии:** 1.0.0 + +**Параметры:** + +* `$page` (int): Номер страницы результатов (по умолчанию: 1) +* `$limit` (int): Количество результатов на странице (по умолчанию: 10) + +**Возвращает:** `ReviewDocsResponseDto` Отрицательные рецензии с пагинацией + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API или валидации +* `KinopoiskResponseException`: При ошибках HTTP-запроса +* `\JsonException`: При ошибках парсинга JSON-ответа + +**Пример:** +```php +// Получить негативные рецензии +$negativeReviews = $reviewRequests->getNegativeReviews(); +// Получить больше негативных рецензий +$negativeReviews = $reviewRequests->getNegativeReviews(1, 50); +``` + diff --git a/docs/dev/kinopoiskdev/Http/SeasonRequests.md b/docs/dev/kinopoiskdev/Http/SeasonRequests.md new file mode 100644 index 0000000..0bddd3e --- /dev/null +++ b/docs/dev/kinopoiskdev/Http/SeasonRequests.md @@ -0,0 +1,123 @@ +# SeasonRequests + +**Описание:** Класс для API-запросов, связанных с сезонами +Предоставляет методы для работы с сезонами сериалов через API Kinopoisk.dev. +Включает получение информации о сезонах, их эпизодах, поиск по различным +критериям и фильтрацию. Поддерживает работу с многосезонными сериалами. +Основные возможности: +- Получение сезона по ID +- Получение всех сезонов сериала +- Поиск сезонов по различным критериям +- Получение сезона по номеру и ID фильма +- Фильтрация по номеру сезона, количеству эпизодов +- Пагинация результатов + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**Пример:** +```php +$seasonRequests = new SeasonRequests('your-api-token'); +// Получение сезона по ID +$season = $seasonRequests->getSeasonById(123); +// Получение всех сезонов сериала +$seasons = $seasonRequests->getSeasonsForMovie(456); +// Поиск сезонов с фильтрами +$filter = new SeasonSearchFilter(); +$filter->number(1)->episodesCount(10, 20); +$seasons = $seasonRequests->searchSeasons($filter, 1, 20); +// Получение конкретного сезона по номеру +$season = $seasonRequests->getSeasonByNumber(456, 2); +``` + +**См. также:** + +* `\KinopoiskDev\Filter\SeasonSearchFilter`: Для настройки фильтрации +* `\KinopoiskDev\Models\Season`: Модель сезона +* `\KinopoiskDev\Responses\Api\SeasonDocsResponseDto`: Ответ с сезонами + +## `getSeasonById()` + +**Описание:** Получает сезон по его ID +Выполняет запрос к API для получения полной информации о сезоне +по его уникальному идентификатору. Возвращает объект Season +со всеми доступными данными: названием, номером, эпизодами, +датами выхода и другими метаданными. + +**С версии:** 1.0.0 + +**API Endpoint:** `/v1.4/season/{id}` + +**Параметры:** + +* `$seasonId` (int): Уникальный идентификатор сезона в системе Kinopoisk + +**Возвращает:** `Season` Сезон со всеми доступными данными + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API или проблемах с сетью +* `KinopoiskResponseException`: При ошибках HTTP-запроса (401, 403, 404) +* `\JsonException`: При ошибках парсинга JSON-ответа + +**Пример:** +```php +$season = $seasonRequests->getSeasonById(123); +echo $season->name; // Название сезона +echo $season->number; // Номер сезона +echo count($season->episodes); // Количество эпизодов +``` + +## `getSeasonsForMovie()` + +**Описание:** Получает сезоны для определенного фильма/сериала + +**Параметры:** + +* `$movieId` (int): Идентификатор фильма/сериала +* `$page` (int): Номер страницы +* `$limit` (int): Результатов на странице + +**Возвращает:** `SeasonDocsResponseDto` Сезоны для фильма/сериала + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API +* `\JsonException`: При ошибках парсинга JSON + +## `searchSeasons()` + +**Описание:** Ищет сезоны по различным критериям + +**API Endpoint:** `/v1.4/season` + +**Параметры:** + +* `$filters` (SeasonSearchFilter|null): Объект фильтра для поиска +* `$page` (int): Номер страницы (по умолчанию: 1) +* `$limit` (int): Количество результатов на странице (по умолчанию: 10) + +**Возвращает:** `SeasonDocsResponseDto` Результаты поиска с пагинацией + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API +* `\JsonException|\KinopoiskDev\Exceptions\KinopoiskResponseException`: При ошибках парсинга JSON + +## `getSeasonByNumber()` + +**Описание:** Получает сезон по ID фильма и номеру сезона + +**Параметры:** + +* `$movieId` (int): Идентификатор фильма/сериала +* `$seasonNumber` (int): Номер сезона + +**Возвращает:** `Season|null` Сезон или null если не найден + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API +* `\JsonException|\KinopoiskDev\Exceptions\KinopoiskResponseException`: При ошибках парсинга JSON + diff --git a/docs/dev/kinopoiskdev/Http/StudioRequests.md b/docs/dev/kinopoiskdev/Http/StudioRequests.md new file mode 100644 index 0000000..59122da --- /dev/null +++ b/docs/dev/kinopoiskdev/Http/StudioRequests.md @@ -0,0 +1,198 @@ +# StudioRequests + +**Описание:** Класс для API-запросов, связанных со студиями +Этот класс предоставляет методы для всех конечных точек студий API Kinopoisk.dev. +Позволяет получать информацию о кинокомпаниях, студиях дубляжа, производителях +и других организациях, участвующих в создании фильмов. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Studio`: Для структуры данных студии +* `\KinopoiskDev\Filter\StudioSearchFilter`: Для фильтрации запросов + +## `getProductionStudios()` + +**Описание:** Получает производственные студии +Удобный метод для получения студий типа "Производство". + +**Параметры:** + +* `$page` (int): Номер страницы результатов +* `$limit` (int): Количество результатов на странице + +**Возвращает:** `StudioDocsResponseDto` Производственные студии + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API +* `\JsonException|\KinopoiskDev\Exceptions\KinopoiskResponseException`: При ошибках парсинга JSON + +## `getStudiosByType()` + +**Описание:** Получает студии по типу +Удобный метод для получения студий определенного типа: +"Производство", "Спецэффекты", "Прокат", "Студия дубляжа" + +**Параметры:** + +* `$type` (string): Тип студии +* `$page` (int): Номер страницы результатов +* `$limit` (int): Количество результатов на странице + +**Возвращает:** `StudioDocsResponseDto` Студии указанного типа + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API +* `\JsonException|\KinopoiskDev\Exceptions\KinopoiskResponseException`: При ошибках парсинга JSON + +## `searchStudios()` + +**Описание:** Ищет студии по различным критериям +Основной метод для поиска студий с поддержкой сложных фильтров. +Позволяет искать по названию, типу студии, подтипу и связанным фильмам. + +**API Endpoint:** `/v1.4/studio` + +**Параметры:** + +* `$filters` (StudioSearchFilter|null): Объект фильтра для поиска студий +* `$page` (int): Номер страницы результатов (по умолчанию: 1) +* `$limit` (int): Количество результатов на странице (по умолчанию: 10, максимум: 250) + +**Возвращает:** `StudioDocsResponseDto` Результаты поиска с пагинацией + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API + +## `getDubbingStudios()` + +**Описание:** Получает студии дубляжа +Удобный метод для получения студий типа "Студия дубляжа". + +**Параметры:** + +* `$page` (int): Номер страницы результатов +* `$limit` (int): Количество результатов на странице + +**Возвращает:** `StudioDocsResponseDto` Студии дубляжа + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API +* `\JsonException|\KinopoiskDev\Exceptions\KinopoiskResponseException`: При ошибках парсинга JSON + +## `getStudiosByTitle()` + +**Описание:** Получает студии по названию +Выполняет поиск студий по точному или частичному совпадению названия. + +**Параметры:** + +* `$title` (string): Название студии для поиска +* `$page` (int): Номер страницы результатов +* `$limit` (int): Количество результатов на странице + +**Возвращает:** `StudioDocsResponseDto` Студии с подходящими названиями + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API +* `\JsonException|\KinopoiskDev\Exceptions\KinopoiskResponseException`: При ошибках парсинга JSON + +## `getStudioById()` + +**Описание:** Получает студию по её уникальному идентификатору + +**Параметры:** + +* `$studioId` (int): Уникальный идентификатор студии + +**Возвращает:** `Studio` Объект студии + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API + +## `getRandomStudio()` + +**Описание:** Получает случайную студию + +**Параметры:** + +* `$filters` (StudioSearchFilter|null): Фильтры для поиска + +**Возвращает:** `Studio` Случайная студия + +## `searchStudiosByName()` + +**Описание:** Выполняет поиск студий по названию (алиас для getStudiosByTitle) + +**Параметры:** + +* `$name` (string): Название для поиска +* `$page` (int): Номер страницы +* `$limit` (int): Количество результатов + +**Возвращает:** `StudioDocsResponseDto` Результаты поиска + +## `getStudiosByCountry()` + +**Описание:** Получает студии по стране + +**Параметры:** + +* `$country` (string): Страна +* `$page` (int): Номер страницы +* `$limit` (int): Количество результатов + +**Возвращает:** `StudioDocsResponseDto` Результаты поиска + +## `getStudiosByYear()` + +**Описание:** Получает студии по году основания + +**Параметры:** + +* `$year` (int): Год основания +* `$page` (int): Номер страницы +* `$limit` (int): Количество результатов + +**Возвращает:** `StudioDocsResponseDto` Результаты поиска + +## `getStudiosByYearRange()` + +**Описание:** Получает студии по диапазону годов основания + +**Параметры:** + +* `$fromYear` (int): Начальный год +* `$toYear` (int): Конечный год +* `$page` (int): Номер страницы +* `$limit` (int): Количество результатов + +**Возвращает:** `StudioDocsResponseDto` Результаты поиска + +## `getStudiosForMovie()` + +**Описание:** Получает студии, связанные с определенным фильмом +Находит все студии, которые принимали участие в создании указанного фильма. + +**Параметры:** + +* `$movieId` (int): Идентификатор фильма +* `$page` (int): Номер страницы результатов +* `$limit` (int): Количество результатов на странице + +**Возвращает:** `StudioDocsResponseDto` Студии, связанные с фильмом + +**Исключения:** + +* `KinopoiskDevException`: При ошибках API +* `\JsonException|\KinopoiskDev\Exceptions\KinopoiskResponseException`: При ошибках парсинга JSON + diff --git a/docs/dev/kinopoiskdev/Kinopoisk.md b/docs/dev/kinopoiskdev/Kinopoisk.md new file mode 100644 index 0000000..9b3b375 --- /dev/null +++ b/docs/dev/kinopoiskdev/Kinopoisk.md @@ -0,0 +1,276 @@ +# Kinopoisk + +**Описание:** Главный класс для работы с API Kinopoisk.dev +Предоставляет базовую функциональность для выполнения HTTP запросов к API, +обработки ответов, кэширования и управления ошибками. Использует современные +PHP 8.3 возможности и архитектурные паттерны. +Основные возможности: +- Выполнение HTTP запросов к API Kinopoisk.dev +- Автоматическое кэширование ответов +- Валидация входных данных +- Обработка ошибок API +- Логирование операций + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Http\MovieRequests`: Для работы с фильмами +* `\KinopoiskDev\Http\PersonRequests`: Для работы с персонами +* `\KinopoiskDev\Http\StudioRequests`: Для работы со студиями +* `\KinopoiskDev\Contracts\CacheInterface`: Интерфейс кэширования +* `\KinopoiskDev\Contracts\LoggerInterface`: Интерфейс логирования + +## `__construct()` + +**Описание:** Конструктор клиента API Kinopoisk +Инициализирует клиент API с указанными параметрами. Если параметры не переданы, +используются значения по умолчанию. API токен может быть передан напрямую +или получен из переменной окружения KINOPOISK_TOKEN. + +**С версии:** 1.0.0 + +**Параметры:** + +* `$apiToken` (string|null): Токен авторизации API (если null, берется из $_ENV['KINOPOISK_TOKEN']) +* `$httpClient` (HttpClient|null): HTTP клиент (если null, создается новый) +* `$cache` (CacheInterface|null): Сервис кэширования (если null, создается FilesystemAdapter) +* `$logger` (LoggerInterface|null): Логгер (если null, логирование отключено) +* `$useCache` (bool): Использовать кэширование (по умолчанию false) +* `$responseValidator` (ValidationService|null): Валидатор ответов API (если null, валидация отключена) + +**Исключения:** + +* `ValidationException`: При отсутствии токена или неверном формате +* `KinopoiskDevException`: При ошибке инициализации компонентов + +**Пример:** +```php +// Минимальная инициализация +$kinopoisk = new Kinopoisk(); +// С кастомными параметрами +$kinopoisk = new Kinopoisk( +apiToken: 'ABC1DEF-2GH3IJK-4LM5NOP-6QR7STU', +useCache: true +); +// С кастомным HTTP клиентом и логгером +$httpClient = new HttpClient(['timeout' => 60]); +$logger = new CustomLogger(); +$kinopoisk = new Kinopoisk('your-api-token', $httpClient, null, $logger); +``` + +## `validateAndSetApiToken()` + +**Описание:** Валидирует и устанавливает API токен +Проверяет наличие и формат API токена. Если токен не передан, +пытается получить его из переменной окружения KINOPOISK_TOKEN. +Валидирует формат токена Kinopoisk.dev. + +**С версии:** 1.0.0 + +**Параметры:** + +* `$apiToken` (string|null): Токен API для валидации + +**Исключения:** + +* `ValidationException`: При отсутствии токена или неверном формате + +## `createDefaultHttpClient()` + +**Описание:** Создает HTTP клиент по умолчанию +Создает экземпляр GuzzleHttp\Client с базовыми настройками +для работы с API Kinopoisk.dev. + +**С версии:** 1.0.0 + +**Возвращает:** `HttpClient` Экземпляр HTTP клиента с настроенными параметрами + +## `makeRequestWithValidation()` + +**Описание:** Выполняет HTTP запрос к API с валидацией ответа +Расширенная версия makeRequest, которая также выполняет валидацию +ответа с эталонными данными, если включена валидация. + +**Параметры:** + +* `$method` (string): HTTP метод +* `$endpoint` (string): Конечная точка API +* `$apiVersion` (string|null): Версия API + +**Возвращает:** `array` Декодированные данные ответа + +**Исключения:** + +* `KinopoiskDevException`: При ошибках запроса или валидации + +## `buildFullUrl()` + +**Описание:** Строит полный URL для запроса + +**Параметры:** + +* `$method` (string): HTTP метод +* `$endpoint` (string): Конечная точка +* `$version` (string): Версия API + +**Возвращает:** `string` Полный URL + +## `makeRequest()` + +**Описание:** Выполняет HTTP запрос к API с поддержкой кэширования +Основной метод для выполнения запросов к API Kinopoisk.dev. Поддерживает +автоматическое кэширование GET запросов и обработку различных HTTP методов. +Валидирует входные параметры перед выполнением запроса. + +**С версии:** 1.0.0 + +**Параметры:** + +* `$method` (string): HTTP метод (GET, POST, PUT, DELETE, PATCH) +* `$endpoint` (string): Конечная точка API (без версии) +* `$apiVersion` (string|null): Версия API (если null, используется API_VERSION) + +**Возвращает:** `ResponseInterface` Ответ от API + +**Исключения:** + +* `KinopoiskDevException`: При ошибках валидации или HTTP запроса +* `ValidationException`: При неверных параметрах запроса + +**Пример:** +```php +// Простой GET запрос +$response = $kinopoisk->makeRequest('GET', 'movie/123'); +// GET запрос с параметрами +$response = $kinopoisk->makeRequest('GET', 'movie', [ +'page' => 1, +'limit' => 10 +]); +// Запрос к другой версии API +$response = $kinopoisk->makeRequest('GET', 'movie/123', [], 'v1.3'); +``` + +## `validateHttpMethod()` + +**Описание:** Валидирует HTTP метод +Проверяет, что переданный HTTP метод поддерживается API. + +**С версии:** 1.0.0 + +**Параметры:** + +* `$method` (string): HTTP метод для валидации + +**Исключения:** + +* `ValidationException`: При неверном или неподдерживаемом методе + +## `validateEndpoint()` + +**Описание:** Валидирует конечную точку API +Проверяет формат и валидность конечной точки API. +Допускает только буквы, цифры, слеши, подчеркивания и дефисы. + +**С версии:** 1.0.0 + +**Параметры:** + +* `$endpoint` (string): Конечная точка для валидации + +**Исключения:** + +* `ValidationException`: При неверном формате конечной точки + +## `generateCacheKey()` + +**Описание:** Генерирует ключ для кэширования +Создает уникальный ключ кэша на основе параметров запроса. +Использует SHA256 хэш для обеспечения уникальности и безопасности. + +**С версии:** 1.0.0 + +**Параметры:** + +* `$method` (string): HTTP метод +* `$endpoint` (string): Конечная точка +* `$version` (string): Версия API + +**Возвращает:** `string` Уникальный ключ кэша + +## `executeHttpRequest()` + +**Описание:** Выполняет HTTP запрос +Формирует полный URL запроса и выполняет его через HTTP клиент. +Добавляет API токен в заголовки запроса. + +**С версии:** 1.0.0 + +**Параметры:** + +* `$method` (string): HTTP метод +* `$endpoint` (string): Конечная точка +* `$version` (string): Версия API + +**Возвращает:** `ResponseInterface` Ответ от сервера + +**Исключения:** + +* `GuzzleException`: При ошибке выполнения HTTP запроса + +## `parseResponse()` + +**Описание:** Обрабатывает ответ от API с валидацией +Парсит HTTP ответ от API, проверяет статус код и декодирует JSON. +Обрабатывает различные типы ошибок API и логирует результаты. +Если включена валидация ответов, сравнивает с эталонными данными. + +**С версии:** 1.0.0 + +**Параметры:** + +* `$response` (ResponseInterface): HTTP ответ от API +* `$requestUrl` (string|null): Полный URL запроса для валидации (опционально) + +**Возвращает:** `array` Декодированные данные ответа + +**Исключения:** + +* `KinopoiskDevException`: При ошибках обработки ответа +* `KinopoiskResponseException`: При ошибках API (401, 403, 404, 500) +* `\JsonException`: При ошибках парсинга JSON + +**Пример:** +```php +$response = $kinopoisk->makeRequest('GET', 'movie/123'); +$data = $kinopoisk->parseResponse($response); +$movie = Movie::fromArray($data); +``` + +## `handleErrorStatusCode()` + +**Описание:** Обрабатывает ошибочные статус коды +Проверяет статус код ответа и выбрасывает соответствующие исключения +для известных ошибок API (401, 403, 404). + +**С версии:** 1.0.0 + +**Параметры:** + +* `$statusCode` (HttpStatusCode|null): Статус код как enum +* `$rawStatusCode` (int|null): Сырой статус код + +**Исключения:** + +* `KinopoiskResponseException`: При известных ошибках API + +## `validateResponse()` + +**Описание:** Валидирует ответ API с эталонными данными + +**Параметры:** + +* `$requestUrl` (string): URL запроса + diff --git a/docs/dev/kinopoiskdev/Models/.nav.yml b/docs/dev/kinopoiskdev/Models/.nav.yml new file mode 100644 index 0000000..d9592c2 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/.nav.yml @@ -0,0 +1,5 @@ +title: Модели +nav: + - "*" +sort: + type: alphabetical diff --git a/docs/dev/kinopoiskdev/Models/AbstractBaseModel.md b/docs/dev/kinopoiskdev/Models/AbstractBaseModel.md new file mode 100644 index 0000000..7ab0ce6 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/AbstractBaseModel.md @@ -0,0 +1,419 @@ +# AbstractBaseModel + +**Описание:** Абстрактный базовый класс для всех моделей +Предоставляет общую функциональность для моделей данных: +валидацию, сериализацию, работу с атрибутами PHP 8.3. +Реализует интерфейс BaseModel и предоставляет готовые +методы для работы с данными API Kinopoisk.dev. +Основные возможности: +- Автоматическая валидация на основе атрибутов Validation +- Сериализация/десериализация с поддержкой JSON +- Обработка конфиденциальных полей +- Безопасное извлечение данных из массивов +- Создание копий объектов с изменениями + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**Пример:** +```php +class Movie extends AbstractBaseModel { +#[Validation(required: true, minLength: 1, maxLength: 255)] +public string $title; +#[Validation(min: 1900, max: 2030)] +public int $year; +#[Sensitive(hideInJson: true)] +public string $apiKey; +public function __construct(string $title, int $year, string $apiKey) { +$this->title = $title; +$this->year = $year; +$this->apiKey = $apiKey; +} +} +$movie = Movie::fromArray(['title' => 'The Matrix', 'year' => 1999, 'apiKey' => 'secret']); +$movie->validate(); +$json = $movie->toJson(); // apiKey не включен в JSON +``` + +**См. также:** + +* `\KinopoiskDev\Models\BaseModel`: Интерфейс базовой модели +* `\KinopoiskDev\Attributes\Validation`: Атрибут валидации +* `\KinopoiskDev\Attributes\Sensitive`: Атрибут конфиденциальных полей +* `\KinopoiskDev\Services\ValidationService`: Сервис валидации + +## `fromJson()` + +**Описание:** Создает объект из JSON строки +Десериализует JSON строку в объект модели. Парсит JSON, +создает массив данных и использует fromArray для создания объекта. + +Десериализует JSON строку в объект модели с обработкой ошибок +парсинга и валидации данных. + +**Параметры:** + +* `$json` (string): JSON строка с данными объекта + +**Возвращает:** `static` Экземпляр модели с заполненными данными + +**Исключения:** + +* `ValidationException`: При ошибках парсинга JSON или валидации данных +* `\JsonException`: При ошибках парсинга JSON + +**Пример:** +```php +$json = '{"title":"The Matrix","year":1999}'; +$movie = Movie::fromJson($json); +echo $movie->title; // The Matrix +``` + +## `fromArray()` + +**Описание:** Создает экземпляр модели из массива данных +Фабричный метод для создания объекта модели из ассоциативного массива, +полученного из API ответа. Должен обрабатывать маппинг полей API +на свойства модели и выполнять базовую валидацию данных. + +Создает экземпляр модели из массива данных с использованием рефлексии. +Автоматически определяет параметры конструктора и передает соответствующие +значения из массива данных. Поддерживает значения по умолчанию. + +**Возвращает:** `static` Экземпляр модели с заполненными данными + +**Исключения:** + +* `\ReflectionException`: При ошибках рефлексии +* `\LogicException`: При попытке создания абстрактного класса +* `ValidationException`: При некорректных данных + +**Пример:** +```php +$data = ['title' => 'The Matrix', 'year' => 1999]; +$movie = Movie::fromArray($data); +// Создается объект Movie с title='The Matrix' и year=1999 +``` + +## `getDataValue()` + +**Описание:** Безопасно извлекает значение из массива данных +Универсальный метод для безопасного извлечения значений из массива +с поддержкой значения по умолчанию при отсутствии ключа. + +**Параметры:** + +* `$key` (string): Ключ для поиска в массиве +* `$default` (mixed): Значение по умолчанию при отсутствии ключа + +**Возвращает:** `mixed` Значение из массива или значение по умолчанию + +**Пример:** +```php +$data = ['title' => 'The Matrix', 'year' => 1999]; +$title = self::getDataValue($data, 'title', 'Unknown'); // 'The Matrix' +$rating = self::getDataValue($data, 'rating', 0); // 0 +``` + +## `getArrayValue()` + +**Описание:** Безопасно извлекает массив из данных +Извлекает значение из массива данных и гарантирует, что результат +будет массивом. Возвращает пустой массив, если ключ отсутствует +или значение не является массивом. + +**Параметры:** + +* `$key` (string): Ключ для поиска в массиве + +**Возвращает:** `array` Массив значений или пустой массив + +**Пример:** +```php +$data = ['genres' => ['action', 'sci-fi'], 'actors' => null]; +$genres = self::getArrayValue($data, 'genres'); // ['action', 'sci-fi'] +$actors = self::getArrayValue($data, 'actors'); // [] +``` + +## `getStringValue()` + +**Описание:** Безопасно извлекает строку из данных +Извлекает строковое значение из массива данных с поддержкой +значения по умолчанию. Возвращает null, если значение не является строкой. + +**Параметры:** + +* `$key` (string): Ключ для поиска в массиве +* `$default` (string|null): Значение по умолчанию при отсутствии ключа + +**Возвращает:** `string|null` Строковое значение или null + +**Пример:** +```php +$data = ['title' => 'The Matrix', 'year' => 1999]; +$title = self::getStringValue($data, 'title'); // 'The Matrix' +$description = self::getStringValue($data, 'description'); // null +``` + +## `getIntValue()` + +**Описание:** Безопасно извлекает целое число из данных +Извлекает целочисленное значение из массива данных с поддержкой +значения по умолчанию. Преобразует числовые строки в целые числа. + +**Параметры:** + +* `$key` (string): Ключ для поиска в массиве +* `$default` (int|null): Значение по умолчанию при отсутствии ключа + +**Возвращает:** `int|null` Целочисленное значение или null + +**Пример:** +```php +$data = ['year' => 1999, 'rating' => '8.7', 'votes' => null]; +$year = self::getIntValue($data, 'year'); // 1999 +$rating = self::getIntValue($data, 'rating'); // 8 +$votes = self::getIntValue($data, 'votes'); // null +``` + +## `getBoolValue()` + +**Описание:** Безопасно извлекает логическое значение из данных +Извлекает логическое значение из массива данных с поддержкой +значения по умолчанию. Возвращает null, если значение не является boolean. + +**Параметры:** + +* `$key` (string): Ключ для поиска в массиве +* `$default` (bool|null): Значение по умолчанию при отсутствии ключа + +**Возвращает:** `bool|null` Логическое значение или null + +**Пример:** +```php +$data = ['isActive' => true, 'isDeleted' => false, 'isPublished' => null]; +$isActive = self::getBoolValue($data, 'isActive'); // true +$isDeleted = self::getBoolValue($data, 'isDeleted'); // false +$isPublished = self::getBoolValue($data, 'isPublished'); // null +``` + +## `with()` + +**Описание:** Создает копию объекта с измененными свойствами +Иммутабельный метод для создания нового экземпляра объекта +с измененными значениями свойств. Полезен для создания +вариаций объекта без изменения оригинала. + +**Возвращает:** `static` Новый экземпляр с примененными изменениями + +**Исключения:** + +* `ValidationException`: При ошибках валидации нового объекта + +**Пример:** +```php +$movie = new Movie('The Matrix', 1999); +// Создаем копию с измененным годом +$updatedMovie = $movie->with(['year' => 2000]); +echo $updatedMovie->title; // The Matrix +echo $updatedMovie->year; // 2000 +echo $movie->year; // 1999 (оригинал не изменился) +``` + +## `toArray()` + +**Описание:** Преобразует объект в массив +Сериализует объект модели в ассоциативный массив для передачи +в API или сохранения в базу данных. Поддерживает контроль +включения null значений. + +Преобразует объект в ассоциативный массив с поддержкой вложенных объектов, +enum значений и конфиденциальных полей. Автоматически обрабатывает +атрибуты ApiField для маппинга имен полей. + +**Параметры:** + +* `$includeNulls` (bool): Включать ли null значения в результат (по умолчанию true) + +**Возвращает:** `array` Ассоциативный массив с данными объекта + +**Пример:** +```php +$movie = new Movie('The Matrix', 1999); +// С null значениями +$array = $movie->toArray(true); +// Результат: ['title' => 'The Matrix', 'year' => 1999, 'rating' => null] +// Без null значений +$array = $movie->toArray(false); +// Результат: ['title' => 'The Matrix', 'year' => 1999] +``` + +## `getApiFieldName()` + +**Описание:** Определяет имя поля для API на основе атрибутов +Извлекает имя поля для API из атрибута ApiField или возвращает +оригинальное имя свойства, если атрибут не задан. + +**Параметры:** + +* `$property` (ReflectionProperty): Свойство для анализа + +**Возвращает:** `string` Имя поля для использования в API + +## `processArrayValue()` + +**Описание:** Обрабатывает значения массива для сериализации +Рекурсивно обрабатывает элементы массива, преобразуя объекты BaseModel +в массивы и enum значения в их скалярные представления. + +**Параметры:** + +* `$value` (array): Массив для обработки +* `$includeNulls` (bool): Включать ли null значения в результат + +**Возвращает:** `array` Обработанный массив + +## `validate()` + +**Описание:** Валидирует данные модели +Проверяет корректность данных модели согласно бизнес-правилам +и ограничениям. Может использовать атрибуты Validation для +автоматической валидации свойств. + +Валидирует объект с использованием ValidationService и атрибутов Validation. +Проверяет все свойства объекта на соответствие заданным правилам валидации. + +**Возвращает:** `bool True` если валидация прошла успешно + +**Исключения:** + +* `ValidationException`: При ошибках валидации с детальным описанием проблем + +**Пример:** +```php +$movie = new Movie('', -1000); // Некорректные данные +try { +$movie->validate(); +echo "Модель валидна"; +} catch (ValidationException $e) { +foreach ($e->getErrors() as $field => $error) { +echo "{$field}: {$error}\n"; +} +} +``` + +## `getValidator()` + +**Описание:** Получает экземпляр валидатора +Возвращает статический экземпляр ValidationService для переиспользования +между объектами одного класса. Создает новый экземпляр при первом вызове. + +**Возвращает:** `ValidationService` Экземпляр сервиса валидации + +## `equals()` + +**Описание:** Сравнивает текущий объект с другим +Выполняет глубокое сравнение объектов на основе их данных. +Объекты считаются равными, если все их свойства имеют одинаковые значения. + +**Параметры:** + +* `$other` (BaseModel): Объект для сравнения + +**Возвращает:** `bool True` если объекты равны, false в противном случае + +**Пример:** +```php +$movie1 = new Movie('The Matrix', 1999); +$movie2 = new Movie('The Matrix', 1999); +$movie3 = new Movie('The Matrix', 2000); +$movie1->equals($movie2); // true +$movie1->equals($movie3); // false +``` + +## `getHash()` + +**Описание:** Возвращает хэш объекта +Генерирует SHA256 хэш на основе JSON представления объекта. +Полезен для кэширования, сравнения версий объектов или +создания уникальных идентификаторов. + +**Возвращает:** `string SHA256` хэш объекта + +**Пример:** +```php +$movie = new Movie('The Matrix', 1999); +$hash = $movie->getHash(); +// Результат: строка из 64 символов (SHA256) +``` + +## `toJson()` + +**Описание:** Возвращает JSON представление объекта +Сериализует объект модели в JSON строку для передачи +по сети или сохранения в файл. Поддерживает настройку +флагов кодирования JSON. + +Сериализует объект в JSON строку с автоматической фильтрацией +конфиденциальных полей согласно атрибутам Sensitive. + +**Параметры:** + +* `$flags` (int): Флаги для json_encode (по умолчанию JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE) + +**Возвращает:** `string JSON` строка с данными объекта + +**Исключения:** + +* `ValidationException`: При ошибке кодирования JSON + +**Пример:** +```php +$movie = new Movie('The Matrix', 1999); +$movie->apiKey = 'secret123'; +$json = $movie->toJson(); +// Результат: '{"title":"The Matrix","year":1999}' (apiKey исключен) +``` + +## `filterSensitiveForJson()` + +**Описание:** Фильтрует конфиденциальные поля для JSON вывода +Удаляет поля, помеченные атрибутом Sensitive с hideInJson=true, +из массива данных перед JSON сериализацией. + +**Возвращает:** `array` Отфильтрованные данные без конфиденциальных полей + +## `isEmpty()` + +**Описание:** Проверяет, является ли объект пустым +Определяет, содержит ли объект какие-либо непустые данные. +Исключает null значения, пустые строки и пустые массивы. + +**Возвращает:** `bool True` если объект не содержит данных, false в противном случае + +**Пример:** +```php +$movie1 = new Movie('', 0); +$movie1->isEmpty(); // true +$movie2 = new Movie('The Matrix', 1999); +$movie2->isEmpty(); // false +``` + +## `getFilledProperties()` + +**Описание:** Возвращает только заполненные свойства +Возвращает ассоциативный массив, содержащий только свойства +с непустыми значениями (исключая null, пустые строки и массивы). + +**Возвращает:** `array` Массив непустых свойств + +**Пример:** +```php +$movie = new Movie('The Matrix', 1999); +$movie->description = ''; +$movie->tags = []; +$filled = $movie->getFilledProperties(); +// Результат: ['title' => 'The Matrix', 'year' => 1999] +``` + diff --git a/docs/dev/kinopoiskdev/Models/ApiImage.md b/docs/dev/kinopoiskdev/Models/ApiImage.md new file mode 100644 index 0000000..106360a --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/ApiImage.md @@ -0,0 +1,76 @@ +# ApiImage + +**Описание:** Класс для представления изображений из API Kinopoisk.dev +Расширенная модель изображения, которая включает дополнительные поля, +возвращаемые API: movieId, type, id, createdAt, updatedAt. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Image`: Базовая модель изображения + +## `__construct()` + +**Описание:** Конструктор модели API изображения + +**Параметры:** + +* `$movieId` (int|null): ID фильма +* `$type` (string|null): Тип изображения +* `$url` (string|null): URL полноразмерного изображения +* `$previewUrl` (string|null): URL превью изображения +* `$height` (int|null): Высота изображения в пикселях +* `$width` (int|null): Ширина изображения в пикселях +* `$createdAt` (string|null): Дата создания +* `$updatedAt` (string|null): Дата обновления +* `$id` (string|null): Уникальный идентификатор + +## `__toString()` + +**Описание:** Строковое представление изображения + +**Возвращает:** `string` Строковое описание изображения + +## `exists()` + +**Описание:** Проверяет, доступно ли изображение + +**Возвращает:** `bool true` если изображение доступно + +## `getFormattedDimensions()` + +**Описание:** Возвращает размеры изображения в виде строки + +**Возвращает:** `string|null` Строка размеров в формате "1920x1080" + +## `fromArray()` + +**Описание:** Создает объект ApiImage из массива данных API + +**Возвращает:** `static` Новый экземпляр класса ApiImage с данными из массива + +## `toArray()` + +**Описание:** Преобразует объект в массив + +**Параметры:** + +* `$includeNulls` (bool): Включать ли null значения + +**Возвращает:** `array` Массив с данными изображения + +## `getBestUrl()` + +**Описание:** Возвращает лучший доступный URL изображения + +**Возвращает:** `string|null URL` наилучшего доступного изображения + +## `validate()` + +**Описание:** Валидация данных + +**Возвращает:** `bool true` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/Audience.md b/docs/dev/kinopoiskdev/Models/Audience.md new file mode 100644 index 0000000..4852a75 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Audience.md @@ -0,0 +1,60 @@ +# Audience + +**Описание:** Класс для представления данных об аудитории фильма +Представляет информацию о количестве зрителей и стране, где собирались +данные об аудитории фильма. Используется для хранения статистики +просмотров и географического распределения зрителей. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Rating`: Для информации о рейтингах +* `\KinopoiskDev\Models\Fees`: Для информации о кассовых сборах + +## `__construct()` + +**Описание:** Конструктор модели аудитории +Создает новый экземпляр класса Audience с указанными параметрами +количества зрителей и страны. Все параметры являются опциональными +и могут быть null при отсутствии данных. + +**Параметры:** + +* `$country` (string|null): Страна сбора данных (null если не указана) +* `$count` (int|null): Количество зрителей (null если данные отсутствуют) + +**См. также:** + +* `Audience::fromArray`: () Для создания объекта из массива данных API + +## `fromArray()` + +**Описание:** Создает объект Audience из массива данных API +- count: int|null - количество зрителей +- country: string|null - страна сбора данных + +**Возвращает:** `static` Новый экземпляр класса Audience + +**См. также:** + +* `Audience::toArray`: () Для обратного преобразования в массив + +## `toArray()` + +**Описание:** Преобразует объект в массив +- count: int|null - количество зрителей +- country: string|null - страна сбора данных + +**Параметры:** + +* `$includeNulls` (bool): Включать ли null значения + +**Возвращает:** `array` Массив с данными об аудитории, содержащий ключи: + +**См. также:** + +* `Audience::fromArray`: () Для создания объекта из массива + diff --git a/docs/dev/kinopoiskdev/Models/BaseModel.md b/docs/dev/kinopoiskdev/Models/BaseModel.md new file mode 100644 index 0000000..e77726f --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/BaseModel.md @@ -0,0 +1,171 @@ +# BaseModel + +**Описание:** Базовый интерфейс для всех моделей данных +Определяет контракт для моделей, работающих с данными API Kinopoisk.dev. +Включает методы для создания объектов из массивов данных, преобразования +в массивы, валидации и сериализации. Все модели данных должны реализовывать +этот интерфейс для обеспечения единообразного API. + +**С версии:** 1.0.0 + +**Версия:** 2.0.0 + +**Пример:** +```php +class Movie implements BaseModel { +public function __construct( +public string $title, +public int $year +) {} +public static function fromArray(array $data): static { +return new static($data['title'], $data['year']); +} +public function toArray(bool $includeNulls = true): array { +return [ +'title' => $this->title, +'year' => $this->year +]; +} +public function validate(): bool { +return !empty($this->title) && $this->year > 1900; +} +public function toJson(int $flags = JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE): string { +return json_encode($this->toArray(), $flags); +} +public static function fromJson(string $json): static { +$data = json_decode($json, true, 512, JSON_THROW_ON_ERROR); +return static::fromArray($data); +} +} +``` + +**См. также:** + +* `\KinopoiskDev\Models\AbstractBaseModel`: Абстрактная реализация базовой модели +* `\KinopoiskDev\Models\Movie`: Модель фильма +* `\KinopoiskDev\Models\Person`: Модель персоны +* `\KinopoiskDev\Models\Studio`: Модель студии + +## `fromArray()` + +**Описание:** Создает экземпляр модели из массива данных +Фабричный метод для создания объекта модели из ассоциативного массива, +полученного из API ответа. Должен обрабатывать маппинг полей API +на свойства модели и выполнять базовую валидацию данных. + +**Возвращает:** `static` Экземпляр модели с заполненными данными + +**Исключения:** + +* `ValidationException`: При некорректных или неполных данных + +**Пример:** +```php +$apiData = [ +'title' => 'The Matrix', +'year' => 1999, +'rating' => 8.7 +]; +$movie = Movie::fromArray($apiData); +echo $movie->title; // The Matrix +``` + +## `fromJson()` + +**Описание:** Создает объект из JSON строки +Десериализует JSON строку в объект модели. Парсит JSON, +создает массив данных и использует fromArray для создания объекта. + +**Параметры:** + +* `$json` (string): JSON строка с данными объекта + +**Возвращает:** `static` Экземпляр модели с заполненными данными + +**Исключения:** + +* `\JsonException`: При ошибке парсинга JSON строки +* `ValidationException`: При некорректных данных после парсинга + +**Пример:** +```php +$json = '{"title":"The Matrix","year":1999}'; +$movie = Movie::fromJson($json); +echo $movie->title; // The Matrix +echo $movie->year; // 1999 +``` + +## `toArray()` + +**Описание:** Преобразует объект в массив +Сериализует объект модели в ассоциативный массив для передачи +в API или сохранения в базу данных. Поддерживает контроль +включения null значений. + +**Параметры:** + +* `$includeNulls` (bool): Включать ли null значения в результат (по умолчанию true) + +**Возвращает:** `array` Данные объекта в виде ассоциативного массива + +**Пример:** +```php +$movie = new Movie('The Matrix', 1999); +// С null значениями +$array = $movie->toArray(true); +// Результат: ['title' => 'The Matrix', 'year' => 1999, 'rating' => null] +// Без null значений +$array = $movie->toArray(false); +// Результат: ['title' => 'The Matrix', 'year' => 1999] +``` + +## `validate()` + +**Описание:** Валидирует данные модели +Проверяет корректность данных модели согласно бизнес-правилам +и ограничениям. Может использовать атрибуты Validation для +автоматической валидации свойств. + +**Возвращает:** `bool True` если данные валидны, false в противном случае + +**Исключения:** + +* `ValidationException`: При ошибке валидации с детальным описанием проблем + +**Пример:** +```php +$movie = new Movie('', -1000); // Некорректные данные +try { +$movie->validate(); +echo "Модель валидна"; +} catch (ValidationException $e) { +echo "Ошибки валидации: " . $e->getMessage(); +} +``` + +## `toJson()` + +**Описание:** Возвращает JSON представление объекта +Сериализует объект модели в JSON строку для передачи +по сети или сохранения в файл. Поддерживает настройку +флагов кодирования JSON. + +**Параметры:** + +* `$flags` (int): Флаги для json_encode (по умолчанию JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE) + +**Возвращает:** `string JSON` строка с данными объекта + +**Исключения:** + +* `\JsonException`: При ошибке сериализации в JSON + +**Пример:** +```php +$movie = new Movie('The Matrix', 1999); +$json = $movie->toJson(); +// Результат: '{"title":"The Matrix","year":1999}' +// С дополнительными флагами +$json = $movie->toJson(JSON_PRETTY_PRINT); +``` + diff --git a/docs/dev/kinopoiskdev/Models/BirthPlace.md b/docs/dev/kinopoiskdev/Models/BirthPlace.md new file mode 100644 index 0000000..7729882 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/BirthPlace.md @@ -0,0 +1,25 @@ +# BirthPlace + +**Описание:** Класс для представления места рождения персоны +Специализированный класс для представления места рождения персоны, наследующий +от базового класса PersonPlace. Предоставляет семантическое разделение между +различными типами мест, связанных с персоной (рождение, смерть и т.д.). +Наследует все методы и свойства родительского класса без изменений. + +**С версии:** 1.0.0 + +**Пример:** +```php +// Создание места рождения из массива +$birthPlace = BirthPlace::fromArray(['value' => 'Москва, Россия']); +// Получение строкового представления +echo $birthPlace; // "Москва, Россия" +// Доступ к значению напрямую +echo $birthPlace->value; // "Москва, Россия" +``` + +**См. также:** + +* `\KinopoiskDev\Models\PersonPlace`: Базовый класс для места персоны +* `\KinopoiskDev\Models\Person`: Класс персоны, использующий места рождения + diff --git a/docs/dev/kinopoiskdev/Models/CurrencyValue.md b/docs/dev/kinopoiskdev/Models/CurrencyValue.md new file mode 100644 index 0000000..ef0db9a --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/CurrencyValue.md @@ -0,0 +1,81 @@ +# CurrencyValue + +**Описание:** Класс для представления денежных значений с валютой +Представляет денежное значение с указанием валюты, используемое для +хранения информации о кассовых сборах фильмов, бюджете и других +финансовых данных в системе Kinopoisk.dev. Поддерживает различные +валюты и обрабатывает отсутствующие значения. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Budget`: Для информации о бюджете фильма +* `\KinopoiskDev\Models\Fees`: Для информации о кассовых сборах + +## `__construct()` + +**Описание:** Конструктор для создания объекта денежного значения +Создает новый экземпляр класса CurrencyValue с указанными значением +и валютой. Все параметры являются опциональными и могут быть null +при отсутствии данных о денежном значении или валюте. + +**Параметры:** + +* `$value` (int|null): Денежное значение в указанной валюте (null если не указано) +* `$currency` (string|null): Код валюты (например, USD, RUB, EUR) или null если не указана + +**См. также:** + +* `CurrencyValue::fromArray`: () Для создания объекта из массива данных API +* `CurrencyValue::toArray`: () Для преобразования объекта в массив + +## `fromJson()` + +**Описание:** Создает объект из JSON строки + +**Параметры:** + +* `$json` (string): JSON строка + +**Возвращает:** `static` Экземпляр модели + +## `fromArray()` + +**Описание:** Создает объект CurrencyValue из массива данных API +Фабричный метод для создания экземпляра класса CurrencyValue из массива +данных, полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения, устанавливая их в null. Используется для десериализации данных +о денежных значениях из ответов API. +- value: int|null - денежное значение +- currency: string|null - код валюты + +**Возвращает:** `static` Новый экземпляр класса CurrencyValue с данными из массива + +**См. также:** + +* `CurrencyValue::toArray`: () Для обратного преобразования в массив + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса CurrencyValue в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных в JSON. +- value: int|null - денежное значение +- currency: string|null - код валюты + +**Возвращает:** `array` Массив с данными о денежном значении, содержащий ключи: + +**См. также:** + +* `CurrencyValue::fromArray`: () Для создания объекта из массива + diff --git a/docs/dev/kinopoiskdev/Models/DeathPlace.md b/docs/dev/kinopoiskdev/Models/DeathPlace.md new file mode 100644 index 0000000..95a286f --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/DeathPlace.md @@ -0,0 +1,17 @@ +# DeathPlace + +**Описание:** Класс для представления места смерти персоны +Специализированный класс для хранения информации о месте смерти персоны. +Наследуется от PersonPlace и предоставляет типизированный интерфейс +для работы с данными о месте смерти в контексте API Kinopoisk.dev. +Класс не добавляет дополнительной функциональности, полностью наследуя +поведение от родительского класса PersonPlace. + +**С версии:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\PersonPlace`: Родительский класс для работы с местами персон +* `\KinopoiskDev\Models\BirthPlace`: Класс для места рождения персоны +* `\KinopoiskDev\Models\Person`: Основной класс модели персоны + diff --git a/docs/dev/kinopoiskdev/Models/Episode.md b/docs/dev/kinopoiskdev/Models/Episode.md new file mode 100644 index 0000000..ac5662f --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Episode.md @@ -0,0 +1,90 @@ +# Episode + +**Описание:** Класс для представления эпизода сериала (версия API 1.4) +Представляет информацию об отдельном эпизоде сериала согласно схеме Episode, +включая номер, название, описание, дату выхода и кадр из эпизода. +Используется в составе сезонов для детальной информации о структуре сериалов. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Season`: Для информации о сезонах +* `\KinopoiskDev\Models\ShortImage`: Для кадров из эпизодов + +## `__construct()` + +**Описание:** Конструктор модели эпизода +Создает новый экземпляр класса Episode с указанными параметрами. +Большинство параметров являются опциональными и могут быть null при отсутствии +соответствующей информации в источнике данных. + +**Параметры:** + +* `$number` (int|null): Номер эпизода +* `$name` (string|null): Название эпизода на русском языке +* `$enName` (string|null): Название эпизода на английском языке +* `$date` (string|null): Дата выхода эпизода (deprecated) +* `$description` (string|null): Описание эпизода на русском языке +* `$still` (ShortImage|null): Кадр из эпизода +* `$airDate` (string|null): Дата выхода эпизода +* `$enDescription` (string|null): Описание эпизода на английском языке + +## `fromArray()` + +**Описание:** Создает объект Episode из массива данных API +Фабричный метод для создания экземпляра класса Episode из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения и преобразует вложенные объекты в соответствующие классы. + +**Параметры:** + +* `$data` (array): Массив данных об эпизоде от API + +**Возвращает:** `\KinopoiskDev\Models\Episode` Новый экземпляр класса Episode с данными из массива + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса Episode в массив, +совместимый с форматом API Kinopoisk.dev. + +**Возвращает:** `array` Массив с данными об эпизоде + +## `getName()` + +**Описание:** Возвращает наилучшее доступное название эпизода + +**Возвращает:** `string|null` Название эпизода или null если не задано + +## `getBestDescription()` + +**Описание:** Возвращает наилучшее доступное описание эпизода + +**Возвращает:** `string|null` Описание эпизода или null если не задано + +## `getActualAirDate()` + +**Описание:** Возвращает актуальную дату выхода эпизода +Приоритет отдается airDate над deprecated полем date + +**Возвращает:** `string|null` Дата выхода эпизода + +## `hasStill()` + +**Описание:** Проверяет наличие кадра из эпизода + +**Возвращает:** `bool true` если кадр доступен, иначе false + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/ExternalId.md b/docs/dev/kinopoiskdev/Models/ExternalId.md new file mode 100644 index 0000000..db386ac --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/ExternalId.md @@ -0,0 +1,187 @@ +# ExternalId + +**Описание:** Класс для представления внешних идентификаторов фильмов +Содержит идентификаторы фильма в различных внешних системах, таких как +Kinopoisk HD, IMDB и The Movie Database (TMDB). Предоставляет методы для +работы с идентификаторами, включая получение URL-адресов и проверку +существования идентификаторов. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\LinkedMovie`: Для связанных фильмов с внешними идентификаторами +* `\KinopoiskDev\Models\Movie`: Для использования внешних идентификаторов в фильмах + +## `__construct()` + +**Описание:** Конструктор для создания объекта внешних идентификаторов +Создает новый экземпляр класса ExternalId с указанными идентификаторами +из внешних систем. Все параметры являются опциональными и могут быть null +при отсутствии соответствующего идентификатора. + +**Параметры:** + +* `$kpHD` (string|null): Идентификатор фильма в системе Kinopoisk HD (null если не указан) +* `$imdb` (string|null): Идентификатор фильма в системе IMDB (null если не указан) +* `$tmdb` (int|null): Идентификатор фильма в системе TMDB (null если не указан) + +**См. также:** + +* `ExternalId::fromArray`: () Для создания объекта из массива данных API +* `ExternalId::toArray`: () Для преобразования объекта в массив + +## `__toString()` + +**Описание:** Возвращает строковое представление внешних идентификаторов +Магический метод для преобразования объекта в строку. Формирует читаемое +представление всех доступных внешних идентификаторов, разделенных запятыми. +Если идентификаторы отсутствуют, возвращает сообщение об их отсутствии. +"KP HD: {id}, IMDB: {id}, TMDB: {id}" или "No external IDs" + +**Возвращает:** `string` Строковое представление внешних идентификаторов в формате + +**См. также:** + +* `ExternalId::getAvailableIds`: () Для получения доступных идентификаторов +* `ExternalId::hasAnyId`: () Для проверки наличия идентификаторов + +## `fromArray()` + +**Описание:** Создает объект ExternalId из массива данных API +Фабричный метод для создания экземпляра класса ExternalId из массива +данных, полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения, устанавливая их в null. Преобразует строковое значение TMDB в целое число. +- kpHD: string|null - идентификатор Kinopoisk HD +- imdb: string|null - идентификатор IMDB +- tmdb: string|int|null - идентификатор TMDB + +**Возвращает:** `static` Новый экземпляр класса ExternalId с данными из массива + +**См. также:** + +* `ExternalId::toArray`: () Для обратного преобразования в массив + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса ExternalId в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных в JSON. +- kpHD: string|null - идентификатор Kinopoisk HD +- imdb: string|null - идентификатор IMDB +- tmdb: int|null - идентификатор TMDB + +**Возвращает:** `array` Массив с данными о внешних идентификаторах, содержащий ключи: + +**См. также:** + +* `ExternalId::fromArray`: () Для создания объекта из массива + +## `getImdbUrl()` + +**Описание:** Генерирует URL-адрес страницы фильма в системе IMDB +Формирует полный URL-адрес страницы фильма в системе IMDB на основе +сохраненного идентификатора. Возвращает null, если идентификатор IMDB +не установлен. + +**Возвращает:** `string|null` URL-адрес страницы фильма в IMDB или null, если идентификатор не установлен + +**См. также:** + +* `ExternalId::getImdbId`: () Для получения идентификатора IMDB +* `ExternalId::hasImdbId`: () Для проверки существования идентификатора + +## `getTmdbUrl()` + +**Описание:** Генерирует URL-адрес страницы фильма в системе TMDB +Формирует полный URL-адрес страницы фильма в системе The Movie Database (TMDB) +на основе сохраненного идентификатора. Возвращает null, если идентификатор TMDB +не установлен. + +**Возвращает:** `string|null` URL-адрес страницы фильма в TMDB или null, если идентификатор не установлен + +**См. также:** + +* `ExternalId::getTmdbId`: () Для получения идентификатора TMDB +* `ExternalId::hasTmdbId`: () Для проверки существования идентификатора + +## `hasAnyId()` + +**Описание:** Проверяет наличие хотя бы одного внешнего идентификатора +Определяет, установлен ли хотя бы один из внешних идентификаторов +(Kinopoisk HD, IMDB или TMDB). Возвращает true, если найден хотя бы один +не null идентификатор. + +**Возвращает:** `bool true,` если установлен хотя бы один идентификатор, false в противном случае + +**См. также:** + +* `ExternalId::hasImdbId`: () Для проверки конкретного идентификатора IMDB +* `ExternalId::hasTmdbId`: () Для проверки конкретного идентификатора TMDB +* `ExternalId::hasKinopoiskHdId`: () Для проверки конкретного идентификатора Kinopoisk HD + +## `hasImdbId()` + +**Описание:** Проверяет наличие идентификатора IMDB +Определяет, установлен ли идентификатор фильма в системе IMDB. +Возвращает true, если идентификатор не равен null. + +**Возвращает:** `bool true,` если идентификатор IMDB установлен, false в противном случае + +**См. также:** + +* `ExternalId::getImdbId`: () Для получения идентификатора IMDB +* `ExternalId::hasAnyId`: () Для проверки любого идентификатора + +## `hasTmdbId()` + +**Описание:** Проверяет наличие идентификатора TMDB +Определяет, установлен ли идентификатор фильма в системе The Movie Database (TMDB). +Возвращает true, если идентификатор не равен null. + +**Возвращает:** `bool true,` если идентификатор TMDB установлен, false в противном случае + +**См. также:** + +* `ExternalId::getTmdbId`: () Для получения идентификатора TMDB +* `ExternalId::hasAnyId`: () Для проверки любого идентификатора + +## `hasKinopoiskHdId()` + +**Описание:** Проверяет наличие идентификатора Kinopoisk HD +Определяет, установлен ли идентификатор фильма в системе Kinopoisk HD. +Возвращает true, если идентификатор не равен null. + +**Возвращает:** `bool true,` если идентификатор Kinopoisk HD установлен, false в противном случае + +**См. также:** + +* `ExternalId::getKinopoiskHdId`: () Для получения идентификатора Kinopoisk HD +* `ExternalId::hasAnyId`: () Для проверки любого идентификатора + +## `getAvailableIds()` + +**Описание:** Возвращает все доступные идентификаторы в виде ассоциативного массива +Собирает все установленные (не null) внешние идентификаторы в ассоциативный массив, +где ключами являются названия систем, а значениями - соответствующие идентификаторы. +Отсутствующие идентификаторы не включаются в результат. +- ключ 'kpHD' содержит идентификатор Kinopoisk HD (если установлен) +- ключ 'imdb' содержит идентификатор IMDB (если установлен) +- ключ 'tmdb' содержит идентификатор TMDB (если установлен) + +**Возвращает:** `array` Ассоциативный массив с доступными идентификаторами, где: + +**См. также:** + +* `ExternalId::hasAnyId`: () Для проверки наличия идентификаторов +* `ExternalId::toArray`: () Для получения всех идентификаторов включая null + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/FactInMovie.md b/docs/dev/kinopoiskdev/Models/FactInMovie.md new file mode 100644 index 0000000..f1f0fde --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/FactInMovie.md @@ -0,0 +1,93 @@ +# FactInMovie + +**Описание:** Модель фактов из фильма +Представляет интересный факт о фильме, сериале или другом произведении. +Может содержать как обычную информацию, так и спойлеры, а также +имеет определенный тип (например, "блупер", "ошибка" и т.д.). + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Movie`: Основная модель фильма +* `\KinopoiskDev\Models\SearchMovie`: Поисковая модель фильма + +## `__construct()` + +**Описание:** Конструктор для создания объекта факта о фильме +Создает новый экземпляр FactInMovie с указанным содержимым факта +и дополнительными метаданными о типе и наличии спойлеров. + +**Параметры:** + +* `$value` (string): Текст факта - основное содержимое информации о фильме +* `$type` (string|null): Тип факта (например, "блупер", "ошибка", "интересный факт") +* `$spoiler` (bool|null): Содержит ли факт спойлеры (true - да, false - нет, null - неизвестно) + +**Пример:** +```php +$fact = new FactInMovie( +value: 'Во время съёмок актёр травмировал руку', +type: 'блупер', +spoiler: false +); +``` + +## `fromArray()` + +**Описание:** Создает объект факта о фильме из массива данных API +Фабричный метод для создания экземпляра класса FactInMovie из массива данных, +полученных от API Kinopoisk.dev. Метод безопасно обрабатывает отсутствующие +значения полей type и spoiler, устанавливая их в null при отсутствии в исходных данных. +Используется для десериализации данных фактов о фильмах, полученных от API. +- value: string - обязательное поле с текстом факта +- type: string|null - опциональный тип факта (по умолчанию null) +- spoiler: bool|null - опциональный флаг спойлера (по умолчанию null) + +**Возвращает:** `static` Новый экземпляр FactInMovie с данными из массива + +**Исключения:** + +* `\TypeError`: Если поле 'value' отсутствует в массиве или имеет неправильный тип + +**Пример:** +```php +$data = [ +'value' => 'Актёр получил травму во время съёмок', +'type' => 'блупер', +'spoiler' => false +]; +$fact = FactInMovie::fromArray($data); +``` + +**См. также:** + +* `FactInMovie::toArray`: () Для обратного преобразования объекта в массив +* `FactInMovie::__construct`: () Конструктор класса с описанием параметров + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса FactInMovie в ассоциативный массив, +содержащий все основные свойства объекта. Используется для сериализации +данных при отправке запросов к API или для экспорта данных в JSON. +Возвращает массив с тремя основными полями: значение факта, тип и статус спойлера. +- value: string - текстовое содержимое факта +- type: string|null - тип факта (null если не определен) +- spoiler: bool|null - признак спойлера (null если не определен) + +**Возвращает:** `array` Ассоциативный массив с данными факта о фильме, содержащий ключи: + +**См. также:** + +* `FactInMovie::fromArray`: () Для создания объекта из массива данных +* `FactInMovie::__construct`: () Для инициализации объекта с данными + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/FactInPerson.md b/docs/dev/kinopoiskdev/Models/FactInPerson.md new file mode 100644 index 0000000..dbe927b --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/FactInPerson.md @@ -0,0 +1,81 @@ +# FactInPerson + +**Описание:** Модель фактов о персоне +Представляет интересный факт о персоне кино (актёре, режиссёре, продюсере и т.д.). +Содержит текстовую информацию о биографии, карьере или других аспектах жизни +деятеля кинематографа. Используется для хранения и отображения дополнительной +информации о персонах из базы данных Kinopoisk.dev. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Person`: Основная модель персоны +* `\KinopoiskDev\Models\FactInMovie`: Модель фактов о фильмах + +## `__construct()` + +**Описание:** Конструктор для создания объекта факта о персоне +Создает новый экземпляр FactInPerson с указанным текстовым содержимым. +Конструктор принимает только основную информацию о факте, +в отличие от фактов о фильмах, не содержит дополнительных метаданных +о типе или наличии спойлеров. + +**Параметры:** + +* `$value` (string): Текст факта - основное содержимое информации о персоне кино + +**Пример:** +```php +$fact = new FactInPerson( +value: 'Актёр изучал театральное искусство в консерватории' +); +``` + +## `fromArray()` + +**Описание:** Создает объект FactInPerson из массива данных API +Фабричный метод для создания экземпляра класса FactInPerson из массива +данных о факте персоны, полученных от API Kinopoisk.dev. +Извлекает значение факта из переданного массива и безопасно обрабатывает +его отсутствие или некорректный формат. +- value: string - текстовое содержимое факта о персоне + +**Параметры:** + +* `$data` (array): Массив данных о факте персоны от API, содержащий ключи: + +**Возвращает:** `static` Новый экземпляр класса FactInPerson с данными из массива + +**Исключения:** + +* `\TypeError`: При отсутствии обязательного поля 'value' в массиве данных + +**См. также:** + +* `FactInPerson::toArray`: () Для обратного преобразования в массив +* `FactInPerson::__construct`: () Конструктор класса + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса FactInPerson в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных в JSON. +Структура возвращаемого массива соответствует формату входных данных. +- value: string - текстовое содержимое факта о персоне + +**Возвращает:** `array` Массив с данными о факте персоны, содержащий ключи: + +**См. также:** + +* `FactInPerson::fromArray`: () Для создания объекта из массива + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/Fees.md b/docs/dev/kinopoiskdev/Models/Fees.md new file mode 100644 index 0000000..4be3a62 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Fees.md @@ -0,0 +1,83 @@ +# Fees + +**Описание:** Класс для представления кассовых сборов фильма по регионам +Представляет информацию о кассовых сборах фильма в различных регионах мира, +включая мировые сборы, сборы в России и США. Каждый регион содержит +денежное значение с валютой, представленное объектом CurrencyValue. +Используется для хранения и обработки финансовой информации о фильмах +из API Kinopoisk.dev. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Budget`: Для информации о бюджете фильма +* `\KinopoiskDev\Models\CurrencyValue`: Для структуры денежных значений + +## `__construct()` + +**Описание:** Конструктор для создания объекта кассовых сборов +Создает новый экземпляр класса Fees с информацией о кассовых сборах +фильма по различным регионам. Все параметры являются опциональными +и могут быть null при отсутствии данных о сборах в конкретном регионе. + +**Параметры:** + +* `$world` (CurrencyValue|null): Мировые кассовые сборы фильма (null если не указаны) +* `$russia` (CurrencyValue|null): Кассовые сборы фильма в России (null если не указаны) +* `$usa` (CurrencyValue|null): Кассовые сборы фильма в США (null если не указаны) + +**См. также:** + +* `Fees::fromArray`: () Для создания объекта из массива данных API +* `Fees::toArray`: () Для преобразования объекта в массив + +## `fromArray()` + +**Описание:** Создает объект Fees из массива данных API +Фабричный метод для создания экземпляра класса Fees из массива +данных о кассовых сборах, полученных от API Kinopoisk.dev. +Безопасно обрабатывает отсутствующие значения, устанавливая их в null. +Автоматически преобразует вложенные массивы в объекты CurrencyValue +для каждого региона. +- world: array|null - данные о мировых сборах +- russia: array|null - данные о сборах в России +- usa: array|null - данные о сборах в США + +**Параметры:** + +* `$data` (array): Массив данных о кассовых сборах от API, содержащий ключи: + +**Возвращает:** `\KinopoiskDev\Models\Fees` Новый экземпляр класса Fees с данными из массива + +**См. также:** + +* `Fees::toArray`: () Для обратного преобразования в массив +* `CurrencyValue::fromArray`: () Для создания объектов денежных значений + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса Fees в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных в JSON. +Автоматически преобразует объекты CurrencyValue в массивы для каждого региона. +- world: array|null - мировые сборы в формате массива +- russia: array|null - сборы в России в формате массива +- usa: array|null - сборы в США в формате массива + +**Возвращает:** `array` Массив с данными о кассовых сборах, содержащий ключи: + +**См. также:** + +* `Fees::fromArray`: () Для создания объекта из массива +* `CurrencyValue::toArray`: () Для преобразования денежных значений в массивы + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/Image.md b/docs/dev/kinopoiskdev/Models/Image.md new file mode 100644 index 0000000..bf7b27c --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Image.md @@ -0,0 +1,140 @@ +# Image + +**Описание:** Класс для представления изображений фильмов +Представляет изображение фильма, включая постеры, фоны, логотипы и другие +визуальные элементы. Содержит URL-адреса изображений в полном размере +и их уменьшенные версии для предварительного просмотра, а также +информацию о размерах и разрешении. Предоставляет методы для анализа +соотношения сторон и категории качества изображения. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\ShortImage`: Для упрощенной модели изображений +* `\KinopoiskDev\Models\Logo`: Для логотипов + +## `__construct()` + +**Описание:** Конструктор модели изображения + +**Параметры:** + +* `$url` (string|null): URL полноразмерного изображения (null если недоступно) +* `$previewUrl` (string|null): URL превью изображения (null если недоступно) +* `$height` (int|null): Высота изображения в пикселях (null если неизвестна) +* `$width` (int|null): Ширина изображения в пикселях (null если неизвестна) + +## `__toString()` + +**Описание:** Строковое представление изображения +Магический метод для получения строкового представления объекта. +Возвращает описательную информацию об изображении, включая размеры +и категорию разрешения. Если изображение недоступно, возвращает +соответствующее сообщение. +или изображение недоступно + +**Возвращает:** `string` Строковое описание изображения в формате "WIDTHxHEIGHT - CATEGORY" + +## `exists()` + +**Описание:** Проверяет, доступно ли изображение +Определяет, доступно ли изображение, проверяя наличие хотя бы одного +из URL-адресов (полноразмерного или превью). + +**Возвращает:** `bool true` если изображение доступно, false в противном случае + +## `getFormattedDimensions()` + +**Описание:** Возвращает размеры изображения в виде строки +Если размеры неизвестны, возвращает null. + +**Возвращает:** `string|null` Строка размеров в формате "1920x1080" или null если размеры неизвестны + +## `getResolutionCategory()` + +**Описание:** Возвращает категорию разрешения изображения +Определяет категорию разрешения на основе размеров изображения. +Если размеры неизвестны, возвращает null. + +**Возвращает:** `string|null` Категория разрешения ('4K', 'Full HD', 'HD', 'SD', 'Low') или null если размеры неизвестны + +## `fromArray()` + +**Описание:** Создает объект Image из массива данных API +Фабричный метод для создания экземпляра класса Image из массива +данных, полученных от API Kinopoisk.dev. Безопасно обрабатывает +отсутствующие значения, устанавливая их в null. +Автоматически преобразует строковые значения размеров в целые числа. +- url: string|null - URL полноразмерного изображения +- previewUrl: string|null - URL превью изображения +- height: int|string|null - высота изображения +- width: int|string|null - ширина изображения + +**Возвращает:** `\KinopoiskDev\Models\Image` Новый экземпляр класса Image с данными из массива + +## `toArray()` + +**Описание:** Преобразует объект в массив +Конвертирует текущий экземпляр класса Image в массив, +совместимый с форматом API Kinopoisk.dev. Используется для +сериализации данных при отправке запросов к API или экспорте в JSON. +- url: string|null - URL полноразмерного изображения +- previewUrl: string|null - URL превью изображения +- height: int|null - высота изображения +- width: int|null - ширина изображения + +**Возвращает:** `array` Массив с данными изображения, содержащий ключи: + +## `getBestUrl()` + +**Описание:** Возвращает лучший доступный URL изображения +Приоритет: полноразмерное изображение > превью + +**Возвращает:** `string|null URL` наилучшего доступного изображения или null если изображения недоступны + +## `getDimensions()` + +**Описание:** Возвращает размеры изображения в виде массива +Если размеры неизвестны, возвращает null. + +**Возвращает:** `array|null` Массив размеров с ключами 'width' и 'height' или null если размеры неизвестны + +## `isPortrait()` + +**Описание:** Проверяет, является ли изображение портретным +Определяет ориентацию изображения на основе соотношения сторон. +Портретным считается изображение с соотношением сторон меньше 1. + +**Возвращает:** `bool|null true` если изображение портретное, false если альбомное или квадратное, null если размеры неизвестны + +## `getAspectRatio()` + +**Описание:** Возвращает соотношение сторон изображения + +**Возвращает:** `float|null` Соотношение сторон (ширина/высота) или null если размеры неизвестны или высота равна 0 + +## `isLandscape()` + +**Описание:** Проверяет, является ли изображение альбомным +Определяет ориентацию изображения на основе соотношения сторон. +Альбомным считается изображение с соотношением сторон больше 1. + +**Возвращает:** `bool|null true` если изображение альбомное, false если портретное или квадратное, null если размеры неизвестны + +## `isSquare()` + +**Описание:** Проверяет, является ли изображение квадратным +Определяет, является ли изображение квадратным, сравнивая соотношение сторон +с 1 с допуском 0.01 для учета погрешностей вычислений. + +**Возвращает:** `bool|null true` если изображение квадратное, false в противном случае, null если размеры неизвестны + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/ItemName.md b/docs/dev/kinopoiskdev/Models/ItemName.md new file mode 100644 index 0000000..73c50ab --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/ItemName.md @@ -0,0 +1,74 @@ +# ItemName + +**Описание:** Класс для представления названия элемента +Простая модель для хранения названий различных элементов системы +Kinopoisk.dev. Используется для представления наименований фильмов, +персон, жанров и других сущностей, когда требуется только строковое +значение названия без дополнительных атрибутов. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**API Endpoint:** `/v1/movie/possible-values-by-field` + +**См. также:** + +* `\KinopoiskDev\Models\Name`: Для представления названий с языком и типом +* `\KinopoiskDev\Models\Movie`: Для основной модели фильма + +## `__construct()` + +**Описание:** Конструктор для создания объекта названия элемента +Создает новый экземпляр класса ItemName с указанным названием. +Используется для инициализации простых строковых названий без +дополнительных метаданных о языке или типе. + +**Параметры:** + +* `$name` (string): Строковое представление названия элемента + +**См. также:** + +* `ItemName::fromArray`: () Для создания объекта из массива данных API +* `ItemName::toArray`: () Для преобразования объекта в массив + +## `fromArray()` + +**Описание:** Создает объект ItemName из массива данных API +Фабричный метод для создания экземпляра класса ItemName из массива +данных, полученных от API Kinopoisk.dev. Извлекает значение названия +из ключа 'name' входного массива и создает новый объект. +- name: string - название элемента + +**Параметры:** + +* `$data` (array): Массив данных от API, содержащий ключ: + +**Возвращает:** `\KinopoiskDev\Models\ItemName` Новый экземпляр класса ItemName с данными из массива + +**См. также:** + +* `ItemName::toArray`: () Для обратного преобразования в массив + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса ItemName в массив, +совместимый с форматом API Kinopoisk.dev. Используется для +сериализации данных при отправке запросов к API или для +экспорта данных в JSON формат. +- name: string - название элемента + +**Возвращает:** `array` Массив с данными о названии элемента, содержащий ключи: + +**См. также:** + +* `ItemName::fromArray`: () Для создания объекта из массива + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/Keyword.md b/docs/dev/kinopoiskdev/Models/Keyword.md new file mode 100644 index 0000000..1ea12bd --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Keyword.md @@ -0,0 +1,88 @@ +# Keyword + +**Описание:** Модель ключевого слова +Эта модель представляет ключевое слово (тематическую метку) из API Kinopoisk.dev, +которое используется для категоризации и поиска фильмов по содержанию и тематике. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +## `__construct()` + +**Описание:** Конструктор модели ключевого слова + +**Параметры:** + +* `$id` (int): Уникальный идентификатор +* `$title` (string|null): Название ключевого слова +* `$movies` (MovieFromKeyword[]): Связанные фильмы +* `$updatedAt` (string): Дата последнего обновления +* `$createdAt` (string): Дата создания + +## `fromArray()` + +**Описание:** Создает экземпляр модели из массива данных + +**Возвращает:** `static` Экземпляр модели ключевого слова + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + +## `isPopular()` + +**Описание:** Проверяет, является ли ключевое слово популярным + +**Параметры:** + +* `$threshold` (int): Минимальное количество фильмов для считания популярным (по умолчанию 10) + +**Возвращает:** `bool True,` если ключевое слово популярное + +## `getMoviesCount()` + +**Описание:** Возвращает количество связанных фильмов + +**Возвращает:** `int` Количество фильмов, использующих это ключевое слово + +## `isRelatedToMovie()` + +**Описание:** Проверяет, связано ли ключевое слово с указанным фильмом + +**Параметры:** + +* `$movieId` (int): ID фильма для проверки + +**Возвращает:** `bool True,` если ключевое слово связано с фильмом + +## `getMovieIds()` + +**Описание:** Получает список ID всех связанных фильмов + +**Возвращает:** `int[]` Массив ID фильмов + +## `getSummary()` + +**Описание:** Возвращает краткую информацию о ключевом слове + +**Возвращает:** `string` Краткое описание ключевого слова + +## `isRecentlyCreated()` + +**Описание:** Проверяет, недавно ли было создано ключевое слово + +**Параметры:** + +* `$days` (int): Количество дней для считания "недавним" (по умолчанию 30) + +**Возвращает:** `bool True,` если ключевое слово создано недавно + +## `toArray()` + +**Описание:** Преобразует модель в массив + +**Возвращает:** `array` Массив данных модели + diff --git a/docs/dev/kinopoiskdev/Models/LinkedMovie.md b/docs/dev/kinopoiskdev/Models/LinkedMovie.md new file mode 100644 index 0000000..15a6286 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/LinkedMovie.md @@ -0,0 +1,97 @@ +# LinkedMovie + +**Описание:** Класс для представления связанного фильма +Представляет упрощенную информацию о фильме, используемую в связанных +записях и ассоциациях. Содержит основные данные о фильме: идентификатор, +названия, тип, постер, рейтинг и год выпуска. Используется для отображения +связанных фильмов (похожие фильмы, сиквелы, приквелы и т.д.) без +необходимости загрузки полной информации. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Movie`: Для полной информации о фильме +* `\KinopoiskDev\Enums\MovieType`: Для типов фильмов +* `\KinopoiskDev\Models\ShortImage`: Для изображений +* `\KinopoiskDev\Models\Rating`: Для рейтингов + +## `__construct()` + +**Описание:** Конструктор для создания экземпляра связанного фильма +Создает новый объект LinkedMovie с указанными параметрами. +Все параметры, кроме идентификатора, являются опциональными и могут +быть null при отсутствии соответствующих данных. Используется для +инициализации объекта с данными о связанном фильме. + +**Параметры:** + +* `$id` (int): Уникальный идентификатор фильма в базе данных +* `$name` (string|null): Русское название фильма (null если не указано) +* `$enName` (string|null): Английское название фильма (null если не указано) +* `$alternativeName` (string|null): Альтернативное название фильма (null если не указано) +* `$type` (MovieType|null): Тип фильма (фильм, сериал, мультфильм и т.д.) или null +* `$poster` (ShortImage|null): Постер фильма или null если отсутствует +* `$rating` (Rating|null): Рейтинги фильма или null если отсутствуют +* `$year` (int|null): Год выпуска фильма или null если не указан + +## `fromArray()` + +**Описание:** Создает объект LinkedMovie из массива данных API +Статический фабричный метод для создания экземпляра класса LinkedMovie +из массива данных, полученных от API Kinopoisk.dev. Безопасно обрабатывает +отсутствующие значения, устанавливая их в null. Автоматически конвертирует +вложенные объекты (тип, постер, рейтинг) в соответствующие классы. +- id: int - уникальный идентификатор +- name: string|null - русское название +- enName: string|null - английское название +- alternativeName: string|null - альтернативное название +- type: string|null - тип фильма +- poster: array|null - данные о постере +- rating: array|null - данные о рейтинге +- year: int|null - год выпуска + +**Параметры:** + +* `$data` (array): Массив данных о связанном фильме от API, содержащий ключи: + +**Возвращает:** `static` Новый экземпляр класса LinkedMovie с данными из массива + +**См. также:** + +* `ShortImage::fromArray`: () Для создания объекта постера +* `Rating::fromArray`: () Для создания объекта рейтинга +* `MovieType::tryFrom`: () Для создания enum типа фильма + +## `toArray()` + +**Описание:** Преобразует объект LinkedMovie в массив данных +Конвертирует текущий экземпляр класса LinkedMovie в массив, +совместимый с форматом API Kinopoisk.dev. Автоматически обрабатывает +вложенные объекты, преобразуя их в соответствующие массивы. +Используется для сериализации данных при отправке запросов к API +или для экспорта данных в JSON. +- id: int - уникальный идентификатор +- name: string|null - русское название +- enName: string|null - английское название +- alternativeName: string|null - альтернативное название +- type: string|null - значение типа фильма +- poster: array|null - данные о постере +- rating: array|null - данные о рейтинге +- year: int|null - год выпуска + +**Возвращает:** `array` Массив с данными о связанном фильме, содержащий ключи: + +**См. также:** + +* `ShortImage::toArray`: () Для преобразования постера в массив +* `Rating::toArray`: () Для преобразования рейтинга в массив + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/Lists.md b/docs/dev/kinopoiskdev/Models/Lists.md new file mode 100644 index 0000000..93bcbed --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Lists.md @@ -0,0 +1,68 @@ +# Lists + +**Описание:** Модель коллекции фильмов +Эта модель представляет коллекцию или список фильмов из API Kinopoisk.dev, +такие как топ-250, жанровые подборки, тематические списки и другие коллекции. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +## `__construct()` + +**Описание:** Конструктор модели коллекции + +**Параметры:** + +* `$category` (string|null): Категория коллекции +* `$slug` (string|null): Уникальный идентификатор коллекции +* `$moviesCount` (int|null): Количество фильмов в коллекции +* `$cover` (ShortImage|null): Обложка коллекции +* `$name` (string): Название коллекции +* `$updatedAt` (string|null): Дата последнего обновления +* `$createdAt` (string|null): Дата создания + +## `fromArray()` + +**Описание:** Создает экземпляр модели из массива данных + +**Возвращает:** `static` Экземпляр модели коллекции + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + +## `getUrl()` + +**Описание:** Получает URL коллекции на сайте + +**Возвращает:** `string|null URL` коллекции или null, если slug отсутствует + +## `isPopular()` + +**Описание:** Проверяет, является ли коллекция популярной (содержит много фильмов) + +**Параметры:** + +* `$threshold` (int): Минимальное количество фильмов для считания коллекции популярной (по умолчанию 100) + +**Возвращает:** `bool True,` если коллекция популярная + +## `getSummary()` + +**Описание:** Возвращает краткую информацию о коллекции + +**Возвращает:** `string` Краткая информация о коллекции + +## `toArray()` + +**Описание:** Преобразует модель в массив + +**Параметры:** + +* `$includeNulls` (bool): Включать ли null значения + +**Возвращает:** `array` Массив данных модели + diff --git a/docs/dev/kinopoiskdev/Models/Logo.md b/docs/dev/kinopoiskdev/Models/Logo.md new file mode 100644 index 0000000..5dad07e --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Logo.md @@ -0,0 +1,90 @@ +# Logo + +**Описание:** Класс для представления логотипа фильма или сериала +Представляет информацию о логотипе произведения, включая URL изображения. +Используется для хранения и обработки данных логотипов фильмов и сериалов, +полученных от API Kinopoisk.dev. Поддерживает сериализацию в массив +и десериализацию из массива данных API. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Movie`: Для основной модели фильма +* `\KinopoiskDev\Models\SearchMovie`: Для поисковой модели фильма + +## `__construct()` + +**Описание:** Конструктор для создания объекта логотипа +Создает новый экземпляр класса Logo с указанным URL изображения. +Параметр является опциональным и может быть null при отсутствии +логотипа для данного произведения. + +**Параметры:** + +* `$url` (string|null): URL изображения логотипа (null если логотип отсутствует) + +**Пример:** +```php +$logo = new Logo('https://example.com/logo.png'); +$emptyLogo = new Logo(); // без логотипа +``` + +**См. также:** + +* `Logo::fromArray`: () Для создания объекта из массива данных API +* `Logo::toArray`: () Для преобразования объекта в массив + +## `fromArray()` + +**Описание:** Создает объект Logo из массива данных API +Фабричный метод для создания экземпляра класса Logo из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения, устанавливая их в null. +- url: string|null - URL изображения логотипа + +**Параметры:** + +* `$data` (array): Массив данных о логотипе от API, содержащий ключи: + +**Возвращает:** `Logo` Новый экземпляр класса Logo с данными из массива + +**Пример:** +```php +$logoData = ['url' => 'https://example.com/logo.png']; +$logo = Logo::fromArray($logoData); +``` + +**См. также:** + +* `Logo::toArray`: () Для обратного преобразования в массив + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса Logo в массив, +совместимый с форматом API Kinopoisk.dev. Используется для +сериализации данных при отправке запросов к API или для +экспорта данных в JSON формат. +- url: string|null - URL изображения логотипа + +**Возвращает:** `array` Массив с данными о логотипе, содержащий ключи: + +**Пример:** +```php +$logo = new Logo('https://example.com/logo.png'); +$array = $logo->toArray(); // ['url' => 'https://example.com/logo.png'] +``` + +**См. также:** + +* `Logo::fromArray`: () Для создания объекта из массива + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/MeiliPersonEntity.md b/docs/dev/kinopoiskdev/Models/MeiliPersonEntity.md new file mode 100644 index 0000000..6628db6 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/MeiliPersonEntity.md @@ -0,0 +1,388 @@ +# MeiliPersonEntity + +**Описание:** Сущность персоны для индексации в поисковой системе MeiliSearch +Этот класс представляет структуру данных персоны для индексации в поисковой системе MeiliSearch. +Содержит основную информацию о персоне, включая биографические данные, профессиональную информацию +и места рождения/смерти. Все свойства являются для обеспечения неизменности данных. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Enums\PersonSex`: Enum для определения пола персоны +* `\KinopoiskDev\Models\Person`: Основная модель персоны + +## `__construct()` + +**Описание:** Создает новый экземпляр сущности персоны для MeiliSearch +Конструктор инициализирует все свойства персоны значениями по умолчанию. +Все параметры являются именованными для удобства использования и поддержки +автоматической генерации объектов из массивов данных API. + +**С версии:** 1.0.0 + +**Параметры:** + +* `$id` (int): Уникальный идентификатор персоны в базе данных +* `$name` (string|null): Имя персоны на русском языке (может быть null для неизвестных персон) +* `$enName` (string|null): Имя персоны на английском языке (может быть null если отсутствует перевод) +* `$photo` (string|null): URL фотографии персоны (может быть null если фото недоступно) +* `$sex` (PersonSex|null): Пол персоны из enum PersonSex (может быть null если не определен) +* `$growth` (int|null): Рост персоны в сантиметрах (может быть null если неизвестен) +* `$birthday` (string|null): Дата рождения в формате ISO 8601 (может быть null если неизвестна) +* `$death` (string|null): Дата смерти в формате ISO 8601 (может быть null если персона жива или дата неизвестна) +* `$age` (int|null): Возраст персоны в годах (может быть null если невозможно вычислить) +* `$birthPlace` (\KinopoiskDev\Models\BirthPlace[]): Массив мест рождения персоны (пустой массив по умолчанию) +* `$deathPlace` (\KinopoiskDev\Models\DeathPlace[]): Массив мест смерти персоны (пустой массив по умолчанию) +* `$profession` (PersonProfession[]|null): Массив профессий персоны (может быть null если профессии неизвестны) + +## `fromArray()` + +**Описание:** Создает объект MeiliPersonEntity из массива данных API +Фабричный метод для создания экземпляра класса MeiliPersonEntity из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения, устанавливая их в null или пустые массивы. + +**Возвращает:** `static` Новый экземпляр класса MeiliPersonEntity + +**См. также:** + +* `MeiliPersonEntity::toArray`: () Для обратного преобразования в массив + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + +## `getBestName()` + +**Описание:** Возвращает наиболее подходящее имя персоны +Определяет и возвращает наиболее подходящее имя персоны, отдавая +предпочтение русскому имени, если оно доступно. Если русское имя +отсутствует, возвращает английское имя. + +**Возвращает:** `string|null` Наиболее подходящее имя персоны или null, если имя не задано + +## `getPhotoUrl()` + +**Описание:** Возвращает URL фотографии персоны +Предоставляет прямой доступ к URL-адресу фотографии персоны. +Может использоваться для отображения изображения персоны в интерфейсе. + +**Возвращает:** `string|null` URL-адрес фотографии или null, если фотография отсутствует + +## `getRoleCategory()` + +**Описание:** Возвращает категории ролей персоны +Определяет все категории профессий персоны на основе проверки различных типов профессий. +Использует современный подход с array_filter для оптимизации производительности +и избежания повторяющихся if-конструкций. Метод создает карту соответствия между +значениями enum профессий и результатами методов проверки, затем фильтрует только +те профессии, которые присутствуют у данной персоны. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**Возвращает:** `array` Массив строковых значений (value) enum PersonProfession для активных профессий персоны + +**См. также:** + +* `PersonProfession`: Enum с возможными категориями профессий +* `self::isActor`: () Проверка, является ли персона актером +* `self::isDirector`: () Проверка, является ли персона режиссером +* `self::isWriter`: () Проверка, является ли персона сценаристом +* `self::isProducer`: () Проверка, является ли персона продюсером +* `self::isComposer`: () Проверка, является ли персона композитором +* `self::isOperator`: () Проверка, является ли персона оператором +* `self::isDesigner`: () Проверка, является ли персона художником +* `self::isEditor`: () Проверка, является ли персона монтажером +* `self::isVoiceActor`: () Проверка, является ли персона актером дубляжа +* `self::isOtherProfession`: () Проверка других профессий персоны + +## `isActor()` + +**Описание:** Проверяет, является ли персона актером +Определяет, является ли данная персона актером на основе значений в массиве профессий. +Метод выполняет строгую проверку (с использованием оператора ===) наличия строкового +значения enum PersonProfession::ACTOR в массиве profession. Возвращает true, если +среди профессий персоны найдена профессия актера. + +**Возвращает:** `bool true,` если персона является актером, false в противном случае + +**См. также:** + +* `PersonProfession::ACTOR`: Enum значение профессии актера +* `self::isDirector`: () Проверка, является ли персона режиссером +* `self::isWriter`: () Проверка, является ли персона сценаристом +* `self::isProducer`: () Проверка, является ли персона продюсером +* `self::isComposer`: () Проверка, является ли персона композитором +* `self::isOperator`: () Проверка, является ли персона оператором +* `self::isDesigner`: () Проверка, является ли персона художником +* `self::isEditor`: () Проверка, является ли персона монтажером +* `self::isVoiceActor`: () Проверка, является ли персона актером дубляжа +* `self::isOtherProfession`: () Проверка других профессий персоны + +## `isDirector()` + +**Описание:** Проверяет, является ли персона режиссером +Метод проверяет наличие профессии "режиссер" в массиве профессий персоны. +Использует строгое сравнение для точного соответствия значения enum +PersonProfession::DIRECTOR среди всех профессий персоны. + +**Возвращает:** `bool true,` если персона является режиссером, false в противном случае + +**См. также:** + +* `PersonProfession::DIRECTOR`: Константа для профессии режиссера +* `self::isActor`: () Проверка, является ли персона актером +* `self::isWriter`: () Проверка, является ли персона сценаристом +* `self::isProducer`: () Проверка, является ли персона продюсером +* `self::isComposer`: () Проверка, является ли персона композитором +* `self::isOperator`: () Проверка, является ли персона оператором +* `self::isDesigner`: () Проверка, является ли персона художником +* `self::isEditor`: () Проверка, является ли персона монтажером +* `self::isVoiceActor`: () Проверка, является ли персона актером дубляжа +* `self::isOtherProfession`: () Проверка других профессий персоны + +## `isWriter()` + +**Описание:** Проверяет, является ли персона сценаристом +Метод проверяет наличие профессии "сценарист" в массиве профессий персоны. +Использует строгое сравнение для точного соответствия значения enum +PersonProfession::WRITER среди всех профессий персоны. + +**Возвращает:** `bool true,` если персона является сценаристом, false в противном случае + +**См. также:** + +* `PersonProfession::WRITER`: Константа для профессии сценариста +* `self::isActor`: () Проверка, является ли персона актером +* `self::isDirector`: () Проверка, является ли персона режиссером +* `self::isProducer`: () Проверка, является ли персона продюсером +* `self::isComposer`: () Проверка, является ли персона композитором +* `self::isOperator`: () Проверка, является ли персона оператором +* `self::isDesigner`: () Проверка, является ли персона художником +* `self::isEditor`: () Проверка, является ли персона монтажером +* `self::isVoiceActor`: () Проверка, является ли персона актером дубляжа +* `self::isOtherProfession`: () Проверка других профессий персоны + +## `isProducer()` + +**Описание:** Проверяет, является ли персона продюсером +Метод проверяет наличие профессии "продюсер" в массиве профессий персоны. +Использует строгое сравнение для точного соответствия значения enum +PersonProfession::PRODUCER среди всех профессий персоны. + +**Возвращает:** `bool true,` если персона является продюсером, false в противном случае + +**См. также:** + +* `PersonProfession::PRODUCER`: Константа для профессии продюсера +* `self::isActor`: () Проверка, является ли персона актером +* `self::isDirector`: () Проверка, является ли персона режиссером +* `self::isWriter`: () Проверка, является ли персона сценаристом +* `self::isComposer`: () Проверка, является ли персона композитором +* `self::isOperator`: () Проверка, является ли персона оператором +* `self::isDesigner`: () Проверка, является ли персона художником +* `self::isEditor`: () Проверка, является ли персона монтажером +* `self::isVoiceActor`: () Проверка, является ли персона актером дубляжа +* `self::isOtherProfession`: () Проверка других профессий персоны + +## `isComposer()` + +**Описание:** Проверяет, является ли персона композитором +Метод проверяет наличие профессии "композитор" в массиве профессий персоны. +Использует строгое сравнение для точного соответствия значения enum +PersonProfession::COMPOSER среди всех профессий персоны. + +**Возвращает:** `bool true,` если персона является композитором, false в противном случае + +**См. также:** + +* `PersonProfession::COMPOSER`: Константа для профессии композитора +* `self::isActor`: () Проверка, является ли персона актером +* `self::isDirector`: () Проверка, является ли персона режиссером +* `self::isWriter`: () Проверка, является ли персона сценаристом +* `self::isProducer`: () Проверка, является ли персона продюсером +* `self::isOperator`: () Проверка, является ли персона оператором +* `self::isDesigner`: () Проверка, является ли персона художником +* `self::isEditor`: () Проверка, является ли персона монтажером +* `self::isVoiceActor`: () Проверка, является ли персона актером дубляжа +* `self::isOtherProfession`: () Проверка других профессий персоны + +## `isOperator()` + +**Описание:** Проверяет, является ли персона оператором +Метод проверяет наличие профессии "оператор" в массиве профессий персоны. +Использует строгое сравнение для точного соответствия значения enum +PersonProfession::OPERATOR среди всех профессий персоны. + +**Возвращает:** `bool true,` если персона является оператором, false в противном случае + +**См. также:** + +* `PersonProfession::OPERATOR`: Константа для профессии оператора +* `self::isActor`: () Проверка, является ли персона актером +* `self::isDirector`: () Проверка, является ли персона режиссером +* `self::isWriter`: () Проверка, является ли персона сценаристом +* `self::isProducer`: () Проверка, является ли персона продюсером +* `self::isComposer`: () Проверка, является ли персона композитором +* `self::isDesigner`: () Проверка, является ли персона художником +* `self::isEditor`: () Проверка, является ли персона монтажером +* `self::isVoiceActor`: () Проверка, является ли персона актером дубляжа +* `self::isOtherProfession`: () Проверка других профессий персоны + +## `isDesigner()` + +**Описание:** Проверяет, является ли персона художником (постановщиком) +Метод проверяет наличие профессии "художник" в массиве профессий персоны. +Использует строгое сравнение для точного соответствия значения enum +PersonProfession::DESIGN среди всех профессий персоны. + +**Возвращает:** `bool true,` если персона является художником, false в противном случае + +**См. также:** + +* `PersonProfession::DESIGN`: Константа для профессии художника +* `self::isActor`: () Проверка, является ли персона актером +* `self::isDirector`: () Проверка, является ли персона режиссером +* `self::isWriter`: () Проверка, является ли персона сценаристом +* `self::isProducer`: () Проверка, является ли персона продюсером +* `self::isComposer`: () Проверка, является ли персона композитором +* `self::isOperator`: () Проверка, является ли персона оператором +* `self::isEditor`: () Проверка, является ли персона монтажером +* `self::isVoiceActor`: () Проверка, является ли персона актером дубляжа +* `self::isOtherProfession`: () Проверка других профессий персоны + +## `isEditor()` + +**Описание:** Проверяет, является ли персона монтажёром +Метод проверяет наличие профессии "монтажер" в массиве профессий персоны. +Использует строгое сравнение для точного соответствия значения enum +PersonProfession::EDITOR среди всех профессий персоны. + +**Возвращает:** `bool true,` если персона является монтажёром, false в противном случае + +**См. также:** + +* `PersonProfession::EDITOR`: Константа для профессии монтажёра +* `self::isActor`: () Проверка, является ли персона актером +* `self::isDirector`: () Проверка, является ли персона режиссером +* `self::isWriter`: () Проверка, является ли персона сценаристом +* `self::isProducer`: () Проверка, является ли персона продюсером +* `self::isComposer`: () Проверка, является ли персона композитором +* `self::isOperator`: () Проверка, является ли персона оператором +* `self::isDesigner`: () Проверка, является ли персона художником +* `self::isVoiceActor`: () Проверка, является ли персона актером дубляжа +* `self::isOtherProfession`: () Проверка других профессий персоны + +## `isVoiceActor()` + +**Описание:** Проверяет, является ли персона актёром дубляжа +Метод проверяет наличие профессии "актер дубляжа" в массиве профессий персоны. +Использует строгое сравнение для точного соответствия значения enum +PersonProfession::VOICE_ACTOR среди всех профессий персоны. + +**Возвращает:** `bool true,` если персона является актером дубляжа, false в противном случае + +**См. также:** + +* `PersonProfession::VOICE_ACTOR`: Константа для актёра дубляжа +* `self::isActor`: () Проверка, является ли персона актером +* `self::isDirector`: () Проверка, является ли персона режиссером +* `self::isWriter`: () Проверка, является ли персона сценаристом +* `self::isProducer`: () Проверка, является ли персона продюсером +* `self::isComposer`: () Проверка, является ли персона композитором +* `self::isOperator`: () Проверка, является ли персона оператором +* `self::isDesigner`: () Проверка, является ли персона художником +* `self::isEditor`: () Проверка, является ли персона монтажером +* `self::isOtherProfession`: () Проверка других профессий персоны + +## `isOtherProfession()` + +**Описание:** Проверяет, является ли персона иной профессии +Метод проверяет наличие профессии "другой" в массиве профессий персоны. +Использует строгое сравнение для точного соответствия значения enum +PersonProfession::DIRECTOR среди всех профессий персоны. + +**Возвращает:** `bool true,` если персона является другой профессии, false в противном случае + +**См. также:** + +* `PersonProfession::DIRECTOR`: Константа для других профессий персоны +* `self::isActor`: () Проверка, является ли персона актером +* `self::isDirector`: () Проверка, является ли персона режиссером +* `self::isWriter`: () Проверка, является ли персона сценаристом +* `self::isProducer`: () Проверка, является ли персона продюсером +* `self::isComposer`: () Проверка, является ли персона композитором +* `self::isOperator`: () Проверка, является ли персона оператором +* `self::isDesigner`: () Проверка, является ли персона художником +* `self::isEditor`: () Проверка, является ли персона монтажером +* `self::isVoiceActor`: () Проверка, является ли персона актером дубляжа + +## `toArray()` + +**Описание:** Преобразует объект сущности персоны в массив данных +Конвертирует все свойства сущности персоны в ассоциативный массив +для сериализации, передачи в API или сохранения в хранилище данных. +Метод выполняет безопасное преобразование nullable enum значений +в их строковые представления через использование null-safe оператора. +Возвращаемый массив содержит как базовые свойства персоны (id, имена, +фото), так и дополнительные данные (профессии на русском и английском +языках, полученные через соответствующие методы). +- id: int - уникальный идентификатор персоны +- photo: string|null - URL фотографии персоны +- name: string|null - русское имя персоны +- enName: string|null - английское имя персоны +- profession: array|null - массив объектов профессий персоны +- professionRu: array - массив профессий на русском языке +- professionEn: array - массив профессий на английском языке +- sex: string|null - пол персоны (значение enum или null) +- growth: int|null - рост персоны в сантиметрах +- birthday: string|null - дата рождения в формате строки +- death: string|null - дата смерти в формате строки +- age: int|null - возраст персоны в годах +- birthPlace: array - массив мест рождения +- deathPlace: array - массив мест смерти + +**С версии:** 1.0.0 + +**Возвращает:** `array` Ассоциативный массив с данными персоны, содержащий ключи: + +**См. также:** + +* `getBestName`: () Для получения наиболее подходящего имени персоны +* `getProfessionRu`: () Для получения массива профессий на русском языке +* `getProfessionEn`: () Для получения массива профессий на английском языке +* `\KinopoiskDev\Enums\PersonSex`: Enum для значений пола персоны +* `\KinopoiskDev\Enums\PersonProfession`: Enum для значений профессий персоны + +## `getProfessionRu()` + +**Описание:** Возвращает профессию персоны на русском языке +Предоставляет доступ к названию профессии персоны на русском языке. +Может использоваться для отображения профессии в русскоязычном интерфейсе. + +**Возвращает:** `array` Название профессии на русском языке или null, если не задано + +**См. также:** + +* `Person::getProfessionEn`: () Для получения профессии на английском языке + +## `getProfessionEn()` + +**Описание:** Возвращает профессию персоны на английском языке +Предоставляет доступ к профессии персоны в виде enum значения. +Может использоваться для программной обработки типа профессии. + +**Возвращает:** `array Enum` значение профессии или null, если не задано + +**См. также:** + +* `Person::getProfessionRu`: () Для получения профессии на русском языке +* `PersonProfession`: Для списка возможных профессий + diff --git a/docs/dev/kinopoiskdev/Models/Movie.md b/docs/dev/kinopoiskdev/Models/Movie.md new file mode 100644 index 0000000..32ad348 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Movie.md @@ -0,0 +1,220 @@ +# Movie + +**Описание:** Класс для представления фильма/сериала из API Kinopoisk.dev +Представляет полную информацию о фильме или сериале, включая базовые данные, +рейтинги, участников, изображения, связанные произведения и другую метаинформацию. +Используется для работы с детальной информацией о произведениях кинематографа. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\SearchMovie`: Для поисковых результатов фильмов +* `\KinopoiskDev\Models\LinkedMovie`: Для связанных фильмов +* `\KinopoiskDev\Models\ExternalId`: Для внешних идентификаторов + +## `__construct()` + +**Описание:** Конструктор для создания объекта фильма/сериала +Создает новый экземпляр класса Movie с указанными параметрами. +Все параметры являются опциональными и могут быть null при отсутствии данных. + +**Параметры:** + +* `$id` (int|null): Уникальный идентификатор фильма +* `$externalId` (ExternalId|null): Внешние идентификаторы (IMDB, TMDB и т.д.) +* `$name` (string|null): Название фильма на русском языке +* `$alternativeName` (string|null): Альтернативное название +* `$enName` (string|null): Название фильма на английском языке +* `$names` (array|null): Массив названий на разных языках +* `$type` (MovieType|null): Тип фильма (фильм, сериал, мини-сериал) +* `$typeNumber` (int|null): Номер типа +* `$year` (int|null): Год выпуска +* `$description` (string|null): Полное описание фильма +* `$shortDescription` (string|null): Краткое описание +* `$slogan` (string|null): Слоган фильма +* `$status` (MovieStatus|null): Статус фильма +* `$facts` (array|null): Массив фактов о фильме +* `$movieLength` (int|null): Длительность фильма в минутах +* `$ratingMpaa` (RatingMpaa|null): Рейтинг MPAA +* `$ageRating` (int|null): Возрастной рейтинг +* `$rating` (Rating|null): Рейтинги фильма +* `$votes` (Votes|null): Голоса за фильм +* `$logo` (Logo|null): Логотип фильма +* `$poster` (ShortImage|null): Постер фильма +* `$backdrop` (ShortImage|null): Фоновое изображение +* `$videos` (VideoTypes|null): Видео материалы +* `$genres` (array): Массив жанров +* `$countries` (array): Массив стран производства +* `$persons` (array): Массив участников съемочной группы +* `$reviewInfo` (ReviewInfo|null): Информация о рецензиях +* `$budget` (CurrencyValue|null): Бюджет фильма +* `$fees` (Fees|null): Кассовые сборы +* `$premiere` (Premiere|null): Информация о премьере +* `$watchability` (Watchability|null): Где посмотреть фильм +* `$releaseYears` (array|null): Годы выпуска +* `$top10` (int|null): Позиция в топ-10 +* `$top250` (int|null): Позиция в топ-250 +* `$isSeries` (bool): Является ли сериалом +* `$ticketsOnSale` (bool|null): Продаются ли билеты +* `$totalSeriesLength` (int|null): Общая длительность сериала +* `$seriesLength` (int|null): Длительность серии +* `$audience` (array|null): Аудитория фильма +* `$lists` (array): Списки фильмов +* `$networks` (Networks|null): Сети вещания +* `$createdAt` (string|null): Дата создания записи +* `$updatedAt` (string|null): Дата обновления записи + +**См. также:** + +* `Movie::fromArray`: () Для создания объекта из массива данных API + +## `fromArray()` + +**Описание:** Создает объект Movie из массива данных API +Фабричный метод для создания экземпляра класса Movie из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения, устанавливая их в null или пустые массивы. + +**Возвращает:** `static` Новый экземпляр класса Movie + +**См. также:** + +* `Movie::toArray`: () Для обратного преобразования в массив + +## `validate()` + +**Описание:** Валидирует данные модели +Проверяет корректность основных полей объекта Movie. +Проверяет наличие обязательного идентификатора и валидность опциональных полей. + +**Возвращает:** `bool True` если данные валидны + +## `getKinopoiskRating()` + +**Описание:** Возвращает рейтинг фильма на Кинопоиске +Извлекает рейтинг фильма из системы Кинопоиск. Возвращает null, +если рейтинг не установлен или объект рейтинга отсутствует. + +**Возвращает:** `float|null` Рейтинг на Кинопоиске (от 0.0 до 10.0) или null, если не установлен + +**См. также:** + +* `Movie::getImdbRating`: () Для получения рейтинга IMDB +* `Rating::getKp`: () Для альтернативного способа получения рейтинга + +## `getImdbRating()` + +**Описание:** Возвращает рейтинг фильма на IMDB +Извлекает рейтинг фильма из системы IMDB. Возвращает null, +если рейтинг не установлен или объект рейтинга отсутствует. + +**Возвращает:** `float|null` Рейтинг на IMDB (от 0.0 до 10.0) или null, если не установлен + +**См. также:** + +* `Movie::getKinopoiskRating`: () Для получения рейтинга Кинопоиска +* `Rating::getImdb`: () Для альтернативного способа получения рейтинга + +## `getPosterUrl()` + +**Описание:** Возвращает URL постера фильма +Извлекает URL-адрес постера фильма из объекта изображения. +Возвращает null, если постер не установлен или URL отсутствует. + +**Возвращает:** `string|null` URL-адрес постера или null, если не установлен + +**См. также:** + +* `Image::getUrl`: () Для получения URL из объекта изображения +* `Movie::getBackdropUrl`: () Для получения URL фонового изображения + +## `getGenreNames()` + +**Описание:** Возвращает массив названий жанров фильма +Извлекает названия жанров из массива объектов жанров и возвращает их +в виде простого массива строк. Если поле 'name' отсутствует у жанра, +возвращается пустая строка. + +**Возвращает:** `array` Массив строк с названиями жанров + +**См. также:** + +* `Movie::getCountryNames`: () Для получения названий стран +* `Movie::getGenres`: () Для получения полной информации о жанрах + +## `getCountryNames()` + +**Описание:** Возвращает массив названий стран производства +Извлекает названия стран из массива объектов стран и возвращает их +в виде простого массива строк. Если поле 'name' отсутствует у страны, +возвращается пустая строка. + +**Возвращает:** `array` Массив строк с названиями стран производства + +**См. также:** + +* `Movie::getGenreNames`: () Для получения названий жанров +* `Movie::getCountries`: () Для получения полной информации о странах + +## `getImdbUrl()` + +**Описание:** Возвращает URL страницы фильма в системе IMDB +Формирует URL-адрес страницы фильма в системе IMDB на основе +внешних идентификаторов. Возвращает null, если внешние идентификаторы +отсутствуют или идентификатор IMDB не установлен. + +**Возвращает:** `string|null` URL-адрес страницы фильма в IMDB или null, если не доступен + +**См. также:** + +* `ExternalId::getImdbUrl`: () Для получения URL из внешних идентификаторов +* `Movie::getTmdbUrl`: () Для получения URL TMDB + +## `getTmdbUrl()` + +**Описание:** Возвращает URL страницы фильма в системе TMDB +Формирует URL-адрес страницы фильма в системе The Movie Database (TMDB) +на основе внешних идентификаторов. Возвращает null, если внешние +идентификаторы отсутствуют или идентификатор TMDB не установлен. + +**Возвращает:** `string|null` URL-адрес страницы фильма в TMDB или null, если не доступен + +**См. также:** + +* `ExternalId::getTmdbUrl`: () Для получения URL из внешних идентификаторов +* `Movie::getImdbUrl`: () Для получения URL IMDB + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса Movie в массив, +совместимый с форматом API Kinopoisk.dev. Используется для +сериализации данных при отправке запросов к API. + +**Возвращает:** `array` Массив с данными фильма + +**См. также:** + +* `Movie::fromArray`: () Для создания объекта из массива + +## `getName()` + +**Описание:** Возвращает наиболее подходящее название фильма. +Метод последовательно проверяет наличие русского названия (`name`), +альтернативного названия (`alternativeName`) и английского названия (`enName`). +Возвращается первое найденное не-null значение. Если все названия отсутствуют, +возвращается пустая строка. + +**С версии:** 1.0.0 + +**Возвращает:** `string` Название фильма или пустая строка, если ни одно из названий не доступно. + +**См. также:** + +* `Movie::`: $name +* `Movie::`: $alternativeName +* `Movie::`: $enName + diff --git a/docs/dev/kinopoiskdev/Models/MovieAward.md b/docs/dev/kinopoiskdev/Models/MovieAward.md new file mode 100644 index 0000000..f2f858f --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/MovieAward.md @@ -0,0 +1,100 @@ +# MovieAward + +**Описание:** Класс для представления награды фильма +Представляет информацию о награде, полученной фильмом или сериалом, +включая номинацию, статус победы и временные метки. +Используется для отображения наградной истории произведения. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Nomination`: Для информации о номинации +* `\KinopoiskDev\Models\Movie`: Для основной модели фильма + +## `__construct()` + +**Описание:** Конструктор для создания объекта награды фильма +Создает новый экземпляр класса MovieAward с указанными параметрами. +Большинство параметров являются опциональными и могут быть null при отсутствии +соответствующей информации в источнике данных. + +**Параметры:** + +* `$nomination` (Nomination|null): Информация о номинации +* `$winning` (bool|null): Статус победы (true - победа, false - номинация) +* `$updatedAt` (string|null): Дата последнего обновления записи +* `$createdAt` (string|null): Дата создания записи +* `$movieId` (int|null): ID фильма (может отсутствовать в некоторых контекстах) + +## `__toString()` + +**Описание:** Возвращает строковое представление награды +Формирует читаемое представление награды, включающее информацию +о номинации и статусе победы. + +**Возвращает:** `string` Строковое представление награды + +## `hasInfo()` + +**Описание:** Проверяет, установлена ли информация о награде + +**Возвращает:** `bool true` если есть информация о номинации или статусе победы, иначе false + +## `getWinningStatus()` + +**Описание:** Возвращает статус награды в текстовом виде + +**Возвращает:** `string` Статус награды ("Победа", "Номинация", "Неизвестно") + +## `fromArray()` + +**Описание:** Создает объект MovieAward из массива данных API +Фабричный метод для создания экземпляра класса MovieAward из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения и преобразует вложенные объекты в соответствующие классы. +- nomination: array|null - данные о номинации +- winning: bool|null - статус победы +- updatedAt: string|null - дата обновления +- createdAt: string|null - дата создания +- movieId: int|null - ID фильма + +**Параметры:** + +* `$data` (array): Массив данных о награде фильма от API, содержащий ключи: + +**Возвращает:** `\KinopoiskDev\Models\MovieAward` Новый экземпляр класса MovieAward с данными из массива + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса MovieAward в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных. + +**Возвращает:** `array` Массив с данными о награде фильма + +## `isWinning()` + +**Описание:** Проверяет, является ли награда победной + +**Возвращает:** `bool true` если фильм победил в номинации, иначе false + +## `isNominationOnly()` + +**Описание:** Проверяет, является ли запись только номинацией + +**Возвращает:** `bool true` если фильм был только номинирован, иначе false + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/MovieFromKeyword.md b/docs/dev/kinopoiskdev/Models/MovieFromKeyword.md new file mode 100644 index 0000000..501048d --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/MovieFromKeyword.md @@ -0,0 +1,45 @@ +# MovieFromKeyword + +**Описание:** Класс для представления фильма из поисковых ключевых слов + +**С версии:** 1.0.0 + +## `__construct()` + +**Описание:** Конструктор + +**Параметры:** + +* `$id` (int|null): ID фильма +* `$name` (string|null): Название фильма +* `$enName` (string|null): Английское название +* `$alternativeName` (string|null): Альтернативное название +* `$type` (string|null): Тип (фильм, сериал и т.д.) +* `$year` (int|null): Год выпуска + +## `fromArray()` + +**Описание:** Создает объект из массива данных API + +**Параметры:** + +* `$data` (array): Данные от API + +**Возвращает:** `static` Новый экземпляр класса + +## `toArray()` + +**Описание:** Преобразует объект в массив + +**Параметры:** + +* `$includeNulls` (bool): Включать ли null значения + +**Возвращает:** `array` Массив данных + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/MovieFromStudio.md b/docs/dev/kinopoiskdev/Models/MovieFromStudio.md new file mode 100644 index 0000000..141e90a --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/MovieFromStudio.md @@ -0,0 +1,75 @@ +# MovieFromStudio + +**Описание:** Класс для представления фильма из студии +Представляет минимальную информацию о фильме в контексте студии, +содержащую только уникальный идентификатор произведения. +Используется как упрощенная модель для связи между студиями и фильмами. + +**С версии:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Studio`: Для основной модели студии +* `\KinopoiskDev\Models\Movie`: Для полной информации о фильме + +## `__construct()` + +**Описание:** Конструктор для создания объекта фильма из студии +Создает новый экземпляр класса MovieFromStudio с указанным идентификатором. +Представляет минимальную информацию о фильме, связанном со студией. + +**Параметры:** + +* `$id` (int): Уникальный идентификатор фильма в системе Kinopoisk + +**См. также:** + +* `MovieFromStudio::fromArray`: () Для создания объекта из массива данных API +* `MovieFromStudio::toArray`: () Для преобразования объекта в массив + +## `fromArray()` + +**Описание:** Создает объект MovieFromStudio из массива данных API +Фабричный метод для создания экземпляра класса MovieFromStudio из массива +данных, полученных от API Kinopoisk.dev. Извлекает только необходимый +идентификатор фильма для создания упрощенной модели. +- id: int - уникальный идентификатор фильма + +**Параметры:** + +* `$data` (array): Массив данных от API, содержащий ключ: + +**Возвращает:** `static` Новый экземпляр MovieFromStudio с данными из массива + +**См. также:** + +* `MovieFromStudio::toArray`: () Для обратного преобразования в массив +* `\KinopoiskDev\Models\BaseModel::fromArray`: () Для интерфейса BaseModel + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса MovieFromStudio в массив, +совместимый с форматом API Kinopoisk.dev. Возвращает только +идентификатор фильма как минимальный набор данных. +- id: int - уникальный идентификатор фильма + +**Параметры:** + +* `$includeNulls` (bool): Включать ли null значения в результат (по умолчанию true) + +**Возвращает:** `array` Массив с данными о фильме, содержащий ключ: + +**См. также:** + +* `MovieFromStudio::fromArray`: () Для создания объекта из массива +* `\KinopoiskDev\Models\BaseModel::toArray`: () Для интерфейса BaseModel + +## `validate()` + +**Описание:** Валидирует данные модели +Проверяет корректность данных модели согласно бизнес-правилам. +Для MovieFromStudio проверяется только валидность идентификатора. + +**Возвращает:** `bool True` если данные валидны, false в противном случае + diff --git a/docs/dev/kinopoiskdev/Models/MovieInPerson.md b/docs/dev/kinopoiskdev/Models/MovieInPerson.md new file mode 100644 index 0000000..8599559 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/MovieInPerson.md @@ -0,0 +1,127 @@ +# MovieInPerson + +**Описание:** Класс для представления персоны в контексте фильма +Представляет информацию о персоне (актер, режиссер, сценарист и др.) в контексте +конкретного фильма или сериала. Содержит основные данные о персоне, включая +идентификатор, имена, рейтинг, описание роли и профессию. Используется для +хранения и обработки данных об участниках кинопроизводства, полученных от API +Kinopoisk.dev. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\PersonInMovie`: Для обратной связи (персона в фильме) +* `\KinopoiskDev\Models\Person`: Для полной информации о персоне +* `\KinopoiskDev\Models\Movie`: Для использования в информации о фильмах + +## `__construct()` + +**Описание:** Конструктор модели фильма в персоне +Создает новый экземпляр класса MovieInPerson с указанными параметрами. +Только идентификатор является обязательным параметром, остальные могут +быть null при отсутствии соответствующей информации о персоне или её роли +в конкретном фильме. + +**Параметры:** + +* `$id` (int): Уникальный идентификатор персоны в системе Kinopoisk +* `$name` (string|null): Имя персоны на русском языке (null если не указано) +* `$alternativeName` (string|null): Альтернативное имя персоны (null если не указано) +* `$rating` (float|null): Рейтинг персоны в контексте данного фильма (null если не указан) +* `$general` (bool|null): Является ли персона главным участником фильма (null если не определено) +* `$description` (string|null): Описание роли персоны в фильме (null если не указано) +* `$enProfession` (string|null): Профессия персоны на английском языке (null если не указана) + +**Пример:** +```php +$moviePerson = new MovieInPerson( +id: 123456, +name: 'Иван Петров', +alternativeName: 'Ivan Petrov', +rating: 8.5, +general: true, +description: 'Главная роль', +enProfession: 'actor' +); +``` + +**См. также:** + +* `MovieInPerson::fromArray`: () Для создания объекта из массива данных API +* `MovieInPerson::toArray`: () Для преобразования объекта в массив + +## `fromArray()` + +**Описание:** Создает объект MovieInPerson из массива данных API +Фабричный метод для создания экземпляра класса MovieInPerson из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие значения, +устанавливая их в null. Идентификатор является обязательным параметром и должен +присутствовать в массиве данных. +- id: int - уникальный идентификатор персоны (обязательный) +- name: string|null - имя персоны на русском языке +- alternativeName: string|null - альтернативное имя персоны +- rating: float|null - рейтинг персоны в контексте фильма +- general: bool|null - является ли персона главным участником +- description: string|null - описание роли в фильме +- enProfession: string|null - профессия на английском языке + +**Параметры:** + +* `$data` (array): Массив данных о персоне от API, содержащий ключи: + +**Возвращает:** `BaseModel` Новый экземпляр класса MovieInPerson с данными из массива + +**Пример:** +```php +$personData = [ +'id' => 123456, +'name' => 'Иван Петров', +'alternativeName' => 'Ivan Petrov', +'rating' => 8.5, +'general' => true, +'description' => 'Главная роль', +'enProfession' => 'actor' +]; +$moviePerson = MovieInPerson::fromArray($personData); +``` + +**См. также:** + +* `MovieInPerson::toArray`: () Для обратного преобразования в массив +* `BaseModel::fromArray`: () Реализация интерфейса BaseModel + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса MovieInPerson в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API, экспорта данных в JSON или других +операций преобразования. Все свойства объекта, включая null-значения, +сохраняются в результирующем массиве. +- id: int - уникальный идентификатор персоны +- name: string|null - имя персоны на русском языке +- alternativeName: string|null - альтернативное имя персоны +- rating: float|null - рейтинг персоны в контексте фильма +- general: bool|null - является ли персона главным участником +- description: string|null - описание роли в фильме +- enProfession: string|null - профессия на английском языке + +**Параметры:** + +* `$includeNulls` (bool): * @return array Массив с данными о персоне в фильме, содержащий ключи: + +**Пример:** +```php +$moviePerson = new MovieInPerson(123456, 'Иван Петров', 'Ivan Petrov'); +$array = $moviePerson->toArray(); +// Результат: ['id' => 123456, 'name' => 'Иван Петров', 'alternativeName' => 'Ivan Petrov', ...] +``` + +**См. также:** + +* `MovieInPerson::fromArray`: () Для создания объекта из массива +* `BaseModel::toArray`: () Реализация интерфейса BaseModel + diff --git a/docs/dev/kinopoiskdev/Models/Name.md b/docs/dev/kinopoiskdev/Models/Name.md new file mode 100644 index 0000000..ca77240 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Name.md @@ -0,0 +1,79 @@ +# Name + +**Описание:** Класс для представления названий фильмов +Представляет информацию о названии фильма, включая само название, язык +и тип названия. Используется для хранения различных вариантов названий +фильмов в разных языках и форматах (официальное название, рабочее название, +альтернативное название и т.д.). + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Movie`: Для использования в информации о фильмах +* `\KinopoiskDev\Models\LinkedMovie`: Для связанных фильмов с названиями + +## `__construct()` + +**Описание:** Конструктор модели названия +Создает новый экземпляр класса Name с указанными параметрами названия, +языка и типа. Параметры язык и тип являются опциональными и могут быть null +при отсутствии соответствующих данных. + +**Параметры:** + +* `$name` (string): Название фильма (основное значение) +* `$language` (string|null): Язык названия в формате ISO 639-1 (например, "ru", "en") или null +* `$type` (string|null): Тип названия (например, "официальное", "рабочее", "альтернативное") или null + +**См. также:** + +* `Name::fromArray`: () Для создания объекта из массива данных API +* `Name::toArray`: () Для преобразования объекта в массив + +## `fromArray()` + +**Описание:** Создает объект Name из массива данных API +Статический фабричный метод для создания экземпляра класса Name из массива +данных, полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения для опциональных параметров, устанавливая их в null. Используется +для десериализации данных о названиях фильмов из ответов API. +- name: string - само название фильма (обязательно) +- language: string|null - язык названия (опционально) +- type: string|null - тип названия (опционально) + +**Параметры:** + +* `$data` (array): Массив данных о названии от API, содержащий ключи: + +**Возвращает:** `static` Новый экземпляр класса Name с данными из массива + +**См. также:** + +* `Name::toArray`: () Для обратного преобразования в массив + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса Name в массив, совместимый с форматом +API Kinopoisk.dev. Используется для сериализации данных при отправке +запросов к API или для экспорта данных в JSON. Включает все свойства +объекта, включая null-значения. +- name: string - название фильма +- language: string|null - язык названия +- type: string|null - тип названия + +**Возвращает:** `array` Массив с данными о названии, содержащий ключи: + +**См. также:** + +* `Name::fromArray`: () Для создания объекта из массива + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/NetworkItem.md b/docs/dev/kinopoiskdev/Models/NetworkItem.md new file mode 100644 index 0000000..5bb634a --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/NetworkItem.md @@ -0,0 +1,113 @@ +# NetworkItem + +**Описание:** Класс для представления элемента сети/телеканала +Представляет информацию об элементе сети или телеканала, включая название и логотип. +Используется для хранения данных о телевизионных сетях, стриминговых платформах +и других вещательных каналах, связанных с фильмами и сериалами. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Logo`: Для работы с логотипами +* `\KinopoiskDev\Models\Movie`: Для использования в фильмах + +## `__construct()` + +**Описание:** Конструктор для создания объекта элемента сети +Создает новый экземпляр класса NetworkItem с указанными параметрами +названия и логотипа. Все параметры являются опциональными и могут быть +null при отсутствии соответствующих данных. + +**Параметры:** + +* `$name` (string|null): Название сети или телеканала (null если не указано) +* `$logo` (Logo|null): Логотип сети или null если отсутствует + +**Пример:** +```php +$network = new NetworkItem( +name: 'Netflix', +logo: new Logo('https://example.com/netflix-logo.png') +); +``` + +**См. также:** + +* `NetworkItem::fromArray`: () Для создания объекта из массива данных API +* `NetworkItem::toArray`: () Для преобразования объекта в массив + +## `fromArray()` + +**Описание:** Создает объект NetworkItem из массива данных API +Фабричный метод для создания экземпляра класса NetworkItem из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие значения, +устанавливая их в null. Автоматически создает вложенный объект Logo при наличии +соответствующих данных через класс DataManager. +- name: string|null - название сети или телеканала +- logo: array|null - данные о логотипе с URL изображения +или не имеет метода fromArray() + +**Параметры:** + +* `$data` (array): Массив данных об элементе сети от API, содержащий ключи: + +**Возвращает:** `static` Новый экземпляр класса NetworkItem с данными из массива + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: Если указанный класс Logo не существует + +**Пример:** +```php +// Создание элемента сети с полными данными +$networkData = [ +'name' => 'Netflix', +'logo' => ['url' => 'https://example.com/netflix-logo.png'] +]; +$network = NetworkItem::fromArray($networkData); +// Создание элемента сети с частичными данными +$partialData = ['name' => 'HBO']; +$network = NetworkItem::fromArray($partialData); // logo будет null +// Создание из пустого массива +$emptyNetwork = NetworkItem::fromArray([]); // все поля будут null +``` + +**См. также:** + +* `NetworkItem::toArray`: () Для обратного преобразования в массив +* `Logo::fromArray`: () Для создания объекта логотипа +* `DataManager::parseObjectData`: () Для парсинга вложенных объектов + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса NetworkItem в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных в JSON формат. +Автоматически преобразует вложенный объект Logo в массив. +- name: string|null - название сети +- logo: array|null - данные о логотипе в формате массива + +**Возвращает:** `array` Массив с данными об элементе сети, содержащий ключи: + +**Пример:** +```php +$network = new NetworkItem('Netflix', new Logo('https://example.com/logo.png')); +$array = $network->toArray(); +// ['name' => 'Netflix', 'logo' => ['url' => 'https://example.com/logo.png']] +``` + +**См. также:** + +* `NetworkItem::fromArray`: () Для создания объекта из массива +* `Logo::toArray`: () Для преобразования логотипа в массив + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/Networks.md b/docs/dev/kinopoiskdev/Models/Networks.md new file mode 100644 index 0000000..f7bdb48 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Networks.md @@ -0,0 +1,114 @@ +# Networks + +**Описание:** Класс для работы с коллекцией сетей/телеканалов +Представляет коллекцию сетей и телеканалов, связанных с фильмом или сериалом. +Используется для группировки информации о производителях контента, +таких как Netflix, HBO, BBC и других телевизионных сетях и стриминговых платформах. +Содержит массив элементов NetworkItem с данными о каждой сети. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\NetworkItem`: Для отдельных элементов сети +* `\KinopoiskDev\Models\Movie`: Для основной модели фильма + +## `__construct()` + +**Описание:** Конструктор для создания объекта коллекции сетей +Создает новый экземпляр класса Networks с указанным массивом элементов сетей. +Параметр является опциональным и может быть null при отсутствии данных +о сетях и телеканалах для данного фильма или сериала. + +**Параметры:** + +* `$items` (NetworkItem[]|null): Массив элементов сетей или null если данные отсутствуют + +**Пример:** +```php +// Создание коллекции с несколькими сетями +$networks = new Networks([ +new NetworkItem('Netflix', new Logo('https://example.com/netflix.png')), +new NetworkItem('HBO', new Logo('https://example.com/hbo.png')) +]); +// Создание пустой коллекции +$emptyNetworks = new Networks(); +``` + +**См. также:** + +* `Networks::fromArray`: () Для создания объекта из массива данных API +* `Networks::toArray`: () Для преобразования объекта в массив +* `NetworkItem`: Для структуры отдельного элемента сети + +## `fromArray()` + +**Описание:** Создает объект Networks из массива данных API +Статический фабричный метод для создания экземпляра класса Networks +из массива данных, полученных от API Kinopoisk.dev. Безопасно обрабатывает +отсутствующие значения и автоматически создает массив объектов NetworkItem +из данных API. Используется для десериализации ответов API в объекты модели. +- items: array|null - массив данных об элементах сетей + +**Параметры:** + +* `$data` (array): Массив данных о сетях от API, содержащий ключи: + +**Возвращает:** `static` Новый экземпляр класса Networks с данными из массива + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: + +**Пример:** +```php +// Создание из полных данных API +$apiData = [ +'items' => [ +['name' => 'Netflix', 'logo' => ['url' => 'https://example.com/netflix.png']], +['name' => 'HBO', 'logo' => ['url' => 'https://example.com/hbo.png']] +] +]; +$networks = Networks::fromArray($apiData); +// Создание из пустых данных +$emptyNetworks = Networks::fromArray([]); +``` + +**См. также:** + +* `Networks::toArray`: () Для обратного преобразования в массив +* `NetworkItem::fromArray`: () Для создания отдельных элементов сети + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса Networks в массив, +совместимый с форматом API Kinopoisk.dev. Автоматически преобразует +все вложенные объекты NetworkItem в массивы. Используется для сериализации +данных при отправке запросов к API или для экспорта в JSON формат. +- items: array|null - массив данных об элементах сетей или null + +**Возвращает:** `array` Массив с данными о сетях, содержащий ключи: + +**Пример:** +```php +$networks = new Networks([ +new NetworkItem('Netflix', new Logo('https://example.com/netflix.png')) +]); +$array = $networks->toArray(); +// ['items' => [['name' => 'Netflix', 'logo' => ['url' => 'https://example.com/netflix.png']]]] +``` + +**См. также:** + +* `Networks::fromArray`: () Для создания объекта из массива +* `NetworkItem::toArray`: () Для преобразования элементов сети в массивы + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/Nomination.md b/docs/dev/kinopoiskdev/Models/Nomination.md new file mode 100644 index 0000000..d3652f4 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Nomination.md @@ -0,0 +1,73 @@ +# Nomination + +**Описание:** Класс для представления номинации +Представляет информацию о номинации на награду, включая +детали о самой награде и название номинации. Используется +в составе наград для фильмов и персон. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\NominationAward`: Для информации о награде +* `\KinopoiskDev\Models\MovieAward`: Для наград фильмов +* `\KinopoiskDev\Models\PersonAward`: Для наград персон + +## `__construct()` + +**Описание:** Конструктор для создания объекта номинации +Создает новый экземпляр класса Nomination с указанными параметрами. +Оба параметра являются опциональными и могут быть null при отсутствии +соответствующей информации в источнике данных. + +**Параметры:** + +* `$award` (NominationAward|null): Информация о награде +* `$title` (string|null): Название номинации (например, "Лучший фильм", "Лучший актер") + +## `__toString()` + +**Описание:** Возвращает строковое представление номинации +Формирует читаемое представление номинации, включающее название +номинации и информацию о награде, если они доступны. + +**Возвращает:** `string` Строковое представление номинации + +## `fromArray()` + +**Описание:** Создает объект Nomination из массива данных API +Фабричный метод для создания экземпляра класса Nomination из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения и преобразует вложенные объекты в соответствующие классы. +- award: array|null - данные о награде +- title: string|null - название номинации + +**Параметры:** + +* `$data` (array): Массив данных о номинации от API, содержащий ключи: + +**Возвращает:** `\KinopoiskDev\Models\Nomination` Новый экземпляр класса Nomination с данными из массива + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса Nomination в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных. +- award: array|null - данные о награде +- title: string|null - название номинации + +**Возвращает:** `array` Массив с данными о номинации, содержащий ключи: + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/NominationAward.md b/docs/dev/kinopoiskdev/Models/NominationAward.md new file mode 100644 index 0000000..aacc72f --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/NominationAward.md @@ -0,0 +1,75 @@ +# NominationAward + +**Описание:** Класс для представления награды в номинации +Представляет информацию о конкретной награде в рамках номинации, +включая название награды и год ее вручения. Используется как часть +более крупной структуры номинаций для фильмов и персон. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Nomination`: Для полной информации о номинации +* `\KinopoiskDev\Models\MovieAward`: Для наград фильмов +* `\KinopoiskDev\Models\PersonAward`: Для наград персон + +## `__construct()` + +**Описание:** Конструктор для создания объекта награды номинации +Создает новый экземпляр класса NominationAward с указанными параметрами. +Оба параметра являются опциональными и могут быть null при отсутствии +соответствующей информации в источнике данных. + +**Параметры:** + +* `$title` (string|null): Название награды (например, "Оскар", "Золотой глобус") +* `$year` (int|null): Год вручения награды + +## `__toString()` + +**Описание:** Возвращает строковое представление награды +Формирует читаемое представление награды, включающее название +и год вручения, если они доступны. + +**Возвращает:** `string` Строковое представление награды + +## `fromArray()` + +**Описание:** Создает объект NominationAward из массива данных API +Фабричный метод для создания экземпляра класса NominationAward из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения, устанавливая их в null. +- title: string|null - название награды +- year: int|null - год вручения награды + +**Параметры:** + +* `$data` (array): Массив данных о награде от API, содержащий ключи: + +**Возвращает:** `\KinopoiskDev\Models\NominationAward` Новый экземпляр класса NominationAward с данными из массива + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса NominationAward в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных. +- title: string|null - название награды +- year: int|null - год вручения награды + +**Возвращает:** `array` Массив с данными о награде, содержащий ключи: + +## `hasInfo()` + +**Описание:** Проверяет, установлена ли информация о награде + +**Возвращает:** `bool true` если есть название или год, иначе false + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/Person.md b/docs/dev/kinopoiskdev/Models/Person.md new file mode 100644 index 0000000..320b03e --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Person.md @@ -0,0 +1,115 @@ +# Person + +**Описание:** Класс для представления персоны из API Kinopoisk.dev +Представляет информацию об актере, режиссере, сценаристе или другом участнике +кинопроизводства. Содержит биографические данные, профессиональную информацию, +фильмографию и другие связанные сведения. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\PersonInMovie`: Для информации о персоне в контексте фильма +* `\KinopoiskDev\Enums\PersonProfession`: Для типов профессий персон +* `\KinopoiskDev\Enums\PersonSex`: Для типов пола персон +* `\KinopoiskDev\Models\MeiliPersonEntity`: Родительский класс + +## `__construct()` + +**Описание:** Конструктор для создания объекта персоны +Создает новый экземпляр класса Person с полным набором данных о персоне. +Все свойства класса являются для обеспечения неизменности данных. +Конструктор также вызывает родительский конструктор для инициализации +базовых свойств наследуемых от MeiliPersonEntity. + +**Параметры:** + +* `$id` (int): Уникальный идентификатор персоны в системе Kinopoisk +* `$name` (string|null): Имя персоны на русском языке +* `$enName` (string|null): Имя персоны на английском языке +* `$photo` (string|null): URL фотографии персоны +* `$sex` (PersonSex|null): Пол персоны (enum значение) +* `$growth` (int|null): Рост персоны в сантиметрах +* `$birthday` (string|null): Дата рождения в формате ISO 8601 +* `$death` (string|null): Дата смерти в формате ISO 8601 +* `$age` (int|null): Возраст персоны в годах +* `$birthPlace` (\KinopoiskDev\Models\BirthPlace[]): Массив мест рождения персоны (пустой массив по умолчанию) +* `$deathPlace` (\KinopoiskDev\Models\DeathPlace[]): Массив мест смерти персоны (пустой массив по умолчанию) +* `$profession` (PersonProfession[]|null): Массив профессий персоны (может быть null если профессии неизвестны) +* `$spouses` (\KinopoiskDev\Models\Spouses[]): Массив данных о супругах персоны +* `$countAwards` (int): Количество наград персоны (по умолчанию 0) +* `$facts` (\KinopoiskDev\Models\FactInPerson[]): Массив интересных фактов о персоне +* `$movies` (\KinopoiskDev\Models\MovieInPerson[]): Массив фильмов с участием персоны +* `$updatedAt` (string|null): Дата последнего обновления записи в формате ISO 8601 +* `$createdAt` (string|null): Дата создания записи в формате ISO 8601 + +**См. также:** + +* `Person::fromArray`: () Для создания объекта из массива данных API +* `Person::toArray`: () Для преобразования объекта в массив +* `MeiliPersonEntity::__construct`: () Конструктор родительского класса + +## `fromArray()` + +**Описание:** Создает объект Person из массива данных API +Фабричный метод для создания экземпляра класса Person из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения и преобразует вложенные объекты в соответствующие классы. + +**Параметры:** + +* `$data` (array): Массив данных о персоне от API, содержащий все возможные поля персоны + +**Возвращает:** `\KinopoiskDev\Models\Person` Новый экземпляр класса Person с данными из массива + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: + +**См. также:** + +* `Person::toArray`: () Для обратного преобразования в массив +* `DataManager::parseEnumValue`: () Для преобразования enum значений + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + +**Исключения:** + +* `\KinopoiskDev\Exceptions\ValidationException`: При ошибке валидации + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса Person в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных. + +**Возвращает:** `array` Массив с полными данными о персоне, содержащий все поля объекта + +**См. также:** + +* `Person::fromArray`: () Для создания объекта из массива +* `DataManager::getObjectsArray`: () Для преобразования массива объектов в массив массивов + +## `getName()` + +**Описание:** Возвращает наиболее подходящее имя персоны. +Метод последовательно проверяет наличие русского имени (`name`) и английского имени (`enName`). +Возвращается первое найденное не-null значение. Если оба имени отсутствуют, +возвращается пустая строка. + +**С версии:** 1.0.0 + +**Возвращает:** `string` Имя персоны или пустая строка, если имена не доступны. + +**См. также:** + +* `Person::`: $enName +* `Person::`: $name + diff --git a/docs/dev/kinopoiskdev/Models/PersonAward.md b/docs/dev/kinopoiskdev/Models/PersonAward.md new file mode 100644 index 0000000..69efe40 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/PersonAward.md @@ -0,0 +1,108 @@ +# PersonAward + +**Описание:** Класс для представления награды персоны +Представляет информацию о награде, полученной персоной (актером, режиссером и т.д.), +включая номинацию, статус победы, связанный фильм и временные метки. +Используется для отображения наградной истории персоны. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Nomination`: Для информации о номинации +* `\KinopoiskDev\Models\Movie`: Для связанного фильма +* `\KinopoiskDev\Models\Person`: Для основной модели персоны + +## `__construct()` + +**Описание:** Конструктор для создания объекта награды персоны +Создает новый экземпляр класса PersonAward с указанными параметрами. +Только personId является обязательным, остальные параметры опциональны. + +**Параметры:** + +* `$personId` (int): ID персоны (обязательный параметр) +* `$nomination` (Nomination|null): Информация о номинации +* `$winning` (bool|null): Статус победы (true - победа, false - номинация) +* `$updatedAt` (string|null): Дата последнего обновления записи +* `$createdAt` (string|null): Дата создания записи +* `$movie` (Movie|null): Связанный фильм за который получена награда + +## `__toString()` + +**Описание:** Возвращает строковое представление награды +Формирует читаемое представление награды, включающее информацию +о номинации, статусе победы и связанном фильме. + +**Возвращает:** `string` Строковое представление награды + +## `hasInfo()` + +**Описание:** Проверяет, установлена ли информация о награде + +**Возвращает:** `bool true` если есть информация о номинации или статусе победы, иначе false + +## `getWinningStatus()` + +**Описание:** Возвращает статус награды в текстовом виде + +**Возвращает:** `string` Статус награды ("Победа", "Номинация", "Неизвестно") + +## `getMovieTitle()` + +**Описание:** Возвращает название связанного фильма + +**Возвращает:** `string|null` Название фильма за который получена награда или null + +## `fromArray()` + +**Описание:** Создает объект PersonAward из массива данных API +Фабричный метод для создания экземпляра класса PersonAward из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения и преобразует вложенные объекты в соответствующие классы. +- personId: int - ID персоны (обязательно) +- nomination: array|null - данные о номинации +- winning: bool|null - статус победы +- updatedAt: string|null - дата обновления +- createdAt: string|null - дата создания +- movie: array|null - данные о связанном фильме + +**Параметры:** + +* `$data` (array): Массив данных о награде персоны от API, содержащий ключи: + +**Возвращает:** `\KinopoiskDev\Models\PersonAward` Новый экземпляр класса PersonAward с данными из массива + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса PersonAward в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных. + +**Возвращает:** `array` Массив с данными о награде персоны + +## `isWinning()` + +**Описание:** Проверяет, является ли награда победной + +**Возвращает:** `bool true` если персона победила в номинации, иначе false + +## `isNominationOnly()` + +**Описание:** Проверяет, является ли запись только номинацией + +**Возвращает:** `bool true` если персона была только номинирована, иначе false + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/PersonInMovie.md b/docs/dev/kinopoiskdev/Models/PersonInMovie.md new file mode 100644 index 0000000..308b935 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/PersonInMovie.md @@ -0,0 +1,81 @@ +# PersonInMovie + +**Описание:** Класс для представления персоны в контексте фильма +Представляет информацию о персоне (актере, режиссере и т.д.) в контексте +конкретного фильма или сериала. Содержит основные данные о персоне, +включая идентификатор, имя, фото и профессиональную информацию. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Person`: Для полной информации о персоне +* `\KinopoiskDev\Models\Movie`: Для информации о фильме + +## `__construct()` + +**Описание:** Конструктор для создания объекта персоны в фильме +Создает новый экземпляр класса PersonInMovie с указанными параметрами. +Только идентификатор является обязательным параметром, остальные могут +быть null при отсутствии соответствующей информации. + +**Параметры:** + +* `$id` (int): Уникальный идентификатор персоны +* `$photo` (string|null): URL фотографии персоны +* `$name` (string|null): Имя персоны на русском языке +* `$enName` (string|null): Имя персоны на английском языке +* `$description` (string|null): Описание роли персоны в фильме +* `$profession` (string|null): Профессия персоны на русском языке +* `$enProfession` (string|null): Профессия персоны на английском языке + +**См. также:** + +* `PersonInMovie::fromArray`: () Для создания объекта из массива данных API +* `PersonInMovie::toArray`: () Для преобразования объекта в массив + +## `fromArray()` + +**Описание:** Создает объект PersonInMovie из массива данных API +Фабричный метод для создания экземпляра класса PersonInMovie из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения, устанавливая их в null. +- id: int - уникальный идентификатор персоны +- photo: string|null - URL фотографии персоны +- name: string|null - имя персоны на русском языке +- enName: string|null - имя персоны на английском языке +- description: string|null - описание роли персоны +- profession: string|null - профессия персоны на русском +- enProfession: string|null - профессия персоны на английском + +**Параметры:** + +* `$data` (array): Массив данных о персоне от API, содержащий ключи: + +**Возвращает:** `\KinopoiskDev\Models\PersonInMovie` Новый экземпляр класса PersonInMovie с данными из массива + +**См. также:** + +* `PersonInMovie::toArray`: () Для обратного преобразования в массив + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса PersonInMovie в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных. + +**Возвращает:** `array` Массив с данными о персоне в фильме, содержащий все поля объекта + +**См. также:** + +* `PersonInMovie::fromArray`: () Для создания объекта из массива + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/PersonPlace.md b/docs/dev/kinopoiskdev/Models/PersonPlace.md new file mode 100644 index 0000000..0235c15 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/PersonPlace.md @@ -0,0 +1,82 @@ +# PersonPlace + +**Описание:** Класс для представления географического места, связанного с персоной +Представляет место рождения или смерти персоны в системе Kinopoisk.dev. +Используется для хранения и обработки географической информации о персонах, +включая города, страны или другие места, связанные с жизнью человека. +Класс предоставляет простой интерфейс для работы с текстовыми данными +о местах в контексте биографической информации. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Person`: Для работы с персонами +* `\KinopoiskDev\Models\PersonPlaceValue`: Для более детальной географической информации + +## `__construct()` + +**Описание:** Строковое значение места рождения или смерти персоны +Содержит текстовое описание географического места, связанного с персоной. +Может содержать название города, страны или полный адрес места рождения/смерти. +Значение доступно только для чтения после создания объекта. + +## `__toString()` + +**Описание:** Возвращает строковое представление места персоны +Магический метод для получения строкового представления объекта PersonPlace. +Используется при приведении объекта к строке или при выводе объекта в контексте, +где требуется строковое значение. Возвращает непосредственно значение места +без дополнительного форматирования. + +**Возвращает:** `string` Строковое представление места рождения/смерти персоны + +**См. также:** + +* `PersonPlace::toArray`: () Для получения данных в формате массива +* `PersonPlace::`: $value Для доступа к свойству места напрямую + +## `fromArray()` + +**Описание:** Создает объект PersonPlace из массива данных API +Фабричный метод для создания экземпляра класса PersonPlace из массива данных, +полученных от API Kinopoisk.dev. Безопасно извлекает значение места из массива +и создает новый объект с соответствующими данными. Используется для +десериализации данных API в объекты модели. +- value: string - текстовое значение места рождения/смерти + +**Параметры:** + +* `$data` (array): Массив данных от API, содержащий ключи: + +**Возвращает:** `static` Новый экземпляр класса PersonPlace с данными из массива + +**См. также:** + +* `PersonPlace::toArray`: () Для обратного преобразования в массив +* `PersonPlace::__construct`: () Для создания объекта с параметрами + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса PersonPlace в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API, кэшировании или экспорте данных. +Возвращает массив с единственным ключом 'value'. +- value: string - текстовое значение места рождения/смерти + +**Возвращает:** `array` Массив с данными о месте, содержащий: + +**См. также:** + +* `PersonPlace::fromArray`: () Для создания объекта из массива +* `PersonPlace::__toString`: () Для получения только текстового значения + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/Premiere.md b/docs/dev/kinopoiskdev/Models/Premiere.md new file mode 100644 index 0000000..a7a20e7 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Premiere.md @@ -0,0 +1,65 @@ +# Premiere + +**Описание:** Класс для представления информации о премьерах фильма +Содержит даты премьер фильма или сериала в различных странах и форматах, +включая мировую премьеру, премьеру в России, цифровой релиз, релиз на DVD и Blu-ray. +Используется для отображения информации о датах выхода произведения. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Movie`: Для использования в информации о фильмах + +## `__construct()` + +**Описание:** Конструктор модели премьеры + +**Параметры:** + +* `$country` (string|null): Страна премьеры +* `$world` (string|null): Дата мировой премьеры в формате ISO +* `$russia` (string|null): Дата премьеры в России в формате ISO +* `$digital` (string|null): Дата цифрового релиза в формате ISO +* `$cinema` (string|null): Дата премьеры в кинотеатрах в формате ISO +* `$bluray` (string|null): Дата релиза на Blu-ray в формате ISO +* `$dvd` (string|null): Дата релиза на DVD в формате ISO + +## `fromArray()` + +**Описание:** Создает объект Premiere из массива данных API +- country: string|null - страна премьеры +- world: string|null - дата мировой премьеры +- russia: string|null - дата премьеры в России +- digital: string|null - дата цифрового релиза +- cinema: string|null - дата премьеры в кинотеатрах +- bluray: string|null - дата релиза на Blu-ray +- dvd: string|null - дата релиза на DVD + +**Возвращает:** `\KinopoiskDev\Models\Premiere` Новый экземпляр класса Premiere с данными из массива + +**См. также:** + +* `Premiere::toArray`: () Для обратного преобразования в массив + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса Premiere в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных. + +**Возвращает:** `array` Массив с данными о премьерах, содержащий все поля объекта + +**См. также:** + +* `Premiere::fromArray`: () Для создания объекта из массива + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/Rating.md b/docs/dev/kinopoiskdev/Models/Rating.md new file mode 100644 index 0000000..bf404b3 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Rating.md @@ -0,0 +1,201 @@ +# Rating + +**Описание:** Класс для представления рейтингов фильма из различных источников +Содержит рейтинги фильма/сериала из различных источников, включая +Кинопоиск, IMDB, TMDB, а также оценки кинокритиков и ожидания зрителей. +Используется для отображения и анализа популярности и качества произведения. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Movie::getRating`: () Для получения рейтинга фильма +* `\KinopoiskDev\Models\Votes`: Для информации о количестве голосов + +## `__construct()` + +**Описание:** Конструктор модели рейтинга +Создает новый экземпляр класса Rating с указанными параметрами рейтингов. +Все параметры являются опциональными и могут быть null при отсутствии данных. + +**Параметры:** + +* `$kp` (float|null): Рейтинг на Кинопоиске (0.0-10.0) +* `$imdb` (float|null): Рейтинг на IMDB (0.0-10.0) +* `$tmdb` (float|null): Рейтинг на TMDB (0.0-10.0) +* `$filmCritics` (float|null): Рейтинг кинокритиков (0.0-100.0) +* `$russianFilmCritics` (float|null): Рейтинг российских кинокритиков (0.0-100.0) +* `$await` (float|null): Рейтинг ожидания (0.0-100.0) + +**См. также:** + +* `Rating::fromArray`: () Для создания объекта из массива данных API + +## `__toString()` + +**Описание:** Возвращает строковое представление рейтингов +Реализует магический метод __toString для преобразования объекта +в строку. Формирует строку, содержащую основные рейтинги в удобочитаемом +формате, разделенные запятыми. + +**Возвращает:** `string` Строковое представление рейтингов или 'No ratings', если рейтинги отсутствуют + +## `fromArray()` + +**Описание:** Создает объект Rating из массива данных API +Фабричный метод для создания экземпляра класса Rating из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения, устанавливая их в null. + +**Возвращает:** `static` Новый экземпляр класса Rating + +**См. также:** + +* `Rating::toArray`: () Для обратного преобразования в массив + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса Rating в массив, +совместимый с форматом API Kinopoisk.dev. Используется для +сериализации данных при отправке запросов к API. + +**Возвращает:** `array` Массив с данными рейтингов + +**См. также:** + +* `Rating::fromArray`: () Для создания объекта из массива + +## `getKinopoiskRating()` + +**Описание:** Возвращает рейтинг фильма на Кинопоиске +Предоставляет доступ к рейтингу фильма в системе Кинопоиск. +Рейтинг представлен в виде числа с плавающей точкой в диапазоне от 0.0 до 10.0. + +**Возвращает:** `float|null` Рейтинг на Кинопоиске или null, если рейтинг отсутствует + +**См. также:** + +* `Rating::getImdbRating`: () Для получения рейтинга IMDB +* `Rating::getTmdbRating`: () Для получения рейтинга TMDB + +## `getImdbRating()` + +**Описание:** Возвращает рейтинг фильма на IMDB +Предоставляет доступ к рейтингу фильма в системе Internet Movie Database (IMDB). +Рейтинг представлен в виде числа с плавающей точкой в диапазоне от 0.0 до 10.0. + +**Возвращает:** `float|null` Рейтинг на IMDB или null, если рейтинг отсутствует + +**См. также:** + +* `Rating::getKinopoiskRating`: () Для получения рейтинга Кинопоиска +* `Rating::getTmdbRating`: () Для получения рейтинга TMDB + +## `getTmdbRating()` + +**Описание:** Возвращает рейтинг фильма на TMDB +Предоставляет доступ к рейтингу фильма в системе The Movie Database (TMDB). +Рейтинг представлен в виде числа с плавающей точкой в диапазоне от 0.0 до 10.0. + +**Возвращает:** `float|null` Рейтинг на TMDB или null, если рейтинг отсутствует + +**См. также:** + +* `Rating::getKinopoiskRating`: () Для получения рейтинга Кинопоиска +* `Rating::getImdbRating`: () Для получения рейтинга IMDB + +## `getFilmCriticsRating()` + +**Описание:** Возвращает рейтинг фильма от кинокритиков +Предоставляет доступ к рейтингу фильма от международных кинокритиков. +Рейтинг представлен в виде числа с плавающей точкой в диапазоне от 0.0 до 100.0. + +**Возвращает:** `float|null` Рейтинг кинокритиков или null, если рейтинг отсутствует + +**См. также:** + +* `Rating::getRussianFilmCriticsRating`: () Для получения рейтинга российских кинокритиков + +## `getRussianFilmCriticsRating()` + +**Описание:** Возвращает рейтинг фильма от российских кинокритиков +Предоставляет доступ к рейтингу фильма от российских кинокритиков. +Рейтинг представлен в виде числа с плавающей точкой в диапазоне от 0.0 до 100.0. + +**Возвращает:** `float|null` Рейтинг российских кинокритиков или null, если рейтинг отсутствует + +**См. также:** + +* `Rating::getFilmCriticsRating`: () Для получения рейтинга международных кинокритиков + +## `getAwaitRating()` + +**Описание:** Возвращает рейтинг ожидания фильма +Предоставляет доступ к рейтингу ожидания фильма, который отражает +интерес аудитории к еще не вышедшему фильму. +Рейтинг представлен в виде числа с плавающей точкой в диапазоне от 0.0 до 100.0. + +**Возвращает:** `float|null` Рейтинг ожидания или null, если рейтинг отсутствует + +## `getHighestRating()` + +**Описание:** Возвращает наивысший доступный рейтинг +Анализирует все доступные рейтинги и возвращает наивысший из них. +Учитывает только основные рейтинги (Кинопоиск, IMDB, TMDB, кинокритики), +игнорируя рейтинги ожидания и российских кинокритиков. + +**Возвращает:** `float|null` Наивысший рейтинг или null, если все рейтинги отсутствуют + +**См. также:** + +* `Rating::getAverageRating`: () Для получения среднего рейтинга + +## `getAverageRating()` + +**Описание:** Возвращает средний рейтинг из всех доступных +Вычисляет среднее арифметическое всех доступных рейтингов. +Учитывает только основные рейтинги (Кинопоиск, IMDB, TMDB, кинокритики), +игнорируя рейтинги ожидания и российских кинокритиков. + +**Возвращает:** `float|null` Средний рейтинг или null, если все рейтинги отсутствуют + +**См. также:** + +* `Rating::getHighestRating`: () Для получения наивысшего рейтинга + +## `hasAnyRating()` + +**Описание:** Проверяет наличие хотя бы одного рейтинга +Определяет, существует ли хотя бы один рейтинг из любого источника. +Учитывает все возможные рейтинги, включая рейтинги ожидания и критиков. + +**Возвращает:** `bool true,` если существует хотя бы один рейтинг, иначе false + +**См. также:** + +* `Rating::getAvailableRatings`: () Для получения всех доступных рейтингов + +## `getAvailableRatings()` + +**Описание:** Возвращает все доступные рейтинги в виде ассоциативного массива +Собирает все ненулевые рейтинги в ассоциативный массив, где ключи +соответствуют источникам рейтингов, а значения - самим рейтингам. +Используется для получения полного набора рейтингов в удобном формате. + +**Возвращает:** `array` Ассоциативный массив доступных рейтингов + +**См. также:** + +* `Rating::hasAnyRating`: () Для проверки наличия хотя бы одного рейтинга + +## `validate()` + +**Описание:** Валидирует данные модели +Проверяет корректность рейтингов. +Все рейтинги должны быть в допустимых диапазонах. + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/Review.md b/docs/dev/kinopoiskdev/Models/Review.md new file mode 100644 index 0000000..88a9241 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Review.md @@ -0,0 +1,101 @@ +# Review + +**Описание:** Класс для представления рецензии на фильм +Представляет информацию о рецензии пользователя на фильм или сериал, +включая текст рецензии, тип (позитивная/негативная/нейтральная), +автора и статистику лайков/дизлайков. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Movie`: Для основной модели фильма + +## `__construct()` + +**Описание:** Конструктор для создания объекта рецензии +Создает новый экземпляр класса Review с указанными параметрами. +Все обязательные поля должны быть переданы при создании объекта. + +**Параметры:** + +* `$id` (int): Уникальный идентификатор рецензии +* `$movieId` (int): ID фильма к которому относится рецензия +* `$authorId` (int): ID автора рецензии +* `$reviewLikes` (int): Количество лайков рецензии +* `$reviewDislikes` (int): Количество дизлайков рецензии +* `$updatedAt` (string): Дата последнего обновления +* `$createdAt` (string): Дата создания рецензии +* `$title` (string|null): Заголовок рецензии +* `$type` (string|null): Тип рецензии (Позитивный/Негативный/Нейтральный) +* `$review` (string|null): Текст рецензии +* `$date` (string|null): Дата создания рецензии (альтернативное поле) +* `$author` (string|null): Имя автора рецензии +* `$userRating` (int|null): Пользовательский рейтинг + +## `fromArray()` + +**Описание:** Создает объект Review из массива данных API +Фабричный метод для создания экземпляра класса Review из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения для опциональных полей. + +**Параметры:** + +* `$data` (array): Массив данных о рецензии от API + +**Возвращает:** `\KinopoiskDev\Models\Review` Новый экземпляр класса Review с данными из массива + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса Review в массив, +совместимый с форматом API Kinopoisk.dev. + +**Возвращает:** `array` Массив с данными о рецензии + +## `isPositive()` + +**Описание:** Проверяет, является ли рецензия позитивной + +**Возвращает:** `bool true` если рецензия позитивная, иначе false + +## `isNegative()` + +**Описание:** Проверяет, является ли рецензия негативной + +**Возвращает:** `bool true` если рецензия негативная, иначе false + +## `isNeutral()` + +**Описание:** Проверяет, является ли рецензия нейтральной + +**Возвращает:** `bool true` если рецензия нейтральная, иначе false + +## `getNetRating()` + +**Описание:** Возвращает общий рейтинг рецензии (лайки - дизлайки) + +**Возвращает:** `int` Разность между лайками и дизлайками + +## `getPositivePercentage()` + +**Описание:** Возвращает процент позитивных оценок рецензии + +**Возвращает:** `float` Процент лайков от общего количества оценок + +## `getActualDate()` + +**Описание:** Возвращает актуальную дату рецензии +Приоритет отдается createdAt над полем date + +**Возвращает:** `string` Дата рецензии + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/ReviewInfo.md b/docs/dev/kinopoiskdev/Models/ReviewInfo.md new file mode 100644 index 0000000..b9f3e62 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/ReviewInfo.md @@ -0,0 +1,75 @@ +# ReviewInfo + +**Описание:** Класс для представления информации о рецензиях на фильм +Содержит статистические данные о рецензиях на фильм или сериал, +включая общее количество рецензий, количество положительных рецензий +и процентное соотношение положительных отзывов. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Movie`: Для использования в информации о фильмах + +## `__construct()` + +**Описание:** Конструктор для создания объекта информации о рецензиях +Создает новый экземпляр класса ReviewInfo с указанными параметрами. +Все параметры являются опциональными и могут быть NULL при отсутствии +соответствующей информации в источнике данных. + +**Параметры:** + +* `$count` (int|null): Общее количество рецензий +* `$positiveCount` (int|null): Количество положительных рецензий +* `$percentage` (string|null): Процент положительных рецензий в виде строки + +**См. также:** + +* `ReviewInfo::fromArray`: () Для создания объекта из массива данных API +* `ReviewInfo::toArray`: () Для преобразования объекта в массив + +## `fromArray()` + +**Описание:** Создает объект ReviewInfo из массива данных API +Фабричный метод для создания экземпляра класса ReviewInfo из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения, устанавливая их в NULL. +- count: int|null - общее количество рецензий +- positiveCount: int|null - количество положительных рецензий +- percentage: string|null - процент положительных рецензий + +**Параметры:** + +* `$data` (array): Массив данных о рецензиях от API, содержащий ключи: + +**Возвращает:** `\KinopoiskDev\Models\ReviewInfo` Новый экземпляр класса ReviewInfo с данными из массива + +**См. также:** + +* `ReviewInfo::toArray`: () Для обратного преобразования в массив + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса ReviewInfo в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных. +- count: int|null - общее количество рецензий +- positiveCount: int|null - количество положительных рецензий +- percentage: string|null - процент положительных рецензий + +**Возвращает:** `array` Массив с данными о рецензиях, содержащий ключи: + +**См. также:** + +* `ReviewInfo::fromArray`: () Для создания объекта из массива + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/SearchMovie.md b/docs/dev/kinopoiskdev/Models/SearchMovie.md new file mode 100644 index 0000000..1f6774c --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/SearchMovie.md @@ -0,0 +1,113 @@ +# SearchMovie + +**Описание:** Класс для представления результатов поиска фильмов +Представляет данные о фильме, полученные при выполнении поиска через API Kinopoisk.dev. +Содержит основную информацию о фильме, включая идентификатор, названия, рейтинги, +постеры, жанры и другие метаданные. Используется для отображения результатов поиска +без необходимости загрузки полной информации о фильме. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Movie`: Для полной информации о фильме +* `\KinopoiskDev\Models\Name`: Для названий фильмов +* `\KinopoiskDev\Models\ExternalId`: Для внешних идентификаторов +* `\KinopoiskDev\Models\Rating`: Для рейтингов +* `\KinopoiskDev\Models\ShortImage`: Для изображений +* `\KinopoiskDev\Models\ItemName`: Для жанров и стран +* `\KinopoiskDev\Models\YearRange`: Для годов выпуска +* `\KinopoiskDev\Models\Logo`: Для логотипов +* `\KinopoiskDev\Models\Votes`: Для голосов + +## `__construct()` + +**Описание:** Конструктор для создания объекта результата поиска фильма +Создает новый экземпляр класса SearchMovie с указанными параметрами. +Большинство параметров являются опциональными и могут быть null при отсутствии +соответствующей информации в источнике данных. Только идентификатор является +обязательным параметром. + +**Параметры:** + +* `$id` (int): Уникальный идентификатор фильма в системе Kinopoisk +* `$name` (string|null): Название фильма на русском языке +* `$alternativeName` (string|null): Альтернативное название фильма +* `$enName` (string|null): Название фильма на английском языке +* `$type` (\KinopoiskDev\Enums\MovieType|null): Тип фильма (фильм, сериал, мультфильм и т.д.) +* `$year` (int|null): Год выпуска фильма +* `$description` (string|null): Полное описание сюжета фильма +* `$shortDescription` (string|null): Краткое описание фильма +* `$movieLength` (int|null): Длительность фильма в минутах +* `$names` (\KinopoiskDev\Models\Name[]|null): Массив всех названий фильма на разных языках +* `$externalId` (ExternalId|null): Внешние идентификаторы (IMDB, TMDB, KinopoiskHD) +* `$logo` (Logo|null): Логотип фильма +* `$poster` (ShortImage|null): Постер фильма +* `$backdrop` (ShortImage|null): Фоновое изображение фильма +* `$rating` (Rating|null): Рейтинг фильма +* `$votes` (Votes|null): Информация о голосах +* `$genres` (\KinopoiskDev\Models\ItemName[]|null): Массив жанров фильма +* `$countries` (\KinopoiskDev\Models\ItemName[]|null): Массив стран производства фильма +* `$releaseYears` (\KinopoiskDev\Models\YearRange[]|null): Массив годов выпуска для разных стран +* `$isSeries` (bool|null): Является ли произведение сериалом +* `$ticketsOnSale` (bool|null): Доступны ли билеты к покупке +* `$totalSeriesLength` (int|null): Общее количество серий +* `$seriesLength` (int|null): Количество серий в сезоне +* `$ratingMpaa` (\KinopoiskDev\Enums\RatingMpaa|null): Рейтинг MPAA (G, PG, PG-13, R, NC-17) +* `$ageRating` (int|null): Возрастной рейтинг +* `$top10` (int|null): Позиция в топ-10 (null если не входит) +* `$top250` (int|null): Позиция в топ-250 (null если не входит) +* `$typeNumber` (int|null): Числовой код типа фильма +* `$status` (\KinopoiskDev\Enums\MovieStatus|null): Статус производства фильма + +**См. также:** + +* `SearchMovie::fromArray`: () Для создания объекта из массива данных API +* `SearchMovie::toArray`: () Для преобразования объекта в массив + +## `fromArray()` + +**Описание:** Создает объект SearchMovie из массива данных API +Фабричный метод для создания экземпляра класса SearchMovie из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие значения, +устанавливая их в null. Автоматически преобразует массивы данных в соответствующие +объекты модели при их наличии. + +**Параметры:** + +* `$data` (array): Массив данных от API, содержащий информацию о фильме + +**Возвращает:** `static` Новый экземпляр SearchMovie с данными из массива + +**Исключения:** + +* `\TypeError`: Если обязательный параметр 'id' отсутствует или имеет неверный тип + +**См. также:** + +* `SearchMovie::toArray`: () Для обратного преобразования в массив +* `SearchMovie::__construct`: () Для создания объекта через конструктор + +## `toArray()` + +**Описание:** Преобразует объект SearchMovie в массив +Конвертирует текущий экземпляр SearchMovie в ассоциативный массив, +сохраняя все свойства объекта. Полезно для сериализации данных, +передачи в API или сохранения в базе данных. +именам свойств, а значения - их содержимому + +**Возвращает:** `array` Ассоциативный массив с данными объекта, где ключи соответствуют + +**См. также:** + +* `SearchMovie::fromArray`: () Для создания объекта из массива +* `SearchMovie::__construct`: () Для создания объекта через конструктор + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/Season.md b/docs/dev/kinopoiskdev/Models/Season.md new file mode 100644 index 0000000..7afc2cc --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Season.md @@ -0,0 +1,94 @@ +# Season + +**Описание:** Класс для представления сезона сериала (версия API 1.4) +Представляет информацию о сезоне сериала согласно схеме Season, +включая номер сезона, количество эпизодов, постер, название, описание +и массив эпизодов. Используется для детальной информации о структуре сериалов. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\EpisodeV1_4`: Для информации об отдельных эпизодах +* `\KinopoiskDev\Models\Movie`: Для основной модели фильма/сериала + +## `__construct()` + +**Описание:** Конструктор для создания объекта сезона +Создает новый экземпляр класса Season с полным набором данных о сезоне. +Большинство параметров являются опциональными и могут быть null при отсутствии +соответствующей информации в источнике данных. + +**Параметры:** + +* `$movieId` (int): ID фильма/сериала к которому относится сезон +* `$number` (int|null): Номер сезона +* `$episodesCount` (int|null): Количество эпизодов в сезоне +* `$episodes` (Episode[]): Массив эпизодов сезона +* `$poster` (ShortImage|null): Постер сезона +* `$name` (string|null): Название сезона на русском языке +* `$enName` (string|null): Название сезона на английском языке +* `$duration` (int|null): Длительность сезона в минутах +* `$description` (string|null): Описание сезона на русском языке +* `$enDescription` (string|null): Описание сезона на английском языке +* `$airDate` (string|null): Дата выхода сезона +* `$updatedAt` (string|null): Дата последнего обновления записи +* `$createdAt` (string|null): Дата создания записи + +## `fromArray()` + +**Описание:** Создает объект Season из массива данных API +Фабричный метод для создания экземпляра класса Season из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения и преобразует вложенные объекты в соответствующие классы. + +**Параметры:** + +* `$data` (array): Массив данных о сезоне от API + +**Возвращает:** `\KinopoiskDev\Models\Season` Новый экземпляр класса Season с данными из массива + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса Season в массив, +совместимый с форматом API Kinopoisk.dev. + +**Возвращает:** `array` Массив с полными данными о сезоне + +## `getBestName()` + +**Описание:** Возвращает наилучшее доступное название сезона + +**Возвращает:** `string|null` Название сезона или null если не задано + +## `getBestDescription()` + +**Описание:** Возвращает наилучшее доступное описание сезона + +**Возвращает:** `string|null` Описание сезона или null если не задано + +## `hasEpisodes()` + +**Описание:** Проверяет, есть ли эпизоды в сезоне + +**Возвращает:** `bool true` если есть эпизоды, иначе false + +## `getAvailableEpisodesCount()` + +**Описание:** Возвращает количество доступных эпизодов + +**Возвращает:** `int` Количество эпизодов в массиве episodes + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/SeasonInfo.md b/docs/dev/kinopoiskdev/Models/SeasonInfo.md new file mode 100644 index 0000000..f4580c7 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/SeasonInfo.md @@ -0,0 +1,70 @@ +# SeasonInfo + +**Описание:** Класс для представления информации о сезоне сериала +Содержит данные о конкретном сезоне сериала, включая номер сезона +и количество эпизодов в нем. Используется для структурирования +информации о сериалах с несколькими сезонами. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Movie`: Для использования в информации о сериалах + +## `__construct()` + +**Описание:** Конструктор для создания объекта информации о сезоне +Создает новый экземпляр класса SeasonInfo с указанными параметрами. +Все параметры являются опциональными и могут быть null при отсутствии +соответствующей информации в источнике данных. + +**Параметры:** + +* `$number` (int|null): Номер сезона +* `$episodesCount` (int|null): Количество эпизодов в сезоне + +**См. также:** + +* `SeasonInfo::fromArray`: () Для создания объекта из массива данных API +* `SeasonInfo::toArray`: () Для преобразования объекта в массив + +## `fromArray()` + +**Описание:** Создает объект SeasonInfo из массива данных API +Фабричный метод для создания экземпляра класса SeasonInfo из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения, устанавливая их в null. +- number: int|null - номер сезона +- episodesCount: int|null - количество эпизодов в сезоне + +**Параметры:** + +* `$data` (array): Массив данных о сезоне от API, содержащий ключи: + +**Возвращает:** `\KinopoiskDev\Models\SeasonInfo` Новый экземпляр класса SeasonInfo с данными из массива + +**См. также:** + +* `SeasonInfo::toArray`: () Для обратного преобразования в массив + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса SeasonInfo в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных. + +**Возвращает:** `array` Массив с данными о сезоне, содержащий все поля объекта + +**См. также:** + +* `SeasonInfo::fromArray`: () Для создания объекта из массива + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/ShortImage.md b/docs/dev/kinopoiskdev/Models/ShortImage.md new file mode 100644 index 0000000..34de411 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/ShortImage.md @@ -0,0 +1,71 @@ +# ShortImage + +**Описание:** Класс для представления упрощенной информации об изображении +Содержит основные данные об изображении, включая URL полного изображения +и URL превью. Используется для хранения информации о постерах, фонах +и других изображениях, связанных с фильмами и сериалами. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Image`: Для полной информации об изображении +* `\KinopoiskDev\Models\Movie`: Для использования в информации о фильмах + +## `__construct()` + +**Описание:** Конструктор для создания объекта упрощенного изображения +Создает новый экземпляр класса ShortImage с указанными параметрами. +Все параметры являются опциональными и могут быть null при отсутствии +соответствующей информации в источнике данных. + +**Параметры:** + +* `$url` (string|null): URL полного изображения +* `$previewUrl` (string|null): URL превью изображения + +**См. также:** + +* `ShortImage::fromArray`: () Для создания объекта из массива данных API +* `ShortImage::toArray`: () Для преобразования объекта в массив + +## `fromArray()` + +**Описание:** Создает объект ShortImage из массива данных API +Фабричный метод для создания экземпляра класса ShortImage из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения, устанавливая их в null. +- url: string|null - URL полного изображения +- previewUrl: string|null - URL превью изображения + +**Параметры:** + +* `$data` (array): Массив данных об изображении от API, содержащий ключи: + +**Возвращает:** `\KinopoiskDev\Models\ShortImage` Новый экземпляр класса ShortImage с данными из массива + +**См. также:** + +* `ShortImage::toArray`: () Для обратного преобразования в массив + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса ShortImage в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных. + +**Возвращает:** `array` Массив с данными об изображении, содержащий все поля объекта + +**См. также:** + +* `ShortImage::fromArray`: () Для создания объекта из массива + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/Spouses.md b/docs/dev/kinopoiskdev/Models/Spouses.md new file mode 100644 index 0000000..492fc3d --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Spouses.md @@ -0,0 +1,88 @@ +# Spouses + +**Описание:** Класс для представления супруга/супруги персоны +Представляет информацию о супруге или супруге персоны, включая персональные данные, +статус отношений, количество детей и причины развода. Используется для хранения +и обработки семейной информации персон из API Kinopoisk.dev. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Enums\PersonSex`: Для определения пола супруга +* `\KinopoiskDev\Models\Person`: Для основной модели персоны + +## `__construct()` + +**Описание:** Конструктор для создания объекта супруга +Создает новый экземпляр класса Spouses с информацией о супруге персоны. +Все свойства являются для обеспечения неизменности данных. +Параметр divorced имеет значение по умолчанию false. + +**Параметры:** + +* `$id` (int): Уникальный идентификатор супруга в базе данных +* `$name` (string): Полное имя супруга +* `$divorcedReason` (string): Причина развода (пустая строка если развода не было) +* `$sex` (PersonSex): Пол супруга (мужской или женский) +* `$children` (int): Количество детей в браке +* `$relation` (string): Описание типа отношений или дополнительная информация +* `$divorced` (bool): Статус развода (true - в разводе, false - в браке, по умолчанию false) + +**См. также:** + +* `Spouses::fromArray`: () Для создания объекта из массива данных API +* `Spouses::toArray`: () Для преобразования объекта в массив + +## `fromArray()` + +**Описание:** Создает объект Spouses из массива данных API +Фабричный метод для создания экземпляра класса Spouses из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает все поля массива +и автоматически преобразует строковое значение пола в enum PersonSex +с помощью метода tryFrom(). +- id: int - уникальный идентификатор супруга +- name: string - полное имя супруга +- divorced: bool - статус развода +- divorcedReason: string - причина развода +- sex: string - пол супруга ('male' или 'female') +- children: int - количество детей +- relation: string - тип отношений + +**Возвращает:** `static` Новый экземпляр класса Spouses с данными из массива + +**См. также:** + +* `Spouses::toArray`: () Для обратного преобразования в массив +* `PersonSex::tryFrom`: () Для безопасного преобразования строки в enum + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса Spouses в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных в JSON. +Enum PersonSex автоматически преобразуется в строковое значение. +- id: int - уникальный идентификатор супруга +- name: string - полное имя супруга +- divorced: bool - статус развода +- divorcedReason: string - причина развода +- sex: PersonSex - пол супруга (enum объект) +- children: int - количество детей +- relation: string - тип отношений + +**Возвращает:** `array` Массив с данными о супруге, содержащий ключи: + +**См. также:** + +* `Spouses::fromArray`: () Для создания объекта из массива +* `PersonSex::value`: Для получения строкового значения enum + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/Studio.md b/docs/dev/kinopoiskdev/Models/Studio.md new file mode 100644 index 0000000..9f3c804 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Studio.md @@ -0,0 +1,101 @@ +# Studio + +**Описание:** Класс для представления студии кинопроизводства +Представляет информацию о студии кинопроизводства, включая тип студии, +название, подтип и связанные с ней фильмы. Используется для хранения +и обработки данных о студиях, полученных от API Kinopoisk.dev. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Enums\StudioType`: Для типов студий +* `\KinopoiskDev\Models\MovieFromStudio`: Для фильмов, связанных со студией +* `\KinopoiskDev\Models\BaseModel`: Базовый интерфейс для всех моделей + +## `__construct()` + +**Описание:** Конструктор для создания объекта студии +Создает новый экземпляр класса Studio с указанными параметрами. +Только идентификатор, дата обновления и дата создания являются обязательными, +остальные параметры могут быть null при отсутствии соответствующей информации. + +**Параметры:** + +* `$id` (string): Уникальный идентификатор студии +* `$subType` (string|null): Подтип студии или null если не определен +* `$title` (string|null): Название студии или null если не определено +* `$type` (StudioType|null): Тип студии или null если не определен +* `$movies` (\KinopoiskDev\Models\MovieFromStudio[]): Массив фильмов, связанных со студией +* `$updateAt` (string): Дата последнего обновления в формате ISO 8601 +* `$createdAt` (string): Дата создания записи в формате ISO 8601 + +**См. также:** + +* `Studio::fromArray`: () Для создания объекта из массива данных API +* `Studio::toArray`: () Для преобразования объекта в массив +* `\KinopoiskDev\Enums\StudioType`: Для возможных типов студий + +## `fromArray()` + +**Описание:** Создает объект Studio из массива данных API +Фабричный метод для создания экземпляра класса Studio из массива данных, +полученных от API Kinopoisk.dev. Метод использует значения по умолчанию +для опциональных параметров и безопасно обрабатывает отсутствующие ключи. +- id: string - уникальный идентификатор студии (обязательный) +- subType: string|null - подтип студии (опциональный) +- title: string|null - название студии (опциональный) +- type: StudioType|null - тип студии (опциональный) +- movies: MovieFromStudio[] - массив связанных фильмов (опциональный) +- updateAt: string - дата последнего обновления (обязательный) +- createdAt: string - дата создания (обязательный) + +**Параметры:** + +* `$data` (array): Массив данных от API, содержащий ключи: + +**Возвращает:** `static` Новый экземпляр Studio с данными из массива + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: + +**См. также:** + +* `Studio::toArray`: () Для обратного преобразования в массив +* `\KinopoiskDev\Models\BaseModel::fromArray`: () Для интерфейса BaseModel +* `\KinopoiskDev\Enums\StudioType`: Для преобразования типа студии + +## `toArray()` + +**Описание:** Преобразует объект Studio в массив данных +Метод для преобразования экземпляра класса Studio в ассоциативный массив +данных. Используется для сериализации объекта в формат, совместимый с API, +или для передачи данных в другие части системы. +- id: string - уникальный идентификатор студии +- subType: string|null - подтип студии +- title: string|null - название студии +- type: StudioType|null - тип студии +- movies: array - массив связанных фильмов +- updateAt: string - дата последнего обновления +- createdAt: string - дата создания + +**Параметры:** + +* `$includeNulls` (bool): Включать ли null значения в результат (по умолчанию true) + +**Возвращает:** `array` Ассоциативный массив с данными студии, содержащий ключи: + +**См. также:** + +* `Studio::fromArray`: () Для создания объекта из массива +* `\KinopoiskDev\Models\BaseModel::toArray`: () Для интерфейса BaseModel + +## `validate()` + +**Описание:** Валидирует данные студии + +**Возвращает:** `bool` + diff --git a/docs/dev/kinopoiskdev/Models/Video.md b/docs/dev/kinopoiskdev/Models/Video.md new file mode 100644 index 0000000..240c32d --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Video.md @@ -0,0 +1,77 @@ +# Video + +**Описание:** Класс для представления видеоматериала +Содержит информацию о видеоматериале, связанном с фильмом или сериалом, +включая URL, название, тип, размер и источник. Используется для хранения +данных о трейлерах, тизерах и других видеоматериалах. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\VideoTypes`: Для коллекции видеоматериалов +* `\KinopoiskDev\Models\Movie`: Для использования в информации о фильмах + +## `__construct()` + +**Описание:** Конструктор для создания объекта видеоматериала +Создает новый экземпляр класса Video с указанными параметрами. +Большинство параметров являются опциональными и могут быть null при отсутствии +соответствующей информации в источнике данных. + +**Параметры:** + +* `$url` (string|null): URL видеоматериала +* `$name` (string|null): Название видеоматериала +* `$site` (string|null): Источник видеоматериала (например, YouTube) +* `$size` (int|null): Размер видеоматериала +* `$type` (string|null): Тип видеоматериала (например, трейлер, тизер) + +**См. также:** + +* `Video::fromArray`: () Для создания объекта из массива данных API +* `Video::toArray`: () Для преобразования объекта в массив + +## `fromArray()` + +**Описание:** Создает объект Video из массива данных API +Фабричный метод для создания экземпляра класса Video из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения, устанавливая их в null. +- url: string|null - URL видеоматериала +- name: string|null - название видеоматериала +- site: string|null - источник видеоматериала +- size: int|null - размер видеоматериала +- type: string|null - тип видеоматериала + +**Параметры:** + +* `$data` (array): Массив данных о видеоматериале от API, содержащий ключи: + +**Возвращает:** `\KinopoiskDev\Models\Video` Новый экземпляр класса Video с данными из массива + +**См. также:** + +* `Video::toArray`: () Для обратного преобразования в массив + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса Video в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных. + +**Возвращает:** `array` Массив с данными о видеоматериале, содержащий все поля объекта + +**См. также:** + +* `Video::fromArray`: () Для создания объекта из массива + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/VideoTypes.md b/docs/dev/kinopoiskdev/Models/VideoTypes.md new file mode 100644 index 0000000..ec19d6e --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/VideoTypes.md @@ -0,0 +1,74 @@ +# VideoTypes + +**Описание:** Класс для представления коллекции видеоматериалов +Содержит коллекцию видеоматериалов, связанных с фильмом или сериалом, +включая трейлеры, тизеры и другие типы видео. Используется для группировки +и организации видеоконтента по категориям. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Video`: Для отдельных видеоматериалов +* `\KinopoiskDev\Models\Movie`: Для использования в информации о фильмах + +## `__construct()` + +**Описание:** Конструктор для создания объекта коллекции видеоматериалов +Создает новый экземпляр класса VideoTypes с указанным массивом трейлеров. +Параметр является опциональным и может быть null при отсутствии +видеоматериалов для данного фильма или сериала. + +**Параметры:** + +* `$trailers` (array|null): Массив объектов Video с трейлерами или null + +**См. также:** + +* `VideoTypes::fromArray`: () Для создания объекта из массива данных API +* `VideoTypes::toArray`: () Для преобразования объекта в массив +* `Video`: Для структуры отдельного видеоматериала + +## `fromArray()` + +**Описание:** Создает объект VideoTypes из массива данных API +Фабричный метод для создания экземпляра класса VideoTypes из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения и преобразует вложенные массивы трейлеров в объекты Video. +- trailers: array|null - массив данных о трейлерах + +**Параметры:** + +* `$data` (array): Массив данных о видеоматериалах от API, содержащий ключи: + +**Возвращает:** `\KinopoiskDev\Models\VideoTypes` Новый экземпляр класса VideoTypes с данными из массива + +**См. также:** + +* `VideoTypes::toArray`: () Для обратного преобразования в массив +* `Video::fromArray`: () Для создания отдельных видеоматериалов + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса VideoTypes в массив, +совместимый с форматом API Kinopoisk.dev. Преобразует все вложенные +объекты Video в массивы. Используется для сериализации данных +при отправке запросов к API или для экспорта данных. +- trailers: array|null - массив данных о трейлерах или null + +**Возвращает:** `array` Массив с данными о видеоматериалах, содержащий ключи: + +**См. также:** + +* `VideoTypes::fromArray`: () Для создания объекта из массива +* `Video::toArray`: () Для преобразования отдельных видеоматериалов в массивы + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/Votes.md b/docs/dev/kinopoiskdev/Models/Votes.md new file mode 100644 index 0000000..2e2bc1a --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Votes.md @@ -0,0 +1,192 @@ +# Votes + +**Описание:** Класс для представления количества голосов из различных источников +Содержит информацию о количестве голосов для фильма/сериала из различных +источников, включая Кинопоиск, IMDB, TMDB, а также голоса кинокритиков +и ожидания зрителей. Используется для анализа популярности произведения. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Movie::getVotes`: () Для получения голосов фильма +* `\KinopoiskDev\Models\Rating`: Для информации о рейтингах + +## `__construct()` + +**Описание:** Конструктор для создания объекта голосов +Создает новый экземпляр класса Votes с количеством голосов из различных источников. +Все параметры являются опциональными и могут быть NULL при отсутствии +соответствующей информации в источнике данных. + +**Параметры:** + +* `$kp` (int|null): Количество голосов на Кинопоиске +* `$imdb` (int|null): Количество голосов на IMDB +* `$tmdb` (int|null): Количество голосов на The Movie Database +* `$filmCritics` (int|null): Количество голосов кинокритиков +* `$russianFilmCritics` (int|null): Количество голосов российских кинокритиков +* `$await` (int|null): Количество голосов ожидания + +**См. также:** + +* `Votes::fromArray`: () Для создания объекта из массива данных API +* `Votes::toArray`: () Для преобразования объекта в массив + +## `__toString()` + +**Описание:** Возвращает строковое представление голосов +Реализует магический метод __toString для преобразования объекта +в строку. Формирует строку, содержащую основные голоса в удобочитаемом +формате, разделенные запятыми. + +**Возвращает:** `string` Строковое представление голосов или 'No votes', если голоса отсутствуют + +**См. также:** + +* `Votes::formatVoteCount`: () Для форматирования количества голосов +* `Votes::getFormattedKpVotes`: () Для получения отформатированных голосов Кинопоиска +* `Votes::getFormattedImdbVotes`: () Для получения отформатированных голосов IMDB + +## `fromArray()` + +**Описание:** Создает объект Votes из массива данных API +Фабричный метод для создания экземпляра класса Votes из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения и преобразует строковые значения в числовые. +- kp: int|null - количество голосов на Кинопоиске +- imdb: int|null - количество голосов на IMDB +- tmdb: int|null - количество голосов на TMDB +- filmCritics: int|null - количество голосов кинокритиков +- russianFilmCritics: int|null - количество голосов российских кинокритиков +- await: int|null - количество голосов ожидания + +**Параметры:** + +* `$data` (array): Массив данных о голосах от API, содержащий ключи: + +**Возвращает:** `\KinopoiskDev\Models\Votes` Новый экземпляр класса Votes с данными из массива + +**См. также:** + +* `Votes::toArray`: () Для обратного преобразования в массив + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса Votes в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных. + +**Возвращает:** `array` Массив с данными о количестве голосов из различных источников + +**См. также:** + +* `Votes::fromArray`: () Для создания объекта из массива + +## `getTotalVotes()` + +**Описание:** Возвращает общее количество голосов со всех платформ +Суммирует количество голосов из всех доступных источников, +включая Кинопоиск, IMDB, TMDB, голоса кинокритиков и ожидания. +Игнорирует отсутствующие (null) значения при подсчете. + +**Возвращает:** `int` Общее количество голосов со всех платформ + +**См. также:** + +* `Votes::getAvailableVotes`: () Для получения голосов в виде ассоциативного массива +* `Votes::getMostVotedPlatform`: () Для определения платформы с наибольшим количеством голосов + +## `getMostVotedPlatform()` + +**Описание:** Возвращает платформу с наибольшим количеством голосов +Определяет, какая из платформ (Кинопоиск, IMDB, TMDB и т.д.) имеет +наибольшее количество голосов. Используется для определения наиболее +популярного источника оценок для данного фильма или сериала. + +**Возвращает:** `string|null` Ключ платформы с наибольшим количеством голосов или null, если голоса отсутствуют + +**См. также:** + +* `Votes::getAvailableVotes`: () Для получения всех доступных голосов +* `Votes::getTotalVotes`: () Для получения общего количества голосов + +## `getAvailableVotes()` + +**Описание:** Возвращает все доступные голоса в виде ассоциативного массива +Собирает все ненулевые значения голосов в ассоциативный массив, где ключи +соответствуют источникам голосов, а значения - количеству голосов. +Используется для получения полного набора голосов в удобном формате. + +**Возвращает:** `array` Ассоциативный массив доступных голосов + +**См. также:** + +* `Votes::hasAnyVotes`: () Для проверки наличия хотя бы одного голоса +* `Votes::getTotalVotes`: () Для получения общего количества голосов + +## `hasAnyVotes()` + +**Описание:** Проверяет наличие хотя бы одного голоса +Определяет, существует ли хотя бы один голос из любого источника. +Учитывает все возможные источники голосов, включая голоса ожидания и критиков. + +**Возвращает:** `bool true,` если существует хотя бы один голос, иначе false + +**См. также:** + +* `Votes::getAvailableVotes`: () Для получения всех доступных голосов + +## `getFormattedKpVotes()` + +**Описание:** Возвращает отформатированное количество голосов Кинопоиска +Предоставляет количество голосов с Кинопоиска в удобочитаемом формате +с использованием суффиксов K/M. Возвращает null, если голоса отсутствуют. + +**Возвращает:** `string|null` Отформатированное количество голосов или null, если голоса отсутствуют + +**См. также:** + +* `Votes::formatVoteCount`: () Для форматирования количества голосов +* `Votes::getFormattedImdbVotes`: () Для получения отформатированных голосов IMDB + +## `formatVoteCount()` + +**Описание:** Форматирует количество голосов с суффиксами K/M +Преобразует числовое значение количества голосов в удобочитаемый формат +с использованием суффиксов K (тысячи) и M (миллионы). Например, 1500 будет +отображаться как "1.5K", а 2000000 как "2.0M". + +**Параметры:** + +* `$count` (int): Количество голосов для форматирования + +**Возвращает:** `string` Отформатированное строковое представление количества голосов + +**См. также:** + +* `Votes::getFormattedKpVotes`: () Для получения отформатированных голосов Кинопоиска +* `Votes::getFormattedImdbVotes`: () Для получения отформатированных голосов IMDB + +## `getFormattedImdbVotes()` + +**Описание:** Возвращает отформатированное количество голосов IMDB +Предоставляет количество голосов с IMDB в удобочитаемом формате +с использованием суффиксов K/M. Возвращает null, если голоса отсутствуют. + +**Возвращает:** `string|null` Отформатированное количество голосов или null, если голоса отсутствуют + +**См. также:** + +* `Votes::formatVoteCount`: () Для форматирования количества голосов +* `Votes::getFormattedKpVotes`: () Для получения отформатированных голосов Кинопоиска + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/Watchability.md b/docs/dev/kinopoiskdev/Models/Watchability.md new file mode 100644 index 0000000..4ca5af5 --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/Watchability.md @@ -0,0 +1,74 @@ +# Watchability + +**Описание:** Класс для представления информации о доступности просмотра +Содержит информацию о платформах и сервисах, где доступен просмотр +фильма или сериала. Используется для отображения списка стриминговых +сервисов, онлайн-кинотеатров и других площадок для просмотра контента. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\WatchabilityItem`: Для отдельных элементов доступности +* `\KinopoiskDev\Models\Movie`: Для использования в информации о фильмах + +## `__construct()` + +**Описание:** Конструктор для создания объекта доступности просмотра +Создает новый экземпляр класса Watchability с указанным массивом элементов. +Параметр является опциональным и может быть пустым массивом при отсутствии +информации о доступности просмотра для данного фильма или сериала. + +**Параметры:** + +* `$items` (array): Массив объектов WatchabilityItem с информацией о платформах + +**См. также:** + +* `Watchability::fromArray`: () Для создания объекта из массива данных API +* `Watchability::toArray`: () Для преобразования объекта в массив +* `WatchabilityItem`: Для структуры отдельного элемента доступности + +## `fromArray()` + +**Описание:** Создает объект Watchability из массива данных API +Фабричный метод для создания экземпляра класса Watchability из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения и преобразует вложенные массивы элементов в объекты WatchabilityItem. +- items: array|null - массив данных о платформах просмотра + +**Параметры:** + +* `$data` (array): Массив данных о доступности просмотра от API, содержащий ключи: + +**Возвращает:** `\KinopoiskDev\Models\Watchability` Новый экземпляр класса Watchability с данными из массива + +**См. также:** + +* `Watchability::toArray`: () Для обратного преобразования в массив +* `WatchabilityItem::fromArray`: () Для создания отдельных элементов доступности + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса Watchability в массив, +совместимый с форматом API Kinopoisk.dev. Преобразует все вложенные +объекты WatchabilityItem в массивы. Используется для сериализации данных +при отправке запросов к API или для экспорта данных. +- items: array - массив данных о платформах просмотра + +**Возвращает:** `array` Массив с данными о доступности просмотра, содержащий ключи: + +**См. также:** + +* `Watchability::fromArray`: () Для создания объекта из массива +* `WatchabilityItem::toArray`: () Для преобразования отдельных элементов в массивы + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/WatchabilityItem.md b/docs/dev/kinopoiskdev/Models/WatchabilityItem.md new file mode 100644 index 0000000..1e34c9a --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/WatchabilityItem.md @@ -0,0 +1,81 @@ +# WatchabilityItem + +**Описание:** Класс для представления элемента доступности просмотра +Представляет информацию об отдельной платформе или сервисе, где доступен +просмотр фильма или сериала. Содержит название сервиса, логотип и URL +для перехода на страницу просмотра. Используется в составе коллекции +Watchability для отображения всех доступных вариантов просмотра. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Watchability`: Для коллекции элементов доступности +* `\KinopoiskDev\Models\Logo`: Для работы с логотипами сервисов + +## `__construct()` + +**Описание:** Конструктор для создания объекта элемента доступности просмотра +Создает новый экземпляр класса WatchabilityItem с указанными параметрами. +Содержит информацию о конкретном сервисе для просмотра фильма или сериала, +включая название, логотип и URL для перехода. + +**Параметры:** + +* `$logo` (Logo): Логотип сервиса (обязательный параметр) +* `$url` (string): URL для перехода на страницу просмотра (обязательный параметр) +* `$name` (string|null): Название сервиса или платформы (может быть null) + +**См. также:** + +* `WatchabilityItem::fromArray`: () Для создания объекта из массива данных API +* `WatchabilityItem::toArray`: () Для преобразования объекта в массив +* `Logo`: Для структуры объекта логотипа + +## `fromArray()` + +**Описание:** Создает объект WatchabilityItem из массива данных API +Фабричный метод для создания экземпляра класса WatchabilityItem из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения и создает вложенный объект Logo из соответствующих данных. +- name: string|null - название сервиса (опционально) +- logo: array - данные о логотипе сервиса (обязательно) +- url: string - URL для перехода на страницу просмотра (обязательно) + +**Параметры:** + +* `$data` (array): Массив данных о сервисе просмотра от API, содержащий ключи: + +**Возвращает:** `\KinopoiskDev\Models\WatchabilityItem` Новый экземпляр класса WatchabilityItem с данными из массива + +**См. также:** + +* `WatchabilityItem::toArray`: () Для обратного преобразования в массив +* `Logo::fromArray`: () Для создания объекта логотипа + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса WatchabilityItem в массив, +совместимый с форматом API Kinopoisk.dev. Преобразует вложенный +объект Logo в массив. Используется для сериализации данных +при отправке запросов к API или для экспорта данных. +- name: string|null - название сервиса +- logo: array - данные о логотипе сервиса +- url: string - URL для перехода на страницу просмотра + +**Возвращает:** `array` Массив с данными о сервисе просмотра, содержащий ключи: + +**См. также:** + +* `WatchabilityItem::fromArray`: () Для создания объекта из массива +* `Logo::toArray`: () Для преобразования логотипа в массив + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/Models/YearRange.md b/docs/dev/kinopoiskdev/Models/YearRange.md new file mode 100644 index 0000000..b502aca --- /dev/null +++ b/docs/dev/kinopoiskdev/Models/YearRange.md @@ -0,0 +1,72 @@ +# YearRange + +**Описание:** Класс для представления диапазона годов +Содержит информацию о диапазоне годов, включая начальный и конечный год. +Используется для хранения периодов выпуска сериалов, временных рамок +для поиска и фильтрации, а также других диапазонов дат в годах. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Movie`: Для использования в информации о фильмах + +## `__construct()` + +**Описание:** Конструктор для создания объекта диапазона годов +Создает новый экземпляр класса YearRange с указанными начальным и конечным годами. +Оба параметра являются опциональными и могут быть null при отсутствии +соответствующей информации в источнике данных. + +**Параметры:** + +* `$start` (int|null): Начальный год диапазона или null +* `$end` (int|null): Конечный год диапазона или null + +**См. также:** + +* `YearRange::fromArray`: () Для создания объекта из массива данных API +* `YearRange::toArray`: () Для преобразования объекта в массив + +## `fromArray()` + +**Описание:** Создает объект YearRange из массива данных API +Фабричный метод для создания экземпляра класса YearRange из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения, устанавливая их в null. +- start: int|null - начальный год диапазона +- end: int|null - конечный год диапазона + +**Параметры:** + +* `$data` (array): Массив данных о диапазоне годов от API, содержащий ключи: + +**Возвращает:** `static` Новый экземпляр класса YearRange с данными из массива + +**См. также:** + +* `YearRange::toArray`: () Для обратного преобразования в массив + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса YearRange в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных. +- start: int|null - начальный год диапазона +- end: int|null - конечный год диапазона + +**Возвращает:** `array` Массив с данными о диапазоне годов, содержащий ключи: + +**См. также:** + +* `YearRange::fromArray`: () Для создания объекта из массива + +## `validate()` + +**Описание:** Валидирует данные модели + +**Возвращает:** `bool True` если данные валидны + diff --git a/docs/dev/kinopoiskdev/README.md b/docs/dev/kinopoiskdev/README.md new file mode 100644 index 0000000..03bdc2e --- /dev/null +++ b/docs/dev/kinopoiskdev/README.md @@ -0,0 +1,142 @@ +# Содержание + +## Filter/ + +* [ReviewSearchFilter](Filter/ReviewSearchFilter.md) +* [SortCriteria](Filter/SortCriteria.md) +* [MovieSearchFilter](Filter/MovieSearchFilter.md) +* [SeasonSearchFilter](Filter/SeasonSearchFilter.md) +* [StudioSearchFilter](Filter/StudioSearchFilter.md) +* [ImageSearchFilter](Filter/ImageSearchFilter.md) +* [KeywordSearchFilter](Filter/KeywordSearchFilter.md) +* [PersonSearchFilter](Filter/PersonSearchFilter.md) +## Contracts/ + +* [CacheInterface](Contracts/CacheInterface.md) +* [LoggerInterface](Contracts/LoggerInterface.md) +## Utils/ + +* [DataManager](Utils/DataManager.md) +* [FilterTrait](Utils/FilterTrait.md) +* [SortManager](Utils/SortManager.md) +* [MovieFilter](Utils/MovieFilter.md) +## Models/ + +* [Spouses](Models/Spouses.md) +* [FactInMovie](Models/FactInMovie.md) +* [Rating](Models/Rating.md) +* [WatchabilityItem](Models/WatchabilityItem.md) +* [ExternalId](Models/ExternalId.md) +* [CurrencyValue](Models/CurrencyValue.md) +* [Name](Models/Name.md) +* [FactInPerson](Models/FactInPerson.md) +* [NominationAward](Models/NominationAward.md) +* [YearRange](Models/YearRange.md) +* [Networks](Models/Networks.md) +* [Watchability](Models/Watchability.md) +* [Movie](Models/Movie.md) +* [MovieInPerson](Models/MovieInPerson.md) +* [Season](Models/Season.md) +* [NetworkItem](Models/NetworkItem.md) +* [PersonPlace](Models/PersonPlace.md) +* [MeiliPersonEntity](Models/MeiliPersonEntity.md) +* [Video](Models/Video.md) +* [DeathPlace](Models/DeathPlace.md) +* [PersonAward](Models/PersonAward.md) +* [LinkedMovie](Models/LinkedMovie.md) +* [ItemName](Models/ItemName.md) +* [SeasonInfo](Models/SeasonInfo.md) +* [Logo](Models/Logo.md) +* [Image](Models/Image.md) +* [Review](Models/Review.md) +* [BirthPlace](Models/BirthPlace.md) +* [Votes](Models/Votes.md) +* [ReviewInfo](Models/ReviewInfo.md) +* [PersonInMovie](Models/PersonInMovie.md) +* [Episode](Models/Episode.md) +* [Audience](Models/Audience.md) +* [ApiImage](Models/ApiImage.md) +* [Premiere](Models/Premiere.md) +* [Lists](Models/Lists.md) +* [BaseModel](Models/BaseModel.md) +* [MovieFromKeyword](Models/MovieFromKeyword.md) +* [Nomination](Models/Nomination.md) +* [Fees](Models/Fees.md) +* [MovieAward](Models/MovieAward.md) +* [SearchMovie](Models/SearchMovie.md) +* [Person](Models/Person.md) +* [AbstractBaseModel](Models/AbstractBaseModel.md) +* [Studio](Models/Studio.md) +* [Keyword](Models/Keyword.md) +* [VideoTypes](Models/VideoTypes.md) +* [ShortImage](Models/ShortImage.md) +* [MovieFromStudio](Models/MovieFromStudio.md) +## Http/ + +* [StudioRequests](Http/StudioRequests.md) +* [MovieRequests](Http/MovieRequests.md) +* [ImageRequests](Http/ImageRequests.md) +* [KeywordRequests](Http/KeywordRequests.md) +* [PersonRequests](Http/PersonRequests.md) +* [SeasonRequests](Http/SeasonRequests.md) +* [ListRequests](Http/ListRequests.md) +* [ReviewRequests](Http/ReviewRequests.md) +## Enums/ + +* [ListCategory](Enums/ListCategory.md) +* [FilterOperator](Enums/FilterOperator.md) +* [SortDirection](Enums/SortDirection.md) +* [ImageType](Enums/ImageType.md) +* [PersonProfession](Enums/PersonProfession.md) +* [MovieType](Enums/MovieType.md) +* [HttpStatusCode](Enums/HttpStatusCode.md) +* [ReviewType](Enums/ReviewType.md) +* [RatingMpaa](Enums/RatingMpaa.md) +* [MovieStatus](Enums/MovieStatus.md) +* [StudioType](Enums/StudioType.md) +* [FilterField](Enums/FilterField.md) +* [SortField](Enums/SortField.md) +* [PersonSex](Enums/PersonSex.md) +## + +* [Kinopoisk](Kinopoisk.md) +## Exceptions/ + +* [KinopoiskResponseException](Exceptions/KinopoiskResponseException.md) +* [ValidationException](Exceptions/ValidationException.md) +* [KinopoiskDevException](Exceptions/KinopoiskDevException.md) +## Services/ + +* [CacheService](Services/CacheService.md) +* [ValidationService](Services/ValidationService.md) +## Responses/ + +* [ErrorResponseDto](Responses/ErrorResponseDto.md) +* [BaseDocsResponseDto](Responses/BaseDocsResponseDto.md) +* [BaseResponseDto](Responses/BaseResponseDto.md) +## Responses/Api/ + +* [ImageDocsResponseDto](Responses/Api/ImageDocsResponseDto.md) +* [PersonDocsResponseDto](Responses/Api/PersonDocsResponseDto.md) +* [MovieAwardDocsResponseDto](Responses/Api/MovieAwardDocsResponseDto.md) +* [PossibleValueDto](Responses/Api/PossibleValueDto.md) +* [KeywordDocsResponseDto](Responses/Api/KeywordDocsResponseDto.md) +* [MovieDocsResponseDto](Responses/Api/MovieDocsResponseDto.md) +* [SearchMovieResponseDto](Responses/Api/SearchMovieResponseDto.md) +* [ListDocsResponseDto](Responses/Api/ListDocsResponseDto.md) +* [SearchPersonResponseDto](Responses/Api/SearchPersonResponseDto.md) +* [ReviewDocsResponseDto](Responses/Api/ReviewDocsResponseDto.md) +* [SeasonDocsResponseDto](Responses/Api/SeasonDocsResponseDto.md) +* [StudioDocsResponseDto](Responses/Api/StudioDocsResponseDto.md) +* [PersonAwardDocsResponseDto](Responses/Api/PersonAwardDocsResponseDto.md) +* [SearchStudioResponseDto](Responses/Api/SearchStudioResponseDto.md) +## Responses/Errors/ + +* [NotFoundErrorResponseDto](Responses/Errors/NotFoundErrorResponseDto.md) +* [UnauthorizedErrorResponseDto](Responses/Errors/UnauthorizedErrorResponseDto.md) +* [ForbiddenErrorResponseDto](Responses/Errors/ForbiddenErrorResponseDto.md) +## Attributes/ + +* [ApiField](Attributes/ApiField.md) +* [Sensitive](Attributes/Sensitive.md) +* [Validation](Attributes/Validation.md) diff --git a/docs/dev/kinopoiskdev/Responses/.nav.yml b/docs/dev/kinopoiskdev/Responses/.nav.yml new file mode 100644 index 0000000..24186ea --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/.nav.yml @@ -0,0 +1,7 @@ +title: Ответы API +nav: + - BaseDocsResponseDto: BaseDocsResponseDto.md + - BaseResponseDto: BaseResponseDto.md + - ErrorResponseDto: ErrorResponseDto.md + - API ответы: Api/ + - Ошибки: Errors/ \ No newline at end of file diff --git a/docs/dev/kinopoiskdev/Responses/Api/.nav.yml b/docs/dev/kinopoiskdev/Responses/Api/.nav.yml new file mode 100644 index 0000000..0fc756b --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Api/.nav.yml @@ -0,0 +1,16 @@ +title: API ответы +nav: + - ImageDocsResponseDto: ImageDocsResponseDto.md + - KeywordDocsResponseDto: KeywordDocsResponseDto.md + - ListDocsResponseDto: ListDocsResponseDto.md + - MovieAwardDocsResponseDto: MovieAwardDocsResponseDto.md + - MovieDocsResponseDto: MovieDocsResponseDto.md + - PersonAwardDocsResponseDto: PersonAwardDocsResponseDto.md + - PersonDocsResponseDto: PersonDocsResponseDto.md + - PossibleValueDto: PossibleValueDto.md + - ReviewDocsResponseDto: ReviewDocsResponseDto.md + - SearchMovieResponseDto: SearchMovieResponseDto.md + - SearchPersonResponseDto: SearchPersonResponseDto.md + - SearchStudioResponseDto: SearchStudioResponseDto.md + - SeasonDocsResponseDto: SeasonDocsResponseDto.md + - StudioDocsResponseDto: StudioDocsResponseDto.md \ No newline at end of file diff --git a/docs/dev/kinopoiskdev/Responses/Api/ImageDocsResponseDto.md b/docs/dev/kinopoiskdev/Responses/Api/ImageDocsResponseDto.md new file mode 100644 index 0000000..6e56367 --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Api/ImageDocsResponseDto.md @@ -0,0 +1,54 @@ +# ImageDocsResponseDto + +**Описание:** DTO ответа для результатов поиска изображений с пагинацией +Класс предоставляет структурированный доступ к результатам поиска изображений +от API Kinopoisk.dev с поддержкой пагинации и специализированными методами +для фильтрации, сортировки и группировки изображений по различным критериям. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Image`: +* `\KinopoiskDev\Responses\BaseDocsResponseDto`: + +## `fromArray()` + +**Описание:** Создает экземпляр DTO из массива данных API +Фабричный метод для создания объекта ImageDocsResponseDto из массива данных, +полученных от API Kinopoisk.dev. Метод использует DataManager для безопасного +преобразования каждого элемента массива docs в объект Image и инициализирует +все параметры пагинации значениями по умолчанию в случае их отсутствия. +- docs: array - массив данных изображений для преобразования +- total: int - общее количество изображений в результате +- limit: int - максимальное количество элементов на странице +- page: int - номер текущей страницы (начиная с 1) +- pages: int - общее количество страниц + +**Возвращает:** `static` Новый экземпляр ImageDocsResponseDto с преобразованными данными + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: При ошибках валидации класса Image или отсутствии метода fromArray + +**См. также:** + +* `\KinopoiskDev\Utils\DataManager::parseObjectArray`: () Используется для преобразования массива объектов +* `\KinopoiskDev\Models\Image::fromArray`: () Метод создания объектов Image из массива данных + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует весь объект DTO в массив, включая преобразование +всех объектов Image в массивы. Полезно для сериализации, +кэширования или передачи данных в другие системы. +- docs: array - массив данных изображений +- total: int - общее количество изображений +- limit: int - лимит на страницу +- page: int - номер текущей страницы +- pages: int - общее количество страниц + +**Возвращает:** `array` Массив данных, содержащий: + diff --git a/docs/dev/kinopoiskdev/Responses/Api/KeywordDocsResponseDto.md b/docs/dev/kinopoiskdev/Responses/Api/KeywordDocsResponseDto.md new file mode 100644 index 0000000..47a7c4f --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Api/KeywordDocsResponseDto.md @@ -0,0 +1,80 @@ +# KeywordDocsResponseDto + +**Описание:** DTO для ответа API с ключевыми словами +Этот класс представляет структурированный ответ от API Kinopoisk.dev +при запросе списка ключевых слов с поддержкой пагинации. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +## `__construct()` + +**Описание:** Конструктор DTO ответа с ключевыми словами + +**Параметры:** + +* `$docs` (Keyword[]): Массив объектов ключевых слов +* `$total` (int): Общее количество ключевых слов, соответствующих запросу +* `$limit` (int): Максимальное количество ключевых слов на странице +* `$page` (int): Номер текущей страницы +* `$pages` (int): Общее количество страниц + +## `getKeywordTitles()` + +**Описание:** Получает все названия ключевых слов + +**Возвращает:** `string[]` Массив названий ключевых слов + +## `getPopularKeywords()` + +**Описание:** Фильтрует ключевые слова по популярности + +**Параметры:** + +* `$threshold` (int): Минимальное количество связанных фильмов + +**Возвращает:** `Keyword[]` Массив популярных ключевых слов + +## `searchByTitle()` + +**Описание:** Ищет ключевые слова, содержащие указанный текст + +**Параметры:** + +* `$searchText` (string): Текст для поиска в названиях + +**Возвращает:** `Keyword[]` Массив найденных ключевых слов + +## `groupByPopularity()` + +**Описание:** Группирует ключевые слова по количеству связанных фильмов + +**Возвращает:** `array` Массив групп ключевых слов + +## `getKeywordsForMovie()` + +**Описание:** Получает ключевые слова, связанные с указанным фильмом + +**Параметры:** + +* `$movieId` (int): ID фильма + +**Возвращает:** `Keyword[]` Массив ключевых слов, связанных с фильмом + +## `getStatistics()` + +**Описание:** Получает статистику по ключевым словам + +**Возвращает:** `array` Статистика + +## `getRecentlyCreated()` + +**Описание:** Получает недавно созданные ключевые слова + +**Параметры:** + +* `$days` (int): Количество дней для считания "недавними" + +**Возвращает:** `Keyword[]` Массив недавно созданных ключевых слов + diff --git a/docs/dev/kinopoiskdev/Responses/Api/ListDocsResponseDto.md b/docs/dev/kinopoiskdev/Responses/Api/ListDocsResponseDto.md new file mode 100644 index 0000000..97e4512 --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Api/ListDocsResponseDto.md @@ -0,0 +1,48 @@ +# ListDocsResponseDto + +**Описание:** DTO для ответа API с коллекциями фильмов +Этот класс представляет структурированный ответ от API Kinopoisk.dev +при запросе списка коллекций фильмов с поддержкой пагинации. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +## `__construct()` + +**Описание:** Конструктор DTO ответа с коллекциями + +**Параметры:** + +* `$docs` (Lists[]): Массив объектов коллекций фильмов +* `$total` (int): Общее количество коллекций, соответствующих запросу +* `$limit` (int): Максимальное количество коллекций на странице +* `$page` (int): Номер текущей страницы +* `$pages` (int): Общее количество страниц + +## `getListNames()` + +**Описание:** Получает все названия коллекций + +**Возвращает:** `string[]` Массив названий коллекций + +## `filterByCategory()` + +**Описание:** Фильтрует коллекции по категории + +**Параметры:** + +* `$category` (string): Название категории для фильтрации + +**Возвращает:** `Lists[]` Массив коллекций указанной категории + +## `getPopularLists()` + +**Описание:** Получает популярные коллекции (с большим количеством фильмов) + +**Параметры:** + +* `$threshold` (int): Минимальное количество фильмов для считания коллекции популярной + +**Возвращает:** `Lists[]` Массив популярных коллекций + diff --git a/docs/dev/kinopoiskdev/Responses/Api/MovieAwardDocsResponseDto.md b/docs/dev/kinopoiskdev/Responses/Api/MovieAwardDocsResponseDto.md new file mode 100644 index 0000000..ed7ba68 --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Api/MovieAwardDocsResponseDto.md @@ -0,0 +1,44 @@ +# MovieAwardDocsResponseDto + +**Описание:** DTO для представления ответа API с наградами фильмов и информацией о пагинации +Расширяет базовый класс BaseDocsResponseDto для специализированной работы с коллекциями +наград фильмов, полученных от API Kinopoisk.dev. Предоставляет стандартный интерфейс +для работы с постраничными результатами поиска наград фильмов, включая метаданные +о количестве результатов и навигации по страницам. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\MovieAward`: Класс модели награды фильма +* `\KinopoiskDev\Responses\BaseDocsResponseDto`: Базовый класс для ответов с документами +* `\KinopoiskDev\Utils\DataManager`: Утилита для преобразования данных + +## `fromArray()` + +**Описание:** Создает экземпляр DTO из массива данных API +Фабричный метод для создания объекта MovieAwardDocsResponseDto из массива данных, +полученных от API Kinopoisk.dev. Использует DataManager для безопасного преобразования +элементов массива docs в объекты MovieAward и устанавливает значения по умолчанию +для всех параметров пагинации в случае их отсутствия в исходных данных. +- docs: array - массив данных наград фильмов для преобразования в объекты MovieAward +- total: int - общее количество наград в результате поиска (по умолчанию 0) +- limit: int - максимальное количество элементов на странице (по умолчанию 10) +- page: int - номер текущей страницы, начиная с 1 (по умолчанию 1) +- pages: int - общее количество доступных страниц (по умолчанию 0) +отсутствии метода fromArray в классе MovieAward, +или некорректной структуре данных + +**Возвращает:** `static` Новый экземпляр MovieAwardDocsResponseDto с преобразованными данными наград + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: При ошибках валидации класса MovieAward, + +**См. также:** + +* `\KinopoiskDev\Utils\DataManager::parseObjectArray`: () Метод для преобразования массива в объекты +* `\KinopoiskDev\Models\MovieAward::fromArray`: () Фабричный метод создания объекта награды + diff --git a/docs/dev/kinopoiskdev/Responses/Api/MovieDocsResponseDto.md b/docs/dev/kinopoiskdev/Responses/Api/MovieDocsResponseDto.md new file mode 100644 index 0000000..11338b1 --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Api/MovieDocsResponseDto.md @@ -0,0 +1,41 @@ +# MovieDocsResponseDto + +**Описание:** Объект-контейнер для ответа API с данными о фильмах и информацией о пагинации +Представляет стандартный ответ API Kinopoisk.dev для запросов возвращающих +коллекцию фильмов с поддержкой пагинации. Содержит массив документов фильмов +и метаданные для постраничной навигации. + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Movie`: Для структуры отдельного фильма +* `\KinopoiskDev\Responses\ErrorResponseDto`: Для обработки ошибок API + +## `fromArray()` + +**Описание:** Создает экземпляр DTO из массива данных API +Фабричный метод для создания объекта MovieDocsResponseDto из массива данных, +полученных от API Kinopoisk.dev. Метод использует значения по умолчанию +для всех параметров пагинации в случае их отсутствия в исходных данных. +Массив docs остается без преобразования и передается как есть. +- docs: array - массив данных фильмов (остается без преобразования) +- total: int - общее количество фильмов в результате (по умолчанию 0) +- limit: int - максимальное количество элементов на странице (по умолчанию 10) +- page: int - номер текущей страницы, начиная с 1 (по умолчанию 1) +- pages: int - общее количество страниц (по умолчанию 0) + +**С версии:** 1.0.0 + +**Возвращает:** `static` Новый экземпляр MovieDocsResponseDto с установленными данными пагинации + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: + +**См. также:** + +* `\KinopoiskDev\Models\Movie`: Класс модели фильма для элементов массива docs +* `\KinopoiskDev\Responses\BaseDocsResponseDto::__construct`: () Конструктор с параметрами +* `\KinopoiskDev\Responses\BaseResponseDto::fromArray`: () Родительский абстрактный метод + diff --git a/docs/dev/kinopoiskdev/Responses/Api/PersonAwardDocsResponseDto.md b/docs/dev/kinopoiskdev/Responses/Api/PersonAwardDocsResponseDto.md new file mode 100644 index 0000000..399d1de --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Api/PersonAwardDocsResponseDto.md @@ -0,0 +1,41 @@ +# PersonAwardDocsResponseDto + +**Описание:** DTO для результатов поиска наград персон с пагинацией +Класс предназначен для представления ответа API при поиске наград персон. +Наследуется от BaseDocsResponseDto и специализируется на работе с коллекцией +объектов PersonAward. Обеспечивает типизированный доступ к данным наград +с поддержкой пагинации результатов. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\PersonAward`: +* `\KinopoiskDev\Responses\BaseDocsResponseDto`: + +## `fromArray()` + +**Описание:** Создает экземпляр DTO из массива данных API +Фабричный метод для создания объекта PersonAwardDocsResponseDto из массива данных, +полученных от API Kinopoisk.dev. Метод использует DataManager для безопасного +преобразования каждого элемента массива docs в объект PersonAward и инициализирует +все параметры пагинации значениями по умолчанию в случае их отсутствия. +- docs: array - массив данных наград персон для преобразования +- total: int - общее количество наград в результате +- limit: int - максимальное количество элементов на странице +- page: int - номер текущей страницы (начиная с 1) +- pages: int - общее количество страниц + +**Возвращает:** `static` Новый экземпляр PersonAwardDocsResponseDto с преобразованными данными + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: При ошибках валидации класса PersonAward или отсутствии метода fromArray + +**См. также:** + +* `\KinopoiskDev\Utils\DataManager::parseObjectArray`: () Используется для преобразования массива объектов +* `\KinopoiskDev\Models\PersonAward::fromArray`: () Метод создания объектов PersonAward из массива данных + diff --git a/docs/dev/kinopoiskdev/Responses/Api/PersonDocsResponseDto.md b/docs/dev/kinopoiskdev/Responses/Api/PersonDocsResponseDto.md new file mode 100644 index 0000000..89d04b2 --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Api/PersonDocsResponseDto.md @@ -0,0 +1,43 @@ +# PersonDocsResponseDto + +**Описание:** DTO ответа для результатов поиска персон с пагинацией +Класс предназначен для представления ответа API при поиске персон. +Наследуется от BaseDocsResponseDto и специализируется на работе с коллекцией +объектов Person. Обеспечивает типизированный доступ к данным персон +с поддержкой пагинации результатов. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Person`: +* `\KinopoiskDev\Responses\BaseDocsResponseDto`: + +## `fromArray()` + +**Описание:** Создает экземпляр DTO из массива данных API +Фабричный метод для создания объекта PersonDocsResponseDto из массива данных, +полученных от API Kinopoisk.dev. Метод использует DataManager для безопасного +преобразования каждого элемента массива docs в объект Person и инициализирует +все параметры пагинации значениями по умолчанию в случае их отсутствия. +- docs: array - массив данных персон для преобразования +- total: int - общее количество персон в результате +- limit: int - максимальное количество элементов на странице +- page: int - номер текущей страницы (начиная с 1) +- pages: int - общее количество страниц + +**С версии:** 1.0.0 + +**Возвращает:** `static` Новый экземпляр PersonDocsResponseDto с преобразованными данными + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: При ошибках валидации класса Person или отсутствии метода fromArray + +**См. также:** + +* `\KinopoiskDev\Utils\DataManager::parseObjectArray`: () Используется для преобразования массива объектов +* `\KinopoiskDev\Models\Person::fromArray`: () Метод создания объектов Person из массива данных + diff --git a/docs/dev/kinopoiskdev/Responses/Api/PossibleValueDto.md b/docs/dev/kinopoiskdev/Responses/Api/PossibleValueDto.md new file mode 100644 index 0000000..78baf01 --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Api/PossibleValueDto.md @@ -0,0 +1,58 @@ +# PossibleValueDto + +**Описание:** Класс для представления возможного значения поля +Представляет информацию о возможном значении для определенного поля API, +включая само значение и вспомогательный slug. Используется для получения +списка доступных значений для фильтрации по конкретным полям. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\ItemName`: Для простых названий элементов + +## `__construct()` + +**Описание:** Конструктор для создания объекта возможного значения +Создает новый экземпляр класса PossibleValueDto с указанными параметрами. +Оба параметра являются опциональными и могут быть null при отсутствии +соответствующей информации в источнике данных. + +**Параметры:** + +* `$name` (string|null): Значение по которому нужно делать запрос в базу данных +* `$slug` (string|null): Вспомогательное значение для идентификации + +## `__toString()` + +**Описание:** Возвращает строковое представление возможного значения +Формирует читаемое представление возможного значения, предпочитая +название перед slug-ом. Если оба значения отсутствуют, возвращает +сообщение о пустом значении. + +**Возвращает:** `string` Строковое представление возможного значения + +## `fromArray()` + +**Описание:** Создает объект PossibleValueDto из массива данных API +Фабричный метод для создания экземпляра класса PossibleValueDto из массива данных, +полученных от API Kinopoisk.dev. Безопасно обрабатывает отсутствующие +значения, устанавливая их в null. +- name: string|null - значение для запроса в базу данных +- slug: string|null - вспомогательное значение + +**Возвращает:** `static` Новый экземпляр класса PossibleValueDto с данными из массива + +## `toArray()` + +**Описание:** Преобразует объект в массив данных +Конвертирует текущий экземпляр класса PossibleValueDto в массив, +совместимый с форматом API Kinopoisk.dev. Используется для сериализации +данных при отправке запросов к API или для экспорта данных. +- name: string|null - значение для запроса +- slug: string|null - вспомогательное значение + +**Возвращает:** `array` Массив с данными о возможном значении, содержащий ключи: + diff --git a/docs/dev/kinopoiskdev/Responses/Api/ReviewDocsResponseDto.md b/docs/dev/kinopoiskdev/Responses/Api/ReviewDocsResponseDto.md new file mode 100644 index 0000000..adc630b --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Api/ReviewDocsResponseDto.md @@ -0,0 +1,43 @@ +# ReviewDocsResponseDto + +**Описание:** DTO ответа для результатов поиска рецензий с пагинацией +Класс предназначен для представления ответа API при поиске рецензий. +Наследуется от BaseDocsResponseDto и специализируется на работе с коллекцией +объектов Review. Обеспечивает типизированный доступ к данным рецензий +с поддержкой пагинации результатов. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Review`: +* `\KinopoiskDev\Responses\BaseDocsResponseDto`: + +## `fromArray()` + +**Описание:** Создает экземпляр DTO из массива данных API +Фабричный метод для создания объекта ReviewDocsResponseDto из массива данных, +полученных от API Kinopoisk.dev. Метод использует DataManager для безопасного +преобразования каждого элемента массива docs в объект Review и инициализирует +все параметры пагинации значениями по умолчанию в случае их отсутствия. +- docs: array - массив данных рецензий для преобразования +- total: int - общее количество рецензий в результате (по умолчанию 0) +- limit: int - максимальное количество элементов на странице (по умолчанию 10) +- page: int - номер текущей страницы, начиная с 1 (по умолчанию 1) +- pages: int - общее количество страниц (по умолчанию 0) + +**С версии:** 1.0.0 + +**Возвращает:** `static` Новый экземпляр ReviewDocsResponseDto с преобразованными данными + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: При ошибках валидации класса Review или отсутствии метода fromArray + +**См. также:** + +* `\KinopoiskDev\Utils\DataManager::parseObjectArray`: () Используется для преобразования массива объектов +* `\KinopoiskDev\Models\Review::fromArray`: () Метод создания объектов Review из массива данных + diff --git a/docs/dev/kinopoiskdev/Responses/Api/SearchMovieResponseDto.md b/docs/dev/kinopoiskdev/Responses/Api/SearchMovieResponseDto.md new file mode 100644 index 0000000..3141616 --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Api/SearchMovieResponseDto.md @@ -0,0 +1,38 @@ +# SearchMovieResponseDto + +**Описание:** Объект-контейнер для ответа API с данными о фильмах и информацией о пагинации +Представляет стандартный ответ API Kinopoisk.dev для запросов возвращающих +коллекцию фильмов с поддержкой пагинации. Содержит массив документов фильмов +и метаданные для постраничной навигации. + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Movie`: Для структуры отдельного фильма +* `\KinopoiskDev\Responses\ErrorResponseDto`: Для обработки ошибок API + +## `fromArray()` + +**Описание:** Создает экземпляр DTO из массива данных API +Фабричный метод для создания объекта DTO из ассоциативного массива, +полученного от API Kinopoisk.dev. Метод использует DataManager для безопасного +преобразования каждого элемента массива docs в объект SearchMovie и инициализирует +все параметры пагинации значениями по умолчанию в случае их отсутствия. +- docs: array - массив данных поиска фильмов для преобразования +- total: int - общее количество найденных фильмов в результате +- limit: int - максимальное количество элементов на странице (по умолчанию 10) +- page: int - номер текущей страницы (начиная с 1, по умолчанию 1) +- pages: int - общее количество страниц (по умолчанию 0) + +**Возвращает:** `static` Новый экземпляр текущего класса DTO с преобразованными данными SearchMovie + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: При ошибках валидации класса SearchMovie или отсутствии метода fromArray + +**См. также:** + +* `\KinopoiskDev\Utils\DataManager::parseObjectArray`: () Используется для преобразования массива объектов +* `\KinopoiskDev\Models\SearchMovie::fromArray`: () Метод создания объектов SearchMovie из массива данных + diff --git a/docs/dev/kinopoiskdev/Responses/Api/SearchPersonResponseDto.md b/docs/dev/kinopoiskdev/Responses/Api/SearchPersonResponseDto.md new file mode 100644 index 0000000..97b472c --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Api/SearchPersonResponseDto.md @@ -0,0 +1,38 @@ +# SearchPersonResponseDto + +**Описание:** Объект-контейнер для ответа API с данными о фильмах и информацией о пагинации +Представляет стандартный ответ API Kinopoisk.dev для запросов возвращающих +коллекцию фильмов с поддержкой пагинации. Содержит массив документов фильмов +и метаданные для постраничной навигации. + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Movie`: Для структуры отдельного фильма +* `\KinopoiskDev\Responses\ErrorResponseDto`: Для обработки ошибок API + +## `fromArray()` + +**Описание:** Создает экземпляр DTO из массива данных API +Фабричный метод для создания объекта DTO из ассоциативного массива, +полученного от API Kinopoisk.dev. Метод использует DataManager для безопасного +преобразования каждого элемента массива docs в объект SearchMovie и инициализирует +все параметры пагинации значениями по умолчанию в случае их отсутствия. +- docs: array - массив данных поиска фильмов для преобразования +- total: int - общее количество найденных фильмов в результате +- limit: int - максимальное количество элементов на странице (по умолчанию 10) +- page: int - номер текущей страницы (начиная с 1, по умолчанию 1) +- pages: int - общее количество страниц (по умолчанию 0) + +**Возвращает:** `static` Новый экземпляр текущего класса DTO с преобразованными данными SearchMovie + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: При ошибках валидации класса SearchMovie или отсутствии метода fromArray + +**См. также:** + +* `\KinopoiskDev\Utils\DataManager::parseObjectArray`: () Используется для преобразования массива объектов +* `\KinopoiskDev\Models\SearchMovie::fromArray`: () Метод создания объектов SearchMovie из массива данных + diff --git a/docs/dev/kinopoiskdev/Responses/Api/SearchStudioResponseDto.md b/docs/dev/kinopoiskdev/Responses/Api/SearchStudioResponseDto.md new file mode 100644 index 0000000..4f04d38 --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Api/SearchStudioResponseDto.md @@ -0,0 +1,2 @@ +# SearchStudioResponseDto + diff --git a/docs/dev/kinopoiskdev/Responses/Api/SeasonDocsResponseDto.md b/docs/dev/kinopoiskdev/Responses/Api/SeasonDocsResponseDto.md new file mode 100644 index 0000000..e4837d7 --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Api/SeasonDocsResponseDto.md @@ -0,0 +1,42 @@ +# SeasonDocsResponseDto + +**Описание:** DTO ответа для результатов поиска сезонов с пагинацией +Класс представляет типизированный ответ API при поиске сезонов сериалов. +Наследуется от BaseDocsResponseDto и специализируется на работе с коллекцией +объектов Season. Обеспечивает безопасное преобразование данных API в типизированные +объекты PHP с поддержкой пагинации результатов поиска. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Models\Season`: Класс модели сезона для элементов массива docs +* `\KinopoiskDev\Responses\BaseDocsResponseDto`: Базовый класс для ответов с пагинацией + +## `fromArray()` + +**Описание:** Создает экземпляр DTO из массива данных API +Фабричный метод для создания объекта SeasonDocsResponseDto из массива данных, +полученных от API Kinopoisk.dev. Использует DataManager для безопасного +преобразования каждого элемента массива docs в объект Season и устанавливает +параметры пагинации с значениями по умолчанию при их отсутствии. +- docs: array - массив данных сезонов для преобразования в объекты Season +- total: int - общее количество сезонов в результате поиска (по умолчанию 0) +- limit: int - максимальное количество элементов на странице (по умолчанию 10) +- page: int - номер текущей страницы, начиная с 1 (по умолчанию 1) +- pages: int - общее количество страниц в результате (по умолчанию 0) + +**Возвращает:** `static` Новый экземпляр SeasonDocsResponseDto с преобразованными данными сезонов + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: При ошибках валидации класса Season или отсутствии метода fromArray + +**См. также:** + +* `\KinopoiskDev\Utils\DataManager::parseObjectArray`: () Используется для преобразования массива объектов +* `\KinopoiskDev\Models\Season::fromArray`: () Метод создания объектов Season из массива данных +* `\KinopoiskDev\Responses\BaseResponseDto::fromArray`: () Родительский абстрактный метод + diff --git a/docs/dev/kinopoiskdev/Responses/Api/StudioDocsResponseDto.md b/docs/dev/kinopoiskdev/Responses/Api/StudioDocsResponseDto.md new file mode 100644 index 0000000..6556084 --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Api/StudioDocsResponseDto.md @@ -0,0 +1,15 @@ +# StudioDocsResponseDto + +## `fromArray()` + +**Описание:** Создает экземпляр DTO из массива данных +Фабричный метод для создания объекта DTO из ассоциативного массива, +полученного из API ответа. Базовый метод, который должен быть переопределен +в дочерних классах для правильной обработки типизированных документов. + +**Возвращает:** `static` Экземпляр конкретного DTO класса + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: + diff --git a/docs/dev/kinopoiskdev/Responses/BaseDocsResponseDto.md b/docs/dev/kinopoiskdev/Responses/BaseDocsResponseDto.md new file mode 100644 index 0000000..59af2a5 --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/BaseDocsResponseDto.md @@ -0,0 +1,176 @@ +# BaseDocsResponseDto + +**Описание:** Базовый класс для всех DTO ответов с пагинацией документов +Предоставляет общую функциональность для пагинированных ответов API, +включая навигацию по страницам и получение элементов коллекции. +Этот абстрактный класс расширяет BaseResponseDto и добавляет +специфичные для пагинации методы. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Responses\Api\MovieDocsResponseDto`: +* `\KinopoiskDev\Responses\Api\PersonDocsResponseDto`: +* `\KinopoiskDev\Responses\BaseResponseDto`: + +## `__construct()` + +**Описание:** Конструктор для создания DTO пагинированного ответа +Инициализирует все необходимые параметры пагинации со значениями по умолчанию. +Все свойства являются для обеспечения неизменности данных. + +**С версии:** 1.0.0 + +**Параметры:** + +* `$total` (int): Общее количество доступных документов в коллекции +* `$limit` (int): Максимальное количество документов на одной странице +* `$page` (int): Номер текущей страницы (начинается с 1) +* `$pages` (int): Общее количество страниц в коллекции + +## `getNextPage()` + +**Описание:** Возвращает номер следующей страницы +Вычисляет номер следующей страницы на основе текущей позиции. +Возвращает null, если текущая страница является последней. + +**С версии:** 1.0.0 + +**Возвращает:** `int|null` Номер следующей страницы или null если следующей страницы нет + +**См. также:** + +* `hasNextPage`: () Для проверки существования следующей страницы + +## `hasNextPage()` + +**Описание:** Проверяет наличие следующей страницы +Определяет, есть ли еще страницы после текущей на основе +сравнения номера текущей страницы с общим количеством страниц. + +**С версии:** 1.0.0 + +**Возвращает:** `bool true` если есть следующая страница, false в противном случае + +**См. также:** + +* `getNextPage`: () Для получения номера следующей страницы + +## `getPreviousPage()` + +**Описание:** Возвращает номер предыдущей страницы +Вычисляет номер предыдущей страницы на основе текущей позиции. +Возвращает null, если текущая страница является первой. + +**С версии:** 1.0.0 + +**Возвращает:** `int|null` Номер предыдущей страницы или null если предыдущей страницы нет + +**См. также:** + +* `hasPreviousPage`: () Для проверки существования предыдущей страницы + +## `hasPreviousPage()` + +**Описание:** Проверяет наличие предыдущей страницы +Определяет, есть ли страницы перед текущей на основе +сравнения номера текущей страницы с единицей. + +**С версии:** 1.0.0 + +**Возвращает:** `bool true` если есть предыдущая страница, false в противном случае + +**См. также:** + +* `getPreviousPage`: () Для получения номера предыдущей страницы + +## `getFirst()` + +**Описание:** Возвращает первый элемент коллекции +Получает первый документ из массива docs текущей страницы. +Возвращает null, если коллекция пуста. + +**С версии:** 1.0.0 + +**Возвращает:** `mixed` Первый документ или null если коллекция пуста + +**См. также:** + +* `getLast`: () Для получения последнего элемента +* `isEmpty`: () Для проверки пустоты коллекции + +## `getLast()` + +**Описание:** Возвращает последний элемент коллекции +Получает последний документ из массива docs текущей страницы. +Создает копию массива для избежания изменения свойства. +Возвращает null, если коллекция пуста. + +**С версии:** 1.0.0 + +**Возвращает:** `mixed` Последний документ или null если коллекция пуста + +**См. также:** + +* `getFirst`: () Для получения первого элемента +* `isEmpty`: () Для проверки пустоты коллекции + +## `isEmpty()` + +**Описание:** Проверяет пустоту коллекции результатов +Определяет, содержит ли текущая страница какие-либо документы. + +**С версии:** 1.0.0 + +**Возвращает:** `bool true` если коллекция пуста, false в противном случае + +**См. также:** + +* `getCurrentPageCount`: () Для получения точного количества элементов + +## `getCurrentPageCount()` + +**Описание:** Возвращает количество результатов на текущей странице +Подсчитывает фактическое количество документов в массиве docs +для текущей страницы. + +**С версии:** 1.0.0 + +**Возвращает:** `int` Количество документов на текущей странице + +**См. также:** + +* `isEmpty`: () Для проверки пустоты коллекции + +## `fromArray()` + +**Описание:** Создает экземпляр DTO из массива данных +Фабричный метод для создания объекта DTO из ассоциативного массива, +полученного из API ответа. Каждый дочерний класс должен реализовать +этот метод в соответствии со своей структурой данных. + +Создает экземпляр DTO из массива данных +Фабричный метод для создания объекта DTO из ассоциативного массива, +полученного из API ответа. Базовый метод, который должен быть переопределен +в дочерних классах для правильной обработки типизированных документов. + +**Возвращает:** `static` Экземпляр конкретного DTO класса + +## `toArray()` + +**Описание:** Преобразует DTO в ассоциативный массив +Метод для сериализации объекта DTO в массив, пригодный для +передачи в JSON или другие форматы. Структура массива должна +соответствовать формату API ответа. + +Конвертирует объект в массив для сериализации +Преобразует все свойства пагинации в ассоциативный массив, +подходящий для JSON-сериализации или передачи в API. + +**С версии:** 1.0.0 + +**Возвращает:** `array` Ассоциативный массив со всеми данными пагинации + diff --git a/docs/dev/kinopoiskdev/Responses/BaseResponseDto.md b/docs/dev/kinopoiskdev/Responses/BaseResponseDto.md new file mode 100644 index 0000000..f84e831 --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/BaseResponseDto.md @@ -0,0 +1,35 @@ +# BaseResponseDto + +**Описание:** Базовый класс для всех DTO ответов API +Обеспечивает единообразный интерфейс для всех объектов передачи данных ответов, +предоставляя стандартные методы для создания из массива и преобразования в массив. +Все конкретные DTO ответов должны наследоваться от этого класса. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Responses\Api\MovieDocsResponseDto`: +* `\KinopoiskDev\Responses\Api\PersonDocsResponseDto`: +* `\KinopoiskDev\Responses\Api\SearchMovieResponseDto`: + +## `fromArray()` + +**Описание:** Создает экземпляр DTO из массива данных +Фабричный метод для создания объекта DTO из ассоциативного массива, +полученного из API ответа. Каждый дочерний класс должен реализовать +этот метод в соответствии со своей структурой данных. + +**Возвращает:** `static` Экземпляр конкретного DTO класса + +## `toArray()` + +**Описание:** Преобразует DTO в ассоциативный массив +Метод для сериализации объекта DTO в массив, пригодный для +передачи в JSON или другие форматы. Структура массива должна +соответствовать формату API ответа. + +**Возвращает:** `array` Ассоциативный массив с данными DTO + diff --git a/docs/dev/kinopoiskdev/Responses/ErrorResponseDto.md b/docs/dev/kinopoiskdev/Responses/ErrorResponseDto.md new file mode 100644 index 0000000..7817f57 --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/ErrorResponseDto.md @@ -0,0 +1,55 @@ +# ErrorResponseDto + +**Описание:** DTO для представления ответа об ошибке API +Класс инкапсулирует информацию об ошибке, возвращаемой API Kinopoisk.dev, +включая HTTP статус код, сообщение об ошибке и тип ошибки. +Используется для унифицированной обработки ошибочных ответов API. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `BaseResponseDto`: + +## `__construct()` + +**Описание:** Конструктор для создания DTO ошибки +Инициализирует все обязательные поля ответа об ошибке. +Все свойства являются для обеспечения неизменности данных. + +**Параметры:** + +* `$statusCode` (int): HTTP статус код ошибки (например, 400, 401, 403, 404, 500) +* `$message` (string): Человекочитаемое сообщение об ошибке на русском языке +* `$error` (string): Краткое техническое описание типа ошибки (например, "Bad Request", "Unauthorized") + +## `fromArray()` + +**Описание:** Создает экземпляр DTO из массива данных +Фабричный метод для создания объекта DTO из ассоциативного массива, +полученного из API ответа. Каждый дочерний класс должен реализовать +этот метод в соответствии со своей структурой данных. + +Создает экземпляр DTO ошибки из массива данных API ответа. +Извлекает обязательные поля statusCode, message и error из массива. + +**Возвращает:** `static` Экземпляр ErrorResponseDto с данными ошибки + +**Исключения:** + +* `\InvalidArgumentException`: Если в массиве отсутствуют обязательные поля + +## `toArray()` + +**Описание:** Преобразует DTO в ассоциативный массив +Метод для сериализации объекта DTO в массив, пригодный для +передачи в JSON или другие форматы. Структура массива должна +соответствовать формату API ответа. + +Преобразует DTO ошибки в ассоциативный массив для сериализации. +Структура возвращаемого массива соответствует формату API ответа. + +**Возвращает:** `array` Ассоциативный массив с полями statusCode, message и error + diff --git a/docs/dev/kinopoiskdev/Responses/Errors/.nav.yml b/docs/dev/kinopoiskdev/Responses/Errors/.nav.yml new file mode 100644 index 0000000..610fccf --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Errors/.nav.yml @@ -0,0 +1,5 @@ +title: Ошибки +nav: + - ForbiddenErrorResponseDto: ForbiddenErrorResponseDto.md + - NotFoundErrorResponseDto: NotFoundErrorResponseDto.md + - UnauthorizedErrorResponseDto: UnauthorizedErrorResponseDto.md \ No newline at end of file diff --git a/docs/dev/kinopoiskdev/Responses/Errors/ForbiddenErrorResponseDto.md b/docs/dev/kinopoiskdev/Responses/Errors/ForbiddenErrorResponseDto.md new file mode 100644 index 0000000..3d7ab68 --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Errors/ForbiddenErrorResponseDto.md @@ -0,0 +1,53 @@ +# ForbiddenErrorResponseDto + +**Описание:** DTO для представления ответа с ошибкой доступа запрещен (HTTP 403) +Этот класс наследует от BaseResponseDto и предоставляет специализированное +представление ошибки 403 Forbidden, которая возникает при превышении дневного +лимита запросов к API Kinopoisk.dev. Все свойства класса являются +для обеспечения неизменности данных ответа. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `BaseResponseDto`: + +## `__construct()` + +**Описание:** Конструктор для создания DTO ошибки доступа запрещен +Инициализирует все свойства ответа об ошибке 403 Forbidden со значениями +по умолчанию. Все параметры являются для обеспечения неизменности +данных после создания объекта. + +**Параметры:** + +* `$statusCode` (int): HTTP статус код 403 +* `$message` (string): Сообщение об ошибке (по умолчанию: "Превышен дневной лимит!") +* `$error` (string): Техническое описание ошибки (по умолчанию: "Forbidden") + +## `fromArray()` + +**Описание:** Создает экземпляр DTO из массива данных +Фабричный метод для создания объекта DTO из ассоциативного массива, +полученного из API ответа. Каждый дочерний класс должен реализовать +этот метод в соответствии со своей структурой данных. + +Создает экземпляр DTO ошибки 403 из массива данных API ответа. +Использует значения по умолчанию для отсутствующих полей в массиве. + +**Возвращает:** `static` Экземпляр ForbiddenErrorResponseDto с данными ошибки + +## `toArray()` + +**Описание:** Преобразует DTO в ассоциативный массив +Метод для сериализации объекта DTO в массив, пригодный для +передачи в JSON или другие форматы. Структура массива должна +соответствовать формату API ответа. + +Преобразует DTO ошибки 403 в ассоциативный массив для сериализации. +Структура возвращаемого массива соответствует формату API ответа. + +**Возвращает:** `array` Ассоциативный массив с полями statusCode, message и error + diff --git a/docs/dev/kinopoiskdev/Responses/Errors/NotFoundErrorResponseDto.md b/docs/dev/kinopoiskdev/Responses/Errors/NotFoundErrorResponseDto.md new file mode 100644 index 0000000..ee78e61 --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Errors/NotFoundErrorResponseDto.md @@ -0,0 +1,56 @@ +# NotFoundErrorResponseDto + +**Описание:** DTO для представления ответа с ошибкой "не найдено" (HTTP 404) +Этот класс наследует от BaseResponseDto и предоставляет специализированное +представление ошибки 404 Not Found, которая возникает когда запрошенный +ресурс не найден или лимит запросов к API Kinopoisk.dev был превышен. +Все свойства класса являются для обеспечения неизменности данных ответа. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `BaseResponseDto`: Базовый класс для всех DTO ответов + +## `__construct()` + +**Описание:** Конструктор для создания DTO ошибки "не найдено" +Инициализирует все свойства ответа об ошибке 404 Not Found со значениями +по умолчанию. Все параметры являются для обеспечения неизменности +данных после создания объекта. + +**Параметры:** + +* `$statusCode` (int): HTTP статус код 404 +* `$message` (string): Сообщение об ошибке (по умолчанию: сообщение о превышении лимита) +* `$error` (string): Техническое описание ошибки (по умолчанию: "Not Found") + +## `fromArray()` + +**Описание:** Создает экземпляр DTO из массива данных +Фабричный метод для создания объекта DTO из ассоциативного массива, +полученного из API ответа. Каждый дочерний класс должен реализовать +этот метод в соответствии со своей структурой данных. + +Создает экземпляр DTO ошибки 404 из массива данных API ответа. +Использует значения по умолчанию для отсутствующих полей в массиве. +- statusCode: int - HTTP статус код (по умолчанию 404) +- message: string - сообщение об ошибке +- error: string - техническое описание ошибки + +**Возвращает:** `static` Экземпляр NotFoundErrorResponseDto с данными ошибки + +## `toArray()` + +**Описание:** Преобразует DTO в ассоциативный массив +Метод для сериализации объекта DTO в массив, пригодный для +передачи в JSON или другие форматы. Структура массива должна +соответствовать формату API ответа. + +Преобразует DTO ошибки 404 в ассоциативный массив для сериализации. +Структура возвращаемого массива соответствует формату API ответа. + +**Возвращает:** `array` Ассоциативный массив с полями statusCode, message и error + diff --git a/docs/dev/kinopoiskdev/Responses/Errors/UnauthorizedErrorResponseDto.md b/docs/dev/kinopoiskdev/Responses/Errors/UnauthorizedErrorResponseDto.md new file mode 100644 index 0000000..00e9191 --- /dev/null +++ b/docs/dev/kinopoiskdev/Responses/Errors/UnauthorizedErrorResponseDto.md @@ -0,0 +1,63 @@ +# UnauthorizedErrorResponseDto + +**Описание:** DTO для представления ответа об ошибке авторизации API +Специализированный класс для обработки ошибок авторизации (HTTP 401), +возникающих при отсутствии или недействительности токена доступа. +Наследуется от BaseResponseDto и предоставляет предустановленные +значения для типичных ошибок авторизации. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**См. также:** + +* `\KinopoiskDev\Responses\BaseResponseDto`: +* `\KinopoiskDev\Responses\ErrorResponseDto`: + +## `__construct()` + +**Описание:** Конструктор для создания DTO ошибки авторизации +Инициализирует объект с предустановленными значениями для типичных +ошибок авторизации. Все параметры имеют значения по умолчанию, +соответствующие стандартному ответу об отсутствии токена. +Все свойства являются для обеспечения неизменности данных. + +**Параметры:** + +* `$statusCode` (int): HTTP статус код авторизации (по умолчанию 401 - Unauthorized) +* `$message` (string): Сообщение об ошибке на русском языке (по умолчанию "В запросе не указан токен!") +* `$error` (string): Краткое техническое описание ошибки (по умолчанию "Unauthorized") + +## `fromArray()` + +**Описание:** Создает экземпляр DTO из массива данных +Фабричный метод для создания объекта DTO из ассоциативного массива, +полученного из API ответа. Каждый дочерний класс должен реализовать +этот метод в соответствии со своей структурой данных. + +Создает экземпляр DTO ошибки авторизации из массива данных API ответа. +Использует значения по умолчанию для отсутствующих полей, что обеспечивает +корректное создание объекта даже при неполных данных от API. +- statusCode: int - HTTP статус код (по умолчанию 401) +- message: string - сообщение об ошибке (по умолчанию "В запросе не указан токен!") +- error: string - тип ошибки (по умолчанию "Unauthorized") + +**Возвращает:** `static` Новый экземпляр UnauthorizedErrorResponseDto с данными ошибки авторизации + +## `toArray()` + +**Описание:** Преобразует DTO в ассоциативный массив +Метод для сериализации объекта DTO в массив, пригодный для +передачи в JSON или другие форматы. Структура массива должна +соответствовать формату API ответа. + +Преобразует DTO ошибки авторизации в ассоциативный массив для сериализации. +Структура возвращаемого массива полностью соответствует формату API ответа +и содержит все необходимые поля для обработки ошибки авторизации. +- statusCode: int - HTTP статус код ошибки +- message: string - человекочитаемое сообщение об ошибке +- error: string - техническое описание типа ошибки + +**Возвращает:** `array` Ассоциативный массив с полями: + diff --git a/docs/dev/kinopoiskdev/Services/.nav.yml b/docs/dev/kinopoiskdev/Services/.nav.yml new file mode 100644 index 0000000..af72fe9 --- /dev/null +++ b/docs/dev/kinopoiskdev/Services/.nav.yml @@ -0,0 +1,4 @@ +title: Сервисы +nav: + - CacheService: CacheService.md + - ValidationService: ValidationService.md diff --git a/docs/dev/kinopoiskdev/Services/CacheService.md b/docs/dev/kinopoiskdev/Services/CacheService.md new file mode 100644 index 0000000..d882d32 --- /dev/null +++ b/docs/dev/kinopoiskdev/Services/CacheService.md @@ -0,0 +1,236 @@ +# CacheService + +**Описание:** Сервис для работы с кэшем +Реализация интерфейса кэширования с использованием PSR-6 Cache. +Обеспечивает типобезопасную работу с различными драйверами кэша. +Поддерживает все основные операции кэширования: получение, сохранение, +удаление, проверка существования и массовые операции. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +**Пример:** +```php +// Создание с файловым кэшем +$cache = new CacheService(new FilesystemAdapter()); +// Сохранение данных +$cache->set('movie_123', $movieData, 3600); +// Получение данных +$data = $cache->get('movie_123'); +// Проверка существования +if ($cache->has('movie_123')) { +// Данные есть в кэше +} +``` + +**См. также:** + +* `\KinopoiskDev\Contracts\CacheInterface`: Интерфейс кэширования +* `\Psr\Cache\CacheItemPoolInterface`: PSR-6 интерфейс кэша + +## `__construct()` + +**Описание:** Конструктор сервиса кэширования +Создает новый экземпляр сервиса кэширования с указанным +PSR-6 адаптером кэша. + +**Параметры:** + +* `$cache` (CacheItemPoolInterface): PSR-6 кэш адаптер (FilesystemAdapter, RedisAdapter и т.д.) + +**Пример:** +```php +use Symfony\Component\Cache\Adapter\FilesystemAdapter; +use Symfony\Component\Cache\Adapter\RedisAdapter; +// Файловый кэш +$cache = new CacheService(new FilesystemAdapter()); +// Redis кэш +$redis = new \Redis(); +$redis->connect('127.0.0.1', 6379); +$cache = new CacheService(new RedisAdapter($redis)); +``` + +## `get()` + +**Описание:** Получает значение из кэша по ключу + +Получает значение из кэша по ключу. Возвращает null, если +ключ не найден или произошла ошибка при обращении к кэшу. +Автоматически нормализует ключ для соответствия PSR-6. + +**Параметры:** + +* `$key` (string): Ключ кэша для получения значения + +**Возвращает:** `mixed|null` Значение из кэша или null если не найдено + +**Пример:** +```php +$movie = $cache->get('movie_123'); +if ($movie !== null) { +// Используем данные из кэша +} +``` + +## `set()` + +**Описание:** Сохраняет значение в кэш + +Сохраняет значение в кэш с указанным временем жизни. +Автоматически нормализует ключ и обрабатывает ошибки. +Возвращает true при успешном сохранении, false при ошибке. + +**Параметры:** + +* `$key` (string): Ключ кэша для сохранения +* `$value` (mixed): Значение для сохранения в кэше +* `$ttl` (int): Время жизни в секундах (по умолчанию 1 час) + +**Возвращает:** `bool True` при успешном сохранении, false при ошибке + +**Пример:** +```php +// Сохранение на 1 час +$success = $cache->set('movie_123', $movieData); +// Сохранение на 30 минут +$success = $cache->set('movie_123', $movieData, 1800); +``` + +## `delete()` + +**Описание:** Удаляет значение из кэша + +Удаляет значение из кэша по ключу. Возвращает true при +успешном удалении или если ключ не существовал, false при ошибке. + +**Параметры:** + +* `$key` (string): Ключ кэша для удаления + +**Возвращает:** `bool True` при успешном удалении, false при ошибке + +**Пример:** +```php +$deleted = $cache->delete('movie_123'); +if ($deleted) { +echo "Ключ удален из кэша"; +} +``` + +## `has()` + +**Описание:** Проверяет наличие ключа в кэше + +Проверяет наличие ключа в кэше. Возвращает true, если +ключ существует и не истек, false в противном случае. + +**Параметры:** + +* `$key` (string): Ключ кэша для проверки + +**Возвращает:** `bool True` если ключ существует, false если нет или произошла ошибка + +**Пример:** +```php +if ($cache->has('movie_123')) { +// Ключ существует в кэше +$data = $cache->get('movie_123'); +} else { +// Ключа нет, загружаем данные +$data = loadMovieFromDatabase(123); +$cache->set('movie_123', $data); +} +``` + +## `clear()` + +**Описание:** Очищает весь кэш + +Очищает весь кэш. Удаляет все сохраненные ключи и значения. +Возвращает true при успешной очистке, false при ошибке. + +**Возвращает:** `bool True` при успешной очистке, false при ошибке + +**Пример:** +```php +$cleared = $cache->clear(); +if ($cleared) { +echo "Весь кэш очищен"; +} +``` + +## `getMultiple()` + +**Описание:** Получает множественные значения по ключам + +Получает множественные значения по ключам. Возвращает +ассоциативный массив найденных ключей и их значений. +Ключи, которые не найдены, не включаются в результат. + +**Параметры:** + +* `$keys` (array): Массив ключей для получения + +**Возвращает:** `array` Ассоциативный массив ключ => значение + +**Пример:** +```php +$keys = ['movie_123', 'movie_456', 'movie_789']; +$movies = $cache->getMultiple($keys); +// Результат: ['movie_123' => $data1, 'movie_456' => $data2] +``` + +## `setMultiple()` + +**Описание:** Сохраняет множественные значения + +Сохраняет множественные значения в кэш. Использует +отложенное сохранение для оптимизации производительности. +Возвращает true при успешном сохранении всех значений. + +**Параметры:** + +* `$ttl` (int): Время жизни в секундах (по умолчанию 1 час) + +**Возвращает:** `bool True` при успешном сохранении, false при ошибке + +**Пример:** +```php +$movies = [ +'movie_123' => $movieData1, +'movie_456' => $movieData2, +'movie_789' => $movieData3 +]; +$success = $cache->setMultiple($movies, 1800); // 30 минут +``` + +## `deleteMultiple()` + +**Описание:** Удаляет несколько ключей из кэша + +**Параметры:** + +* `$keys` (array): Массив ключей для удаления + +**Возвращает:** `bool True,` если все ключи успешно удалены, False при ошибке + +## `normalizeKey()` + +**Описание:** Нормализует ключ кэша для соответствия PSR-6 +Преобразует ключ кэша в формат, совместимый с PSR-6. +Заменяет недопустимые символы на подчеркивания. + +**Параметры:** + +* `$key` (string): Исходный ключ кэша + +**Возвращает:** `string` Нормализованный ключ, совместимый с PSR-6 + +**Пример:** +```php +// Внутреннее использование +$normalized = $this->normalizeKey('movie:123:data'); +// Результат: 'movie_123_data' +``` + diff --git a/docs/dev/kinopoiskdev/Services/ValidationService.md b/docs/dev/kinopoiskdev/Services/ValidationService.md new file mode 100644 index 0000000..6555e55 --- /dev/null +++ b/docs/dev/kinopoiskdev/Services/ValidationService.md @@ -0,0 +1,396 @@ +# ValidationService + +**Описание:** Сервис для валидации данных +Выполняет валидацию объектов на основе атрибутов PHP 8.3. +Поддерживает различные типы валидации: обязательные поля, +ограничения длины, диапазоны значений, регулярные выражения. +Использует рефлексию для автоматического обнаружения правил валидации. + +**С версии:** 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; +} +$validator = new ValidationService(); +$movie = new Movie(); +$movie->title = ''; +$movie->year = 1800; +try { +$validator->validate($movie); +} catch (ValidationException $e) { +foreach ($e->getErrors() as $field => $error) { +echo "{$field}: {$error}\n"; +} +} +``` + +**См. также:** + +* `\KinopoiskDev\Attributes\Validation`: Атрибут валидации +* `\KinopoiskDev\Exceptions\ValidationException`: Исключения валидации + +## `validate()` + +**Описание:** Валидирует объект на основе атрибутов свойств +Основной метод валидации, который анализирует все свойства объекта +и проверяет их на соответствие правилам, заданным в атрибутах Validation. +Выбрасывает ValidationException при обнаружении ошибок валидации. + +**Параметры:** + +* `$object` (object): Объект для валидации (должен иметь свойства с атрибутами Validation) + +**Возвращает:** `bool True` если валидация прошла успешно + +**Исключения:** + +* `ValidationException`: При ошибках валидации с детальным описанием проблем + +**Пример:** +```php +$movie = new Movie(); +$movie->title = 'The Matrix'; +$movie->year = 1999; +try { +$validator->validate($movie); +echo "Объект валиден"; +} catch (ValidationException $e) { +echo "Ошибки валидации: " . $e->getMessage(); +} +``` + +## `validateProperty()` + +**Описание:** Валидирует конкретное свойство объекта +Проверяет одно свойство объекта на соответствие правилам валидации, +заданным в атрибуте Validation. Поддерживает различные типы проверок +в зависимости от типа значения свойства. + +**Параметры:** + +* `$object` (object): Объект для валидации +* `$property` (ReflectionProperty): Свойство для валидации + +**Возвращает:** `array` Массив ошибок валидации в формате ['property' => 'error'] + +## `validateString()` + +**Описание:** Валидирует строковое значение +Выполняет валидацию строковых значений согласно правилам: +минимальная/максимальная длина и соответствие регулярному выражению. + +**Параметры:** + +* `$value` (string): Строковое значение для валидации +* `$validation` (Validation): Правила валидации из атрибута +* `$propertyName` (string): Название свойства для сообщений об ошибках + +**Возвращает:** `array` Массив ошибок валидации + +## `validateNumeric()` + +**Описание:** Валидирует числовое значение +Выполняет валидацию числовых значений согласно правилам: +минимальное/максимальное значение. + +**Параметры:** + +* `$value` (float|int): Числовое значение для валидации +* `$validation` (Validation): Правила валидации из атрибута +* `$propertyName` (string): Название свойства для сообщений об ошибках + +**Возвращает:** `array` Массив ошибок валидации + +## `validateArray()` + +**Описание:** Валидирует массив данных по правилам +Альтернативный метод валидации для работы с массивами данных +вместо объектов. Полезен для валидации входных данных API +или данных форм. + +**Возвращает:** `bool True` если валидация прошла успешно + +**Исключения:** + +* `ValidationException`: При ошибках валидации + +**Пример:** +```php +$data = [ +'title' => 'The Matrix', +'year' => 1999, +'rating' => 8.7 +]; +$rules = [ +'title' => ['required' => true, 'min_length' => 1, 'max_length' => 255], +'year' => ['min' => 1900, 'max' => 2030], +'rating' => ['min' => 0, 'max' => 10] +]; +try { +$validator->validateArray($data, $rules); +echo "Данные валидны"; +} catch (ValidationException $e) { +echo "Ошибки: " . $e->getMessage(); +} +``` + +## `validateFieldValue()` + +**Описание:** Валидирует значение поля по правилам +Вспомогательный метод для валидации отдельного поля +согласно переданным правилам. Поддерживает различные +типы правил валидации. + +**Параметры:** + +* `$value` (mixed): Значение поля для валидации +* `$fieldName` (string): Название поля для сообщений об ошибках + +**Возвращает:** `array` Массив ошибок валидации + +## `validateValue()` + +**Описание:** Валидирует значение на основе правил валидации +Универсальный метод для валидации любого значения +согласно объекту Validation. Возвращает сообщение об ошибке +или null при успешной валидации. + +**Параметры:** + +* `$value` (mixed): Значение для валидации +* `$validation` (Validation): Правила валидации + +**Возвращает:** `string|null` Сообщение об ошибке или null если валидация прошла успешно + +## `validateApiToken()` + +**Описание:** Валидирует API токен + +**Параметры:** + +* `$token` (string|null): API токен для валидации + +**Возвращает:** `bool` + +**Исключения:** + +* `ValidationException`: + +## `validateHttpMethod()` + +**Описание:** Валидирует HTTP метод + +**Параметры:** + +* `$method` (string): HTTP метод + +**Возвращает:** `bool` + +**Исключения:** + +* `ValidationException`: + +## `validateEndpoint()` + +**Описание:** Валидирует endpoint + +**Параметры:** + +* `$endpoint` (string): Endpoint для валидации + +**Возвращает:** `bool` + +**Исключения:** + +* `ValidationException`: + +## `validateYear()` + +**Описание:** Валидирует год + +**Параметры:** + +* `$year` (int): Год для валидации + +**Возвращает:** `bool` + +**Исключения:** + +* `ValidationException`: + +## `validateRating()` + +**Описание:** Валидирует рейтинг + +**Параметры:** + +* `$rating` (float): Рейтинг для валидации + +**Возвращает:** `bool` + +**Исключения:** + +* `ValidationException`: + +## `validateLimit()` + +**Описание:** Валидирует лимит + +**Параметры:** + +* `$limit` (int): Лимит для валидации + +**Возвращает:** `bool` + +**Исключения:** + +* `ValidationException`: + +## `validatePage()` + +**Описание:** Валидирует номер страницы + +**Параметры:** + +* `$page` (int): Номер страницы + +**Возвращает:** `bool` + +**Исключения:** + +* `ValidationException`: + +## `validateMovieId()` + +**Описание:** Валидирует ID фильма + +**Параметры:** + +* `$movieId` (int): ID фильма + +**Возвращает:** `bool` + +**Исключения:** + +* `ValidationException`: + +## `validatePersonId()` + +**Описание:** Валидирует ID персоны + +**Параметры:** + +* `$personId` (int): ID персоны + +**Возвращает:** `bool` + +**Исключения:** + +* `ValidationException`: + +## `validateGenre()` + +**Описание:** Валидирует жанр + +**Параметры:** + +* `$genre` (string): Жанр для валидации + +**Возвращает:** `bool` + +**Исключения:** + +* `ValidationException`: + +## `validateCountry()` + +**Описание:** Валидирует страну + +**Параметры:** + +* `$country` (string): Страна для валидации + +**Возвращает:** `bool` + +**Исключения:** + +* `ValidationException`: + +## `validateProfession()` + +**Описание:** Валидирует профессию + +**Параметры:** + +* `$profession` (string): Профессия для валидации + +**Возвращает:** `bool` + +**Исключения:** + +* `ValidationException`: + +## `validateSearchQuery()` + +**Описание:** Валидирует поисковый запрос + +**Параметры:** + +* `$query` (string): Поисковый запрос + +**Возвращает:** `bool` + +**Исключения:** + +* `ValidationException`: + +## `validateDate()` + +**Описание:** Валидирует дату + +**Параметры:** + +* `$date` (string): Дата в формате Y-m-d + +**Возвращает:** `bool` + +**Исключения:** + +* `ValidationException`: + +## `validateDateRange()` + +**Описание:** Валидирует диапазон дат + +**Параметры:** + +* `$startDate` (string): Начальная дата +* `$endDate` (string): Конечная дата + +**Возвращает:** `bool` + +**Исключения:** + +* `ValidationException`: + +## `validateNotEmptyArray()` + +**Описание:** Валидирует непустой массив + +**Параметры:** + +* `$array` (array): Массив для валидации + +**Возвращает:** `bool` + +**Исключения:** + +* `ValidationException`: + diff --git a/docs/dev/kinopoiskdev/Utils/.nav.yml b/docs/dev/kinopoiskdev/Utils/.nav.yml new file mode 100644 index 0000000..fd7d713 --- /dev/null +++ b/docs/dev/kinopoiskdev/Utils/.nav.yml @@ -0,0 +1,6 @@ +title: Утилиты +nav: + - DataManager: DataManager.md + - FilterTrait: FilterTrait.md + - MovieFilter: MovieFilter.md + - SortManager: SortManager.md diff --git a/docs/dev/kinopoiskdev/Utils/DataManager.md b/docs/dev/kinopoiskdev/Utils/DataManager.md new file mode 100644 index 0000000..d8be34a --- /dev/null +++ b/docs/dev/kinopoiskdev/Utils/DataManager.md @@ -0,0 +1,211 @@ +# DataManager + +## `getObjectsArray()` + +**Описание:** Преобразует массив объектов в массив массивов +Статический вспомогательный метод для преобразования коллекции объектов +в массив массивов путем вызова метода toArray() для каждого объекта. +Используется для сериализации связанных объектов (например, жанров, стран, +персон) при преобразовании основного объекта в массив данных. +Может быть массивом объектов с методом toArray(), null, false или пустым массивом. +Если передан массив, каждый элемент должен содержать метод toArray() +Возвращает пустой массив, если входные данные являются falsy-значением +(null, false, 0, пустой массив, пустая строка) + +**Параметры:** + +* `$objects` (mixed): Коллекция объектов для преобразования или любое другое значение. + +**Возвращает:** `array` Массив массивов, полученный путем вызова toArray() для каждого объекта. + +**Пример:** +```php +// Преобразование массива объектов жанров +$genres = [new Genre('драма'), new Genre('триллер')]; +$result = DataManager::getObjectsArray($genres); +// Результат: [['name' => 'драма'], ['name' => 'триллер']] +// Преобразование массива объектов стран +$countries = [new Country('США'), new Country('Великобритания')]; +$result = DataManager::getObjectsArray($countries); +// Результат: [['name' => 'США'], ['name' => 'Великобритания']] +// Обработка пустого значения +$result = DataManager::getObjectsArray(null); +// Результат: [] +// Обработка false +$result = DataManager::getObjectsArray(false); +// Результат: [] +``` + +**См. также:** + +* `Movie::toArray`: () Основной метод преобразования объекта фильма в массив +* `Genre::toArray`: () Метод преобразования жанра в массив +* `Country::toArray`: () Метод преобразования страны в массив +* `Person::toArray`: () Метод преобразования персоны в массив + +## `parseObjectAuto()` + +**Описание:** Автоматически парсит объект из массива данных в зависимости от типа +Универсальный метод для автоматической обработки объектов, который определяет, +является ли значение по указанному ключу массивом объектов или одиночным объектом, +и соответственно выбирает подходящий метод парсинга. Используется для автоматизации +процесса обработки данных API, где одно и то же поле может содержать как массив +объектов, так и одиночный объект. + +**Параметры:** + +* `$key` (string): Ключ в массиве данных, по которому находится значение для парсинга +* `$cls` (string): Полное имя класса для создания объектов (должен иметь метод fromArray) +* `$default` (mixed): Значение по умолчанию, возвращаемое при отсутствии данных (по умолчанию null) + +**Возвращает:** `mixed` Массив объектов указанного класса, одиночный объект или значение по умолчанию + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: Если указанный класс не существует или не имеет метода fromArray + +**См. также:** + +* `DataManager::parseObjectArray`: () Для обработки массива объектов +* `DataManager::parseObjectData`: () Для обработки одиночного объекта + +## `parseObjectArray()` + +**Описание:** Разбирает данные объекта из массива API +Статический метод для извлечения и преобразования данных объектов из массива API +по указанному ключу. Если ключ существует в массиве, применяет функцию преобразования +к каждому элементу: создает объект через fromArray() для массивов или возвращает +элемент как есть для других типов данных. Используется для обработки коллекций +связанных объектов (жанры, страны, персоны и т.д.) при десериализации данных API. +Метод выполняет автоматическую проверку существования указанного класса и наличия +в нем метода fromArray() перед началом обработки данных. Это обеспечивает безопасность +и предотвращает ошибки выполнения при работе с некорректными классами. +Класс должен содержать статический метод fromArray() +Каждый элемент массива либо преобразован в объект через fromArray(), +либо возвращен в исходном виде для неассоциативных данных +или не содержит метод fromArray() + +**Параметры:** + +* `$key` (string): Ключ для поиска в массиве данных (например, 'genres', 'countries', 'persons') +* `$cls` (string): Имя класса для создания объектов (например, 'Genre', 'Country', 'Person'). +* `$default` (mixed): Значение по умолчанию, возвращаемое при отсутствии ключа (по умолчанию пустой массив) + +**Возвращает:** `array` Массив объектов указанного типа или значение по умолчанию, если ключ не найден. + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: Если указанный класс не существует + +**Пример:** +```php +// Обработка массива жанров из API +$apiData = ['genres' => [['name' => 'драма'], ['name' => 'триллер']]]; +$genres = DataManager::parseObjectArray($apiData, 'genres', 'Genre'); +// Результат: [Genre объект 'драма', Genre объект 'триллер'] +// Обработка отсутствующего ключа с кастомным значением по умолчанию +$result = DataManager::parseObjectArray($apiData, 'missing_key', 'Country', []); +// Результат: [] +// Обработка данных с null значением по умолчанию +$result = DataManager::parseObjectArray($apiData, 'actors', 'Person', null); +// Результат: null (если ключ 'actors' отсутствует) +// Обработка смешанных данных (массивы и примитивы) +$mixedData = ['items' => [['id' => 1, 'name' => 'test'], 'simple_string']]; +$result = DataManager::parseObjectArray($mixedData, 'items', 'SomeClass'); +// Результат: [SomeClass объект, 'simple_string'] +``` + +**См. также:** + +* `DataManager::getObjectsArray`: () Для преобразования объектов в массивы +* `Genre::fromArray`: () Для создания объектов жанров +* `Country::fromArray`: () Для создания объектов стран +* `Person::fromArray`: () Для создания объектов персон +* `LinkedMovie::fromArray`: () Для создания объектов связанных фильмов + +## `parseObjectData()` + +**Описание:** Парсит данные объекта из массива через фабричный метод +Универсальный статический метод для создания объектов из массивов данных +с использованием фабричного метода fromArray. Выполняет валидацию существования +класса и требуемого метода, возвращая экземпляр объекта указанного класса +или значение по умолчанию при отсутствии данных. + +**Параметры:** + +* `$key` (string): Ключ в массиве данных для извлечения значения +* `$cls` (string): Полное имя класса для создания объекта (с пространством имен) +* `$default` (mixed): Значение по умолчанию, возвращаемое при отсутствии данных + +**Возвращает:** `mixed` Экземпляр указанного класса, созданный через fromArray, или значение по умолчанию + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: Если указанный класс не существует +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: Если в классе отсутствует метод fromArray + +**Пример:** +```php +// Создание объекта рейтинга из массива данных +$rating = Helper::parseObjectData( +$apiData, +'rating', +Rating::class, +new Rating() +); +// Создание объекта изображения с null по умолчанию +$poster = Helper::parseObjectData( +$movieData, +'poster', +ShortImage::class +); +``` + +**См. также:** + +* `\KinopoiskDev\Models\Rating::fromArray`: () Пример использования с моделью рейтинга +* `\KinopoiskDev\Models\Image::fromArray`: () Пример использования с моделью изображения +* `\KinopoiskDev\Models\ExternalId::fromArray`: () Пример использования с внешними ID + +## `parseEnumValue()` + +**Описание:** Разбирает значение enum из массива данных по указанному ключу +Безопасно извлекает значение из массива данных и пытается преобразовать его +в соответствующий enum с помощью метода tryFrom. Если ключ отсутствует в массиве +или значение не может быть преобразовано в enum, возвращается значение по умолчанию. +Выполняет проверку существования указанного класса enum перед попыткой преобразования. + +**Параметры:** + +* `$key` (string): Ключ в массиве, значение которого необходимо получить +* `$enumClass` (string): Полное имя класса enum для преобразования значения +* `$default` (mixed): Значение по умолчанию, возвращаемое при отсутствии ключа или неудачном преобразовании + +**Возвращает:** `mixed` Экземпляр enum или значение по умолчанию при неудачном преобразовании + +**Исключения:** + +* `\KinopoiskDev\Exceptions\KinopoiskDevException`: Если указанный класс enum не существует + +**Пример:** +```php +// Разбор типа фильма из данных API +$movieType = parseEnumValue( +data: ['type' => 'movie'], +key: 'type', +enumClass: MovieType::class +); +// Разбор с значением по умолчанию +$status = parseEnumValue( +data: $apiData, +key: 'status', +enumClass: Status::class, +default: Status::UNKNOWN +); +``` + +**См. также:** + +* `\KinopoiskDev\Enums\MovieType`: Пример использования с enum типов фильмов +* `\KinopoiskDev\Enums\FilterField`: Пример использования с enum полей фильтрации + diff --git a/docs/dev/kinopoiskdev/Utils/FilterTrait.md b/docs/dev/kinopoiskdev/Utils/FilterTrait.md new file mode 100644 index 0000000..1e149f5 --- /dev/null +++ b/docs/dev/kinopoiskdev/Utils/FilterTrait.md @@ -0,0 +1,128 @@ +# FilterTrait + +**Описание:** Трейт для общих методов фильтрации +Этот трейт предоставляет общие методы фильтрации, которые могут использоваться +в различных классах фильтров. Он следует принципу DRY (Don't Repeat Yourself), +централизуя общую логику фильтрации. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +## `movieId()` + +**Описание:** Добавляет фильтр по ID фильма + +**Параметры:** + +* `$movieId` (int): ID фильма + +## `name()` + +**Описание:** Добавляет фильтр по названию + +**Параметры:** + +* `$name` (string): Название +* `$operator` (string): Оператор сравнения + +## `enName()` + +**Описание:** Добавляет фильтр по английскому названию + +**Параметры:** + +* `$enName` (string): Английское название +* `$operator` (string): Оператор сравнения + +## `type()` + +**Описание:** Добавляет фильтр по типу + +**Параметры:** + +* `$type` (string|\KinopoiskDev\Enums\ReviewType): Тип +* `$operator` (string): Оператор сравнения + +**Возвращает:** `\KinopoiskDev\Filter\MovieSearchFilter|\KinopoiskDev\Filter\ImageSearchFilter|\KinopoiskDev\Filter\KeywordSearchFilter|\KinopoiskDev\Filter\PersonSearchFilter|\KinopoiskDev\Filter\ReviewSearchFilter|\KinopoiskDev\Filter\SeasonSearchFilter|\KinopoiskDev\Filter\StudioSearchFilter|\KinopoiskDev\Utils\FilterTrait` + +## `searchByName()` + +**Описание:** Добавляет поисковый фильтр по названию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `searchByEnName()` + +**Описание:** Добавляет поисковый фильтр по английскому названию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `searchByDescription()` + +**Описание:** Добавляет поисковый фильтр по описанию с использованием регулярных выражений + +**Параметры:** + +* `$query` (string): Поисковый запрос + +## `withMinRating()` + +**Описание:** Добавляет фильтр по минимальному рейтингу + +**Параметры:** + +* `$minRating` (float): Минимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `withMaxRating()` + +**Описание:** Добавляет фильтр по максимальному рейтингу + +**Параметры:** + +* `$maxRating` (float): Максимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `withRatingBetween()` + +**Описание:** Добавляет фильтр по диапазону рейтинга + +**Параметры:** + +* `$minRating` (float): Минимальный рейтинг +* `$maxRating` (float): Максимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb и т.д.) + +## `addRangeFilter()` + +**Описание:** Добавляет фильтр по диапазону + +**Параметры:** + +* `$field` (string): Имя поля +* `$minValue` (int): Минимальное значение +* `$maxValue` (int): Максимальное значение + +## `seasonRange()` + +**Описание:** Добавляет фильтр по диапазону сезонов + +**Параметры:** + +* `$fromSeason` (int): Начальный сезон +* `$toSeason` (int): Конечный сезон + +## `ageRange()` + +**Описание:** Добавляет фильтр по возрастному диапазону + +**Параметры:** + +* `$minAge` (int): Минимальный возраст +* `$maxAge` (int): Максимальный возраст + diff --git a/docs/dev/kinopoiskdev/Utils/MovieFilter.md b/docs/dev/kinopoiskdev/Utils/MovieFilter.md new file mode 100644 index 0000000..8baace4 --- /dev/null +++ b/docs/dev/kinopoiskdev/Utils/MovieFilter.md @@ -0,0 +1,653 @@ +# MovieFilter + +**Описание:** Класс для создания фильтров при поиске фильмов +Этот класс предоставляет методы для построения параметров фильтрации +при поиске фильмов через API Kinopoisk.dev + +**Ссылка:** https://kinopoiskdev.readme.io/reference/moviecontroller_findmanybyqueryv1_4 + +## `id()` + +**Описание:** Добавляет фильтр по ID фильма + +**Параметры:** + +* `$id` (int|array): ID фильма или массив ID +* `$operator` (string): Оператор сравнения (eq, ne, in, nin) + +## `addFilter()` + +**Описание:** Добавляет произвольный фильтр + +**Параметры:** + +* `$field` (string): Поле для фильтрации +* `$value` (mixed): Значение фильтра +* `$operator` (string): Оператор сравнения + +## `externalId()` + +**Описание:** Добавляет фильтр по внешнему ID фильма + +## `name()` + +**Описание:** Добавляет фильтр по названию фильма + +**Параметры:** + +* `$name` (string): Название фильма +* `$operator` (string): Оператор сравнения (eq, ne, in, nin, regex) + +## `enName()` + +**Описание:** Добавляет фильтр по английскому названию фильма + +**Параметры:** + +* `$enName` (string): Английское название фильма +* `$operator` (string): Оператор сравнения (eq, ne, in, nin, regex) + +## `alternativeName()` + +**Описание:** Добавляет фильтр по альтернативному названию фильма + +**Параметры:** + +* `$alternativeName` (string): Альтернативное название фильма +* `$operator` (string): Оператор сравнения (eq, ne, in, nin, regex) + +## `names()` + +**Описание:** Добавляет фильтр по всем названиям фильма + +**Параметры:** + +* `$names` (string|array): Название или массив названий +* `$operator` (string): Оператор сравнения (eq, ne, in, nin, regex) + +## `description()` + +**Описание:** Добавляет фильтр по описанию фильма + +**Параметры:** + +* `$description` (string): Описание фильма +* `$operator` (string): Оператор сравнения (eq, ne, regex) + +## `shortDescription()` + +**Описание:** Добавляет фильтр по краткому описанию фильма + +**Параметры:** + +* `$shortDescription` (string): Краткое описание фильма +* `$operator` (string): Оператор сравнения (eq, ne, regex) + +## `slogan()` + +**Описание:** Добавляет фильтр по слогану фильма + +**Параметры:** + +* `$slogan` (string): Слоган фильма +* `$operator` (string): Оператор сравнения (eq, ne, regex) + +## `type()` + +**Описание:** Добавляет фильтр по типу фильма + +**Параметры:** + +* `$type` (string): Тип фильма (movie, tv-series, cartoon, anime, animated-series, tv-show) +* `$operator` (string): Оператор сравнения (eq, ne, in, nin) + +## `typeNumber()` + +**Описание:** Добавляет фильтр по номеру типа фильма + +**Параметры:** + +* `$typeNumber` (int): Номер типа фильма (1-6) +* `$operator` (string): Оператор сравнения (eq, ne, in, nin, gt, gte, lt, lte) + +## `isSeries()` + +**Описание:** Добавляет фильтр по признаку сериала + +**Параметры:** + +* `$isSeries` (bool): Является ли фильм сериалом + +## `status()` + +**Описание:** Добавляет фильтр по статусу фильма + +**Параметры:** + +* `$status` (string): Статус фильма (filming, pre-production, completed, announced, post-production) +* `$operator` (string): Оператор сравнения (eq, ne, in, nin) + +## `year()` + +**Описание:** Добавляет фильтр по году выпуска + +**Параметры:** + +* `$year` (int): Год выпуска +* `$operator` (string): Оператор сравнения (eq, ne, in, nin, gt, gte, lt, lte) + +## `yearRange()` + +**Описание:** Добавляет фильтр по диапазону годов выпуска + +**Параметры:** + +* `$fromYear` (int): Начальный год +* `$toYear` (int): Конечный год + +## `releaseYears()` + +**Описание:** Добавляет фильтр по годам релиза + +**Параметры:** + +* `$releaseYears` (array): Массив годов релиза + +## `rating()` + +**Описание:** Добавляет фильтр по рейтингу + +**Параметры:** + +* `$rating` (float|array): Рейтинг или массив с параметрами рейтинга +* `$field` (string): Поле рейтинга (kp, imdb, tmdb, filmCritics, russianFilmCritics, await) +* `$operator` (string): Оператор сравнения (eq, ne, in, nin, gt, gte, lt, lte) + +## `ratingRange()` + +**Описание:** Добавляет фильтр по диапазону рейтинга + +**Параметры:** + +* `$minRating` (float): Минимальный рейтинг +* `$maxRating` (float): Максимальный рейтинг +* `$field` (string): Поле рейтинга (kp, imdb, tmdb, filmCritics, russianFilmCritics, await) + +## `ratingMpaa()` + +**Описание:** Добавляет фильтр по рейтингу MPAA + +**Параметры:** + +* `$ratingMpaa` (string): Рейтинг MPAA (g, pg, pg-13, r, nc-17) +* `$operator` (string): Оператор сравнения (eq, ne, in, nin) + +## `ageRating()` + +**Описание:** Добавляет фильтр по возрастному рейтингу + +**Параметры:** + +* `$ageRating` (int): Возрастной рейтинг +* `$operator` (string): Оператор сравнения (eq, ne, in, nin, gt, gte, lt, lte) + +## `votes()` + +**Описание:** Добавляет фильтр по голосам + +**Параметры:** + +* `$votes` (int|array): Количество голосов или массив с параметрами голосов +* `$field` (string): Поле голосов (kp, imdb, tmdb, filmCritics, russianFilmCritics, await) +* `$operator` (string): Оператор сравнения (eq, ne, in, nin, gt, gte, lt, lte) + +## `votesRange()` + +**Описание:** Добавляет фильтр по диапазону голосов + +**Параметры:** + +* `$minVotes` (int): Минимальное количество голосов +* `$maxVotes` (int): Максимальное количество голосов +* `$field` (string): Поле голосов (kp, imdb, tmdb, filmCritics, russianFilmCritics, await) + +## `seasonsInfo()` + +**Описание:** Добавляет фильтр по информации о сезонах + +## `budget()` + +**Описание:** Добавляет фильтр по бюджету + +## `audience()` + +**Описание:** Добавляет фильтр по аудитории + +## `movieLength()` + +**Описание:** Добавляет фильтр по длительности фильма + +**Параметры:** + +* `$movieLength` (int): Длительность фильма в минутах +* `$operator` (string): Оператор сравнения (eq, ne, in, nin, gt, gte, lt, lte) + +## `seriesLength()` + +**Описание:** Добавляет фильтр по длительности серии + +**Параметры:** + +* `$seriesLength` (int): Длительность серии в минутах +* `$operator` (string): Оператор сравнения (eq, ne, in, nin, gt, gte, lt, lte) + +## `totalSeriesLength()` + +**Описание:** Добавляет фильтр по общей длительности сериала + +**Параметры:** + +* `$totalSeriesLength` (int): Общая длительность сериала в минутах +* `$operator` (string): Оператор сравнения (eq, ne, in, nin, gt, gte, lt, lte) + +## `genres()` + +**Описание:** Добавляет фильтр по жанрам + +**Параметры:** + +* `$genres` (string|array): Жанр или массив жанров +* `$operator` (string): Оператор сравнения (eq, ne, in, nin) + +## `includeGenres()` + +**Описание:** Добавляет фильтр для включения жанров (оператор +) + +**Параметры:** + +* `$genres` (string|array): Жанр или массив жанров для включения + +## `excludeGenres()` + +**Описание:** Добавляет фильтр для исключения жанров (оператор !) + +**Параметры:** + +* `$genres` (string|array): Жанр или массив жанров для исключения + +## `countries()` + +**Описание:** Добавляет фильтр по странам + +**Параметры:** + +* `$countries` (string|array): Страна или массив стран +* `$operator` (string): Оператор сравнения (eq, ne, in, nin) + +## `includeCountries()` + +**Описание:** Добавляет фильтр для включения стран (оператор +) + +**Параметры:** + +* `$countries` (string|array): Страна или массив стран для включения + +## `excludeCountries()` + +**Описание:** Добавляет фильтр для исключения стран (оператор !) + +**Параметры:** + +* `$countries` (string|array): Страна или массив стран для исключения + +## `poster()` + +**Описание:** Добавляет фильтр по постеру + +## `backdrop()` + +**Описание:** Добавляет фильтр по фоновому изображению + +## `logo()` + +**Описание:** Добавляет фильтр по логотипу + +## `ticketsOnSale()` + +**Описание:** Добавляет фильтр по наличию билетов в продаже + +**Параметры:** + +* `$ticketsOnSale` (bool): Наличие билетов в продаже + +## `videos()` + +**Описание:** Добавляет фильтр по видео + +## `networks()` + +**Описание:** Добавляет фильтр по сетям + +## `persons()` + +**Описание:** Добавляет фильтр по участникам + +## `facts()` + +**Описание:** Добавляет фильтр по фактам + +## `fees()` + +**Описание:** Добавляет фильтр по сборам + +## `premiere()` + +**Описание:** Добавляет фильтр по премьере + +## `premiereRange()` + +**Описание:** Добавляет фильтр по диапазону дат премьеры + +**Параметры:** + +* `$fromDate` (string): Начальная дата в формате dd.mm.yyyy +* `$toDate` (string): Конечная дата в формате dd.mm.yyyy +* `$country` (string): Страна премьеры (russia, world, usa, ...) + +## `similarMovies()` + +**Описание:** Добавляет фильтр по похожим фильмам + +## `sequelsAndPrequels()` + +**Описание:** Добавляет фильтр по сиквелам и приквелам + +## `watchability()` + +**Описание:** Добавляет фильтр по доступности просмотра + +## `lists()` + +**Описание:** Добавляет фильтр по спискам + +## `top10()` + +**Описание:** Добавляет фильтр по топ-10 + +**Параметры:** + +* `$top10` (int): Позиция в топ-10 +* `$operator` (string): Оператор сравнения (eq, ne, in, nin, gt, gte, lt, lte) + +## `top250()` + +**Описание:** Добавляет фильтр по топ-250 + +**Параметры:** + +* `$top250` (int): Позиция в топ-250 +* `$operator` (string): Оператор сравнения (eq, ne, in, nin, gt, gte, lt, lte) + +## `updatedAt()` + +**Описание:** Добавляет фильтр по дате обновления + +**Параметры:** + +* `$updatedAt` (string): Дата обновления +* `$operator` (string): Оператор сравнения (eq, ne, gt, gte, lt, lte) + +## `createdAt()` + +**Описание:** Добавляет фильтр по дате создания + +**Параметры:** + +* `$createdAt` (string): Дата создания +* `$operator` (string): Оператор сравнения (eq, ne, gt, gte, lt, lte) + +## `getFilters()` + +**Описание:** Возвращает массив фильтров + +**Возвращает:** `array` + +## `notNullFields()` + +**Описание:** Исключение записей с пустыми значениями в указанных полях + +**Параметры:** + +* `$fields` (array): Массив названий полей + +## `reset()` + +**Описание:** Сбрасывает все фильтры + +## `setMaxLimit()` + +**Описание:** Устанавливает лимит количества элементов в результате запроса +Метод устанавливает ограничение на количество возвращаемых элементов +в текущем запросе. Используется для пагинации и контроля объема данных. +Добавляет фильтр 'limit' в массив фильтров запроса. + +**Параметры:** + +* `$int` (int): Максимальное количество элементов для возврата (должно быть положительным числом) + +**Возвращает:** `self` Возвращает текущий экземпляр объекта для поддержки цепочки вызовов (fluent interface) + +## `setPageNumber()` + +**Описание:** Устанавливает номер страницы для пагинации результатов +Задает номер страницы для получения определенного набора результатов +при выполнении запросов с пагинацией. Страницы нумеруются начиная с 1. +Значение сохраняется в массиве фильтров под ключом 'page' для +последующего использования в API-запросах. + +**С версии:** 1.0.0 + +**Параметры:** + +* `$int` (int): Номер страницы для получения результатов (должен быть больше 0) + +**Возвращает:** `self` Возвращает текущий экземпляр для цепочного вызова методов + +**Пример:** +```php +$filter = new MovieSearchFilter(); +$filter->page(2)->limit(20); // Получить вторую страницу с 20 результатами +// Использование в цепочке методов +$results = $movieRequests->searchMovies( +$filter->year(2023)->page(3)->limit(50) +); +``` + +## `removeSortByField()` + +**Описание:** Удаляет сортировку по указанному полю + +**Параметры:** + +* `$field` (SortField): Поле для удаления из сортировки + +## `toggleSort()` + +**Описание:** Переключает направление сортировки для указанного поля +Если сортировка по полю существует, меняет направление на противоположное. +Если сортировки нет, добавляет с направлением по умолчанию. + +**Параметры:** + +* `$field` (SortField): Поле для переключения сортировки + +## `sortBy()` + +**Описание:** Добавляет сортировку по указанному полю + +**Параметры:** + +* `$field` (SortField): Поле для сортировки +* `$direction` (SortDirection|null): Направление сортировки (по умолчанию используется рекомендуемое) + +## `addSortCriteria()` + +**Описание:** Добавляет критерий сортировки +Добавляет новый критерий сортировки к текущему набору. +Если критерий для указанного поля уже существует, он будет заменен. + +**Параметры:** + +* `$criteria` (SortCriteria): Критерий сортировки + +## `hasSortBy()` + +**Описание:** Проверяет, установлена ли сортировка по указанному полю + +**Параметры:** + +* `$field` (SortField): Поле для проверки + +**Возвращает:** `bool true,` если сортировка по полю установлена, false в противном случае + +## `getSortDirection()` + +**Описание:** Возвращает направление сортировки для указанного поля + +**Параметры:** + +* `$field` (SortField): Поле для получения направления + +**Возвращает:** `SortDirection|null` Направление сортировки или null, если сортировка не установлена + +## `getSortCriteria()` + +**Описание:** Возвращает все критерии сортировки + +**Возвращает:** `SortCriteria[]` Массив критериев сортировки + +## `setSortCriteria()` + +**Описание:** Устанавливает множественные критерии сортировки +Заменяет текущие критерии сортировки новым набором. + +**Параметры:** + +* `$criteria` (SortCriteria[]): Массив критериев сортировки + +## `clearSort()` + +**Описание:** Очищает все критерии сортировки + +## `addMultipleSort()` + +**Описание:** Добавляет множественные критерии сортировки из массива строк + +**Параметры:** + +* `$sorts` (array): Массив строк в формате "field:direction" или просто "field" + +**Пример:** +```php +$filter->addMultipleSort([ +'rating.kp:desc', +'year:asc', +'name' // будет использовано направление по умолчанию +]); +``` + +## `getSortData()` + +**Описание:** Преобразует критерии сортировки в параметры для API +Формирует строку сортировки в формате, ожидаемом API Kinopoisk.dev. +Множественные критерии объединяются запятыми. + +**Возвращает:** `array|null` Массив с данными о критериях сортировки или null, если критерии не установлены + +## `getSortCount()` + +**Описание:** Возвращает количество установленных критериев сортировки + +**Возвращает:** `int` Количество критериев сортировки + +## `hasAnySorting()` + +**Описание:** Проверяет, установлены ли какие-либо критерии сортировки + +**Возвращает:** `bool true,` если есть хотя бы один критерий сортировки, false в противном случае + +## `getFirstSortCriteria()` + +**Описание:** Возвращает первый критерий сортировки + +**Возвращает:** `SortCriteria|null` Первый критерий или null, если критерии отсутствуют + +## `getLastSortCriteria()` + +**Описание:** Возвращает последний критерий сортировки + +**Возвращает:** `SortCriteria|null` Последний критерий или null, если критерии отсутствуют + +## `sortByImdbRating()` + +**Описание:** Сортировка по рейтингу IMDB (по убыванию) + +## `sortByDesc()` + +**Описание:** Добавляет сортировку по убыванию + +**Параметры:** + +* `$field` (SortField): Поле для сортировки + +## `sortByYearOldFirst()` + +**Описание:** Сортировка по году выпуска (по возрастанию - сначала старые) + +## `sortByAsc()` + +**Описание:** Добавляет сортировку по возрастанию + +**Параметры:** + +* `$field` (SortField): Поле для сортировки + +## `sortByName()` + +**Описание:** Сортировка по названию (по алфавиту) + +## `sortByPopularity()` + +**Описание:** Сортировка по популярности (количество голосов Кинопоиска) + +## `sortByCreated()` + +**Описание:** Сортировка по дате создания записи (сначала новые) + +## `sortByUpdated()` + +**Описание:** Сортировка по дате обновления записи (сначала обновленные) + +## `sortByBest()` + +**Описание:** Комбинированная сортировка по рейтингу и году +Сначала по рейтингу Кинопоиска (по убыванию), затем по году (по убыванию). + +## `sortByYear()` + +**Описание:** Сортировка по году выпуска (по убыванию - сначала новые) + +## `sortByKinopoiskRating()` + +**Описание:** Сортировка по рейтингу Кинопоиска (по убыванию) + +## `exportSortCriteria()` + +**Описание:** Экспорт критериев сортировки в массив для сериализации + +**Возвращает:** `array>` Массив с данными о критериях сортировки + +## `importSortCriteria()` + +**Описание:** Импорт критериев сортировки из массива + diff --git a/docs/dev/kinopoiskdev/Utils/SortManager.md b/docs/dev/kinopoiskdev/Utils/SortManager.md new file mode 100644 index 0000000..967d059 --- /dev/null +++ b/docs/dev/kinopoiskdev/Utils/SortManager.md @@ -0,0 +1,199 @@ +# SortManager + +**Описание:** Trait для добавления функциональности сортировки к фильтрам +Этот trait предоставляет методы для управления параметрами сортировки +при выполнении запросов к API Kinopoisk.dev. Может использоваться +в классах фильтрации для расширения их функциональности. + +**С версии:** 1.0.0 + +**Версия:** 1.0.0 + +## `removeSortByField()` + +**Описание:** Удаляет сортировку по указанному полю + +**Параметры:** + +* `$field` (SortField): Поле для удаления из сортировки + +## `toggleSort()` + +**Описание:** Переключает направление сортировки для указанного поля +Если сортировка по полю существует, меняет направление на противоположное. +Если сортировки нет, добавляет с направлением по умолчанию. + +**Параметры:** + +* `$field` (SortField): Поле для переключения сортировки + +## `sortBy()` + +**Описание:** Добавляет сортировку по указанному полю + +**Параметры:** + +* `$field` (SortField): Поле для сортировки +* `$direction` (SortDirection|null): Направление сортировки (по умолчанию используется рекомендуемое) + +## `addSortCriteria()` + +**Описание:** Добавляет критерий сортировки +Добавляет новый критерий сортировки к текущему набору. +Если критерий для указанного поля уже существует, он будет заменен. + +**Параметры:** + +* `$criteria` (SortCriteria): Критерий сортировки + +## `hasSortBy()` + +**Описание:** Проверяет, установлена ли сортировка по указанному полю + +**Параметры:** + +* `$field` (SortField): Поле для проверки + +**Возвращает:** `bool true,` если сортировка по полю установлена, false в противном случае + +## `getSortDirection()` + +**Описание:** Возвращает направление сортировки для указанного поля + +**Параметры:** + +* `$field` (SortField): Поле для получения направления + +**Возвращает:** `SortDirection|null` Направление сортировки или null, если сортировка не установлена + +## `getSortCriteria()` + +**Описание:** Возвращает все критерии сортировки + +**Возвращает:** `SortCriteria[]` Массив критериев сортировки + +## `setSortCriteria()` + +**Описание:** Устанавливает множественные критерии сортировки +Заменяет текущие критерии сортировки новым набором. + +**Параметры:** + +* `$criteria` (SortCriteria[]): Массив критериев сортировки + +## `clearSort()` + +**Описание:** Очищает все критерии сортировки + +## `addMultipleSort()` + +**Описание:** Добавляет множественные критерии сортировки из массива строк + +**Параметры:** + +* `$sorts` (array): Массив строк в формате "field:direction" или просто "field" + +**Пример:** +```php +$filter->addMultipleSort([ +'rating.kp:desc', +'year:asc', +'name' // будет использовано направление по умолчанию +]); +``` + +## `getSortData()` + +**Описание:** Преобразует критерии сортировки в параметры для API +Формирует строку сортировки в формате, ожидаемом API Kinopoisk.dev. +Множественные критерии объединяются запятыми. + +**Возвращает:** `array|null` Массив с данными о критериях сортировки или null, если критерии не установлены + +## `getSortCount()` + +**Описание:** Возвращает количество установленных критериев сортировки + +**Возвращает:** `int` Количество критериев сортировки + +## `hasAnySorting()` + +**Описание:** Проверяет, установлены ли какие-либо критерии сортировки + +**Возвращает:** `bool true,` если есть хотя бы один критерий сортировки, false в противном случае + +## `getFirstSortCriteria()` + +**Описание:** Возвращает первый критерий сортировки + +**Возвращает:** `SortCriteria|null` Первый критерий или null, если критерии отсутствуют + +## `getLastSortCriteria()` + +**Описание:** Возвращает последний критерий сортировки + +**Возвращает:** `SortCriteria|null` Последний критерий или null, если критерии отсутствуют + +## `sortByImdbRating()` + +**Описание:** Сортировка по рейтингу IMDB (по убыванию) + +## `sortByDesc()` + +**Описание:** Добавляет сортировку по убыванию + +**Параметры:** + +* `$field` (SortField): Поле для сортировки + +## `sortByYearOldFirst()` + +**Описание:** Сортировка по году выпуска (по возрастанию - сначала старые) + +## `sortByAsc()` + +**Описание:** Добавляет сортировку по возрастанию + +**Параметры:** + +* `$field` (SortField): Поле для сортировки + +## `sortByName()` + +**Описание:** Сортировка по названию (по алфавиту) + +## `sortByPopularity()` + +**Описание:** Сортировка по популярности (количество голосов Кинопоиска) + +## `sortByCreated()` + +**Описание:** Сортировка по дате создания записи (сначала новые) + +## `sortByUpdated()` + +**Описание:** Сортировка по дате обновления записи (сначала обновленные) + +## `sortByBest()` + +**Описание:** Комбинированная сортировка по рейтингу и году +Сначала по рейтингу Кинопоиска (по убыванию), затем по году (по убыванию). + +## `sortByYear()` + +**Описание:** Сортировка по году выпуска (по убыванию - сначала новые) + +## `sortByKinopoiskRating()` + +**Описание:** Сортировка по рейтингу Кинопоиска (по убыванию) + +## `exportSortCriteria()` + +**Описание:** Экспорт критериев сортировки в массив для сериализации + +**Возвращает:** `array>` Массив с данными о критериях сортировки + +## `importSortCriteria()` + +**Описание:** Импорт критериев сортировки из массива + diff --git a/docs/dev/kinopoiskdev/notkinopoiskphp-compare.md b/docs/dev/kinopoiskdev/notkinopoiskphp-compare.md new file mode 100644 index 0000000..d1c1090 --- /dev/null +++ b/docs/dev/kinopoiskdev/notkinopoiskphp-compare.md @@ -0,0 +1,187 @@ +# Сравнение KinopoiskDev и NotKinopoiskPHP + +## Обзор + +**Важно:** Это два совершенно разных API от разных команд разработки! + +- **KinopoiskDev** - обертка для официального API [kinopoisk.dev](https://kinopoisk.dev) от команды Open Movie Database +- **NotKinopoiskPHP** - обертка для неофициального API kinopoiskapiunofficial.tech от независимых разработчиков + +Эти API **не совместимы** между собой, имеют разную структуру данных и эндпоинты. + +## Основные различия + +### API и разработка + +| Аспект | KinopoiskDev | NotKinopoiskPHP | +| ----------------- | ----------------------------------------------------------- | ------------------------------------------------------------------ | +| **API** | [kinopoisk.dev](https://kinopoisk.dev) | [kinopoiskapiunofficial.tech](https://kinopoiskapiunofficial.tech) | +| **Статус** | Активная разработка, современный API | Стабильный, но менее активная разработка | +| **Поддержка** | [Telegram группа](https://t.me/omdb_dev) (7,908 участников) | ❌ Даже на EMail не отвечают | +| **Совместимость** | ❌ Не совместим с NotKinopoiskPHP | ❌ Не совместим с KinopoiskDev | + +### Архитектура библиотек + +| Аспект | KinopoiskDev | NotKinopoiskPHP | +| --------------- | ------------------------------------------------------------------------- | --------------------------------------- | +| **Подход** | Объектно-ориентированный с использованием атрибутов PHP 8.3+ | Функциональный с использованием трейтов | +| **Структура** | Модульная с четким разделением ответственности | Монолитная с общими классами | +| **Валидация** | Декларативная через атрибуты `#[Validation]` | Ручная валидация в методах | +| **Кэширование** | Интерфейс `CacheInterface` с возможностью подключения различных драйверов | Встроенное кэширование | +| **Логирование** | PSR-3 совместимый `LoggerInterface` | Простое логирование | + +### Функциональность + +| Функция | KinopoiskDev | NotKinopoiskPHP | +| -------------------------- | ---------------------------------------------- | ---------------------- | +| **Поиск фильмов** | ✅ Расширенные фильтры с поддержкой диапазонов | ✅ Базовые фильтры | +| **Поиск персон** | ✅ Специализированные фильтры для персон | ✅ Базовый поиск | +| **Работа с изображениями** | ✅ Фильтры по разрешению, типу | ✅ Базовые возможности | +| **Валидация данных** | ✅ Автоматическая через атрибуты | ⚠️ Ручная | +| **Обработка ошибок** | ✅ Специализированные исключения | ✅ Базовые исключения | +| **Кэширование** | ✅ Гибкая система кэширования | ⚠️ Простое кэширование | +| **Логирование** | ✅ PSR-3 совместимое | ⚠️ Базовое | + +### Примеры использования + +#### KinopoiskDev + +```php +use KinopoiskDev\Kinopoisk; +use KinopoiskDev\Filter\MovieSearchFilter; + +$kinopoisk = new Kinopoisk(apiToken: 'your-token'); + +// Поиск с расширенными фильтрами +$filter = new MovieSearchFilter(); +$filter->withYearBetween(2020, 2024) + ->withMinRating(7.0, 'kp') + ->withAllGenres(['драма', 'комедия']) + ->onlyMovies(); + +$movies = $kinopoisk->searchMovies($filter); +``` + +#### NotKinopoiskPHP + +```php +use NotKinopoiskPHP\Client; + +$client = new Client('your-token'); + +// Поиск с базовыми параметрами +$movies = $client->searchMovies([ + 'year' => '2020-2024', + 'rating.kp' => '7-10', + 'genres.name' => 'драма,комедия', + 'type' => 'movie' +]); +``` + +## Преимущества KinopoiskDev + +### 1. Современный подход + +- Использование PHP 8.3+ атрибутов +- Строгая типизация +- Объектно-ориентированный дизайн + +### 2. Расширенная функциональность + +- Более гибкие фильтры +- Специализированные классы для разных типов данных +- Автоматическая валидация + +### 3. Лучшая архитектура + +- Модульная структура +- Интерфейсы для расширяемости +- PSR стандарты + +### 4. Безопасность + +- Атрибут `#[Sensitive]` для конфиденциальных данных +- Автоматическое скрытие в JSON/массивах + +## Преимущества NotKinopoiskPHP + +### 1. Простота использования + +- Более простой API +- Меньше кода для базовых операций +- Быстрый старт + +### 2. Совместимость + +- Работает с более старыми версиями PHP +- Меньше зависимостей + +### 3. Стабильность + +- Более зрелая библиотека +- Больше тестов + +## Рекомендации по выбору + +### Выберите KinopoiskDev если: + +- Используете PHP 8.3+ +- Нужны расширенные возможности фильтрации +- Важна архитектура и расширяемость +- Требуется строгая типизация +- Нужна интеграция с PSR стандартами + +### Выберите NotKinopoiskPHP если: + +- Используете более старые версии PHP +- Нужны только базовые операции +- Важна простота использования +- Требуется максимальная совместимость + +## Миграция + +**⚠️ Важно:** Прямая миграция между библиотеками невозможна из-за разных API! + +### Переход с NotKinopoiskPHP на KinopoiskDev + +Требуется полный рефакторинг кода, так как: + +1. **Разные API ключи** - нужны отдельные ключи для каждого API +2. **Разная структура данных** - модели и ответы не совместимы +3. **Разные эндпоинты** - URL и параметры запросов отличаются +4. **Разная логика фильтрации** - синтаксис фильтров не совпадает + +### Пример рефакторинга + +```php +// NotKinopoiskPHP (старый код) +$client = new Client('token'); +$movies = $client->searchMovies(['year' => '2023']); + +// KinopoiskDev (новый код) - ПОЛНОСТЬЮ ПЕРЕПИСАТЬ! +$kinopoisk = new Kinopoisk(apiToken: 'new-token-for-kinopoisk-dev'); +$filter = new MovieSearchFilter(); +$filter->year(2023); +$movies = $kinopoisk->searchMovies($filter); +``` + +### Рекомендации по миграции + +1. **Получить новый API ключ** на [kinopoisk.dev](https://kinopoisk.dev) +2. **Изучить документацию** нового API +3. **Переписать все запросы** с нуля +4. **Обновить обработку ответов** под новую структуру данных +5. **Протестировать** все функции + +## Заключение + +**KinopoiskDev** представляет собой современную библиотеку для официального API [kinopoisk.dev](https://kinopoisk.dev) с активной поддержкой через [Telegram группу](https://t.me/omdb_dev) (7,908 участников). Это выбор для новых проектов, требующих современного и активно поддерживаемого API. + +**NotKinopoiskPHP** остается стабильным решением для неофициального API kinopoiskapiunofficial.tech, подходящим для проектов, которые уже используют этот API или требуют максимальной совместимости со старыми версиями PHP. + +**Выбор зависит от:** + +- Требований к официальности API +- Необходимости активной поддержки +- Совместимости с существующим кодом +- Версии PHP в проекте