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

SequelPrequelResponse

Описание

SequelPrequelResponse - это специализированный класс ответа для работы с сиквелами, приквелами и связанными фильмами от Kinopoisk API. Наследует функциональность SimpleResponse и предоставляет расширенные методы для фильтрации и анализа связанных фильмов по типам отношений.

Основные возможности

  • Фильтрация фильмов по типу отношения (сиквелы, приквелы, римейки, похожие)
  • Объединение и сортировка связанных фильмов
  • Статистика по типам отношений
  • Группировка фильмов по типам связей
  • Проверка наличия фильмов определенного типа
  • Получение уникальных типов отношений

Наследование

PHP
1
2
NotKinopoisk\Responses\SimpleResponse
└── NotKinopoisk\Responses\SequelPrequelResponse

Конструктор

PHP
1
public function __construct(public array $items)

Параметры

  • $items (array) - Массив связанных фильмов

Статические методы

fromArray()

PHP
1
public static function fromArray(array $data, string $cls): self

Создает экземпляр SequelPrequelResponse из массива данных API.

Параметры

  • $data (array) - Массив данных от API
  • $cls (string) - Имя класса для элементов коллекции

Возвращает

  • SequelPrequelResponse - Новый экземпляр с данными о связанных фильмах

Исключения

  • KpValidationException - Если данные имеют некорректную структуру

Методы экземпляра

getPrequelsAndSequels()

PHP
1
public function getPrequelsAndSequels(): array

Получает объединённый и отсортированный список приквелов и сиквелов.

Возвращает

  • array<int, RelatedFilm> - Отсортированный массив приквелов и сиквелов

Исключения

  • KpValidationException - При ошибках во время обработки данных

Пример использования

PHP
1
2
3
4
$combined = $response->getPrequelsAndSequels();
foreach ($combined as $film) {
    echo "{$film->getDisplayName()} - {$film->relationType->getDescription()}\n";
}

getSequels()

PHP
1
public function getSequels(): array

Получает все фильмы-сиквелы.

Возвращает

  • array<int, RelatedFilm> - Массив фильмов-сиквелов

Исключения

  • KpValidationException - При некорректной структуре данных

Пример использования

PHP
1
2
3
4
5
$sequels = $response->getSequels();
echo "Найдено сиквелов: " . count($sequels) . "\n";
foreach ($sequels as $sequel) {
    echo "- {$sequel->getDisplayName()}\n";
}

getPrequels()

PHP
1
public function getPrequels(): array

Получает все фильмы-приквелы.

Возвращает

  • array<int, RelatedFilm> - Массив фильмов-приквелов

Исключения

  • KpValidationException - При некорректной структуре данных

Пример использования

PHP
1
2
3
4
5
$prequels = $response->getPrequels();
echo "Найдено приквелов: " . count($prequels) . "\n";
foreach ($prequels as $prequel) {
    echo "- {$prequel->getDisplayName()}\n";
}

hasFilmsOfType()

PHP
1
public function hasFilmsOfType(RelationType $type): bool

Проверяет наличие фильмов указанного типа.

Параметры

  • $type (RelationType) - Тип отношения для проверки

Возвращает

  • bool - True если фильмы присутствуют, false в противном случае

Пример использования

PHP
1
2
3
4
5
6
7
if ($response->hasFilmsOfType(RelationType::SEQUEL)) {
    echo "У фильма есть сиквелы\n";
}

if ($response->hasFilmsOfType(RelationType::PREQUEL)) {
    echo "У фильма есть приквелы\n";
}

getByRelationType()

PHP
1
public function getByRelationType(RelationType $type): array

Получает все фильмы указанного типа отношения.

Параметры

  • $type (RelationType) - Тип отношения между фильмами

Возвращает

  • array<int, RelatedFilm> - Массив фильмов указанного типа

Исключения

  • KpValidationException - При некорректных параметрах или данных

Пример использования

PHP
1
2
3
4
5
// Получение фильмов по типу
$sequels = $response->getByRelationType(RelationType::SEQUEL);
$prequels = $response->getByRelationType(RelationType::PREQUEL);
$remakes = $response->getByRelationType(RelationType::REMAKE);
$similar = $response->getByRelationType(RelationType::SIMILAR);

getRemakes()

PHP
1
public function getRemakes(): array

Получает все римейки.

Возвращает

  • array<int, RelatedFilm> - Массив римейков

Исключения

  • KpValidationException - При некорректной структуре данных

Пример использования

PHP
1
2
3
4
5
$remakes = $response->getRemakes();
echo "Найдено римейков: " . count($remakes) . "\n";
foreach ($remakes as $remake) {
    echo "- {$remake->getDisplayName()}\n";
}

getSimilar()

PHP
1
public function getSimilar(): array

Получает все похожие фильмы.

Возвращает

  • array<int, RelatedFilm> - Массив похожих фильмов

Исключения

  • KpValidationException - При некорректной структуре данных

Пример использования

PHP
1
2
3
4
5
$similar = $response->getSimilar();
echo "Найдено похожих фильмов: " . count($similar) . "\n";
foreach ($similar as $film) {
    echo "- {$film->getDisplayName()}\n";
}

