README

Framework-agnostic DTO library with code generation for PHP.

Unlike runtime reflection libraries, this library generates optimized DTO classes at build time, giving you:

Zero runtime reflection overhead
Perfect IDE autocomplete with real methods
Excellent static analysis support (PHPStan/Psalm work out of the box)
Reviewable generated code in pull requests

See Motivation for why code generation beats runtime reflection.

Installation

composer require php-collective/dto

Quick Start

Define DTOs in PHP (or XML, YAML, NEON):

// config/dto.php
use PhpCollective\Dto\Config\Dto;
use PhpCollective\Dto\Config\Field;
use PhpCollective\Dto\Config\Schema;

return Schema::create()
    ->dto(Dto::create('Car')->fields(
        Field::string('color'),
        Field::dto('owner', 'Owner'),
    ))
    ->dto(Dto::create('Owner')->fields(
        Field::string('name'),
    ))
    ->toArray();

Generate and use:

vendor/bin/dto generate

$car = CarDto::createFromArray(['color' => 'red']);
$car->setOwner(OwnerDto::create(['name' => 'John']));
$array = $car->toArray();

See Quick Start Guide for detailed examples.

Immutable DTOs

A more realistic example using immutable DTOs for a blog system:

// config/dto.php
return Schema::create()
    ->dto(Dto::create('Article')->immutable()->fields(
        Field::int('id')->required(),
        Field::string('title')->required(),
        Field::string('slug')->required(),
        Field::string('content'),
        Field::dto('author', 'Author')->required(),
        Field::collection('tags', 'Tag')->singular('tag'),
        Field::bool('published')->defaultValue(false),
        Field::string('publishedAt'),
    ))
    ->dto(Dto::create('Author')->immutable()->fields(
        Field::string('name')->required(),
        Field::string('email'),
        Field::string('avatarUrl'),
    ))
    ->dto(Dto::create('Tag')->immutable()->fields(
        Field::string('name')->required(),
        Field::string('slug')->required(),
    ))
    ->toArray();

// Creating from API/database response
$article = ArticleDto::createFromArray($apiResponse);

Reading in a template (e.g., Twig, Blade, or plain PHP):

<!-- templates/article/view.php -->
<article>
    <h1><?= htmlspecialchars($article->getTitle()) ?></h1>
    <p class="meta">
        By <?= htmlspecialchars($article->getAuthor()->getName()) ?>
        <?php if ($article->getPublishedAt()) { ?>
            on <?= $article->getPublishedAt() ?>
        <?php } ?>
    </p>

    <div class="tags">
        <?php foreach ($article->getTags() as $tag) { ?>
            <a href="/tag/<?= $tag->getSlug() ?>"><?= htmlspecialchars($tag->getName()) ?></a>
        <?php } ?>
    </div>

    <div class="content">
        <?= $article->getContent() ?>
    </div>
</article>

Features

Types: int, float, string, bool, array, mixed, DTOs, classes, enums
Union types: int|string, int|float|string (PHP 8.0+)
Collections: 'type' => 'Item[]', 'collection' => true with add/get/has methods
Associative collections: keyed access with 'associative' => true
Immutable DTOs: 'immutable' => true with with*() methods
Default values: 'defaultValue' => 0
Required fields: 'required' => true
Deprecations: 'deprecated' => 'Use newField instead'
Inflection: automatic snake_case/camelCase/dash-case conversion
Deep cloning: $dto->clone()
Nested reading: $dto->read(['path', 'to', 'field'])
PHPDoc generics: @var \ArrayObject<int, ItemDto> for static analysis
TypeScript generation: Generate TypeScript interfaces from your DTO configs
Schema Importer: Auto-create DTOs from JSON data or JSON Schema

Configuration Formats

PHP - native arrays or fluent builder
XML - XSD validation, IDE autocomplete
YAML - requires pecl install yaml
NEON - requires nette/neon

TypeScript Generation

Generate TypeScript interfaces directly from your DTO configuration - keeping frontend and backend types in sync:

# Single file output
vendor/bin/dto typescript --config-path=config/ --output=frontend/src/types/

# Multi-file with separate imports
vendor/bin/dto typescript --multi-file --file-case=dashed --output=types/

// Generated: types/dto.ts
export interface UserDto {
    id: number;
    name: string;
    email: string;
    address?: AddressDto;
    roles?: RoleDto[];
}

Options: --readonly, --strict-nulls, --file-case=pascal|dashed|snake

See TypeScript Generation for full documentation.

Schema Importer

Bootstrap DTO configurations from existing JSON data or JSON Schema definitions:

use PhpCollective\Dto\Importer\Importer;

$importer = new Importer();

// From API response example
$json = '{"name": "John", "age": 30, "email": "john@example.com"}';
$config = $importer->import($json);

// From JSON Schema
$schema = file_get_contents('openapi-schema.json');
$config = $importer->import($schema, ['format' => 'xml']);

Outputs to PHP, XML, YAML, or NEON format. Perfect for integrating with external APIs.

See Schema Importer for full documentation.

Documentation

Quick Start Guide - Getting started with examples
Configuration Builder - Fluent API for defining DTOs
Examples - Practical usage patterns
TypeScript Generation - Generate TypeScript interfaces
Schema Importer - Bootstrap DTOs from JSON data/schema
Motivation - Why code generation beats runtime reflection

Integrations

This is the standalone core library. For framework-specific integrations:

CakePHP: dereuromark/cakephp-dto - Bake commands, plugin
Laravel: php-collective/laravel-dto - Artisan commands, service provider
Symfony: php-collective/symfony-dto - Console commands, bundle integration

php-collective / dto

Maintainers

Details