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

title: Перечисления description: Система перечислений KinopoiskDev для типизированных констант и значений keywords: перечисления, enums, фильтры, сортировка, статусы, типы category: enums tags: - Kinopoisk - enums

Перечисления

Система перечислений KinopoiskDev предоставляет типизированные константы для всех возможных значений, используемых в API. Все enum'ы основаны на PHP 8.1+ перечислениях для обеспечения типобезопасности и читаемости кода.

Обзор

Перечисления в KinopoiskDev используются для:

  • Типобезопасности - предотвращение использования недопустимых значений
  • Читаемости кода - понятные названия вместо магических чисел
  • Валидации - автоматическая проверка допустимых значений
  • Документации - самодокументируемый код с описаниями

Доступные перечисления

FilterField

Файл: FilterField.md

Enum для полей фильтрации, содержащий все возможные поля для фильтрации данных через API:

PHP
1
2
3
4
5
6
7
8
9
enum FilterField: string {
    case ID = 'id';
    case NAME = 'name';
    case YEAR = 'year';
    case RATING_KP = 'rating.kp';
    case GENRES = 'genres.name';
    case COUNTRIES = 'countries.name';
    // ... и многие другие
}

Возможности:

  • Все поля API для фильтрации
  • Поддержка составных полей (rating.kp, votes.imdb)
  • Методы для определения типа поля
  • Проверка поддержки операторов

FilterOperator

Файл: FilterOperator.md

Enum для операторов фильтрации, определяющий все возможные операции сравнения:

PHP
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
enum FilterOperator: string {
    case EQUALS = 'eq';
    case NOT_EQUALS = 'ne';
    case GREATER_THAN = 'gt';
    case LESS_THAN = 'lt';
    case IN = 'in';
    case NOT_IN = 'nin';
    case RANGE = 'range';
    // ... и другие
}

Возможности:

  • Операторы сравнения (eq, ne, gt, lt, gte, lte)
  • Операторы включения/исключения (in, nin, all)
  • Операторы диапазонов (range)
  • Регулярные выражения (regex)

SortField

Файл: SortField.md

Enum для полей сортировки при поиске фильмов и персон:

PHP
1
2
3
4
5
6
7
8
9
enum SortField: string {
    case ID = 'id';
    case NAME = 'name';
    case YEAR = 'year';
    case RATING_KP = 'rating.kp';
    case VOTES_KP = 'votes.kp';
    case CREATED_AT = 'createdAt';
    // ... и другие
}

Возможности:

  • Поля для сортировки фильмов
  • Поля для сортировки персон
  • Методы для определения типа данных
  • Рекомендуемые направления сортировки

SortDirection

Файл: SortDirection.md

Enum для направления сортировки результатов поиска:

PHP
1
2
3
4
enum SortDirection: string {
    case ASC = 'asc';
    case DESC = 'desc';
}

Возможности:

  • Возрастающая сортировка (ASC)
  • Убывающая сортировка (DESC)
  • Методы для получения противоположного направления
  • Символьные представления (↑, ↓)

MovieType

Файл: MovieType.md

Enum для типов фильмов, возвращаемых API:

PHP
1
2
3
4
5
6
7
8
enum MovieType: string {
    case MOVIE = 'movie';
    case TV_SERIES = 'tv-series';
    case CARTOON = 'cartoon';
    case ANIME = 'anime';
    case ANIMATED_SERIES = 'animated-series';
    case TV_SHOW = 'tv-show';
}

Возможности:

  • Все типы контента КиноПоиска
  • Человекочитаемые названия
  • Фильтрация по типам

MovieStatus

Файл: MovieStatus.md

Enum для статусов фильмов в производстве:

PHP
1
2
3
4
5
6
7
enum MovieStatus: string {
    case FILMING = 'filming';
    case PRE_PRODUCTION = 'pre-production';
    case COMPLETED = 'completed';
    case ANNOUNCED = 'announced';
    case POST_PRODUCTION = 'post-production';
}

Возможности:

  • Статусы производства фильмов
  • Фильтрация по статусам
  • Человекочитаемые названия

PersonProfession

Файл: PersonProfession.md

Enum для профессий персон в кинематографе:

PHP
1
2
3
4
5
6
7
8
enum PersonProfession: string {
    case ACTOR = 'actor';
    case DIRECTOR = 'director';
    case WRITER = 'writer';
    case PRODUCER = 'producer';
    case COMPOSER = 'composer';
    // ... и другие
}

Возможности:

  • Все профессии в кинематографе
  • Поддержка русского и английского языков
  • Множественные формы названий
  • Фильтрация персон по профессиям

PersonSex

Файл: PersonSex.md

Enum для пола персон:

PHP
1
2
3
4
enum PersonSex: string {
    case MALE = 'male';
    case FEMALE = 'female';
}

Возможности:

  • Определение пола персон
  • Русские названия
  • Фильтрация по полу

RatingMpaa

Файл: RatingMpaa.md

Enum для рейтингов MPAA (Американская ассоциация кинокомпаний):

PHP
1
2
3
4
5
6
7
enum RatingMpaa: string {
    case G = 'g';
    case PG = 'pg';
    case PG13 = 'pg13';
    case R = 'r';
    case NC17 = 'nc17';
}

Возможности:

  • Все рейтинги MPAA
  • Описания возрастных ограничений
  • Фильтрация по возрастным рейтингам

ImageType

Файл: ImageType.md

Enum для типов изображений:

