DerEuroMark View RSS

Introducing php-collective/dto: The Code-Generation Approach

Data Transfer Objects (DTOs) have become essential in modern PHP applications. They provide type safety, IDE autocomplete, and make your code more maintainable. But the PHP ecosystem has long debated how to implement them: runtime reflection or manual boilerplate?

php-collective/dto takes a third path: code generation. Define your DTOs once in configuration, generate optimized PHP classes, and enjoy the best of both worlds.

What You Get

1. Perfect IDE Support – Real methods = perfect autocomplete, “Find Usages”, refactoring
2. Excellent Static Analysis – PHPStan/Psalm work without plugins or special annotations
3. Reviewable Code – Generated classes appear in pull requests
4. Zero Runtime Overhead – No reflection, no type parsing per instantiation
5. Framework Agnostic – Works anywhere PHP runs

1. Multiple Configuration Formats

Choose what works for your team:

XML (with XSD validation):

<dto name="User">
    <field name="id" type="int" required="true"/>
    <field name="email" type="string" required="true"/>
    <field name="roles" type="string[]" collection="true"/>
</dto>

Or use YAML or NEON for minimal syntax. Or stick to the PHP one above.

2. Mutable and Immutable Options

Mutable (default) – traditional setters:

$user = new UserDto();
$user->setName('John');
$user->setEmail('john@example.com');

Immutable – returns new instances:

$user = new UserDto(['name' => 'John']);
$updated = $user->withEmail('john@example.com');
// $user is unchanged, $updated has new email

Configure per-DTO:

Dto::immutable('Event')->fields(/* ... */);

3. Smart Key Format Conversion

APIs use snake_case. JavaScript wants camelCase. Forms send dashed-keys. Handle all of them:

// From snake_case database
$dto->fromArray($dbRow, false, UserDto::TYPE_UNDERSCORED);

// To camelCase for JavaScript
return $dto->toArray(); // default camelCase

// To snake_case for Python API
return $dto->toArray(UserDto::TYPE_UNDERSCORED);

4. Collections with Type Safety

<dto name="Order">
    <field name="items" type="OrderItem[]" collection="true" singular="item"/>
</dto>

Generated methods:

$order->getItems();           // ArrayObject<OrderItemDto>
$order->addItem($itemDto);    // Type-checked
$order->hasItems();           // Collection not empty

Associative collections work too:

$config->addSetting('theme', $settingDto);
$theme = $config->getSetting('theme');

Custom collection factories let you use Laravel Collections, Doctrine ArrayCollection, or CakePHP Collection (when generated with a non-\ArrayObject collection type):

Dto::setCollectionFactory(fn($items) => collect($items));

// Now all getters return Laravel collections
$order->getItems()->filter(...)->sum(...);

5. Deep Nesting and Safe Access

$company = new CompanyDto($data);

// Safe nested reading with default
$city = $company->read(['departments', 0, 'address', 'city'], 'Unknown');

// Deep cloning - nested objects are fully cloned
$clone = $company->clone();
$clone->getDepartments()[0]->setName('Changed');
// Original unchanged

6. TypeScript Generation

Share types with your frontend:

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

Generates:

export interface UserDto {
    id: number;
    email: string;
    name?: string;
    roles: string[];
}

export interface OrderDto {
    id: number;
    customer: UserDto;
    items: OrderItemDto[];
}

Options include multi-file output, readonly interfaces, and strict null handling.

7. Field Tracking for Partial Updates

Know exactly what was changed:

$dto = new UserDto();
$dto->setEmail('new@example.com');

$changes = $dto->touchedToArray();
// ['email' => 'new@example.com']

// Perfect for partial database updates
$repository->update($userId, $changes);

8. OrFail Methods for Non-Null Guarantees

Every nullable field gets an OrFail variant:

$email = $dto->getEmail();        // string|null
$email = $dto->getEmailOrFail();  // string (throws if null)

Use after validation to avoid null checks:

$email = $dto->getEmailOrFail(); // PHPStan now knows it is not nullable

9. Required Fields

Enforce data integrity at creation:

<field name="id" type="int" required="true"/>

new UserDto(['name' => 'John']);
// InvalidArgumentException: Required fields missing: id

10. Validation Rules

Beyond required fields, you can add common validation constraints:

