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

AbstractBaseModel

Описание: Абстрактный базовый класс для всех моделей Предоставляет общую функциональность для моделей данных: валидацию, сериализацию, работу с атрибутами PHP 8.3. Реализует интерфейс BaseModel и предоставляет готовые методы для работы с данными API Kinopoisk.dev. Основные возможности: - Автоматическая валидация на основе атрибутов Validation - Сериализация/десериализация с поддержкой JSON - Обработка конфиденциальных полей - Безопасное извлечение данных из массивов - Создание копий объектов с изменениями

С версии: 1.0.0

Версия: 1.0.0

Пример:

PHP
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
class Movie extends AbstractBaseModel {
#[Validation(required: true, minLength: 1, maxLength: 255)]
public string $title;
#[Validation(min: 1900, max: 2030)]
public int $year;
#[Sensitive(hideInJson: true)]
public string $apiKey;
public function __construct(string $title, int $year, string $apiKey) {
$this->title = $title;
$this->year = $year;
$this->apiKey = $apiKey;
}
}
$movie = Movie::fromArray(['title' => 'The Matrix', 'year' => 1999, 'apiKey' => 'secret']);
$movie->validate();
$json = $movie->toJson(); // apiKey не включен в JSON

См. также:

  • \KinopoiskDev\Models\BaseModel: Интерфейс базовой модели
  • \KinopoiskDev\Attributes\Validation: Атрибут валидации
  • \KinopoiskDev\Attributes\Sensitive: Атрибут конфиденциальных полей
  • \KinopoiskDev\Services\ValidationService: Сервис валидации

fromJson()

Описание: Создает объект из JSON строки Десериализует JSON строку в объект модели. Парсит JSON, создает массив данных и использует fromArray для создания объекта.

Десериализует JSON строку в объект модели с обработкой ошибок парсинга и валидации данных.

Параметры:

  • $json (string): JSON строка с данными объекта

Возвращает: static Экземпляр модели с заполненными данными

Исключения:

  • ValidationException: При ошибках парсинга JSON или валидации данных
  • \JsonException: При ошибках парсинга JSON

Пример:

PHP
1
2
3
$json = '{"title":"The Matrix","year":1999}';
$movie = Movie::fromJson($json);
echo $movie->title; // The Matrix

fromArray()

Описание: Создает экземпляр модели из массива данных Фабричный метод для создания объекта модели из ассоциативного массива, полученного из API ответа. Должен обрабатывать маппинг полей API на свойства модели и выполнять базовую валидацию данных.

Создает экземпляр модели из массива данных с использованием рефлексии. Автоматически определяет параметры конструктора и передает соответствующие значения из массива данных. Поддерживает значения по умолчанию.

Возвращает: static Экземпляр модели с заполненными данными

Исключения:

  • \ReflectionException: При ошибках рефлексии
  • \LogicException: При попытке создания абстрактного класса
  • ValidationException: При некорректных данных

Пример:

PHP
1
2
3
$data = ['title' => 'The Matrix', 'year' => 1999];
$movie = Movie::fromArray($data);
// Создается объект Movie с title='The Matrix' и year=1999

getDataValue()

Описание: Безопасно извлекает значение из массива данных Универсальный метод для безопасного извлечения значений из массива с поддержкой значения по умолчанию при отсутствии ключа.

Параметры:

  • $key (string): Ключ для поиска в массиве
  • $default (mixed): Значение по умолчанию при отсутствии ключа

Возвращает: mixed Значение из массива или значение по умолчанию

Пример:

PHP
1
2
3
$data = ['title' => 'The Matrix', 'year' => 1999];
$title = self::getDataValue($data, 'title', 'Unknown'); // 'The Matrix'
$rating = self::getDataValue($data, 'rating', 0);       // 0

getArrayValue()

Описание: Безопасно извлекает массив из данных Извлекает значение из массива данных и гарантирует, что результат будет массивом. Возвращает пустой массив, если ключ отсутствует или значение не является массивом.

Параметры:

  • $key (string): Ключ для поиска в массиве

Возвращает: array<mixed> Массив значений или пустой массив

Пример:

