babaev-an / ANB PHP COMPONENTS PACK

classes/ClassMapper.md

Класс ClassMapper

Пространство имён: goodboyalex\php_components_pack
Полное имя класса: goodboyalex\php_components_pack\ClassMapper
Тип: финальный класс
Версия: 1.1
Доступно с: 1.0

Описание

Класс предназначен для сопоставления классов и объектов — обеспечивает:

  • перенос свойств между объектами с учётом правил;
  • подготовку и парсинг свойств класса;
  • преобразование массивов в объекты классов;
  • работу со значениями по умолчанию для типов.

Автор

  • Имя: Александр Бабаев
  • Email: contact_with_us@babaev-an.ru

Метаданные

  • PSR‑4: goodboyalex/php_components_pack
  • Модификатор класса: final
  • Ключевые зависимости:
    • goodboyalex\php_components_pack\attributes\GetOnly
    • goodboyalex\php_components_pack\models\ClassMapOptions
    • goodboyalex\php_components_pack\types\GUID

Методы

mapClass()

public static function mapClass(
    object $from,
    object $to,
    ClassMapOptions $options = new ClassMapOptions()
): void

Описание:
Передаёт одинаковые параметры из класса‑донора ($from) в класс‑приёмник ($to), учитывая:

  • игнорируемые свойства ($ignoredProperties);
  • разрешённые свойства ($allowedProperties).

Параметры:

  • $from (object) — класс‑донор.
  • $to (object) — класс‑приёмник.
  • $options (ClassMapOptions) — параметры привязки свойств (по умолчанию — новый экземпляр ClassMapOptions).

Возвращаемое значение:
Не возвращает значение (void).

prepareClassProperties()

public static function prepareClassProperties(
    array $params,
    ReflectionClass $classReflector,
    ClassMapOptions $options = new ClassMapOptions()
): array

Описание:
Подготавливает значения свойств класса на основе входных данных.

Параметры:

  • $params (array) — данные запроса.
  • $classReflector (ReflectionClass) — анализатор класса.
  • $options (ClassMapOptions) — параметры привязки (по умолчанию — новый экземпляр ClassMapOptions).

Возвращаемое значение:

  • array — массив данных класса.

getClassParametersArrayParser()

public static function getClassParametersArrayParser(
    array &$source,
    array $parametersKeys,
    mixed $value,
    ClassMapOptions $options = new ClassMapOptions()
): void

Описание:
Парсит массив свойств класса, разбивая ключи на части (например, Page_Meta_Id → ["Page", "Meta", "Id"]).

Параметры:

  • $source (array&) — исходный массив (передаётся по ссылке, модифицируется в процессе).
  • $parametersKeys (array) — массив имён свойств.
  • $value (mixed) — значение свойства.
  • $options (ClassMapOptions) — параметры привязки свойств (по умолчанию — новый экземпляр ClassMapOptions).

Возвращаемое значение:
Не возвращает значение (void).

mapToClassProperty()

public static function mapToClassProperty(
    string $className,
    array $properties
): mixed

Описание:
Преобразует массив данных в объект указанного класса.

Параметры:

  • $className (string) — имя класса.
  • $properties (array) — массив данных.

Возвращаемое значение:

  • mixed — объект класса.

Исключения:

  • Exception — при ошибках создания объекта.

setParameterToClass()

public static function setParameterToClass(
    ReflectionClass $classReflector,
    string $propertyName,
    mixed $classObj,
    mixed $value
): void

Описание:
Присваивает значение параметра объекту класса через рефлектор.

Параметры:

  • $classReflector (ReflectionClass) — рефлектор класса.
  • $propertyName (string) — имя свойства.
  • $classObj (mixed) — объект класса.
  • $value (mixed) — значение.

Возвращаемое значение:
Не возвращает значение (void).

Исключения:

  • Exception — при ошибках установки значения.

getDefaults()

public static function getDefaults(string $typeName): mixed

