DTOs at the Speed of Plain PHP – DerEuroMark

Introducing php-collective/dto: The Code-Generation Approach

Data Transfer Objects (DTOs) have become essential in modern PHP applications. They provide type safety, IDE autocomplete, and make your code more maintainable. But the PHP ecosystem has long debated how to implement them: runtime reflection or manual boilerplate?

php-collective/dto takes a third path: code generation. Define your DTOs once in configuration, generate optimized PHP classes, and enjoy the best of both worlds.

What You Get

1. Perfect IDE Support – Real methods = perfect autocomplete, “Find Usages”, refactoring
2. Excellent Static Analysis – PHPStan/Psalm work without plugins or special annotations
3. Reviewable Code – Generated classes appear in pull requests
4. Zero Runtime Overhead – No reflection, no type parsing per instantiation
5. Framework Agnostic – Works anywhere PHP runs

1. Multiple Configuration Formats

Choose what works for your team:

XML (with XSD validation):

<dto name="User">
    <field name="id" type="int" required="true"/>
    <field name="email" type="string" required="true"/>
    <field name="roles" type="string[]" collection="true"/>
</dto>

Or use YAML or NEON for minimal syntax. Or stick to the PHP one above.

2. Mutable and Immutable Options

Mutable (default) – traditional setters:

$user = new UserDto();
$user->setName('John');
$user->setEmail('[email protected]');

Immutable – returns new instances:

$user = new UserDto(['name' => 'John']);
$updated = $user->withEmail('[email protected]');
// $user is unchanged, $updated has new email

Configure per-DTO:

Dto::immutable('Event')->fields(/* ... */);

3. Smart Key Format Conversion

APIs use snake_case. JavaScript wants camelCase. Forms send dashed-keys. Handle all of them:

// From snake_case database
$dto->fromArray($dbRow, false, UserDto::TYPE_UNDERSCORED);
// To camelCase for JavaScript
return $dto->toArray(); // default camelCase
// To snake_case for Python API
return $dto->toArray(UserDto::TYPE_UNDERSCORED);

4. Collections with Type Safety

<dto name="Order">
    <field name="items" type="OrderItem[]" collection="true" singular="item"/>
</dto>

Generated methods:

$order->getItems();           // ArrayObject<OrderItemDto>
$order->addItem($itemDto);    // Type-checked
$order->hasItems();           // Collection not empty

Associative collections work too:

$config->addSetting('theme', $settingDto);
$theme = $config->getSetting('theme');

Custom collection factories let you use Laravel Collections, Doctrine ArrayCollection, or CakePHP Collection (when generated with a non-\ArrayObject collection type):

Dto::setCollectionFactory(fn($items) => collect($items));
// Now all getters return Laravel collections
$order->getItems()->filter(...)->sum(...);

5. Deep Nesting and Safe Access

$company = new CompanyDto($data);
// Safe nested reading with default
$city = $company->read(['departments', 0, 'address', 'city'], 'Unknown');
// Deep cloning - nested objects are fully cloned
$clone = $company->clone();
$clone->getDepartments()[0]->setName('Changed');
// Original unchanged

6. TypeScript Generation

Share types with your frontend:

vendor/bin/dto typescript --output=frontend/src/types/

Generates:

export interface UserDto {
    id: number;
    email: string;
    name?: string;
    roles: string[];
}
export interface OrderDto {
    id: number;
    customer: UserDto;
    items: OrderItemDto[];
}

Options include multi-file output, readonly interfaces, and strict null handling.

7. Field Tracking for Partial Updates

Know exactly what was changed:

$dto = new UserDto();
$dto->setEmail('[email protected]');
$changes = $dto->touchedToArray();
// ['email' => '[email protected]']
// Perfect for partial database updates
$repository->update($userId, $changes);

8. OrFail Methods for Non-Null Guarantees

Every nullable field gets an OrFail variant:

$email = $dto->getEmail();        // string|null
$email = $dto->getEmailOrFail();  // string (throws if null)

Use after validation to avoid null checks:

$email = $dto->getEmailOrFail(); // PHPStan now knows it is not nullable

9. Required Fields

Enforce data integrity at creation:

<field name="id" type="int" required="true"/>

new UserDto(['name' => 'John']);
// InvalidArgumentException: Required fields missing: id

10. Validation Rules

Beyond required fields, you can add common validation constraints:

Dto::create('User')->fields(
    Field::string('name')->required()->minLength(2)->maxLength(100),
    Field::string('email')->required()->pattern('/^[^@]+@[^@]+\.[^@]+$/'),
    Field::int('age')->min(0)->max(150),
)

Validation runs on instantiation. Null fields skip validation — rules only apply when a value is present.

The validationRules() method extracts all rules as metadata, useful for bridging to framework validators:

$rules = $dto->validationRules();
// ['name' => ['required' => true, 'minLength' => 2, 'maxLength' => 100], ...]

11. Enum Support

<field name="status" type="\App\Enum\OrderStatus"/>

