jooservices/dto

A PHP 8.5+ DTO and Data library with immutable DTOs and mutable Data objects

v2.0.0 2026-08-19 18:25 UTC

Requires

• php: >=8.5
• jooservices/exceptions: ^1.0

Requires (Dev)

• captainhook/captainhook: ^5.23
• captainhook/plugin-composer: ^5.3
• fakerphp/faker: ^1.24
• friendsofphp/php-cs-fixer: ^3.65
• laravel/pint: ^1.18
• phpbench/phpbench: ^1.6
• phpmd/phpmd: ^2.15
• phpstan/phpstan: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^12.0 || ^13.0
• squizlabs/php_codesniffer: ^3.8 || ^4.0

Suggests

• psr/container: Required when using registry auto-discovery with dependency injection via SupportsDiscovery::setContainer().
• psr/log: Enables debug logging during DTO hydration via Engine constructor injection.

MIT

• JOOservices

• data
• mapping
• dto
• hydration
• normalization
• casting
• data-transfer-object

Published on Packagist.org on 2026-08-19 18:25 UTC

README

The JOOservices DTO Library is a PHP 8.5+ library for constructor-based DTO hydration, mutable data objects, opt-in validation, serialization control, and DTO collection wrappers.

Package name: jooservices/dto

Latest stable release: v2.0.0

Install

composer require jooservices/dto

Quick example

use JOOservices\Dto\Attributes\MapFrom;
use JOOservices\Dto\Core\Dto;

final class UserDto extends Dto
{
    public function __construct(
        public readonly string $id,
        #[MapFrom('email_address')]
        public readonly string $email,
        public readonly \DateTimeImmutable $createdAt,
    ) {}
}

$user = UserDto::from([
    'id' => 'u_123',
    'email_address' => '[e-mail]',
    'createdAt' => '2026-01-15T10:30:00+00:00',
]);

$payload = $user->toArray();

Design contract

All DTOs must declare a constructor with public promoted properties. Constructor-less DTOs are not supported.

What is supported today

• Dto and Data
• hydration from arrays, JSON strings, and simple public-property objects
• scalar, enum, and DateTimeInterface casting
• nested single DTO hydration
• class-level polymorphic DTO hydration with #[DiscriminatorMap]
• typed array hydration from common PHPDoc annotations such as Type[], array<Type>, and list<Type>
• fallback property defaults with #[DefaultFrom]
• opt-in validation with attributes and standalone Dto::validate() on existing instances
• serialization filtering and wrapping
• lazy derived serialization through ComputesLazyProperties
• property-level #[Pipeline] and request-wide Context::$globalPipeline during hydration
• DataCollection and PaginatedCollection
• JSON Schema / OpenAPI generators with self-contained recursive $ref graphs
• CastMode validation plus optional decoupling of unknown-key rejection and scalar coercion

Important current limitations

• CastWith / TransformWith options are constructor-spread arguments for the configured class, not free-form bags passed into cast() / transform()
• intersection types remain pass-through at runtime
• phpDocumentor local generation is blocked until the generator supports PHP 8.5 cleanly

See Migration to 2.0 if you are upgrading from 1.x.

Documentation

Start with:

• Documentation Hub
• Changelog
• AI Skills Usage Guide
• phpDocumentor config for future API reference generation: phpdoc.dist.xml
• Installation
• Quick Start
• Risks, Legacy, and Gaps

AI Support

This repository includes an AI skill pack for agents working in Cursor, Claude Code, VS Code, JetBrains, and Antigravity.

Start with:

• AGENTS.md
• CLAUDE.md
• AI Skills Map
• AI Skills Usage Guide

The canonical skill source lives in .github/skills/, with adapter layers for each supported AI environment.

Development

composer lint:fast
composer lint
composer lint:all
composer lint:fix
composer test
composer test:coverage
composer bench
composer bench:quick
composer instructions:verify
composer check
composer ci

Contributor workflow details live in:

• Setup
• Contributing
• CI/CD
• Release Process
• AI Skills

Approved Git flow summary:

• normal feature and fix work branches from develop and PRs back into develop
• release preparation uses release/<version> from develop, then PRs into master
• releases are tagged from master
• master merges back into develop after release or hotfix completion

Community

• Contributing
• Security Policy
• Code of Conduct

GitHub Actions and Services

Current GitHub Actions coverage:

• CI: reusable validate → quality → security → coverage pipeline (lint matrix, Unit and Integration suites, 85% per-suite coverage gate, Gitleaks Scan - secret, composer audit, Codecov upload, Codacy coverage upload when CODACY_API_TOKEN is configured, optional SonarQube Cloud analysis when SONAR_TOKEN is configured)
• Release: tag v*.*.* validation, GitHub release, Packagist update
• PR Labeler: apply labels to pull requests
• Semantic PR Title: enforce pull request title format
• OpenSSF Scorecard: publish scorecard results as SARIF

External services currently used by workflows:

• Codecov for coverage upload in ci.yml
• Codacy for grade badge visibility and optional coverage upload via CODACY_API_TOKEN in ci.yml
• Packagist update webhook in release.yml
• GitHub Releases and GitHub Discussions in release.yml
• OpenSSF Scorecard in scorecard.yml
• GitHub SARIF upload through CodeQL infrastructure in scorecard.yml

Important notes:

• No workflow currently defines Docker-style services: containers such as MySQL, Redis, or PostgreSQL.
• SonarQube Cloud analysis is present in ci.yml, but it only runs after tests pass and only when SONAR_TOKEN is available.

License

This project is licensed under the MIT License.