---
title: "Data Transfer Objects"
manual: "RTE CKEditor Image"
version: "main"
permalink: "https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:api-dtos@main"
source: "API/DTOs.rst"
rendered: "2026-10-01T01:27:51+00:00"
---

# Data Transfer Objects {#api-dtos}

<!-- TODO: no Markdown rendering for "versionadded" -->

DTOs provide type-safe data contracts between services.

Data Transfer Objects (DTOs) encapsulate validated, sanitized data for image rendering.
They are immutable (`readonly`) to ensure data integrity throughout the rendering pipeline.

**Table of contents**

-   [ImageRenderingDto](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:imagerenderingdto@main)
-   [LinkDto](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:linkdto@main)
-   [Usage example](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:usage-example@main)
-   [Related documentation](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:related-documentation@main)

## ImageRenderingDto {#api-imagerenderingdto}

-   **class ImageRenderingDto**

    -   *Fully qualified name:* `\Netresearch\RteCKEditorImage\Domain\Model\ImageRenderingDto`

    Type-safe container for all image rendering data.

> [!IMPORTANT]
> All security validation MUST occur in `ImageResolverService` before DTO construction.
> The DTO represents validated, sanitized data ready for presentation.

### Properties {#properties}

**ImageRenderingDto class definition**

```php
final readonly class ImageRenderingDto
{
    public function __construct(
        public string $src,              // Image source URL (validated)
        public int $width,               // Display width in pixels
        public int $height,              // Display height in pixels
        public ?string $alt,             // Alternative text for accessibility
        public ?string $title,           // Title attribute for hover tooltip
        public array $htmlAttributes,    // Additional HTML attributes
        public ?string $caption,         // Caption text (XSS-sanitized)
        public ?LinkDto $link,           // Link/popup configuration
        public bool $isMagicImage,       // Whether TYPO3 processing enabled
    ) {}
}
```

### Property details {#property-details}

-   **src**

    -   *Type:* string
    -   *Required:* true

    The processed image URL. Always validated and safe for output.

-   **width**

    -   *Type:* int
    -   *Required:* true

    Display width in pixels. Used for proper aspect ratio and layout.

-   **height**

    -   *Type:* int
    -   *Required:* true

    Display height in pixels. Used for proper aspect ratio and layout.

-   **alt**

    -   *Type:* ?string

    Alternative text for accessibility (screen readers, broken images).

-   **title**

    -   *Type:* ?string

    Title attribute shown as tooltip on hover.

-   **htmlAttributes**

    -   *Type:* array\<string,mixed>
    -   *Required:* true

    Additional HTML attributes such as:

    -   `class`: CSS classes.
    -   `style`: Inline styles.
    -   `loading`: Lazy loading setting (`lazy`, `eager`).
    -   `data-*`: Custom data attributes.

-   **caption**

    -   *Type:* ?string

    Caption text for `<figcaption>`. Already sanitized with `htmlspecialchars()`.

-   **link**

    -   *Type:* ?LinkDto

    Link or popup configuration. See [LinkDto](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:api-linkdto@main).

-   **isMagicImage**

    -   *Type:* bool
    -   *Required:* true

    Indicates whether TYPO3 image processing (magic images) was applied.

## LinkDto {#api-linkdto}

-   **class LinkDto**

    -   *Fully qualified name:* `\Netresearch\RteCKEditorImage\Domain\Model\LinkDto`

    Encapsulates link/popup configuration for linked images.

### Properties {#properties-1}

**LinkDto class definition**

```php
final readonly class LinkDto
{
    public function __construct(
        public string $url,        // Link URL (validated)
        public ?string $target,    // Link target (_blank, _self, etc.)
        public ?string $class,     // CSS class for link element
        public ?string $params,    // Additional URL parameters
        public bool $isPopup,      // Whether this is a popup/lightbox link
        public ?array $jsConfig,   // JavaScript configuration for lightbox
    ) {}

    /**
     * Get URL with params properly appended.
     */
    public function getUrlWithParams(): string;
}
```

### Property details {#property-details-1}

-   **url**

    -   *Type:* string
    -   *Required:* true

    The link target URL. Validated against dangerous protocols.

-   **target**

    -   *Type:* ?string

    Link target attribute (`_blank`, `_self`, `_parent`, `_top`).

-   **class**

    -   *Type:* ?string

    CSS classes applied to the `<a>` element.

-   **params**

    -   *Type:* ?string

    <!-- TODO: no Markdown rendering for "versionadded" -->

    Additional URL parameters to append to the link URL (e.g., `&L=1&type=123`).
    These correspond to TYPO3's TypoLink `additionalParams` field.

    The `getUrlWithParams()` method handles proper concatenation:

    -   If URL has no query string: `&L=1` becomes `?L=1`
    -   If URL already has query: params are appended with `&`
    -   URL fragments (`#section`) are preserved at the end

-   **isPopup**

    -   *Type:* bool
    -   *Required:* true

    Whether the link should open in a popup/lightbox instead of navigating.

-   **jsConfig**

    -   *Type:* ?array\<string,mixed>

    JavaScript configuration for lightbox/popup behavior:

    **Example jsConfig structure**

    ```php
    [
        'width' => 800,
        'height' => 600,
        'effect' => 'fade'
    ]
    ```

### Methods {#methods}

-   **getUrlWithParams()**

    <!-- TODO: no Markdown rendering for "versionadded" -->

    Returns the URL with additional parameters properly appended.

    Handles query string normalization:

    ```php
    // URL without query string
    $dto = new LinkDto(url: '/page', params: '&L=1');
    $dto->getUrlWithParams(); // '/page?L=1'

    // URL with existing query string
    $dto = new LinkDto(url: '/page?foo=bar', params: '&L=1');
    $dto->getUrlWithParams(); // '/page?foo=bar&L=1'

    // URL with fragment (preserved at end)
    $dto = new LinkDto(url: '/page#section', params: '&L=1');
    $dto->getUrlWithParams(); // '/page?L=1#section'
    ```

## Usage example {#usage-example}

**Creating DTOs for image rendering**

```php
use Netresearch\RteCKEditorImage\Domain\Model\ImageRenderingDto;
use Netresearch\RteCKEditorImage\Domain\Model\LinkDto;

// Create link DTO for popup
$link = new LinkDto(
    url: '/fileadmin/images/large.jpg',
    target: null,
    class: 'lightbox',
    params: null,
    isPopup: true,
    jsConfig: ['effect' => 'fade']
);

// Create link DTO for external link with parameters
$externalLink = new LinkDto(
    url: 'https://example.com/page',
    target: '_blank',
    class: 'external-link',
    params: '&utm_source=rte&utm_medium=image',
    isPopup: false,
    jsConfig: null
);
// $externalLink->getUrlWithParams() returns:
// 'https://example.com/page?utm_source=rte&utm_medium=image'

// Create image DTO
$image = new ImageRenderingDto(
    src: '/fileadmin/_processed_/image_hash.jpg',
    width: 800,
    height: 600,
    alt: 'Example image',
    title: 'Click to enlarge',
    htmlAttributes: ['class' => 'img-responsive', 'loading' => 'lazy'],
    caption: 'Photo by Photographer',
    link: $link,
    isMagicImage: true
);

// DTOs are immutable - properties cannot be changed
// $image->width = 1000; // Error: Cannot modify readonly property
```

## Related documentation {#related-documentation}

-   [Services API](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:api-services@main) \- Service architecture using DTOs.
-   [Template Overrides](https://docs.typo3.org/permalink/netresearch/rte-ckeditor-image:examples-template-overrides@main) \- Accessing DTO in templates.