JOOservices DTO Library

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: v1.6.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' => 'john@example.com',
    'createdAt' => '2026-01-15T10:30:00+00:00',
]);

$payload = $user->toArray();

Design contract

All DTOs are expected to declare a constructor with public promoted properties. While some helper methods may continue to work with constructor-less DTOs for backward compatibility, constructor-less DTOs are not part of the recommended or guaranteed API contract.

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

• deprecated placeholder attributes Computed, Deprecated, and OptionalProperty are not runtime-active (use ComputesLazyProperties, app-level deprecation, and nullable/defaults instead)
• Context::$transformerMode remains reserved and is not behavior-defining
• CastWith / TransformWith options are constructor-spread arguments for the configured class, not free-form bags passed into cast() / transform()

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
composer lint:all
composer test
composer test:coverage
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: security checks, lint matrix, tests, 98% minimum statement coverage, Codecov upload, Codacy coverage upload when CODACY_API_TOKEN is configured, and optional SonarQube Cloud analysis when SONAR_TOKEN is configured
• Codacy: uploads Codacy SARIF results to GitHub Code Scanning on pull requests, pushes to master, and a weekly schedule
• Fortify: required Fortify AST check on master/develop; skips cleanly when Fortify credentials are not configured
• Release: validate tags, create GitHub releases, trigger Packagist update
• PR Labeler: apply labels to pull requests
• Semantic PR Title: enforce pull request title format
• OpenSSF Scorecard: publish scorecard results as SARIF
• Secret Scanning: Gitleaks CLI via .github/workflows/secret-scanning.yml (shared .gitleaks.toml, no GITLEAKS_LICENSE)

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.