Data Transfer Objects 

New in version 13.1.5

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 

class ImageRenderingDto
Fully qualified name
\Netresearch\RteCKEditorImage\Domain\Model\ImageRenderingDto

Type-safe container for all image rendering data.

Properties 

ImageRenderingDto class definition 
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
    ) {}
}
Copied!

Property details 

src

src
Type
string
Required

true

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

width

width
Type
int
Required

true

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

height

height
Type
int
Required

true

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

alt

alt
Type
?string

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

title

title
Type
?string

Title attribute shown as tooltip on hover.

htmlAttributes

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

caption
Type
?string

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

isMagicImage

isMagicImage
Type
bool
Required

true

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

LinkDto 

class LinkDto
Fully qualified name
\Netresearch\RteCKEditorImage\Domain\Model\LinkDto

Encapsulates link/popup configuration for linked images.

Properties 

LinkDto class definition 
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;
}
Copied!

Property details 

url

url
Type
string
Required

true

The link target URL. Validated against dangerous protocols.

target

target
Type
?string

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

class

class
Type
?string

CSS classes applied to the <a> element.

params

params
Type
?string

New in version 13.5.0

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

isPopup
Type
bool
Required

true

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

jsConfig

jsConfig
Type
?array<string,mixed>

JavaScript configuration for lightbox/popup behavior:

Example jsConfig structure 
[
    'width' => 800,
    'height' => 600,
    'effect' => 'fade'
]
Copied!

Methods 

getUrlWithParams ( )

New in version 13.5.0

Returns the URL with additional parameters properly appended.

Handles query string normalization:

// 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'
Copied!

Usage example 

Creating DTOs for image rendering 
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
Copied!