// From enum instance
$order->setStatus(OrderStatus::Pending);
// From backing value - auto-converted
$order = new OrderDto(['status' => 'confirmed']);
$order->getStatus(); // OrderStatus::Confirmed

12. Value Objects and DateTime

<field name="price" type="\Money\Money"/>
<field name="createdAt" type="\DateTimeImmutable"/>

Custom factories for complex instantiation:

Field::class('date', \DateTimeImmutable::class)->factory('createFromFormat')

13. Transform Functions

Apply callables to transform values during hydration or serialization:

Field::string('email')
    ->transformFrom('App\\Transform\\Email::normalize')  // Before hydration
    ->transformTo('App\\Transform\\Email::mask')         // After serialization

Useful for normalizing input (trimming, lowercasing) or masking output (hiding sensitive data). For collections, transforms apply to each element.

14. DTO Inheritance

Share common fields:

Dto::create('BaseEntity')->fields(
    Field::int('id')->required(),
    Field::class('createdAt', \DateTimeImmutable::class),
)
Dto::create('User')->extends('BaseEntity')->fields(
    Field::string('email')->required(),
)
// UserDto has id, createdAt, and email

15. Array Shapes

Every generated DTO now gets shaped array types on toArray() and createFromArray():

// UserDto with fields: id (int, required), name (string), email (string, required)
/**
 * @return array{id: int, name: string|null, email: string}
 */
public function toArray(?string $type = null, ?array $fields = null, bool $touched = false): array

