Download the PHP package gpalyan/dto-forge without Composer

PHP DTO Package

A flexible and powerful Data Transfer Object (DTO) library for PHP that provides validation, type casting, default value generation, and convenient data manipulation methods.

Contents

• Features
• Installation
• Basic Usage
  • Creating DTOs
  • Magic Methods
  • Filling Data
  • Merging DTOs
  • Comparing DTOs
  • Cloning DTOs
  • Serialization
• Nested DTOs
• Validation
  • Using Built-in Validators
  • Validation Errors
  • Creating Custom Validators
• Default Value Generation
  • Creating Custom Generators
• Type Casting
  • Casting Collections
• Masking
• API Reference
• Contributing

Features

• Easy DTO Creation - Create DTOs from arrays, JSON, or use fluent setters
• Built-in Validation - Validate data with custom rules (required fields, INN validation, etc.)
• Type Casting - Automatic type conversion for scalar values
• Data Manipulation - Merge, diff, fill, and clone DTOs
• Nested DTOs - Full support for nested DTO structures
• Default Values - Generate default values automatically when needed
• Serialization - Convert to arrays and JSON easily
• Masking - Redact sensitive fields on serialization without mutating the DTO

Installation

Basic Usage

Creating DTOs

All DTOs must extend BaseDto:

Magic Methods

DTOs automatically provide getters, setters, and checkers for all properties without explicit method definitions. You don't need to manually create getter/setter methods - they are generated automatically based on property names using camelCase convention.

Filling Data

Merging DTOs

Comparing DTOs

Cloning DTOs

Serialization

Nested DTOs

Validation

Validation is applied via PHP attributes on DTO properties.

Using Built-in Validators

Validation Errors

Get all validation errors that occurred during DTO population:

Creating Custom Validators

Implement PropertyValidatorInterface to create your own validators:

Requirements for custom validators:

• Must be a PHP 8 Attribute with Attribute::TARGET_PROPERTY
• Must implement PropertyValidatorInterface
• Throw DtoValidationException on validation failure

Default Value Generation

Generate default values for properties using attributes.

Creating Custom Generators

Implement DefaultValueGeneratorInterface to create your own generators:

Requirements for custom generators:

• Must be a PHP 8 Attribute with Attribute::TARGET_PROPERTY
• Must implement DefaultValueGeneratorInterface
• Implement generate(BaseDto $dto): mixed - returns the generated value
• Implement supports(BaseDto $dto, string $propertyName): bool - determines if generation should occur

Type Casting

The package automatically casts values to appropriate types:

Casting Collections

An array property does not know what its items are. To cast each element into a DTO, declare the item type explicitly with the #[CastEachTo] attribute:

Each raw array (or JSON object) is constructed into the given class; values that are already instances of that class are passed through unchanged. Casting is opt-in via this attribute only — docblock @var Item[] annotations are treated as documentation and never drive casting.

Note: #[CastEachTo] and #[ArrayOf] are not meant to be combined on the same property. CastEachTo constructs items from raw data; #[ArrayOf] validates a collection of already-built (e.g. polymorphic) objects without constructing them. In strict mode #[ArrayOf] runs before casting and will reject raw input — pick the one that matches your intent.

Masking

Masking redacts property values on serialization only — the stored DTO value is never changed. It is opt-in per call via the masking flag on toArray() / toJson().

A mask is a PHP attribute implementing PropertyMaskInterface:

Requirements / behavior:

• Must be a PHP 8 Attribute with Attribute::TARGET_PROPERTY implementing PropertyMaskInterface.
• apply(string $value): string is called only for string values, and only when masking is enabled.
• One mask per property — the first attribute wins.
• Nested DTOs are masked recursively; masking never mutates the DTO, only its serialized output.

API Reference

Core Methods

• fill(array $data): self - Fill DTO with data from array
• merge(DtoInterface $dto): self - Merge another DTO into this one
• diff(DtoInterface $dto): array - Get differences between DTOs
• clone(): self - Create a deep copy of the DTO
• toArray(): array - Convert DTO to array
• toJson(): string - Convert DTO to JSON string
• generateDefaultsIfAllowed(): void - Generate default values for null fields

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.