Описание:
Возвращает значение по умолчанию для указанного типа.

Параметры:

  • $typeName (string) — название типа (например, "int", "string").

Возвращаемое значение:

  • mixed — значение по умолчанию для типа.

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

Пример 1: Перенос свойств между объектами

$donor = new SomeClass();
$receiver = new AnotherClass();

ClassMapper::mapClass($donor, $receiver, new ClassMapOptions(allowed: ['id', 'name'], ignored: ['created_at']);

Пример 2: Создание объекта из массива

$data = ['id' => 1, 'name' => 'Test'];
$object = ClassMapper::mapToClassProperty('App\Models\User', $data);

Пример 3: Подготовка свойств класса

$reflector = new ReflectionClass(SomeClass::class);
$prepared = ClassMapper::prepareClassProperties(
    ['id' => 1],
    $reflector,
    new ClassMapOptions()
);

Примечания

  1. Все методы — статические, не требуют создания экземпляра класса.
  2. Для работы с рефлексией требуется расширение Reflection в PHP.
  3. Класс использует ClassMapOptions для гибкой настройки правил сопоставления.
  4. Метод mapToClassProperty() может выбрасывать исключение при ошибках создания объекта.

Дополнительные сведения

Зависимости и требования

Обязательные классы/интерфейсы:

  • ClassMapOptions — определяет правила сопоставления свойств;
  • ReflectionClass — используется для анализа структуры классов;
  • базовые типы PHP (string, array, mixed).

Требования к окружению:

  • PHP 8.0+ (для поддержки типизации и синтаксиса);
  • включённое расширение Reflection (стандартно в PHP).

Особенности реализации

  1. Безопасность типов
    Все методы строго типизированы, что снижает риск ошибок при передаче параметров.

  2. Гибкость конфигурации
    Через ClassMapOptions можно:

    • явно указывать разрешённые свойства (allowedProperties);
    • исключать свойства из сопоставления (ignoredProperties);
    • настраивать поведение парсера.

  3. Работа с вложенными структурами
    Метод getClassParametersArrayParser() поддерживает разбиение составных ключей (например, User_Profile_Id → ['User', 'Profile', 'Id']).

  4. Обработка исключений
    Критические операции (например, создание объектов) оборачиваются в try‑catch с выбросом Exception.

Рекомендации по использованию

  1. Для маппинга объектов
    Используйте mapClass() с чётко заданными allowedProperties, чтобы избежать неожиданного переноса данных.

  2. Для преобразования массивов
    Перед вызовом mapToClassProperty() убедитесь, что:

    • класс существует;
    • массив содержит все обязательные поля.

  3. Для отладки
    Включите логирование исключений из setParameterToClass(), чтобы отслеживать ошибки установки свойств.

Типичные сценарии применения

  1. API‑интеграции
    Преобразование JSON‑ответов в объекты бизнес‑логики:

    $user = ClassMapper::mapToClassProperty(
   User::class,
   json_decode($apiResponse, true)
);

  2. Миграции данных
    Перенос свойств между устаревшими и новыми классами:

    ClassMapper::mapClass($legacyObject, $newObject, new ClassMapOptions([
   'allowedProperties' => ['id', 'title', 'content']
]));

  3. Валидация входных данных
    Подготовка параметров перед передачей в конструктор:

    $validated = ClassMapper::prepareClassProperties(
   $_POST,
   new ReflectionClass(FormModel::class)
);

Ограничения и известные проблемы

  1. Отсутствие поддержки интерфейсов
    Класс не проверяет соответствие интерфейсов при маппинге.

  2. Ограниченная обработка типов
    getDefaults() поддерживает только базовые типы PHP (не учитывает кастомные классы).

  3. Нет кэширования рефлектора
    Повторный вызов prepareClassProperties() для одного класса создаёт новый ReflectionClass.

  4. Строгая типизация
    При несоответствии типов в setParameterToClass() будет выброшено исключение.

На главную | Содержание

Назад