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
JSON Schema generation for API documentation
Schema importer to bootstrap DTOs from JSON data or OpenAPI specs

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
Performance - Benchmarks and optimization tips
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