README

Dto используется для передачи типизированных данных между слоями приложения, подготовки данных для сохранения в БД или отправки http запросов, с трансформацией в нужный формат.

Класс Dto расширяет функционал объекта для реализации возможности управления объектом и его данными:\

Управление преобразованием типов;\
Управление дефолтными значениями;\
Управление маппингом свойств при заполнении;\
Управление сериализацией объекта в массив или json;\
Управление хуками объекта.

Для реализации функционала работы с Dto необходимо расширить объект от класса \Atlcom\Dto или подключить к своему объекту трейт \Atlcom\Traits\AsDto.
class MyDto extends \Atlcom\Dto {}
ИЛИ
class MyDto {
    use \Atlcom\Traits\AsDto;
}

${\textsf{\color{red}Начиная с версии Dto 2.61 поддерживается PHP 8.2 и выше}}$

Установка

composer require atlcom/dto

История изменений

Открыть историю

Описание методов

Создание и заполнение:

@method public static create(mixed ...$data)
Создает объект Dto из переданных именованных аргументов / ассоциативного массива / объекта / строки json.

@method public static fill(array $data)
Создает объект Dto из переданного ассоциативного массива.

@method static collect(array $items)
Преобразует массив или коллекцию данных в коллекцию из dto.

@method public fillFromArray(array $data)
Заполняет объект Dto из переданного ассоциативного массива.

@method public fillFromData(mixed $data)
Заполняет объект Dto из переданного ассоциативного массива / объекта / строки json.

@method public fillFromObject(array $data)
Заполняет объект Dto из переданного объекта с публичными свойствами.

@method public fillFromDto(self $data)
Заполняет объект Dto из другого объекта Dto с публичными свойствами.

@method public fillFromJson(self $data)
Заполняет объект Dto из строки json.

@method public merge(object $data)
Объединяет объект Dto с переданным ассоциативным массивом.

@method public clear()
Очищает все свойства Dto.

@method public transformToDto(string $dtoClass, array $array = [])
Трансформирует объект Dto в объект другого класса Dto и дополняет данными из массива.

@method public isEmpty()
Проверяет dto на заполнение хотя бы одного свойства.

@method public static getProperties()
Возвращает массив свойств dto.

@method public static getPropertiesWithFirstType()
Возвращает массив всех свойств dto с его первым типом.

@method public static getPropertiesWithAllTypes()
Возвращает массив всех свойств dto со всеми его типами.

Методы сериализации (приведение к массиву/json):

@method public toArray(?bool $onlyFilled = null)
Сериализация Dto в массив.

@method public static toArrayBlank()
Возвращает массив с пустыми значениями всех свойств dto.

@method public static toArrayBlankRecursive()
Возвращает массив с пустыми значениями всех свойств dto с рекурсией по объектам.

@method public toJson($options = 0)
Сериализация Dto в строку json.

Переопределяемые методы в дочернем классе (события):

@override @method protected defaults(): array { return []; }
Задаёт массив значений для свойств при заполнении Dto по умолчанию.

@override @method protected mappings(): array { return []; }
Задаёт массив имён свойств для маппинга в другие свойства.

@override @method protected casts(): array { return []; }
Задаёт массив приведения типов свойств при заполнении Dto.

@override @method protected exceptions(string $messageCode, array $messageItems): string {}
Возвращает сообщение об ошибке по его коду при работе с Dto.

@override @method protected onCreating(array &$data): void {}
Метод-хук вызывается перед созданием и заполнением Dto.

@override @method protected onCreated(array $data): void {}
Метод-хук вызывается после создания и заполнения Dto.

@override @method protected onFilling(array &$array): void {}
Метод-хук вызывается перед заполнением Dto.

@override @method protected onFilled(array $array): void {}
Метод-хук вызывается после заполнения Dto.

@override @method protected onMerging(array &$array): void {}
Метод-хук вызывается перед объединением массива в Dto.

@override @method protected onMerged(array $array): void {}
Метод-хук вызывается после объединения массива в Dto.

@override @method protected onSerializing(array &$array): void {}
Метод-хук вызывается перед сериализацией в массив.

@override @method protected onAssigning(string $key, mixed $value): void {}
Метод-хук выполняется перед изменением значения свойства Dto.

@override @method protected onAssigned(string $key): void {}
Метод-хук вызывается после изменения значения свойства Dto.
Для вызова метода при изменении отдельного свойства требуется PROTECTED или PRIVATE у этого свойства.