getStatistics()

PHP
1
public function getStatistics(): array

Получает статистику по всем типам отношений.

Возвращает

  • array<string, int> - Статистика по типам отношений

Пример использования

PHP
1
2
3
4
5
6
7
$stats = $response->getStatistics();
echo "Общая статистика:\n";
echo "- Сиквелов: {$stats['sequels']}\n";
echo "- Приквелов: {$stats['prequels']}\n";
echo "- Римейков: {$stats['remakes']}\n";
echo "- Похожих: {$stats['similar']}\n";
echo "- Всего: {$stats['total']}\n";

countByType()

PHP
1
public function countByType(RelationType $type): int

Возвращает количество фильмов указанного типа.

Параметры

  • $type (RelationType) - Тип отношения для подсчёта

Возвращает

  • int - Количество фильмов указанного типа

Пример использования

PHP
1
2
3
4
5
$sequelCount = $response->countByType(RelationType::SEQUEL);
echo "Количество сиквелов: $sequelCount\n";

$prequelCount = $response->countByType(RelationType::PREQUEL);
echo "Количество приквелов: $prequelCount\n";

hasRelatedFilms()

PHP
1
public function hasRelatedFilms(): bool

Проверяет, есть ли связанные фильмы.

Возвращает

  • bool - True если есть хотя бы один связанный фильм

Пример использования

PHP
1
2
3
4
5
if ($response->hasRelatedFilms()) {
    echo "У фильма есть связанные фильмы\n";
} else {
    echo "У фильма нет связанных фильмов\n";
}

getAvailableRelationTypes()

PHP
1
public function getAvailableRelationTypes(): array

Получает все уникальные типы отношений в текущем наборе данных.

Возвращает

  • array<RelationType> - Массив уникальных типов отношений

Пример использования

PHP
1
2
3
4
5
$types = $response->getAvailableRelationTypes();
echo "Доступные типы отношений:\n";
foreach ($types as $type) {
    echo "- {$type->getDescription()}\n";
}

groupByRelationType()

PHP
1
public function groupByRelationType(): array

Группирует связанные фильмы по типу отношения.

Возвращает

  • array<string, array<RelatedFilm>> - Ассоциативный массив, где ключи - строковые значения типов связей, а значения - массивы объектов RelatedFilm

Пример использования

PHP
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Группировка связанных фильмов
$groups = $response->groupByRelationType();

// Обработка сгруппированных данных
foreach ($groups as $relationType => $films) {
    echo "Тип связи: {$relationType}\n";
    echo "Количество фильмов: " . count($films) . "\n";

    foreach ($films as $film) {
        echo "  - {$film->getDisplayName()}\n";
    }
    echo "\n";
}

// Получение конкретного типа связи
$sequels = $groups['SEQUEL'] ?? [];
$similars = $groups['SIMILAR'] ?? [];

// Проверка наличия определённого типа
if (isset($groups['PREQUEL'])) {
    echo "Найдены приквелы: " . count($groups['PREQUEL']) . " шт.\n";
}

Типы отношений

Класс поддерживает следующие типы отношений:

  • SEQUEL - Сиквелы (продолжения)
  • PREQUEL - Приквелы (предыстории)
  • REMAKE - Римейки (новые версии)
  • SIMILAR - Похожие фильмы
  • UNKNOWN - Неизвестный тип связи

Обработка ошибок

Класс включает комплексную обработку ошибок:

  • Валидация структуры данных API
  • Проверка типизации элементов
  • Обработка некорректных типов отношений
  • Безопасная фильтрация и группировка

Пример полного использования

PHP
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
use NotKinopoisk\Responses\SequelPrequelResponse;
use NotKinopoisk\Models\RelatedFilm;
use NotKinopoisk\Enums\RelationType;

// Получение данных от API
$apiData = [
    ['kinopoiskId' => 1, 'relationType' => 'SEQUEL'],
    ['kinopoiskId' => 2, 'relationType' => 'PREQUEL'],
    ['kinopoiskId' => 3, 'relationType' => 'SIMILAR']
];

// Создание объекта ответа
$response = SequelPrequelResponse::fromArray($apiData, RelatedFilm::class);

// Анализ связанных фильмов
$sequels = $response->getSequels();
$prequels = $response->getPrequels();
$similar = $response->getSimilar();

$stats = $response->getStatistics();
$groups = $response->groupByRelationType();

echo "Статистика связанных фильмов:\n";
foreach ($stats as $type => $count) {
    echo "- {$type}: {$count}\n";
}

// Проверка наличия определенных типов
if ($response->hasFilmsOfType(RelationType::SEQUEL)) {
    echo "Найдены сиквелы: " . count($sequels) . "\n";
}

if ($response->hasRelatedFilms()) {
    echo "Всего связанных фильмов: " . count($response->items) . "\n";
}

Связанные классы

  • SimpleResponse - Базовый класс для простых ответов
  • RelatedFilm - Модель связанного фильма
  • RelationType - Перечисление типов отношений
  • KpValidationException - Исключение для ошибок валидации