README

✅ Requires PHP 8.1–8.5

DTO Toolkit Core is a lightweight, framework-agnostic library for defining, transforming, and (soon) validating Data Transfer Objects (DTOs) in PHP.

It offers a clean, declarative API powered by attributes — handling normalization, casting, and output shaping — all without coupling to any specific framework.

Casters, modifiers, and validators are composed into a fully declarative transformation DSL, JIT-compiled into efficient processing chains at runtime.

✨ Features

🧱 Minimal and framework-agnostic
🏷️ Attribute-based processing system with flexible resolution
🎯 Optional validation and normalization layers
🔄 Easily transform between DTOs and entities/models
🧩 Designed to work with pluggable framework adapters (Laravel, Symfony, etc.)

📦 Installation

composer require nandan108/dto-toolkit

🚀 Quick Start

use Nandan108\DtoToolkit\Core\{FullDto, CastTo};

// FullDto includes all standard traits (CreatesFromArray, NormalizesFromAttributes, ExportsToEntity)
class MyDto extends FullDto {
    #[CastTo\Trimmed()]
    public ?string $name = null;
}

// Build DTO from array
$dto = MyDto::newFromArray(['name' => '  Alice  ']);

// Transform into an entity
$entity = $dto->toEntity();

Use a framework adapter (e.g. Symfony or Laravel) to unlock request/response integration and validation support.

📦 Core Namespace

If you're not using a framework, start with:

Nandan108\DtoToolkit\Core\FullDto
Nandan108\DtoToolkit\Core\CastTo

These provide a convenient, framework-free entry point with all standard functionality included.

📚 Documentation

DTO Fundamentals – what DTOs are, why they matter, and how to use them in modern PHP
Casting – how casting works and how to write your own
Attributes - List of attributes
Lifecycle – Understanding the lifecycle of a DTO
Lifecycle Hooks – customize behavior with postLoad() and preOutput()
Toolkit Comparison – see how this toolkit compares to other PHP DTO/mapping libraries
Processing in detail — Validating and Transforming Data Through Nodes
Built-In Core Casters — Full list of available CastTo\* casters
Built-In Core Validators — list of available Validate\* validators (more are planned)
Built-In Core Modifiers — Full list of available Mod\* chain modifiers
Dependency Injection
Writing Adapters (planned)

🧩 Adapter Packages

Laravel Adapter: nandan108/dto-toolkit-laravel (planned)
Symfony Adapter: nandan108/dto-toolkit-symfony (planned)

Adapters will provide support for:

Framework-compatible error handling and translations, for both validators and casters
fromRequest() for DTO hydration from HTTP requests
toEntity() or toModel() adapter-specific hydration
toResponse() generation
DI for class-based casters resolution
Graceful handling of validation and casting exceptions in HTTP contexts, with standardized API error responses

🧪 Testing & Quality

100% test coverage using PHPUnit
Psalm level 3
Code style enforced with PHP-CS-Fixer:
- Based on the @Symfony rule set
- Aligned => for better readability
- Disallows implicit loose comparisons (==, !=)
Commit message style: conventional, with details if any

🤝 Contributing

Bug reports, ideas, and contributions welcome! This project aims to stay lean, clean, and focused. If you're building an adapter or extending the system, feel free to open a discussion or issue.

🧭 Design Philosophy

This toolkit is built on a simple idea: do the most work with the least number of moving parts.

It favors:

Declarative code over procedural boilerplate
Clever, expressive syntax without falling into obfuscation
Minimalism with power — clean by default, extensible when needed
Framework-agnostic design with optional adapters that integrate smoothly when needed
Zero magic in the core — everything is traceable, explicit, and predictable
Opt-in magic in adapters — for just the right touch of convenience when working with frameworks
Separation of concerns and composability — inspired by the Unix philosophy of doing one thing well
Performance-conscious by design — DTOs should feel lightweight and fast to use, even in large batch transformations.

Verbose code is a tax on your time. This toolkit aims to keep things sharp, concise, and purposeful — so you can focus on what matters.

nandan108 / dto-toolkit

Maintainers

Details