Dto::create('User')->fields(
    Field::string('name')->required()->minLength(2)->maxLength(100),
    Field::string('email')->required()->pattern('/^[^@]+@[^@]+\.[^@]+$/'),
    Field::int('age')->min(0)->max(150),
)

Validation runs on instantiation. Null fields skip validation — rules only apply when a value is present.

The validationRules() method extracts all rules as metadata, useful for bridging to framework validators:

$rules = $dto->validationRules();
// ['name' => ['required' => true, 'minLength' => 2, 'maxLength' => 100], ...]

11. Enum Support

<field name="status" type="\App\Enum\OrderStatus"/>

// From enum instance
$order->setStatus(OrderStatus::Pending);

// From backing value - auto-converted
$order = new OrderDto(['status' => 'confirmed']);
$order->getStatus(); // OrderStatus::Confirmed

12. Value Objects and DateTime

<field name="price" type="\Money\Money"/>
<field name="createdAt" type="\DateTimeImmutable"/>

Custom factories for complex instantiation:

Field::class('date', \DateTimeImmutable::class)->factory('createFromFormat')

13. Transform Functions

Apply callables to transform values during hydration or serialization:

Field::string('email')
    ->transformFrom('App\\Transform\\Email::normalize')  // Before hydration
    ->transformTo('App\\Transform\\Email::mask')         // After serialization

Useful for normalizing input (trimming, lowercasing) or masking output (hiding sensitive data). For collections, transforms apply to each element.

14. DTO Inheritance

Share common fields:

Dto::create('BaseEntity')->fields(
    Field::int('id')->required(),
    Field::class('createdAt', \DateTimeImmutable::class),
)

Dto::create('User')->extends('BaseEntity')->fields(
    Field::string('email')->required(),
)
// UserDto has id, createdAt, and email

15. Array Shapes

Every generated DTO now gets shaped array types on toArray() and createFromArray():

// UserDto with fields: id (int, required), name (string), email (string, required)
/**
 * @return array{id: int, name: string|null, email: string}
 */
public function toArray(?string $type = null, ?array $fields = null, bool $touched = false): array