PHP
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
enum ImageType: string {
    case BACKDROP = 'backdrops';
    case COVER = 'cover';
    case FRAME = 'frame';
    case PROMO = 'promo';
    case SCREENSHOT = 'screenshot';
    case SHOOTING = 'shooting';
    case STILL = 'still';
    case WALLPAPER = 'wallpaper';
}

Возможности:

  • Все типы изображений
  • Фильтрация изображений по типам
  • Специализированные фильтры

HttpStatusCode

Файл: HttpStatusCode.md

Enum для HTTP статус кодов, используемых в API:

PHP
1
2
3
4
5
6
7
enum HttpStatusCode: int {
    case OK = 200;
    case UNAUTHORIZED = 401;
    case FORBIDDEN = 403;
    case NOT_FOUND = 404;
    case INTERNAL_SERVER_ERROR = 500;
}

Возможности:

  • Основные HTTP статус коды
  • Описания на русском языке
  • Проверка успешности/ошибки

ReviewType

Файл: ReviewType.md

Enum для типов отзывов:

PHP
1
2
3
4
5
enum ReviewType: string {
    case POSITIVE = 'Позитивный';
    case NEGATIVE = 'Негативный';
    case NEUTRAL = 'Нейтральный';
}

Возможности:

  • Типы отзывов
  • Фильтрация отзывов
  • Русские названия

ListCategory

Файл: ListCategory.md

Enum для категорий списков:

PHP
1
2
3
4
5
6
7
enum ListCategory: string {
    case ONLINE = 'Онлайн-кинотеатр';
    case AWARD = 'Премии';
    case FEE = 'Сборы';
    case SERIES = 'Сериалы';
    case MOVIE = 'Фильмы';
}

Возможности:

  • Категории списков КиноПоиска
  • Фильтрация по категориям
  • Русские названия

StudioType

Файл: StudioType.md

Enum для типов студий:

PHP
1
2
3
4
5
6
enum StudioType: string {
    case PRODUCTION = 'Производство';
    case SPECIAL_EFFECTS = 'Спецэффекты';
    case DISTRIBUTION = 'Прокат';
    case DUBBING_STUDIO = 'Студия дубляжа';
}

Возможности:

  • Типы студий в кинематографе
  • Описания на русском и английском
  • Фильтрация студий по типам

Использование

Базовые примеры

PHP
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<?php

use KinopoiskDev\Enums\FilterField;
use KinopoiskDev\Enums\FilterOperator;
use KinopoiskDev\Enums\SortDirection;
use KinopoiskDev\Enums\MovieType;

// Использование в фильтрах
$filter = new MovieSearchFilter();
$filter->addFilter(FilterField::YEAR, FilterOperator::EQUALS, 2023);
$filter->addFilter(FilterField::TYPE, FilterOperator::EQUALS, MovieType::MOVIE);

// Использование в сортировке
$filter->sortBy(FilterField::RATING_KP, SortDirection::DESC);

Проверка типов полей

PHP
1
2
3
4
5
6
7
8
9
// Проверка поддержки диапазонов
if (FilterField::YEAR->supportsRange()) {
    $filter->addRangeFilter(FilterField::YEAR, 2020, 2024);
}

// Проверка поддержки включения/исключения
if (FilterField::GENRES->supportsIncludeExclude()) {
    $filter->withIncludedGenres(['драма', 'комедия']);
}

Работа с направлениями сортировки

PHP
1
2
3
4
5
$direction = SortDirection::ASC;
$reverseDirection = $direction->reverse(); // DESC

echo $direction->getSymbol(); // ↑
echo $direction->getDescription(); // Сортировка по возрастанию

Фильтрация по профессиям

PHP
1
2
3
4
5
6
7
8
use KinopoiskDev\Enums\PersonProfession;

$filter = new PersonSearchFilter();
$filter->withProfession(PersonProfession::ACTOR);

// Получение русского названия
echo PersonProfession::ACTOR->getRussianName(); // "Актер"
echo PersonProfession::ACTOR->getRussianPluralName(); // "Актеры"

Интеграция с фильтрами

Автоматическая валидация

PHP
1
2
3
4
// Enum'ы автоматически валидируются в фильтрах
$filter = new MovieSearchFilter();
$filter->withType(MovieType::MOVIE); // ✅ Корректно
$filter->withType('invalid_type');   // ❌ Ошибка валидации

Типобезопасность

PHP
1
2
3
4
// IDE поддержка и автодополнение
$filter->withStatus(MovieStatus::COMPLETED);
$filter->withRatingMpaa(RatingMpaa::PG13);
$filter->withImageType(ImageType::POSTER);

Связанные разделы

  • Filter - классы фильтров, использующие enum'ы
  • Utils - утилиты для работы с enum'ами
  • Kinopoisk - главный класс с поддержкой enum'ов

Преимущества

Типобезопасность

PHP
1
2
3
4
5
// Вместо строковых констант
$filter->addFilter('year', 'eq', 2023);

// Используйте enum'ы
$filter->addFilter(FilterField::YEAR, FilterOperator::EQUALS, 2023);

Читаемость

PHP
1
2
3
4
// Понятные названия вместо магических чисел
$filter->withType(MovieType::TV_SERIES);
$filter->withStatus(MovieStatus::FILMING);
$filter->withProfession(PersonProfession::DIRECTOR);

Валидация

PHP
1
2
3
4
5
6
// Автоматическая проверка допустимых значений
enum MovieType: string {
    case MOVIE = 'movie';
    case TV_SERIES = 'tv-series';
    // Только эти значения допустимы
}

Полезные ссылки

Перечисления KinopoiskDev - обеспечивают типобезопасность и читаемость кода через строго типизированные константы.