Перейти к содержанию

PersonRequests

Описание: Класс для API-запросов, связанных с персонами Предоставляет полный набор методов для работы с персонами через API Kinopoisk.dev. Включает поиск персон, получение детальной информации, наград, фильтрацию по профессиям и другим критериям. Поддерживает расширенную фильтрацию, пагинацию и обработку ошибок. Основные возможности: - Поиск персон по различным критериям - Получение детальной информации о персоне - Работа с наградами персон - Фильтрация по профессиям (актеры, режиссеры и т.д.) - Поиск по имени с поддержкой регулярных выражений - Специализированные методы для популярных запросов

С версии: 1.0.0

Версия: 1.0.0

Пример:

PHP
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
$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
1
2
3
$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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
// Получение случайной персоны без фильтров
$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
1
2
3
4
// Поиск по русскому имени
$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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
// Получение первых 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: Для структуры ответа