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

MovieRequests

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

С версии: 1.0.0

Версия: 1.0.0

Пример:

PHP
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
$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
1
2
3
$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
1
2
3
4
5
6
// Получить любой случайный фильм
$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<array<string, mixed>> Массив возможных значений с полями name и slug

Исключения:

  • KinopoiskDevException: При передаче неподдерживаемого поля
  • KinopoiskResponseException: При ошибках HTTP-запроса
  • \JsonException: При ошибках парсинга JSON-ответа

Пример:

PHP
1
2
3
4
5
6
// Получить все жанры
$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
1
2
3
4
// Поиск фильма по названию
$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
1
2
3
4
// Получить последние фильмы текущего года
$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
1
2
3
4
// Получить боевики
$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
1
2
3
4
5
6
// Простой поиск всех фильмов
$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
1
2
3
4
// Получить американские фильмы
$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
1
2
3
4
// Получить фильмы 90-х годов
$movies90s = $movieRequests->getMoviesByYearRange(1990, 1999);
// Получить фильмы последнего десятилетия
$recentMovies = $movieRequests->getMoviesByYearRange(2014, 2024, 1, 100);