@override @method protected onException(Throwable $exception): void {}
Метод-хук вызывается перед исключением ().
Для вызова метода при изменении отдельного свойства требуется PROTECTED или PRIVATE у этого свойства.

Цепочки опций сериализации (для приведения к array/json):

@method public autoCasts(bool $autoCasts = true)
Включение/отключение опции сериализации автоматического приведения типов при заполнении Dto.

@method public autoMappings(bool $autoMappings = true)
Включение/отключение опции автоматического маппинга свойств при заполнении Dto или преобразовании в массив.

@method public onlyFilled(bool $onlyFilled = true)
Включение/отключение опции сериализации в массив только заполненных свойств.

@method public onlyNotNull(bool $onlyNotNull = true)
Включение/отключение опции сериализации в массив только не null свойств.

@method public onlyKeys(string|array|object ...$data)
Добавление опции сериализации в массив только указанных свойств.

@method public includeStyles(bool $includeStyles = true)
Добавление опции сериализации в массив для добавления разных стилей свойств camel/snake.

@method public includeArray(string|array ...$data)
Добавление опции сериализации в массив для добавления дополнительных свойств.

@method public excludeKeys(string|array ...$data)
Добавление опции сериализации в массив для исключения свойств.

@method public mappingKeys(string|array|object ...$data)
Добавление опции сериализации в массив для маппинга имён свойств.

@method public serializeKeys(string|array|object|bool ...$data)
Добавление опции сериализации в массив для преобразования объектов к скалярному типу.

@method public withProtectedKeys(string|array|object|bool ...$data)
Добавление опции сериализации в массив для добавления protected свойств.

@method public withPrivateKeys(string|array|object|bool ...$data)
Добавление опции сериализации в массив для добавления private свойств.

@method public withoutOptions(string|array|object|bool ...$data)
Добавление опции отключения всех ранее установленных опций.

@method public withCustomOptions()
Включает опцию при преобразовании в массив: преобразование customOptions свойств к массиву.

@method public customOptions(array $options)
Добавление своих опций в dto.

@method public setCustomOption()
Добавляет свою опцию в dto.

@method public getCustomOption()
Возвращает значение своей опции в dto.

@method public for(object $object)
Добавление опции сериализации в массив для подготовки свойств к заданному объекту/сущности.

Реализация интерфейсов:

@interface ArrayAccess
Включает реализацию интерфейса ArrayAccess для работы с dto как с массивом.

@interface Countable
Включает реализацию интерфейса Countable для включения метода count().

@interface IteratorAggregate
Включает реализацию интерфейса IteratorAggregate для включения метода getIterator().

@interface JsonSerializable
Включает реализацию интерфейса JsonSerializable для метода json_encode($dto).

@interface Serializable
Включает реализацию интерфейса Serializable для методов serialize($dto)/unserialize($dto).

@interface Stringable
Включает реализацию интерфейса Stringable для работы с dto как со строкой (string)$dto.

${\textsf{\color{red}ВНИМАНИЕ}}$ После каждого выполнения toArray() и toJson() все цепочки опций сбрасываются.

Примеры:

$exampleDto = ExampleDto::create(a: 1, b: 2, c: null);
$exampleDto = ExampleDto::fill(['a' => 1, 'b' => 2, 'c' => null]);

$exampleDto = ExampleDto::create(['a' => 1, 'b' => 2]);
$exampleDto = (new ExampleDto())->fillFromArray(['a' => 1, 'b' => 2]);

$exampleDto = ExampleDto::create((object)['a' => 1, 'b' => 2]);
$exampleDto = (new ExampleDto())->fillFromObject((object)['a' => 1, 'b' => 2]);

$exampleDto = ExampleDto::create('{"a": 1, "b": 2}');
$exampleDto = (new ExampleDto())->fillFromJson('{"a": 1, "b": 2}');

$exampleDto = ExampleDto::fill(['a' => 1, 'c' => 3])
    ->merge(['b' => 2]);
$exampleArray = $exampleDto
    ->onlyKeys(['a', 'b'])
    ->excludeKeys(['c'])
    ->mappingKeys(['a' => 'aa', 'b' => 'bb'])
    ->serializeKeys(['a', 'b'])
    ->toArray();

$carEntity = new CarEntity();
$exampleDto = ExampleDto::create();
$exampleArray = $exampleDto->for($carEntity)->toArray();
$exampleArray = $exampleDto->for(CarEntity::class)->toArray();

Пример Dependency Injection Dto вместо Request в Laravel

Открыть пример для Laravel

Примеры из тестов

Открыть все примеры

Переопределяемые методы

Открыть список

atlcom / dto

Maintainers

Details