1. IDE Autocomplete – $dto->toArray()['na suggests name
2. Typo Detection – $dto->toArray()['naem'] shows error
3. Type Inference – ['name' => $name] = $dto->toArray() infers $name as string|null
4. Destructuring Support – Full type safety when unpacking arrays

16. JSON Schema Generation

Complement your TypeScript types with JSON Schema for API documentation and contract testing:

vendor/bin/dto jsonschema --output=schemas/

Supports --single-file (with $defs references), --multi-file, --no-refs (inline nested objects), and --date-format options.

Also:

• Property name mapping via mapFrom() and mapTo() — read from email_address in input, write to emailAddr in output
• Default values for fields
• Deprecation annotations (IDE warnings for deprecated fields)
• Union types support (string|int)
• Generic collection type hints (@return ArrayObject<int, ItemDto>)
• Computed/derived fields via traits (getFullName() from firstName + lastName)
• Schema importer (bootstrap DTOs from JSON schemas or OpenAPI 3.x specifications)
• JSON serialization via serialize()/unserialize()
• Doctrine mapper generation (--mapper) for SELECT NEW style constructors
• Collection adapters (CakePHP, Laravel, Doctrine) via adapter registry

API Response Transformation

class UserController
{
    public function show(int $id): JsonResponse
    {
        $user = $this->repository->find($id);
        $dto = UserDto::createFromArray($user->toArray());
        // Snake case for JSON API
        return new JsonResponse($dto->toArray(UserDto::TYPE_UNDERSCORED));
    }
}

Form Handling with Partial Updates

public function update(Request $request, int $id): Response
{
    $dto = new UserDto();
    $dto->fromArray($request->all(), false, UserDto::TYPE_UNDERSCORED);
    // Only update fields that were actually submitted
    $this->repository->update($id, $dto->touchedToArray());
    return new Response('Updated');
}

Event Sourcing with Immutable DTOs

$event = new OrderPlacedDto([
    'eventId' => Uuid::uuid4()->toString(),
    'aggregateId' => $orderId,
    'occurredAt' => new DateTimeImmutable(),
    'order' => $orderDto,
]);
// Create corrected version without mutating original
$corrected = $event->withVersion(2);

Simple DTO Creation (User with 6 fields)

Standalone benchmarks (using spatie/data-transfer-object instead of laravel-data, which requires a full Laravel app) show 52.8K/s and symfony/serializer 106K/s.

Complex Nested DTOs (Order with User, Address, 3 Items)

Standalone nested results: spatie/data-transfer-object 10.6K/s, symfony/serializer 13.6K/s.

The gap widens with complexity. Runtime libraries pay reflection costs for every nested object. Generated code doesn’t.

Serialization (toArray)

Property Access (10 reads)

Getter methods are nearly as fast as direct property access – the small overhead is negligible in real applications.

Mutable vs Immutable Operations

Immutable operations are ~1.6x slower due to object cloning, but still extremely fast at 8.3 million operations per second.

JSON Serialization

At 339K JSON documents per second, this is more than sufficient for any web application. A typical API handles 1K-10K requests/second.

Visual Comparison

Simple DTO Creation (ops/sec, higher is better):
┌──────────────────────────────────────────────────────────────────┐
│ Plain PHP        ████████████████████████████████████    3.64M/s │
│ php-collective   ██████████████████                      1.68M/s │
│ laravel-data     █                                       67.7K/s │
│ valinor          █                                       63.4K/s │
└──────────────────────────────────────────────────────────────────┘
Complex Nested DTO (ops/sec, higher is better):
┌──────────────────────────────────────────────────────────────────┐
│ Plain PHP        ██████████████████████████████████       571K/s │
│ php-collective   ███████████████████                      322K/s │
│ laravel-data     ████                                    20.5K/s │
│ valinor          ███                                     14.6K/s │
└──────────────────────────────────────────────────────────────────┘

Key Insights

1. php-collective/dto is 25-26x faster than runtime DTO libraries for object creation
2. Only ~2.2x slower than plain PHP — generated code approaches hand-written performance
3. Serialization is ~22x faster than spatie/laravel-data — generated toArrayFast() avoids per-field metadata lookups
4. The performance gap grows with nesting – more nested objects = more reflection overhead for runtime libraries
5. Can process ~322K complex nested DTOs per second – sufficient for any batch processing scenario
6. Property access and mutability operations are near-native speed

Stage 0: The Array Wilderness

This is where most legacy PHP projects start. Data flows as associative arrays, and every access is a leap of faith:

// Controller
public function view(int $id): Response
{
    $user = $this->Users->get($id, contain: ['Addresses', 'Roles']);
    $data = $user->toArray();
    // Pass array to service
    $summary = $this->buildSummary($data);
    return $this->response->withJson($summary);
}
private function buildSummary(array $data): array
{
    return [
        'full_name' => $data['first_name'] . ' ' . $data['last_name'],
        'city' => $data['address']['city'] ?? 'Unknown',  // exists?
        'role_count' => count($data['roles'] ?? []),       // array?
    ];
}

Problems: no autocomplete, no type safety, no way to know the shape without reading the query. A typo like $data['adress'] silently returns null.

Stage 1: Introduce DTOs at the Boundary

Start where it hurts most — the API response layer. Replace outgoing arrays with DTOs:

// Define the DTO config
Dto::create('UserSummary')->fields(
    Field::string('fullName')->required(),
    Field::string('city'),
    Field::int('roleCount'),
);

vendor/bin/dto generate

// Controller — only the return type changes
public function view(int $id): Response
{
    $user = $this->Users->get($id, contain: ['Addresses', 'Roles']);
    $summary = new UserSummaryDto([
        'fullName' => $user->first_name . ' ' . $user->last_name,
        'city' => $user->address?->city,
        'roleCount' => count($user->roles),
    ]);
    return $this->response->withJson($summary->toArray());
}

The entity query stays the same. The service layer stays the same. But the API contract is now explicit, typed, and autocomplete-friendly. If someone removes city from the DTO config, the generator catches it.

Stage 2: Move DTOs Inward to Service Methods

Once boundaries are typed, push DTOs into service signatures:

// Before: what does this array contain? Who knows.
public function calculateShipping(array $order): float
// After: explicit contract
public function calculateShipping(OrderDto $order): float
{
    $weight = $order->getItems()
        ->filter(fn(OrderItemDto $item) => $item->getWeight() > 0)
        ->sum(fn(OrderItemDto $item) => $item->getWeight());
    return $this->rateCalculator->forWeight($weight, $order->getAddress());
}

Every caller now gets a compile-time check (via PHPStan) that they’re passing the right data. The method signature is the documentation.

Stage 3: Replace Internal Array Passing

Target the most common pattern — methods that return arrays of mixed data:

// Before
public function getStats(): array
{
    return [
        'total_users' => $this->Users->find()->count(),
        'active_today' => $this->Users->find('activeToday')->count(),
        'revenue' => $this->Orders->find()->sumOf('total'),
    ];
}
// Template: $stats['total_users'] — typo-prone, no autocomplete

// After
public function getStats(): DashboardStatsDto
{
    return new DashboardStatsDto([
        'totalUsers' => $this->Users->find()->count(),
        'activeToday' => $this->Users->find('activeToday')->count(),
        'revenue' => $this->Orders->find()->sumOf('total'),
    ]);
}
// Template: $stats->getTotalUsers() — autocomplete, type-checked

Stage 4: Use Projection for Read-Only Queries

For CakePHP 5.3+, skip the entity entirely on read paths:

// Before: full entity hydration, then manual mapping
$users = $this->Users->find()
    ->select(['id', 'email', 'name', 'created'])
    ->contain(['Roles'])
    ->all()
    ->toArray();
// After: straight to DTO, no entity in between
$users = $this->Users->find()
    ->select(['id', 'email', 'name', 'created'])
    ->contain(['Roles'])
    ->projectAs(UserListDto::class)
    ->all()
    ->toArray();

The query result maps directly into UserListDto objects. No entity overhead, no intermediate array step.

What to Migrate First

Not everything needs a DTO. Prioritize based on pain:

Rules of Thumb

• Don’t convert everything at once. Start with the file you’re already editing.
• One DTO per PR. Each conversion is a small, reviewable change.
• Let the pain guide you. If you’ve been burned by a missing array key, that’s where the DTO goes.
• Keep entities for writes. Entities handle validation, callbacks, and persistence. DTOs handle data transfer. They coexist.
• Generated DTOs can wrap entities. Use UserDto::createFromArray($entity->toArray()) as a bridge during migration — no need to refactor the query layer first.