PHP
1
2
3
$data = ['genres' => ['action', 'sci-fi'], 'actors' => null];
$genres = self::getArrayValue($data, 'genres'); // ['action', 'sci-fi']
$actors = self::getArrayValue($data, 'actors'); // []

getStringValue()

Описание: Безопасно извлекает строку из данных Извлекает строковое значение из массива данных с поддержкой значения по умолчанию. Возвращает null, если значение не является строкой.

Параметры:

  • $key (string): Ключ для поиска в массиве
  • $default (string|null): Значение по умолчанию при отсутствии ключа

Возвращает: string|null Строковое значение или null

Пример:

PHP
1
2
3
$data = ['title' => 'The Matrix', 'year' => 1999];
$title = self::getStringValue($data, 'title');           // 'The Matrix'
$description = self::getStringValue($data, 'description'); // null

getIntValue()

Описание: Безопасно извлекает целое число из данных Извлекает целочисленное значение из массива данных с поддержкой значения по умолчанию. Преобразует числовые строки в целые числа.

Параметры:

  • $key (string): Ключ для поиска в массиве
  • $default (int|null): Значение по умолчанию при отсутствии ключа

Возвращает: int|null Целочисленное значение или null

Пример:

PHP
1
2
3
4
$data = ['year' => 1999, 'rating' => '8.7', 'votes' => null];
$year = self::getIntValue($data, 'year');     // 1999
$rating = self::getIntValue($data, 'rating'); // 8
$votes = self::getIntValue($data, 'votes');   // null

getBoolValue()

Описание: Безопасно извлекает логическое значение из данных Извлекает логическое значение из массива данных с поддержкой значения по умолчанию. Возвращает null, если значение не является boolean.

Параметры:

  • $key (string): Ключ для поиска в массиве
  • $default (bool|null): Значение по умолчанию при отсутствии ключа

Возвращает: bool|null Логическое значение или null

Пример:

PHP
1
2
3
4
$data = ['isActive' => true, 'isDeleted' => false, 'isPublished' => null];
$isActive = self::getBoolValue($data, 'isActive');     // true
$isDeleted = self::getBoolValue($data, 'isDeleted');   // false
$isPublished = self::getBoolValue($data, 'isPublished'); // null

with()

Описание: Создает копию объекта с измененными свойствами Иммутабельный метод для создания нового экземпляра объекта с измененными значениями свойств. Полезен для создания вариаций объекта без изменения оригинала.

Возвращает: static Новый экземпляр с примененными изменениями

Исключения:

  • ValidationException: При ошибках валидации нового объекта

Пример:

PHP
1
2
3
4
5
6
$movie = new Movie('The Matrix', 1999);
// Создаем копию с измененным годом
$updatedMovie = $movie->with(['year' => 2000]);
echo $updatedMovie->title; // The Matrix
echo $updatedMovie->year;  // 2000
echo $movie->year;         // 1999 (оригинал не изменился)

toArray()

Описание: Преобразует объект в массив Сериализует объект модели в ассоциативный массив для передачи в API или сохранения в базу данных. Поддерживает контроль включения null значений.

Преобразует объект в ассоциативный массив с поддержкой вложенных объектов, enum значений и конфиденциальных полей. Автоматически обрабатывает атрибуты ApiField для маппинга имен полей.

Параметры:

  • $includeNulls (bool): Включать ли null значения в результат (по умолчанию true)

Возвращает: array<string, mixed> Ассоциативный массив с данными объекта

Пример:

PHP
1
2
3
4
5
6
7
$movie = new Movie('The Matrix', 1999);
// С null значениями
$array = $movie->toArray(true);
// Результат: ['title' => 'The Matrix', 'year' => 1999, 'rating' => null]
// Без null значений
$array = $movie->toArray(false);
// Результат: ['title' => 'The Matrix', 'year' => 1999]

getApiFieldName()

Описание: Определяет имя поля для API на основе атрибутов Извлекает имя поля для API из атрибута ApiField или возвращает оригинальное имя свойства, если атрибут не задан.

Параметры:

  • $property (ReflectionProperty): Свойство для анализа

Возвращает: string Имя поля для использования в API

processArrayValue()

Описание: Обрабатывает значения массива для сериализации Рекурсивно обрабатывает элементы массива, преобразуя объекты BaseModel в массивы и enum значения в их скалярные представления.

