CLI Reference

Complete reference for the DTO Generator command-line interface.

Installation

After installing via Composer, the CLI is available at:

vendor/bin/dto

Commands

generate (default)

Generate PHP DTOs from configuration files.

vendor/bin/dto generate [options]

This is the default command, so vendor/bin/dto is equivalent to vendor/bin/dto generate.

typescript

Generate TypeScript interfaces from configuration files.

vendor/bin/dto typescript [options]

jsonschema

Generate JSON Schema from configuration files.

vendor/bin/dto jsonschema [options]

Common Options

Options available for all commands:

Option	Description
--config-path=PATH	Path to config directory (default: config/)
--format=FORMAT	Config format: xml, yaml, neon, php (default: auto-detect)
--verbose, -v	Verbose output with detailed information
--quiet, -q	Minimal output, only errors
--help, -h	Show help message

Generate Options

Options specific to PHP DTO generation:

Option	Description
--src-path=PATH	Path to src directory (default: src/)
--namespace=NS	Namespace for generated DTOs (default: App)
--dry-run	Show what would be generated without writing files
--force	Regenerate all DTOs, even if unchanged
--confirm	Validate PHP syntax of generated files
--mapper	Generate Doctrine-compatible mapper classes

TypeScript Options

Options specific to TypeScript generation:

Option	Description
--output=PATH	Path for TypeScript output (default: types/)
--single-file	Generate all types in one file (default)
--multi-file	Generate each type in separate file
--readonly	Make all interface fields readonly
--strict-nulls	Use | null instead of ? for nullable fields
--file-case=CASE	File naming: pascal, dashed, snake (default: pascal)

JSON Schema Options

Options specific to JSON Schema generation:

Option	Description
--output=PATH	Path for JSON Schema output (default: schemas/)
--single-file	Generate all schemas in one file with $defs (default)
--multi-file	Generate each schema in separate file
--no-refs	Inline nested DTOs instead of using $ref
--date-format=FMT	Date format: date-time, date, string (default: date-time)

Examples

Basic Generation

# Generate with defaults (config/ -> src/Dto/)
vendor/bin/dto generate

# Same as above (generate is default command)
vendor/bin/dto

Custom Paths

# Custom config and output paths
vendor/bin/dto generate --config-path=dto/ --src-path=app/

# Custom namespace
vendor/bin/dto generate --namespace=MyApp\\Dto

# All custom
vendor/bin/dto generate \
  --config-path=definitions/ \
  --src-path=lib/ \
  --namespace=Acme\\Data

Preview and Debug

# See what would be generated without writing
vendor/bin/dto generate --dry-run

# Verbose output for debugging
vendor/bin/dto generate --dry-run --verbose

# Validate generated PHP syntax
vendor/bin/dto generate --confirm

Force Regeneration

# Regenerate all DTOs, ignoring timestamps
vendor/bin/dto generate --force

Doctrine Mapper Generation

# Generate DTOs with Doctrine-compatible mapper classes
vendor/bin/dto generate --mapper

# Creates:
#   src/Dto/UserDto.php           - Standard DTO
#   src/Dto/Mapper/UserDtoMapper.php - Mapper with positional constructor

The mapper classes extend the DTOs with positional constructors for use with Doctrine's SELECT NEW syntax. See Framework Integration for usage details.

TypeScript Generation

# Generate TypeScript interfaces (single file)
vendor/bin/dto typescript

# Custom output directory
vendor/bin/dto typescript --output=frontend/src/types/

# Separate files with dashed naming
vendor/bin/dto typescript --multi-file --file-case=dashed
# Creates: user-dto.ts, order-dto.ts, etc.

# Readonly interfaces with strict nulls
vendor/bin/dto typescript --readonly --strict-nulls

JSON Schema Generation

# Generate JSON Schema (single file with $defs)
vendor/bin/dto jsonschema

# Custom output directory
vendor/bin/dto jsonschema --output=api/schemas/

# Separate files with external $ref
vendor/bin/dto jsonschema --multi-file
# Creates: UserDto.json, OrderDto.json, etc.

# Inline nested DTOs instead of using $ref
vendor/bin/dto jsonschema --no-refs

# Custom date format
vendor/bin/dto jsonschema --date-format=date

CI/CD Integration

# In CI pipeline - fail if DTOs are outdated
vendor/bin/dto generate --dry-run
if [ $? -ne 0 ]; then
  echo "DTOs are not up to date. Run 'vendor/bin/dto generate' locally."
  exit 1
fi

# Or validate syntax after generation
vendor/bin/dto generate --confirm

Configuration File Discovery

The CLI auto-detects configuration files in the following order:

1. Single file: {config-path}/dto.{ext} where {ext} is xml, yaml, neon, or php
2. Multiple files: {config-path}/dto/*.{ext}

Format Detection

When --format is not specified:

1. Checks file extension
2. For directories, scans for first recognized format
3. Falls back to XML

Multiple Configuration Files

You can split DTOs across multiple files:

config/
└── dto/
    ├── user.xml
    ├── order.xml
    └── product.xml

All files in the directory are merged during generation.

Exit Codes

Code	Meaning
0	Success
1	Error (invalid config, generation failure, etc.)

Environment Variables

The CLI respects standard environment variables:

Variable	Effect
NO_COLOR	Disables colored output
TERM=dumb	Disables colored output

Scripting

Composer Scripts

Add to composer.json:

{
  "scripts": {
    "dto:generate": "dto generate",
    "dto:generate-mapper": "dto generate --mapper",
    "dto:check": "dto generate --dry-run",
    "dto:typescript": "dto typescript --output=frontend/types/",
    "dto:schema": "dto jsonschema --output=api/schemas/"
  }
}

Then run:

composer dto:generate
composer dto:check

Git Hooks

Pre-commit hook to ensure DTOs are current:

#!/bin/sh
# .git/hooks/pre-commit

vendor/bin/dto generate --dry-run --quiet
if [ $? -ne 0 ]; then
  echo "Error: DTO configuration has changed."
  echo "Run 'vendor/bin/dto generate' and commit the generated files."
  exit 1
fi

Makefile

.PHONY: dto dto-check dto-typescript

dto:
	vendor/bin/dto generate

dto-check:
	vendor/bin/dto generate --dry-run

dto-typescript:
	vendor/bin/dto typescript --output=frontend/src/types/