1. IDE Autocomplete – $dto->toArray()['na suggests name
2. Typo Detection – $dto->toArray()['naem'] shows error
3. Type Inference – ['name' => $name] = $dto->toArray() infers $name as string|null
4. Destructuring Support – Full type safety when unpacking arrays

16. JSON Schema Generation

Complement your TypeScript types with JSON Schema for API documentation and contract testing:

vendor/bin/dto jsonschema --output=schemas/

Supports --single-file (with $defs references), --multi-file, --no-refs (inline nested objects), and --date-format options.

Also:

• Property name mapping via mapFrom() and mapTo() — read from email_address in input, write to emailAddr in output
• Default values for fields
• Deprecation annotations (IDE warnings for deprecated fields)
• Union types support (string|int)
• Generic collection type hints (@return ArrayObject<int, ItemDto>)
• Computed/derived fields via traits (getFullName() from firstName + lastName)
• Schema importer (bootstrap DTOs from JSON schemas or OpenAPI 3.x specifications)
• JSON serialization via serialize()/unserialize()
• Doctrine mapper generation (--mapper) for SELECT NEW style constructors
• Collection adapters (CakePHP, Laravel, Doctrine) via adapter registry

API Response Transformation

class UserController
{
    public function show(int $id): JsonResponse
    {
        $user = $this->repository->find($id);
        $dto = UserDto::createFromArray($user->toArray());

        // Snake case for JSON API
        return new JsonResponse($dto->toArray(UserDto::TYPE_UNDERSCORED));
    }
}

Form Handling with Partial Updates

public function update(Request $request, int $id): Response
{
    $dto = new UserDto();
    $dto->fromArray($request->all(), false, UserDto::TYPE_UNDERSCORED);

    // Only update fields that were actually submitted
    $this->repository->update($id, $dto->touchedToArray());

    return new Response('Updated');
}

Event Sourcing with Immutable DTOs

$event = new OrderPlacedDto([
    'eventId' => Uuid::uuid4()->toString(),
    'aggregateId' => $orderId,
    'occurredAt' => new DateTimeImmutable(),
    'order' => $orderDto,
]);

// Create corrected version without mutating original
$corrected = $event->withVersion(2);

Simple DTO Creation (User with 6 fields)

Standalone benchmarks (using spatie/data-transfer-object instead of laravel-data, which requires a full Laravel app) show 52.8K/s and symfony/serializer 106K/s.

Complex Nested DTOs (Order with User, Address, 3 Items)

Standalone nested results: spatie/data-transfer-object 10.6K/s, symfony/serializer 13.6K/s.

The gap widens with complexity. Runtime libraries pay reflection costs for every nested object. Generated code doesn’t.

Serialization (toArray)

Property Access (10 reads)

Getter methods are nearly as fast as direct property access – the small overhead is negligible in real applications.

Mutable vs Immutable Operations

Immutable operations are ~1.6x slower due to object cloning, but still extremely fast at 8.3 million operations per second.

JSON Serialization

At 339K JSON documents per second, this is more than sufficient for any web application. A typical API handles 1K-10K requests/second.

Visual Comparison

Simple DTO Creation (ops/sec, higher is better):
┌──────────────────────────────────────────────────────────────────┐
│ Plain PHP        ████████████████████████████████████    3.64M/s │
│ php-collective   ██████████████████                      1.68M/s │
│ laravel-data     █                                       67.7K/s │
│ valinor          █                                       63.4K/s │
└──────────────────────────────────────────────────────────────────┘

Complex Nested DTO (ops/sec, higher is better):
┌──────────────────────────────────────────────────────────────────┐
│ Plain PHP        ██████████████████████████████████       571K/s │
│ php-collective   ███████████████████                      322K/s │
│ laravel-data     ████                                    20.5K/s │
│ valinor          ███                                     14.6K/s │
└──────────────────────────────────────────────────────────────────┘

Key Insights

1. php-collective/dto is 25-26x faster than runtime DTO libraries for object creation
2. Only ~2.2x slower than plain PHP — generated code approaches hand-written performance
3. Serialization is ~22x faster than spatie/laravel-data — generated toArrayFast() avoids per-field metadata lookups
4. The performance gap grows with nesting – more nested objects = more reflection overhead for runtime libraries
5. Can process ~322K complex nested DTOs per second – sufficient for any batch processing scenario
6. Property access and mutability operations are near-native speed

Stage 0: The Array Wilderness

This is where most legacy PHP projects start. Data flows as associative arrays, and every access is a leap of faith:

// Controller
public function view(int $id): Response
{
    $user = $this->Users->get($id, contain: ['Addresses', 'Roles']);
    $data = $user->toArray();

    // Pass array to service
    $summary = $this->buildSummary($data);

    return $this->response->withJson($summary);
}

private function buildSummary(array $data): array
{
    return [
        'full_name' => $data['first_name'] . ' ' . $data['last_name'],
        'city' => $data['address']['city'] ?? 'Unknown',  // exists?
        'role_count' => count($data['roles'] ?? []),       // array?
    ];
}

Problems: no autocomplete, no type safety, no way to know the shape without reading the query. A typo like $data['adress'] silently returns null.

Stage 1: Introduce DTOs at the Boundary

Start where it hurts most — the API response layer. Replace outgoing arrays with DTOs:

// Define the DTO config
Dto::create('UserSummary')->fields(
    Field::string('fullName')->required(),
    Field::string('city'),
    Field::int('roleCount'),
);

vendor/bin/dto generate

// Controller — only the return type changes
public function view(int $id): Response
{
    $user = $this->Users->get($id, contain: ['Addresses', 'Roles']);

    $summary = new UserSummaryDto([
        'fullName' => $user->first_name . ' ' . $user->last_name,
        'city' => $user->address?->city,
        'roleCount' => count($user->roles),
    ]);

    return $this->response->withJson($summary->toArray());
}

The entity query stays the same. The service layer stays the same. But the API contract is now explicit, typed, and autocomplete-friendly. If someone removes city from the DTO config, the generator catches it.

Stage 2: Move DTOs Inward to Service Methods

Once boundaries are typed, push DTOs into service signatures:

// Before: what does this array contain? Who knows.
public function calculateShipping(array $order): float

// After: explicit contract
public function calculateShipping(OrderDto $order): float
{
    $weight = $order->getItems()
        ->filter(fn(OrderItemDto $item) => $item->getWeight() > 0)
        ->sum(fn(OrderItemDto $item) => $item->getWeight());

    return $this->rateCalculator->forWeight($weight, $order->getAddress());
}

Every caller now gets a compile-time check (via PHPStan) that they’re passing the right data. The method signature is the documentation.

Stage 3: Replace Internal Array Passing

Target the most common pattern — methods that return arrays of mixed data:

// Before
public function getStats(): array
{
    return [
        'total_users' => $this->Users->find()->count(),
        'active_today' => $this->Users->find('activeToday')->count(),
        'revenue' => $this->Orders->find()->sumOf('total'),
    ];
}

// Template: $stats['total_users'] — typo-prone, no autocomplete

// After
public function getStats(): DashboardStatsDto
{
    return new DashboardStatsDto([
        'totalUsers' => $this->Users->find()->count(),
        'activeToday' => $this->Users->find('activeToday')->count(),
        'revenue' => $this->Orders->find()->sumOf('total'),
    ]);
}

// Template: $stats->getTotalUsers() — autocomplete, type-checked

Stage 4: Use Projection for Read-Only Queries

For CakePHP 5.3+, skip the entity entirely on read paths:

// Before: full entity hydration, then manual mapping
$users = $this->Users->find()
    ->select(['id', 'email', 'name', 'created'])
    ->contain(['Roles'])
    ->all()
    ->toArray();

// After: straight to DTO, no entity in between
$users = $this->Users->find()
    ->select(['id', 'email', 'name', 'created'])
    ->contain(['Roles'])
    ->projectAs(UserListDto::class)
    ->all()
    ->toArray();

The query result maps directly into UserListDto objects. No entity overhead, no intermediate array step.

What to Migrate First

Not everything needs a DTO. Prioritize based on pain:

Rules of Thumb

• Don’t convert everything at once. Start with the file you’re already editing.
• One DTO per PR. Each conversion is a small, reviewable change.
• Let the pain guide you. If you’ve been burned by a missing array key, that’s where the DTO goes.
• Keep entities for writes. Entities handle validation, callbacks, and persistence. DTOs handle data transfer. They coexist.
• Generated DTOs can wrap entities. Use UserDto::createFromArray($entity->toArray()) as a bridge during migration — no need to refactor the query layer first.

Basic Usage

// In your controller or view
$this->loadHelper('Geo.Leaflet', ['autoScript' => true]);

// Create a map
$map = $this->Leaflet->map([
    'zoom' => 13,
    'lat' => 48.2082,
    'lng' => 16.3738,
]);
echo $map;

// Add markers
$this->Leaflet->addMarker([
    'lat' => 48.2082,
    'lng' => 16.3738,
    'title' => 'Vienna',
    'content' => 'Welcome to <b>Vienna</b>!',
]);

$this->Leaflet->finalize();

Tile Provider Freedom

One of the biggest advantages of Leaflet is tile provider independence. The plugin includes built-in presets for popular free providers:

// OpenStreetMap (default)
$this->Leaflet->useTilePreset(LeafletHelper::TILES_OSM);

// CartoDB Light - great for data visualization
$this->Leaflet->useTilePreset(LeafletHelper::TILES_CARTO_LIGHT);

// CartoDB Dark - perfect for dark mode UIs
$this->Leaflet->useTilePreset(LeafletHelper::TILES_CARTO_DARK);

Or use any custom tile provider:

echo $this->Leaflet->map([
    'zoom' => 10,
    'lat' => 48.2082,
    'lng' => 16.3738,
    'tileLayer' => [
        'url' => 'https://{s}.tile.opentopomap.org/{z}/{x}/{y}.png',
        'options' => [
            'attribution' => '© OpenStreetMap, © OpenTopoMap',
            'maxZoom' => 17,
        ],
    ],
]);

Free Tile Provider Comparison

*Fair use policy applies

Advanced Features

The LeafletHelper supports everything you’d expect from a modern mapping library:

// Auto-centering on markers
$map = $this->Leaflet->map(['autoCenter' => true]);
$this->Leaflet->addMarker(['lat' => 48.2, 'lng' => 16.3]);
$this->Leaflet->addMarker(['lat' => 47.0, 'lng' => 15.4]);
$this->Leaflet->finalize();

// Drawing shapes
$this->Leaflet->addPolyline(
    ['lat' => 48.2082, 'lng' => 16.3738],
    ['lat' => 47.0707, 'lng' => 15.4395],
    ['color' => '#ff0000', 'weight' => 5]
);

// Circles with radius
$this->Leaflet->addCircle([
    'lat' => 48.2082,
    'lng' => 16.3738,
    'radius' => 5000,  // meters
    'fillOpacity' => 0.2,
]);

// GeoJSON support
$this->Leaflet->addGeoJson($geoJsonData);

// Marker clustering for large datasets
$this->Leaflet->enableClustering();

Supported Providers

You can also create custom providers by extending the base provider classes if you need to integrate with other services.

Usage

$this->loadHelper('Geo.StaticMap');

// Basic static map
echo $this->StaticMap->image([
    'lat' => 48.2082,
    'lng' => 16.3738,
    'zoom' => 12,
]);

// Switch providers easily
echo $this->StaticMap->image([
    'provider' => StaticMapHelper::PROVIDER_GEOAPIFY,
    'lat' => 48.2082,
    'lng' => 16.3738,
    'zoom' => 12,
    'style' => 'osm-bright',
]);

// Add markers
echo $this->StaticMap->image([
    'provider' => StaticMapHelper::PROVIDER_MAPBOX,
    'zoom' => 12,
    'markers' => [
        ['lat' => 48.2082, 'lng' => 16.3738, 'color' => 'red', 'label' => 'A'],
        ['lat' => 48.1951, 'lng' => 16.3715, 'color' => 'blue', 'label' => 'B'],
    ],
]);

Configuration

Set up your preferred provider globally:

// config/app_local.php
'StaticMap' => [
    'provider' => 'geoapify',
    'size' => '400x300',
    'geoapify' => [
        'apiKey' => env('GEOAPIFY_API_KEY'),
        'style' => 'osm-bright',
    ],
],

Provider Fallback Chain

Set up automatic failover between providers:

'Geocoder' => [
    'providers' => [
        Geocoder::PROVIDER_NOMINATIM,   // Try free option first
        Geocoder::PROVIDER_GEOAPIFY,    // Fall back to Geoapify
        Geocoder::PROVIDER_GOOGLE,      // Google as last resort
    ],
    'nominatim' => [
        'userAgent' => 'MyApp/1.0',
    ],
    'geoapify' => [
        'apiKey' => env('GEOAPIFY_API_KEY'),
    ],
    'google' => [
        'apiKey' => env('GOOGLE_MAPS_API_KEY'),
    ],
],

The chain automatically handles rate limiting and server errors, trying the next provider when one fails.

Geocoding Provider Comparison

1. Interactive Maps: GoogleMapHelper to LeafletHelper

Before:

$this->loadHelper('Geo.GoogleMap');
echo $this->GoogleMap->map();
$this->GoogleMap->addMarker(['lat' => 48.2, 'lng' => 16.3]);
$this->GoogleMap->finalize();

After:

$this->loadHelper('Geo.Leaflet', ['autoScript' => true]);
echo $this->Leaflet->map();
$this->Leaflet->addMarker(['lat' => 48.2, 'lng' => 16.3]);
$this->Leaflet->finalize();

2. Static Maps

Before:

echo $this->GoogleMap->staticMap(['center' => '48.2,16.3', 'zoom' => 12]);

After:

$this->loadHelper('Geo.StaticMap');
echo $this->StaticMap->image([
    'lat' => 48.2,
    'lng' => 16.3,
]);

3. Geocoding

Before:

'Geocoder' => [
    'apiKey' => env('GOOGLE_MAPS_API_KEY'),
],

After:

'Geocoder' => [
    'provider' => Geocoder::PROVIDER_GEOAPIFY,
    'geoapify' => [
        'apiKey' => env('GEOAPIFY_API_KEY'),
    ],
],

Marker Clustering

When displaying many markers on a Leaflet map, clustering prevents visual clutter and improves performance:

$this->Leaflet->enableClustering();

// Add hundreds of markers
foreach ($locations as $location) {
    $this->Leaflet->addMarker([
        'lat' => $location->lat,
        'lng' => $location->lng,
    ]);
}

Nearby markers are automatically grouped into clusters that expand when clicked or zoomed.

Spatial Queries with Index Support

For applications with larger datasets, the plugin now supports spatial queries using native database spatial functions. Instead of calculating distances purely in PHP or with basic SQL, you can leverage spatial indexes for significant performance improvements.

$query = $this->Addresses->find('spatial', [
    'lat' => 48.2082,
    'lng' => 16.3738,
    'distance' => 100,  // km
]);

The spatial finder uses a two-stage approach:

1. A bounding box pre-filter with ST_Within() leverages spatial indexes to quickly eliminate distant records
2. ST_Distance_Sphere() then calculates precise distances on the filtered result set

This works with MySQL 5.7+, MariaDB 10.4+, and PostGIS databases. For smaller datasets, the standard distance finder remains a simpler option.

public function up(): void {
    // Add coordinates column as nullable first
    $this->table('addresses')
        ->addColumn('coordinates', 'point', ['null' => true])
        ->update();

    // Populate from existing lat/lng data
    $this->execute("
        UPDATE addresses
        SET coordinates = ST_GeomFromText(CONCAT('POINT(', lng, ' ', lat, ')'))
    ");

    // Make NOT NULL with SRID 0 (required for spatial index)
    $this->execute("
        ALTER TABLE addresses
        MODIFY COLUMN coordinates POINT NOT NULL SRID 0
    ");

    // Add spatial index
    $this->execute('ALTER TABLE addresses ADD SPATIAL INDEX coordinates (coordinates)');
}

public function beforeSave(EventInterface $event, EntityInterface $entity): void {
    // Only for MySQL/MariaDB
    if (!$this->getConnection()->getDriver() instanceof Mysql) {
        return;
    }

    if ($entity->isDirty('lat') || $entity->isDirty('lng') || $entity->isNew()) {
        $entity->set(
            'coordinates',
            $this->getConnection()->newQuery()
                ->func('ST_GeomFromText', [sprintf('POINT(%s %s)', $entity->lng, $entity->lat)])
        );
    }
}

Why Djot instead of Markdown?

First of all it is also more secure and therefore also perfect if not all users are “trustable” admins. It is also twice as fast.

Read the pros and syntax improvements in the linked repo above for details.

Whole Templates using DjotView

Render entire templates written in Djot syntax with .djot extension.

Controller:

// src/Controller/PagesController.php
public function documentation(): void
{
    $this->viewBuilder()->setClassName('Markup.Djot');
    $this->set('username', $this->Authentication->getIdentity()->username);
}

Template (templates/Pages/documentation.djot):

# Welcome, {{username}}!

This page was rendered from a `.djot` template file.

You can use all djot features:

- *Bold* and _italic_ text
- [Links](https://example.com)
- `Code blocks`

## Features

| Feature | Status |
|---------|--------|
| Tables  | Yes    |
| Lists   | Yes    |
| Code    | Yes    |

Partial Templates

Use the Djot helper to render partial content within regular PHP templates.

AppView setup:

// src/View/AppView.php
public function initialize(): void
{
    $this->addHelper('Markup.Djot');
}

Template usage:

// templates/Articles/view.php
<div class="article-content">
    <?= $this->Djot->convert($article->body) ?>
</div>

<aside class="sidebar">
    <?= $this->Djot->convert($article->summary) ?>
</aside>

Code Snippets and Small Elements

Ideal for flash messages, notifications, or any small dynamic content.

Flash messages:

// src/Controller/UsersController.php
public function register(): void
{
    if ($this->request->is('post')) {
        // ... save logic
        $this->Flash->success('Account created! Check your _email_ for the *activation link*.');
    }
}

Custom flash element (templates/element/flash/default.php):

<?php
/** @var string $message */
?>
<div class="flash-message <?= h($class ?? 'info') ?>">
    <?= $this->Djot->convert($message) ?>
</div>

Helper methods for inline content:

// In any template
$notice = '_Note:_ This action *cannot* be undone.';
echo $this->Djot->convert($notice);

// Tooltips or help text
$helpText = 'Use `Ctrl+S` to save or `Ctrl+Z` to undo.';
echo $this->Djot->convert($helpText);

Rich Text Formatting

Djot supports the familiar emphasis and strong formatting, plus several extras:

Smart Typography

Smart quotes, em-dashes, en-dashes, and ellipsis are handled automatically:

• "Hello" becomes “Hello” with curved quotes
• --- becomes an em-dash (—)
• -- becomes an en-dash (–)
• ... becomes an ellipsis (…)

Tables with Alignment

Full table support with column alignment:

| Feature     | Status |   Notes |
|:------------|:------:|--------:|
| Left-align  | Center | Right   |

Captions (Images, Blockquotes & Tables)

The ^ prefix adds a caption to the block immediately above it:

> To be or not to be,
> that is the question.

^ William Shakespeare

Renders as:

Soft break mode

Configure soft breaks as per context and user needs:

$renderer = $converter->getRenderer(); // HtmlRenderer

// Default - newline in source, invisible in browser
$renderer->setSoftBreakMode(SoftBreakMode::Newline);

// Space - same visual result, slightly smaller HTML
$renderer->setSoftBreakMode(SoftBreakMode::Space);

// Break - every source line break becomes visible <br>
$renderer->setSoftBreakMode(SoftBreakMode::Break);

This actually allows a certain compatibility with users that are used to Markdown line breaking within normal text. So this is useful for chats or simple text inputs.

As this only affects the rendering, but not the parsing, this is still fully spec-compliant in that way.

Significant Newlines Mode (Markdown-Like)

This mode is for users accustomed to Markdown’s “human” behavior where newlines intuitively interrupt blocks.

The Djot specification states: “Paragraphs can never be interrupted by other block-level elements.”

In standard Djot, this means lists and other elements require blank lines before them – more “spaced” than what Markdown users expect.

There’s an easy solution to get the best of both worlds:

$converter = new DjotConverter(significantNewlines: true);

$result = $converter->convert("Here's a list:
- Item one
- Item two");
// Output: <p>Here's a list:</p>\n<ul><li>Item one</li><li>Item two</li></ul>

If you need a marker character (-, *, +, >) at the start of a line without triggering a block, use escaping:

// Without escaping - creates a list
$result = $converter->convert("Price:
- 10 dollars");
// Output: <p>Price:</p><ul><li>10 dollars</li></ul>

// With escaping - literal text
$result = $converter->convert("Price:
\\- 10 dollars");
// Output: <p>Price:<br>- 10 dollars</p>

This returns you to standard Djot behavior for that line.

This mode is useful when migrating existing systems where users expect Markdown-like behavior – most content works without changes, and the rare edge cases can be escaped.
For offline docs and anything needed to be more agnostic one should still use the default spec compliant way.

Extension System

The library includes a clean, modern extension system, making common features trivial to add:

use Djot\DjotConverter;
use Djot\Extension\ExternalLinksExtension;
use Djot\Extension\TableOfContentsExtension;
use Djot\Extension\DefaultAttributesExtension;

$converter = new DjotConverter();
$converter
    ->addExtension(new ExternalLinksExtension())
    ->addExtension(new TableOfContentsExtension(position: 'top'))
    ->addExtension(new DefaultAttributesExtension([
        'image' => ['loading' => 'lazy'],
        'table' => ['class' => 'table table-striped'],
    ]));

Built-in Extensions

The DefaultAttributesExtension is particularly useful:

$converter->addExtension(new DefaultAttributesExtension([
    'image' => ['loading' => 'lazy', 'decoding' => 'async'],
    'table' => ['class' => 'table table-bordered'],
    'block_quote' => ['class' => 'blockquote'],
]));

Extensions can also be combined. For example, AutolinkExtension should be registered before ExternalLinksExtension so auto-linked URLs also get the external link attributes.

Custom Rendering with Events

For more control, use the event system directly:

use Djot\Renderer\Event\RenderEvent;

$renderer = $converter->getRenderer();

// Convert :emoji: symbols to actual emoji
$renderer->addEventListener('render.symbol', function (RenderEvent $event) {
    $node = $event->getNode();
    $emoji = match ($node->getName()) {
        'smile' => '😊',
        'heart' => '❤',
        'rocket' => '🚀',
        default => ':' . $node->getName() . ':',
    };
    $event->setHtml($emoji);
});

// Add target="_blank" to external links
$renderer->addEventListener('render.link', function (RenderEvent $event) {
    $link = $event->getNode();
    $url = $link->getDestination();
    if (str_starts_with($url, 'http')) {
        $link->setAttribute('target', '_blank');
        $link->setAttribute('rel', 'noopener noreferrer');
    }
});

Custom Inline Patterns

Need #hashtags or wiki-style links? The parser supports custom inline patterns:

use Djot\Node\Inline\Link;
use Djot\Node\Inline\Text;

$parser = $converter->getParser()->getInlineParser();

// #hashtags → tag pages
$parser->addInlinePattern('/#([a-zA-Z][a-zA-Z0-9_]*)/', function ($match, $groups) {
    $link = new Link('/tags/' . strtolower($groups[1]));
    $link->appendChild(new Text('#' . $groups[1]));
    return $link;
});

echo $converter->convert('Check out #PHP and #Djot!');
// <p>Check out <a href="/tags/php">#PHP</a> and <a href="/tags/djot">#Djot</a>!</p>