Параметры:

  • $value (array): Массив для обработки
  • $includeNulls (bool): Включать ли null значения в результат

Возвращает: array<mixed> Обработанный массив

validate()

Описание: Валидирует данные модели Проверяет корректность данных модели согласно бизнес-правилам и ограничениям. Может использовать атрибуты Validation для автоматической валидации свойств.

Валидирует объект с использованием ValidationService и атрибутов Validation. Проверяет все свойства объекта на соответствие заданным правилам валидации.

Возвращает: bool True если валидация прошла успешно

Исключения:

  • ValidationException: При ошибках валидации с детальным описанием проблем

Пример:

PHP
1
2
3
4
5
6
7
8
9
$movie = new Movie('', -1000); // Некорректные данные
try {
$movie->validate();
echo "Модель валидна";
} catch (ValidationException $e) {
foreach ($e->getErrors() as $field => $error) {
echo "{$field}: {$error}\n";
}
}

getValidator()

Описание: Получает экземпляр валидатора Возвращает статический экземпляр ValidationService для переиспользования между объектами одного класса. Создает новый экземпляр при первом вызове.

Возвращает: ValidationService Экземпляр сервиса валидации

equals()

Описание: Сравнивает текущий объект с другим Выполняет глубокое сравнение объектов на основе их данных. Объекты считаются равными, если все их свойства имеют одинаковые значения.

Параметры:

  • $other (BaseModel): Объект для сравнения

Возвращает: bool True если объекты равны, false в противном случае

Пример:

PHP
1
2
3
4
5
$movie1 = new Movie('The Matrix', 1999);
$movie2 = new Movie('The Matrix', 1999);
$movie3 = new Movie('The Matrix', 2000);
$movie1->equals($movie2); // true
$movie1->equals($movie3); // false

getHash()

Описание: Возвращает хэш объекта Генерирует SHA256 хэш на основе JSON представления объекта. Полезен для кэширования, сравнения версий объектов или создания уникальных идентификаторов.

Возвращает: string SHA256 хэш объекта

Пример:

PHP
1
2
3
$movie = new Movie('The Matrix', 1999);
$hash = $movie->getHash();
// Результат: строка из 64 символов (SHA256)

toJson()

Описание: Возвращает JSON представление объекта Сериализует объект модели в JSON строку для передачи по сети или сохранения в файл. Поддерживает настройку флагов кодирования JSON.

Сериализует объект в JSON строку с автоматической фильтрацией конфиденциальных полей согласно атрибутам Sensitive.

Параметры:

  • $flags (int): Флаги для json_encode (по умолчанию JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE)

Возвращает: string JSON строка с данными объекта

Исключения:

  • ValidationException: При ошибке кодирования JSON

Пример:

PHP
1
2
3
4
$movie = new Movie('The Matrix', 1999);
$movie->apiKey = 'secret123';
$json = $movie->toJson();
// Результат: '{"title":"The Matrix","year":1999}' (apiKey исключен)

filterSensitiveForJson()

Описание: Фильтрует конфиденциальные поля для JSON вывода Удаляет поля, помеченные атрибутом Sensitive с hideInJson=true, из массива данных перед JSON сериализацией.

Возвращает: array<string, mixed> Отфильтрованные данные без конфиденциальных полей

isEmpty()

Описание: Проверяет, является ли объект пустым Определяет, содержит ли объект какие-либо непустые данные. Исключает null значения, пустые строки и пустые массивы.

Возвращает: bool True если объект не содержит данных, false в противном случае

Пример:

PHP
1
2
3
4
$movie1 = new Movie('', 0);
$movie1->isEmpty(); // true
$movie2 = new Movie('The Matrix', 1999);
$movie2->isEmpty(); // false

getFilledProperties()

Описание: Возвращает только заполненные свойства Возвращает ассоциативный массив, содержащий только свойства с непустыми значениями (исключая null, пустые строки и массивы).

Возвращает: array<string, mixed> Массив непустых свойств

Пример:

PHP
1
2
3
4
5
$movie = new Movie('The Matrix', 1999);
$movie->description = '';
$movie->tags = [];
$filled = $movie->getFilledProperties();
// Результат: ['title' => 'The Matrix', 'year' => 1999]