PersonRequests¶
Описание: Класс для API-запросов, связанных с персонами Предоставляет полный набор методов для работы с персонами через API Kinopoisk.dev. Включает поиск персон, получение детальной информации, наград, фильтрацию по профессиям и другим критериям. Поддерживает расширенную фильтрацию, пагинацию и обработку ошибок. Основные возможности: - Поиск персон по различным критериям - Получение детальной информации о персоне - Работа с наградами персон - Фильтрация по профессиям (актеры, режиссеры и т.д.) - Поиск по имени с поддержкой регулярных выражений - Специализированные методы для популярных запросов
С версии: 1.0.0
Версия: 1.0.0
Пример:
См. также:
\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 | |
---|---|
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
Пример:
См. также:
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 | |
---|---|
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
:
Пример:
См. также:
\KinopoiskDev\Filter\PersonSearchFilter
: Для параметров фильтрации\KinopoiskDev\Models\PersonAward
: Для структуры данных наград персон\KinopoiskDev\Responses\PersonAwardDocsResponseDto
: Для структуры ответа