Removed Components 

• RTE processing mode ("ts_images")
• SoftReference Index for inline images
• Magic Image processing (automatic scaling, cropping via TSConfig)
• Image storage handling (RTE_imageStorageDir)
• CLI cleanup command (cleanup:rteimages)
• Public API methods (ImportExport->getRTEoriginalFilename(), RteHtmlParser->TS_images_rte())

Later Deprecation 

In TYPO3 v12.4 (Deprecation #99237), the MagicImageService class was deprecated with no direct migration path.

Primary Approach: Structured Content 

Move images from inline RTE fields to proper relational fields:

// TCA Configuration Example
'columns' => [
    'bodytext' => [
        'config' => [
            'type' => 'text',
            'enableRichtext' => true,
        ],
    ],
    'images' => [
        'config' => [
            'type' => 'file',
            'allowed' => 'common-image-types',
            'maxitems' => 10,
        ],
    ],
],

Benefits of Structured Content:

• ✅ Better content reuse
• ✅ Proper metadata management
• ✅ Responsive image generation
• ✅ Clean separation of concerns
• ✅ Modern TYPO3 architecture
• ✅ Better editor experience

Fallback Approach: Extensions 

For projects that need inline image functionality, TYPO3 recommends extensions like rte_ckeditor_image or creating custom extension implementations.

Real-World Requirements 

1. Legacy Content Migration

   Many TYPO3 installations have years of content with inline images. Migrating to structured content requires significant time and resources.

2. Editorial Workflows

   Some editorial teams are trained on inline image workflows and prefer WYSIWYG image placement directly in text.

3. Content Nature

   Certain content types (news articles, blog posts, documentation) naturally contain inline images that are contextually bound to surrounding text.

4. Migration Bridge

   Provides a transition path while planning migration to structured content.

What This Extension Provides 

• Backward compatibility with RTEHtmlArea image workflows
• Magic Image processing (automatic scaling via TSConfig)
• TYPO3 FAL integration (native file browser)
• Modern CKEditor 5 implementation
• Image attributes (width, height, alt, title, quality)
• Custom styles via CKEditor style system
• Event-driven architecture for extensibility

Use This Extension When 

✅ You have legacy content with extensive inline images that cannot be migrated immediately

✅ Editorial workflow requires inline image placement with WYSIWYG editing

✅ Content is tightly coupled to surrounding text (inline diagrams, screenshots, examples)

✅ Migration timeline is long and you need a working solution now

✅ Small to medium projects where structured content overhead isn't justified

Follow TYPO3 Guidelines Instead When 

❌ Starting a new project - Build with structured content from the beginning

❌ Images are reusable - Same images appear across multiple content elements

❌ Need advanced features - Responsive images, WebP conversion, image variants

❌ Multi-language sites - Image metadata needs proper translation workflows

❌ Large editorial teams - Structured content provides better governance

❌ Long-term maintainability - Align with TYPO3's architectural direction

Planning Migration 

1. Audit content - Identify all RTE fields with inline images
2. Create TCA fields - Add proper FAL reference fields
3. Write migration script - Extract inline images to relations
4. Update templates - Adjust Fluid templates for structured content
5. Train editors - Update editorial workflows and documentation

Migration Tools 

TYPO3 provides tools for content migration:

• Data Handler API for programmatic content updates
• TypoScript processors for rendering
• CLI commands for batch processing

This extension can coexist during the migration period.

How to contribute translations 

1. Create a Crowdin account (free for open source contributors)
2. Join the TYPO3 translation team for your language
3. Translate strings directly in the Crowdin web interface
4. Review translations from other contributors
5. Suggest improvements to existing translations

Why translate 

• Make TYPO3 more accessible to speakers of your language
• Help the global TYPO3 community
• No programming knowledge required
• Translations are automatically integrated via pull requests

Translation notes 

• Some terms like "Retina", "Ultra", "Standard" are multilingual - keep as-is or transliterate if more natural in your language
• Context notes are provided for technical terms to help with accurate translation
• Your contributions are reviewed by language coordinators before integration

Need help 

• Contact the TYPO3 localization team on TYPO3 Slack in #typo3-localization-team
• Check the TYPO3 Translation Documentation

Development & Maintenance 

• Netresearch DTT GmbH
• Sebastian Koschel
• Sebastian Mendel
• Rico Sonntag

Community Contributors 

See GitHub Contributors

For Custom RTE Presets 

These examples show how to create custom configurations that override the automatic defaults. If you just installed the extension and it's working, you don't need these.

# Only needed if customizing the default toolbar
editor:
  config:
    toolbar:
      items:
        - insertimage

# Example: Custom preset with limited toolbar
editor:
  config:
    toolbar:
      items:
        - bold
        - italic
        - insertimage

By Use Case 

• Basic editor → Minimal Setup
• Style-aware images → Adding Image Styles
• Responsive images → Integration & Configuration
• Restricted access → File Mounts

By Component 

• CKEditor plugin → Integration & Configuration
• File browser → Integration & Configuration
• Frontend rendering → Frontend Rendering
• Image processing → Image Processing Configuration

Creating Custom Presets 

If you need to customize the toolbar or RTE behavior beyond the defaults, create a custom preset:

imports:
  # Import default RTE config
  - { resource: "EXT:rte_ckeditor/Configuration/RTE/Default.yaml" }
  # Import image plugin configuration
  - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Plugin.yaml" }

editor:
  config:
    toolbar:
      items:
        - heading
        - '|'
        - insertimage
        - link
        - '|'
        - bold
        - italic

$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['custom']
    = 'EXT:my_ext/Configuration/RTE/Custom.yaml';

RTE.default.preset = custom

Advanced RTE Configuration 

imports:
  - { resource: "EXT:rte_ckeditor/Configuration/RTE/Minimal.yaml" }
  - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Plugin.yaml" }

editor:
  config:
    removePlugins: null
    toolbar:
      items:
        - insertimage

# Different presets for different fields
RTE.default.preset = default
RTE.config.tt_content.bodytext.preset = full
RTE.config.tt_content.header.preset = simple

Configuration Topics 

• Page TSConfig Setup - Page TSConfig settings and upload configuration
• Frontend Rendering - TypoScript and frontend rendering setup
• Advanced Configuration - Advanced configuration, styles, and best practices

General Documentation 

• Integration & Configuration - Main configuration guide overview
• Quick Start - Quick start guide
• Troubleshooting & Support - Troubleshooting guide

Magic Image Configuration 

Configure maximum image dimensions for automatic image processing:

Example:

RTE.default.buttons.image.options.magic {
    maxWidth = 1920
    maxHeight = 9999
}

Processing Modes 

RTE.default.proc.overruleMode := addToList(default)

Upload Folder Configuration 

Example:

RTE.default.buttons.image.options {
    defaultUploadFolder = 1:rte_uploads/
    createUploadFolderIfNeeded = 1
}

Enable for Specific Content Types 

# Only enable for tt_content bodytext
RTE.config.tt_content.bodytext {
    preset = default
    buttons.image.options.magic {
        maxWidth = 1200
        maxHeight = 800
    }
}

Disable for Specific Fields 

# Disable RTE entirely for specific field
RTE.config.tt_content.header.disabled = 1

File Mounts 

Ensure backend users have appropriate file mounts:

options.defaultUploadFolder = 1:user_uploads/rte/

Access Restrictions 

# Allow only specific file extensions
options.file_list.validFileExtensions = jpg,jpeg,png,gif,webp

Language-Specific Presets 

[siteLanguage("locale") == "de_DE"]
    RTE.default.preset = german
[END]

[siteLanguage("locale") == "en_US"]
    RTE.default.preset = english
[END]

Debug RTE Configuration 

Enable RTE debugging:

RTE.default.showButtons = *
RTE.default.hideButtons =

Verify Configuration Loading 

Check active RTE configuration in backend:

1. Edit content element
2. Open browser console
3. Check CKEDITOR.config object

Configuration Priority 

Configuration precedence (highest to lowest):

1. Field-specific config: RTE.config.tt_content.bodytext
2. Type-specific config: RTE.config.tt_content
3. Default config: RTE.default
4. Extension defaults

Configuration Topics 

• RTE Setup - RTE configuration and basic setup
• Frontend Rendering - TypoScript and frontend rendering setup
• Advanced Configuration - Advanced configuration, styles, and best practices

General Documentation 

• Integration & Configuration - Main configuration guide overview
• Quick Start - Quick start guide
• Troubleshooting & Support - Troubleshooting guide

Frontend Rendering Setup 

The extension provides default configuration. You can customize it:

lib.parseFunc_RTE {
    tags.img = TEXT
    tags.img {
        current = 1
        preUserFunc = Netresearch\RteCKEditorImage\Controller\ImageRenderingController->renderImageAttributes
    }

    tags.a = TEXT
    tags.a {
        current = 1
        preUserFunc = Netresearch\RteCKEditorImage\Controller\ImageLinkRenderingController->renderImages
    }

    nonTypoTagStdWrap.HTMLparser.tags.img.fixAttrib {
        # Remove internal data attributes from frontend
        allparams.unset = 1
        data-htmlarea-file-uid.unset = 1
        data-htmlarea-file-table.unset = 1
        # Keep zoom attributes for popup/lightbox rendering (ImageRenderingController.php)
        # data-htmlarea-zoom.unset = 1
        # data-htmlarea-clickenlarge.unset = 1
        data-title-override.unset = 1
        data-alt-override.unset = 1
    }
}

lib.parseFunc_RTE.nonTypoTagStdWrap.encapsLines.encapsTagList := addToList(img)

Default CSS Class 

Add default class to all RTE images:

lib.parseFunc_RTE {
    nonTypoTagStdWrap.HTMLparser.tags.img.fixAttrib.class {
        default = img-fluid responsive-image
    }
}

Lazyload Configuration 

Enable native browser lazy loading:

styles.content.image.lazyLoading = lazy
# Options: lazy, eager, auto

Lightbox/Popup Integration 

base: 'https://example.com/'
rootPageId: 1
dependencies:
  - netresearch/rte-ckeditor-image

The extension provides lib.contentElement.settings.media.popup configuration with sensible defaults for click-to-enlarge functionality. When editors enable "Enlarge on Click" in the image dialog, images will open in a JavaScript popup window.

Default Configuration (automatically loaded via ext_localconf.php):

lib.contentElement.settings.media.popup {
    # Opens in popup window (800x600 max)
    bodyTag = <body style="margin:0; background:#fff;">
    wrap = <a href="javascript:close();"> | </a>
    width = 800m
    height = 600m
    JSwindow = 1
    JSwindow.newWindow = 1
    directImageLink = 0
}

Using with Lightbox Libraries (PhotoSwipe, GLightbox, etc.):

Override the default configuration to use direct image links with custom CSS classes:

lib.contentElement.settings.media.popup {
    # Direct link to image for lightbox libraries
    directImageLink = 1

    # Add lightbox-specific classes and attributes
    linkParams.ATagParams.dataWrap = class="lightbox" rel="lightbox-gallery"
}

Legacy fluid_styled_content Integration:

If using fluid_styled_content constants, enable lightbox mode:

styles.content.textmedia.linkWrap.lightboxEnabled = 1

Complete TypoScript Configuration Options 

lib.parseFunc_RTE {
    tags.img = TEXT
    tags.img {
        current = 1
        preUserFunc = Netresearch\RteCKEditorImage\Controller\ImageRenderingController->renderImageAttributes
    }
}

lib.parseFunc_RTE {
    tags.a = TEXT
    tags.a {
        current = 1
        preUserFunc = Netresearch\RteCKEditorImage\Controller\ImageLinkRenderingController->renderImages
    }
}

lib.parseFunc_RTE.nonTypoTagStdWrap.HTMLparser.tags.img {
    fixAttrib {
        # Remove internal data attributes
        data-htmlarea-file-uid.unset = 1
        data-htmlarea-file-table.unset = 1
        # Keep zoom attributes for popup/lightbox rendering (ImageRenderingController.php)
        # data-htmlarea-zoom.unset = 1
        # data-htmlarea-clickenlarge.unset = 1
        data-title-override.unset = 1
        data-alt-override.unset = 1
    }
}

lib.parseFunc_RTE.nonTypoTagStdWrap.HTMLparser.tags.img.fixAttrib.class {
    default = img-fluid
    list = img-fluid,img-thumbnail,rounded
}

# Template Constants
styles.content.image.lazyLoading = lazy
# Options: lazy, eager, auto

# Template Constants
styles.content.textmedia.linkWrap.lightboxEnabled = 1
styles.content.textmedia.linkWrap.lightboxCssClass = lightbox
styles.content.textmedia.linkWrap.lightboxRelAttribute = lightbox[{field:uid}]

lib.parseFunc_RTE.nonTypoTagStdWrap.HTMLparser.tags.img {
    width =
    height =
    # Allows TYPO3 to process dimensions
}

lib.parseFunc_RTE.nonTypoTagStdWrap.encapsLines {
    encapsTagList := addToList(img)
    remapTag.img = p
}

Configuration Topics 

• RTE Setup - RTE configuration and basic setup
• Page TSConfig Setup - Page TSConfig settings and upload configuration
• Advanced Configuration - Advanced configuration, styles, and best practices

General Documentation 

• Integration & Configuration - Main configuration guide overview
• Quick Start - Quick start guide
• Troubleshooting & Support - Troubleshooting guide

Adding Image Styles 

Define custom styles for images:

editor:
  config:
    style:
      definitions:
        - name: 'Image Left'
          element: 'img'
          classes: ['float-left', 'mr-3']
        - name: 'Image Right'
          element: 'img'
          classes: ['float-right', 'ml-3']
        - name: 'Image Center'
          element: 'img'
          classes: ['d-block', 'mx-auto']
        - name: 'Full Width'
          element: 'img'
          classes: ['w-100']

Style Groups 

Organize styles in groups:

editor:
  config:
    style:
      definitions:
        # ... style definitions ...

      # Group styles in dropdown
      groupDefinitions:
        - name: 'Image Alignment'
          styles: ['Image Left', 'Image Right', 'Image Center']
        - name: 'Image Size'
          styles: ['Full Width', 'Half Width']

Image Processing Configuration 

$GLOBALS['TYPO3_CONF_VARS']['GFX'] = [
    'processor' => 'ImageMagick',
    'processor_path' => '/usr/bin/',
    'processor_enabled' => true,
    'processor_effects' => true,

    // Image quality
    'jpg_quality' => 85,

    // Maximum dimensions
    'imagefile_ext' => 'gif,jpg,jpeg,png,webp',
];

Processed File Cache 

TYPO3 caches processed images in _processed_/ folder. Clear if needed:

# TYPO3 CLI
./vendor/bin/typo3 cache:flush --group=pages

Performance Best Practices 

• Configure appropriate image processing quality (jpg_quality: 85)
• Enable TYPO3 page caching for content with images
• Use WebP format where supported
• Implement lazy loading for images below the fold
• Set reasonable maximum dimensions in TSConfig
• Consider using CDN for image delivery in production

Minimal Setup 

imports:
  - { resource: "EXT:rte_ckeditor/Configuration/RTE/Minimal.yaml" }
  - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Plugin.yaml" }

editor:
  config:
    removePlugins: null
    toolbar:
      items: [insertimage]

Full-Featured Setup 

imports:
  - { resource: "EXT:rte_ckeditor/Configuration/RTE/Full.yaml" }
  - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Plugin.yaml" }

editor:
  config:
    removePlugins: null
    toolbar:
      items:
        - heading
        - '|'
        - bold
        - italic
        - '|'
        - insertimage
        - link
        - '|'
        - bulletedList
        - numberedList
        - '|'
        - style

    style:
      definitions:
        - name: 'Image Left'
          element: 'img'
          classes: ['float-left']
        - name: 'Image Right'
          element: 'img'
          classes: ['float-right']

  externalPlugins:
    typo3image:
      allowedExtensions: "jpg,jpeg,png,gif,webp"

RTE.default {
    preset = full

    buttons.image.options.magic {
        maxWidth = 1920
        maxHeight = 1080
    }
}

lib.parseFunc_RTE.nonTypoTagStdWrap.HTMLparser.tags.img.fixAttrib.class {
    default = img-fluid
}

Configuration Best Practices 

1. Start with minimal configuration and add features incrementally
2. Test in staging environment before deploying to production
3. Use separate RTE presets for different content types
4. Enable caching for processed images
5. Set appropriate maxWidth/maxHeight to prevent oversized images
6. Configure lazy loading for better performance
7. Use meaningful style names that reflect intent, not appearance
8. Document custom configurations for team members

Security Considerations 

• Restrict allowed file extensions to safe image formats
• Configure appropriate file mounts for backend users
• Review and limit upload folder permissions
• Validate image dimensions and file sizes
• Keep extension and TYPO3 core up to date

Maintenance 

• Regularly clear processed image cache
• Monitor storage usage in upload folders
• Review and clean unused images periodically
• Keep documentation of custom configurations
• Test after TYPO3 core or extension updates

Extension Configuration 

You can customize the automatic behavior via Extension Configuration:

Admin Tools > Settings > Extension Configuration > rte_ckeditor_image

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['rte_ckeditor_image'] = [
    'enableAutomaticRteSoftref' => true,
    'excludedTables' => 'tx_form_formframework,sys_template',
];

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['rte_ckeditor_image'] = [
    'enableAutomaticRteSoftref' => true,
    'includedTablesOnly' => 'tt_content,tx_news_domain_model_news',
];

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['rte_ckeditor_image'] = [
    'enableAutomaticRteSoftref' => false,
];

./vendor/bin/typo3 cache:flush

Troubleshooting Third-Party Extension Issues 

# Include static template in your root template
# Template > Info/Modify > Edit whole template record > Includes
# Select: "CKEditor Image Support" for "Include static (from extensions)"

Configuration Topics 

• RTE Setup - RTE configuration and basic setup
• Page TSConfig Setup - Page TSConfig settings and upload configuration
• Frontend Rendering - TypoScript and frontend rendering setup

General Documentation 

• Integration & Configuration - Main configuration guide overview
• Quick Start - Quick start guide
• Troubleshooting & Support - Troubleshooting guide

Installation 

composer require netresearch/rte-ckeditor-image:^13.0

That's it! The extension automatically:

• ✅ Registers the rteWithImages preset for backend RTE
• ✅ Configures toolbar with insertimage button for all sites
• ✅ Loads TypoScript for frontend image rendering
• ✅ No manual configuration required

Result: Full image functionality working out-of-the-box ✅

Verification 

1. Backend: Log into TYPO3 backend → Edit any content element → RTE should show image button
2. Frontend: Insert image in RTE → Save → View frontend → Image renders correctly

Custom Preset 

imports:
  - { resource: "EXT:rte_ckeditor/Configuration/RTE/Default.yaml" }
  - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Plugin.yaml" }

editor:
  config:
    toolbar:
      items:
        - heading
        - '|'
        - bold
        - italic
        - '|'
        - insertimage
        - link

Register Custom Preset 

$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['custom']
    = 'EXT:my_site/Configuration/RTE/Custom.yaml';

Enable Custom Preset 

RTE.default.preset = custom

Configuration 

editor:
  config:
    style:
      definitions:
        # Alignment Styles
        - name: 'Float Left'
          element: 'img'
          classes: ['float-start', 'me-3', 'mb-3']
        - name: 'Float Right'
          element: 'img'
          classes: ['float-end', 'ms-3', 'mb-3']
        - name: 'Center'
          element: 'img'
          classes: ['d-block', 'mx-auto']

        # Size Styles
        - name: 'Thumbnail'
          element: 'img'
          classes: ['img-thumbnail']
        - name: 'Rounded'
          element: 'img'
          classes: ['rounded']
        - name: 'Circle'
          element: 'img'
          classes: ['rounded-circle']

        # Responsive
        - name: 'Responsive'
          element: 'img'
          classes: ['img-fluid']

      groupDefinitions:
        - name: 'Image Alignment'
          styles: ['Float Left', 'Float Right', 'Center']
        - name: 'Image Style'
          styles: ['Thumbnail', 'Rounded', 'Circle', 'Responsive']

CSS (if not using Bootstrap) 

.float-start { float: left; }
.float-end { float: right; }
.me-3 { margin-right: 1rem; }
.ms-3 { margin-left: 1rem; }
.mb-3 { margin-bottom: 1rem; }
.d-block { display: block; }
.mx-auto { margin-left: auto; margin-right: auto; }

.img-thumbnail {
    padding: 0.25rem;
    background-color: #fff;
    border: 1px solid #dee2e6;
    border-radius: 0.25rem;
    max-width: 100%;
    height: auto;
}

.rounded { border-radius: 0.25rem; }
.rounded-circle { border-radius: 50%; }
.img-fluid { max-width: 100%; height: auto; }

Result: Professional image styling options ✅

TypoScript Setup 

lib.parseFunc_RTE {
    tags.img = TEXT
    tags.img {
        current = 1
        preUserFunc = MyVendor\MySite\UserFunc\ResponsiveImageRenderer->render
    }
}

PHP Implementation 

namespace MyVendor\MySite\UserFunc;

use TYPO3\CMS\Core\Resource\FileRepository;
use TYPO3\CMS\Core\Resource\ProcessedFile;
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer;

class ResponsiveImageRenderer
{
    public function render(
        string $content,
        array $conf,
        ContentObjectRenderer $cObj
    ): string {
        // Parse img tag
        if (!preg_match('/<img([^>]*)>/i', $content, $imgMatch)) {
            return $content;
        }

        // Extract data-htmlarea-file-uid
        if (!preg_match('/data-htmlarea-file-uid="(\d+)"/', $imgMatch[1], $uidMatch)) {
            return $content;
        }

        $fileUid = (int)$uidMatch[1];

        // Get FAL file
        $fileRepository = GeneralUtility::makeInstance(FileRepository::class);
        try {
            $file = $fileRepository->findByUid($fileUid);
        } catch (\Exception $e) {
            return $content;
        }

        // Generate responsive variants
        $breakpoints = [
            'xs' => 480,
            'sm' => 768,
            'md' => 992,
            'lg' => 1200,
            'xl' => 1920
        ];

        $srcsetParts = [];
        foreach ($breakpoints as $name => $width) {
            $processedFile = $file->process(
                ProcessedFile::CONTEXT_IMAGECROPSCALEMASK,
                ['width' => $width]
            );
            $srcsetParts[] = $processedFile->getPublicUrl() . ' ' . $width . 'w';
        }

        $srcset = implode(', ', $srcsetParts);
        $sizes = '(max-width: 768px) 100vw, (max-width: 992px) 50vw, 33vw';

        // Replace img tag with srcset version
        $newImg = str_replace(
            '<img',
            '<img srcset="' . htmlspecialchars($srcset) . '" sizes="' . $sizes . '"',
            $imgMatch[0]
        );

        return str_replace($imgMatch[0], $newImg, $content);
    }
}

Result HTML 

<img
    src="/fileadmin/image.jpg"
    srcset="/fileadmin/_processed_/image_480.jpg 480w,
            /fileadmin/_processed_/image_768.jpg 768w,
            /fileadmin/_processed_/image_992.jpg 992w,
            /fileadmin/_processed_/image_1200.jpg 1200w,
            /fileadmin/_processed_/image_1920.jpg 1920w"
    sizes="(max-width: 768px) 100vw, (max-width: 992px) 50vw, 33vw"
    alt="Image description"
/>

Result: Automatic responsive images ✅

PhotoSwipe Lightbox 

Objective: Integrate PhotoSwipe lightbox library for advanced gallery features

npm install photoswipe

page {
    includeJSFooterlibs {
        photoswipe = EXT:my_site/Resources/Public/JavaScript/photoswipe.min.js
        photoswipe_init = EXT:my_site/Resources/Public/JavaScript/lightbox-init.js
    }

    includeCSS {
        photoswipe = EXT:my_site/Resources/Public/Css/photoswipe.css
    }
}

lib.parseFunc_RTE {
    tags.img = TEXT
    tags.img {
        current = 1
        preUserFunc = MyVendor\MySite\UserFunc\LightboxImageRenderer->render
    }
}

namespace MyVendor\MySite\UserFunc;

use TYPO3\CMS\Core\Resource\FileRepository;
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer;

class LightboxImageRenderer
{
    public function render(
        string $content,
        array $conf,
        ContentObjectRenderer $cObj
    ): string {
        // Check if zoom enabled
        if (strpos($content, 'data-htmlarea-zoom') === false) {
            return $content;
        }

        // Extract file UID
        if (!preg_match('/data-htmlarea-file-uid="(\d+)"/', $content, $match)) {
            return $content;
        }

        $fileUid = (int)$match[1];
        $fileRepository = GeneralUtility::makeInstance(FileRepository::class);

        try {
            $file = $fileRepository->findByUid($fileUid);
        } catch (\Exception $e) {
            return $content;
        }

        // Remove data attributes for frontend
        $content = preg_replace('/\s*data-htmlarea-[^=]+="[^"]*"/', '', $content);

        // Wrap in lightbox link
        $lightboxLink = sprintf(
            '<a href="%s" data-pswp-width="%d" data-pswp-height="%d" target="_blank">%s</a>',
            $file->getPublicUrl(),
            $file->getProperty('width'),
            $file->getProperty('height'),
            $content
        );

        return $lightboxLink;
    }
}

import PhotoSwipeLightbox from 'photoswipe/lightbox';
import 'photoswipe/style.css';

const lightbox = new PhotoSwipeLightbox({
    gallery: '.ce-bodytext',
    children: 'a[data-pswp-width]',
    pswpModule: () => import('photoswipe'),
});

lightbox.init();

Native Lazy Loading 

Objective: Improve page load performance with native lazy loading

lib.parseFunc_RTE {
    nonTypoTagStdWrap.HTMLparser.tags.img {
        fixAttrib {
            loading {
                set = lazy
            }
            # Remove internal attributes
            data-htmlarea-file-uid.unset = 1
            data-htmlarea-file-table.unset = 1
            # Keep zoom attributes for popup/lightbox rendering
            # data-htmlarea-zoom.unset = 1
        }
    }
}

<img src="..." loading="lazy" alt="..." />

Intersection Observer Fallback 

For older browsers:

page.includeJSFooterlibs.lazyload = EXT:my_site/Resources/Public/JavaScript/lazyload.js

lib.parseFunc_RTE {
    nonTypoTagStdWrap.HTMLparser.tags.img {
        fixAttrib {
            class {
                list = lazyload
            }
            data-src {
                # Copy src to data-src
                stdWrap.field = src
            }
            src {
                # Set placeholder
                set = data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 3 2'%3E%3C/svg%3E
            }
        }
    }
}

document.addEventListener('DOMContentLoaded', function() {
    const imageObserver = new IntersectionObserver((entries, observer) => {
        entries.forEach(entry => {
            if (entry.isIntersecting) {
                const img = entry.target;
                img.src = img.dataset.src;
                img.classList.remove('lazyload');
                imageObserver.unobserve(img);
            }
        });
    });

    document.querySelectorAll('img.lazyload').forEach(img => {
        imageObserver.observe(img);
    });
});

Extended Image Properties 

Objective: Add custom fields to image dialog

import { Plugin } from '@ckeditor/ckeditor5-core';

export default class ExtendedTypo3Image extends Plugin {
    static get pluginName() {
        return 'ExtendedTypo3Image';
    }

    init() {
        const editor = this.editor;

        // Extend schema with custom attributes
        editor.model.schema.extend('typo3image', {
            allowAttributes: ['customCaption', 'customCopyright']
        });

        // Add upcast conversion
        editor.conversion.for('upcast').attributeToAttribute({
            view: 'data-custom-caption',
            model: 'customCaption'
        });

        // Add downcast conversion
        editor.conversion.for('downcast').attributeToAttribute({
            model: 'customCaption',
            view: 'data-custom-caption'
        });

        // Modify image dialog
        editor.on('typo3image:dialog', (evt, { dialog, modelElement }) => {
            // Add custom fields to dialog
            const customFields = $(`
                <div class="form-group">
                    <label>Custom Caption</label>
                    <input type="text" class="form-control" name="customCaption"
                           value="${modelElement.getAttribute('customCaption') || ''}" />
                </div>
                <div class="form-group">
                    <label>Copyright</label>
                    <input type="text" class="form-control" name="customCopyright"
                           value="${modelElement.getAttribute('customCopyright') || ''}" />
                </div>
            `);

            dialog.$el.append(customFields);

            // Override dialog.get() to include custom fields
            const originalGet = dialog.get;
            dialog.get = function() {
                const attrs = originalGet.call(this);
                attrs.customCaption = customFields.find('[name="customCaption"]').val();
                attrs.customCopyright = customFields.find('[name="customCopyright"]').val();
                return attrs;
            };
        });
    }
}

editor:
  config:
    importModules:
      - '@my-vendor/my-site/extended-typo3image.js'

Fetch and Upload External Images 

$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['rte_ckeditor_image'] = [
    'fetchExternalImages' => true,
];

options.defaultUploadFolder = 1:user_upload/rte_images/

namespace MyVendor\MySite\Hooks;

use TYPO3\CMS\Core\Resource\File;
use TYPO3\CMS\Core\Resource\Folder;

class CustomImageFetchHook
{
    public function postProcessExternalImage(
        string $externalUrl,
        File $uploadedFile,
        Folder $targetFolder
    ): void {
        // Add custom metadata
        $uploadedFile->updateProperties([
            'title' => 'Imported from ' . parse_url($externalUrl, PHP_URL_HOST),
            'description' => 'Automatically fetched external image',
        ]);

        // Trigger image optimization
        $this->optimizeImage($uploadedFile);
    }

    protected function optimizeImage(File $file): void
    {
        // Custom optimization logic
        // e.g., compress, resize, convert format
    }
}

$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['rte_ckeditor_image']['postProcessExternalImage'][]
    = \MyVendor\MySite\Hooks\CustomImageFetchHook::class . '->postProcessExternalImage';

Language-Specific Image Variants 

[siteLanguage("languageId") == 0]
    # Default language (English)
    RTE.default.preset = default
[END]

[siteLanguage("languageId") == 1]
    # German
    RTE.default.preset = german
    RTE.default.buttons.image.options.defaultUploadFolder = 1:user_upload/de/
[END]

[siteLanguage("languageId") == 2]
    # French
    RTE.default.preset = french
    RTE.default.buttons.image.options.defaultUploadFolder = 1:user_upload/fr/
[END]

imports:
  - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Plugin.yaml" }

editor:
  config:
    language: de
    style:
      definitions:
        - name: 'Bild Links'
          element: 'img'
          classes: ['float-left']
        - name: 'Bild Rechts'
          element: 'img'
          classes: ['float-right']

Automatic Image Optimization 

namespace MyVendor\MySite\Hooks;

use TYPO3\CMS\Core\DataHandling\DataHandler;
use TYPO3\CMS\Core\Resource\FileRepository;
use TYPO3\CMS\Core\Utility\GeneralUtility;

class ImageOptimizationHook
{
    public function processDatamap_afterDatabaseOperations(
        string $status,
        string $table,
        string $id,
        array $fieldArray,
        DataHandler $dataHandler
    ): void {
        if ($table !== 'tt_content') {
            return;
        }

        foreach ($fieldArray as $field => $value) {
            if (!$this->isRteField($table, $field)) {
                continue;
            }

            // Find images in RTE content
            preg_match_all('/data-htmlarea-file-uid="(\d+)"/', $value, $matches);

            foreach ($matches[1] as $fileUid) {
                $this->optimizeImage((int)$fileUid);
            }
        }
    }

    protected function isRteField(string $table, string $field): bool
    {
        $tcaConfig = $GLOBALS['TCA'][$table]['columns'][$field]['config'] ?? [];
        return ($tcaConfig['enableRichtext'] ?? false) === true;
    }

    protected function optimizeImage(int $fileUid): void
    {
        $fileRepository = GeneralUtility::makeInstance(FileRepository::class);

        try {
            $file = $fileRepository->findByUid($fileUid);

            // Generate optimized variants
            $file->process(
                \TYPO3\CMS\Core\Resource\ProcessedFile::CONTEXT_IMAGECROPSCALEMASK,
                ['width' => 1920, 'height' => 1080]
            );

            // Generate WebP variant
            $file->process(
                \TYPO3\CMS\Core\Resource\ProcessedFile::CONTEXT_IMAGECROPSCALEMASK,
                ['width' => 1920, 'height' => 1080, 'fileExtension' => 'webp']
            );
        } catch (\Exception $e) {
            // Log error
        }
    }
}

$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_tcemain.php']['processDatamapClass'][]
    = \MyVendor\MySite\Hooks\ImageOptimizationHook::class;

Controller Test Example 

namespace Netresearch\RteCKEditorImage\Tests\Functional\Controller;

use TYPO3\TestingFramework\Core\Functional\FunctionalTestCase;

class SelectImageControllerTest extends FunctionalTestCase
{
    protected $testExtensionsToLoad = [
        'typo3conf/ext/rte_ckeditor_image'
    ];

    /**
     * @test
     */
    public function infoActionReturnsJsonForValidFile(): void
    {
        // Import test data
        $this->importDataSet(__DIR__ . '/Fixtures/sys_file.xml');

        // Create request
        $request = $this->createRequest('/typo3/rte/wizard/selectimage')
            ->withQueryParams([
                'action' => 'info',
                'fileId' => 1,
                'table' => 'sys_file'
            ]);

        // Execute
        $response = $this->executeFrontendRequest($request);

        // Assert
        self::assertEquals(200, $response->getStatusCode());

        $json = json_decode((string)$response->getBody(), true);
        self::assertArrayHasKey('uid', $json);
        self::assertArrayHasKey('url', $json);
        self::assertEquals(1, $json['uid']);
    }
}

Database Hook Test Example 

namespace Netresearch\RteCKEditorImage\Tests\Unit\Database;

use Netresearch\RteCKEditorImage\Database\RteImagesDbHook;
use TYPO3\TestingFramework\Core\Unit\UnitTestCase;

class RteImagesDbHookTest extends UnitTestCase
{
    /**
     * @test
     */
    public function processDatamapAddsImageAttributes(): void
    {
        $hook = new RteImagesDbHook(/* dependencies */);

        $fieldArray = ['bodytext' => '<img src="/fileadmin/image.jpg" />'];
        $hook->processDatamap_postProcessFieldArray('new', 'tt_content', '1', $fieldArray, $dataHandler);

        self::assertStringContainsString('alt=', $fieldArray['bodytext']);
    }
}

Execute Test Suites 

# Functional tests
./vendor/bin/phpunit -c Build/phpunit-functional.xml

# Unit tests
./vendor/bin/phpunit -c Build/phpunit-unit.xml

Result: Automated testing suite ✅

Most Common Issues 

// Ensure these dependencies are present:
static get requires() {
    return ['StyleUtils', 'GeneralHtmlSupport'];
}

Enable Debug Mode 

$GLOBALS['TYPO3_CONF_VARS']['SYS']['devIPmask'] = '*';
$GLOBALS['TYPO3_CONF_VARS']['SYS']['displayErrors'] = 1;

Browser Console 

• Check for JavaScript errors
• Monitor network requests
• Inspect CKEditor plugin loading

TYPO3 Logs 

• Check var/log/typo3_*.log
• Review deprecation log
• Monitor PHP error log

Database Queries 

• Enable SQL debug mode
• Check soft references
• Verify file relations

Self-Help Resources 

1. Check this troubleshooting guide
2. Review Integration & Configuration
3. Consult Examples & Use Cases
4. Search GitHub Issues

Community Support 

GitHub Discussions

github.com/netresearch/t3x-rte_ckeditor_image/discussions

TYPO3 Slack

#ext-rte_ckeditor_image channel

TYPO3 Forum

typo3.org/community/meet

Reporting Bugs 

Report bugs: github.com/netresearch/t3x-rte_ckeditor_image/issues

Include:

• TYPO3 version
• PHP version
• Extension version
• Steps to reproduce
• Error messages
• Browser console output

Issue: Extension Not Working After TYPO3 13 Upgrade 

Symptoms:

• Extension installed but not functional
• Errors about missing classes

Solution: Ensure correct version compatibility:

{
  "require": {
    "typo3/cms-core": "^13.4",
    "netresearch/rte-ckeditor-image": "^13.0"
  }
}

composer update
./vendor/bin/typo3 cache:flush
./vendor/bin/typo3 extension:setup

Issue: Style Drop-Down Dependency Error 

Symptoms:

• Styles disabled when image selected
• Style changes not applied to images

Cause: Missing GeneralHtmlSupport dependency (fixed in v13.0.0+)

Solution: Ensure you're using extension version 13.0.0 or higher:

composer require netresearch/rte-ckeditor-image:^13.0

The plugin now requires:

static get requires() {
    return ['StyleUtils', 'GeneralHtmlSupport'];  // Both mandatory
}

Issue: JavaScript Dependency Errors 

Symptoms:

• Browser console shows "GeneralHtmlSupport is not defined"
• Editor doesn't load properly

Cause: Extension version < 13.0.0

Solution: Update to latest version:

composer update netresearch/rte-ckeditor-image

Issue: Configuration Changes Not Applied 

Symptoms:

• RTE configuration changes don't take effect
• Old behavior persists after updates

Solution: Clear all caches:

# Clear all TYPO3 caches
./vendor/bin/typo3 cache:flush

# Clear system cache specifically
./vendor/bin/typo3 cache:flush --group=system

# Clear browser cache and reload

Issue: File References Not Updated 

Symptoms:

• Image selected but error occurs
• Empty image inserted
• "File Not Found" errors

Solution: Clear file abstraction layer cache:

./vendor/bin/typo3 cache:flush --group=system

Additional Steps:

1. Verify file exists in fileadmin/
2. Check file permissions (readable by web server)
3. Rebuild reference index:

./vendor/bin/typo3 referenceindex:update

Issue: File Browser Empty or Not Loading 

Symptoms:

• Modal opens but shows no files
• File browser stuck loading

Causes:

1. No file mount configured for backend user
2. Missing file permissions
3. Empty fileadmin directory

Solution:

# User TSConfig
options.defaultUploadFolder = 1:fileadmin/user_upload/

Verify backend user has file mount in: Backend → User Management → Backend Users → File Mounts

Issue: Processed Images Directory Not Writable 

Symptoms:

• Original large images displayed
• No _processed_/ directory created
• Slow page load due to large images

Solution: Check directory permissions:

# Ensure _processed_/ is writable
chmod 775 fileadmin/_processed_/

# Verify ownership
chown www-data:www-data fileadmin/_processed_/

Issue: Static Template Not Included 

Symptoms:

• Images visible in backend RTE
• Images missing in frontend output

Solution:

1. Include Static Template:

   • Go to Template → Info/Modify
   • Edit whole template record
   • Include CKEditor Image Support before Fluid Styled Content
2. Verify TypoScript:

lib.parseFunc_RTE {
    tags.img = TEXT
    tags.img {
        current = 1
        preUserFunc = Netresearch\RteCKEditorImage\Controller\ImageRenderingController->renderImageAttributes
    }
}

Issue: Click-to-Enlarge Not Working with sys_template Records (TYPO3 v13) 

Symptoms:

• Images display correctly in frontend
• Click-to-enlarge functionality doesn't work
• Data attributes still visible in HTML output (data-htmlarea-zoom, data-htmlarea-file-uid)
• Image processing hooks not executed

Cause:

In TYPO3 v13, sys_template records prevent site sets from loading. Legacy installations like the Introduction Package use sys_template records instead of modern site sets. When a sys_template exists on a page, TYPO3 ignores site set dependencies, so the extension's TypoScript configuration is never loaded.

Detection:

Check if your site uses sys_template records:

SELECT uid, pid, title, include_static_file
FROM sys_template
WHERE deleted=0 AND hidden=0;

If records exist and data-htmlarea-* attributes appear in frontend HTML, the extension's TypoScript is not being loaded.

Solution 1: Manual TypoScript Include (Quick Fix)

Add TypoScript directly to the sys_template record:

1. Go to WEB > Template module
2. Select page with sys_template record
3. Click Edit the whole template record
4. In Setup field, add:

# Include RTE CKEditor Image TypoScript
<INCLUDE_TYPOSCRIPT: source="FILE:EXT:rte_ckeditor_image/Configuration/TypoScript/ImageRendering/setup.typoscript">

5. Save template
6. Clear all caches:

./vendor/bin/typo3 cache:flush

Solution 2: Migrate to Site Sets (Recommended for TYPO3 v13)

Modern TYPO3 v13 approach:

1. Remove sys_template records from pages (or set them to deleted/hidden)
2. Enable site set dependencies in config/sites/<site>/config.yaml:

base: 'https://example.com/'
rootPageId: 1
dependencies:
  - typo3/fluid-styled-content
  - netresearch/rte-ckeditor-image

3. Clear caches:

./vendor/bin/typo3 cache:flush

4. Verify in frontend - data attributes should be removed and click-to-enlarge should work

Why This Happens:

• Zero-config installation (via ext_localconf.php) loads TypoScript globally
• sys_template records override global TypoScript for their page tree
• Bootstrap Package in sys_template clears lib.parseFunc_RTE hooks
• Site sets are ignored when sys_template exists

Verification:

After applying fix, check frontend HTML:

<!-- Before (BROKEN): -->
<img src="..." data-htmlarea-zoom="true" data-htmlarea-file-uid="2" />

<!-- After (WORKING): -->
<a href="/index.php?eID=tx_cms_showpic&file=2&...">
    <img src="..." />
</a>

Issue: ImageMagick/GraphicsMagick Not Configured 

Symptoms:

• Original large images displayed instead of processed versions
• Image processing test fails

Solution: Verify image processing configuration:

// LocalConfiguration.php
$GLOBALS['TYPO3_CONF_VARS']['GFX'] = [
    'processor' => 'ImageMagick',  // or 'GraphicsMagick'
    'processor_path' => '/usr/bin/',
    'processor_enabled' => true,
];

Test Image Processing:

./vendor/bin/typo3 backend:test:imageprocessing

Check Extension Installation 

# Verify extension is installed
composer show netresearch/rte-ckeditor-image

# Check TYPO3 extension list
./vendor/bin/typo3 extension:list

Verify Configuration Loading 

# Page TSConfig - Enable RTE debugging
RTE.default.showButtons = *
RTE.default.hideButtons =

Check Browser Console 

1. Open browser DevTools (F12)
2. Go to Console tab

3. Look for errors related to:

   • Plugin loading
   • Configuration issues
   • Missing dependencies

Monitor Network Requests 

1. Open browser DevTools
2. Go to Network tab

3. Check for failed requests to:

   • /rte/wizard/selectimage
   • Backend image info API

Issue: Large Database Size 

Symptoms:

• Database growing rapidly
• sys_refindex table very large

Cause: Excessive soft reference entries

Solution: Rebuild reference index:

./vendor/bin/typo3 referenceindex:update

Check References:

-- Find images in RTE content
SELECT uid, bodytext
FROM tt_content
WHERE bodytext LIKE '%data-htmlarea-file-uid%';

Issue: Image Button Not Visible in Toolbar 

Symptoms:

• Insert image button missing from CKEditor toolbar
• RTE loads but no image functionality

Causes:

1. Plugin not properly imported in RTE configuration
2. removePlugins includes image plugin
3. Toolbar configuration missing insertimage item

Solution:

# Configuration/RTE/Default.yaml
imports:
  - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Plugin.yaml" }

editor:
  config:
    removePlugins: null  # Critical: Don't remove image plugin
    toolbar:
      items:
        - insertimage  # Add to toolbar

Issue: Style Drop-Down Not Working with Images 

Symptoms:

• Styles disabled when image selected
• Style changes not applied to images

Cause: Missing GeneralHtmlSupport dependency (fixed in v13.0.0+)

Solution: Ensure you're using extension version 13.0.0 or higher:

composer require netresearch/rte-ckeditor-image:^13.0

The plugin now requires:

static get requires() {
    return ['StyleUtils', 'GeneralHtmlSupport'];  // Both mandatory
}

Issue: Custom Image Styles Lost After Upgrade 

Symptoms:

• Custom styles no longer available
• Style drop-down empty

Cause: RTE configuration changed

Solution: Re-apply custom styles in RTE configuration:

editor:
  config:
    style:
      definitions:
        - name: 'Your Custom Style'
          element: 'img'
          classes: ['your-class']

Issue: File Browser Empty or Not Loading 

Symptoms:

• Modal opens but shows no files
• File browser stuck loading

Causes:

1. No file mount configured for backend user
2. Missing file permissions
3. Empty fileadmin directory

Solution:

# User TSConfig
options.defaultUploadFolder = 1:fileadmin/user_upload/

Verify backend user has file mount in: Backend → User Management → Backend Users → File Mounts

Issue: "File Not Found" After Selection 

Symptoms:

• Image selected but error occurs
• Empty image inserted

Causes:

1. File reference invalid
2. Storage not accessible
3. File deleted from filesystem

Solution:

1. Verify file exists in fileadmin/
2. Check file permissions (readable by web server)
3. Clear file abstraction layer cache:

./vendor/bin/typo3 cache:flush --group=system

Issue: Magic Image Maximum Dimensions Not Working 

Symptoms:

• Images not respecting configured maxWidth/maxHeight
• Large images not being resized

Cause: TSConfig settings in custom template extension not loaded (TYPO3 bug #87068)

Solution: Add settings to root page config instead:

# In root page TSConfig (not template extension)
RTE.default.buttons.image.options.magic {
    maxWidth = 1920
    maxHeight = 9999
}

Issue: JavaScript Console Errors 

Symptoms:

• Browser console shows errors
• Editor doesn't load properly

composer update netresearch/rte-ckeditor-image

imports:
  - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Plugin.yaml" }

Issue: Double-Click on Image Does Nothing 

Symptoms:

• Double-clicking image doesn't open dialog
• Edit functionality not working

Causes:

1. DoubleClickObserver not registered
2. JavaScript error blocking execution
3. Image not recognized as typo3image

Solution:

1. Check browser console for JavaScript errors
2. Verify image has data-htmlarea-file-uid attribute
3. Clear browser cache and reload
4. Check CKEditor version compatibility (requires CKEditor 5)

Issue: Editor Not Initializing 

Symptoms:

• CKEditor doesn't load
• Textarea remains plain text field

Causes:

1. JavaScript errors preventing initialization
2. RTE configuration not loaded
3. Browser cache issues

Solution:

1. Check browser console for errors
2. Verify RTE preset is enabled:

# Configuration/RTE/Default.yaml
imports:
  - { resource: "EXT:rte_ckeditor/Configuration/RTE/Default.yaml" }
  - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Plugin.yaml" }

3. Clear browser and TYPO3 caches:

./vendor/bin/typo3 cache:flush

4. Force reload in browser (Ctrl+Shift+R)

Issue: Plugin Not Recognized 

Symptoms:

• Image plugin functionality missing
• Console error about undefined plugin

Cause: Plugin configuration not properly loaded

Solution: Ensure proper import order:

# Configuration/RTE/Default.yaml
imports:
  # Base CKEditor configuration first
  - { resource: "EXT:rte_ckeditor/Configuration/RTE/Default.yaml" }
  # Then image plugin
  - { resource: "EXT:rte_ckeditor_image/Configuration/RTE/Plugin.yaml" }

editor:
  config:
    # Ensure plugin is not removed
    removePlugins: null
    toolbar:
      items:
        - insertimage

Enable RTE Debugging 

# Page TSConfig
RTE.default.showButtons = *
RTE.default.hideButtons =

Check Loaded Configuration 

Browser console:

// Check if plugin loaded
console.log(CKEDITOR.instances);

// Inspect editor config
const editor = Object.values(CKEDITOR.instances)[0];
console.log(editor.config);

Monitor Network Requests 

1. Open browser DevTools
2. Go to Network tab
3. Trigger image selection

4. Check for failed requests to:

   • /rte/wizard/selectimage
   • Backend image info API

Inspect DOM Elements 

Check if images have required attributes:

// In browser console
document.querySelectorAll('img[data-htmlarea-file-uid]');

Issue: Images Not Appearing in Frontend 

Symptoms:

• Images visible in backend RTE
• Images missing in frontend output

Causes:

1. TypoScript rendering hooks missing (rare with v13.0.0+)
2. Cached content
3. Custom TypoScript overriding automatic configuration

Solution:

1. Verify TypoScript is loaded (v13.0.0+ automatic):

   The extension automatically loads TypoScript. Verify it's present:

   lib.parseFunc_RTE {
       tags.img = TEXT
       tags.img {
           current = 1
           preUserFunc = Netresearch\RteCKEditorImage\Controller\ImageRenderingController->renderImageAttributes
       }
   }

   Copied!

2. Clear Caches:

   ./vendor/bin/typo3 cache:flush

   Copied!

3. Check for TypoScript conflicts:

   If you have custom lib.parseFunc_RTE configuration, ensure it doesn't override the image rendering hooks.

Issue: Processed Images Not Generated 

Symptoms:

• Original large images displayed
• No _processed_/ directory created
• Slow page load due to large images

Causes:

1. Image processing disabled
2. ImageMagick/GraphicsMagick not configured
3. File permissions issue

Solution:

1. Verify Image Processing Configuration:

// LocalConfiguration.php
$GLOBALS['TYPO3_CONF_VARS']['GFX'] = [
    'processor' => 'ImageMagick',  // or 'GraphicsMagick'
    'processor_path' => '/usr/bin/',
    'processor_enabled' => true,
];

2. Test Image Processing:

# TYPO3 CLI
./vendor/bin/typo3 backend:test:imageprocessing

3. Check Directory Permissions:

# Ensure _processed_/ is writable
chmod 775 fileadmin/_processed_/

4. Check Processed Files:

ls -la fileadmin/_processed_/

Issue: Broken Image Links 

Symptoms:

• Broken image icon displayed
• 404 errors in browser console
• Missing image files

Causes:

1. File moved or deleted
2. Invalid file reference
3. Storage configuration changed

Solution:

1. Verify File Exists:

# Check if file exists in fileadmin
ls -la fileadmin/path/to/image.jpg

2. Check File References:

-- Find images in RTE content
SELECT uid, pid, bodytext
FROM tt_content
WHERE bodytext LIKE '%data-htmlarea-file-uid%';

3. Rebuild Reference Index:

./vendor/bin/typo3 referenceindex:update

4. Clear File Caches:

./vendor/bin/typo3 cache:flush --group=system

Issue: Wrong Image Path in Output 

Symptoms:

• Image src points to wrong location
• Absolute paths instead of relative
• Missing domain in URLs

Cause: Incorrect TypoScript configuration

Solution:

# Ensure proper path generation
config.absRefPrefix = /
config.baseURL = https://your-domain.com/

Issue: Images Display at Wrong Size 

Symptoms:

• Images too large or too small
• Dimensions not respected
• Responsive behavior broken

Causes:

1. CSS conflicts
2. Missing width/height attributes
3. Responsive image configuration issues

Solution:

1. Check Generated HTML:

<!-- Should include width and height -->
<img src="..." width="800" height="600" />

2. Verify CSS:

/* Ensure images are responsive */
.rte img {
    max-width: 100%;
    height: auto;
}

3. Check TypoScript Configuration:

lib.parseFunc_RTE.tags.img {
    current = 1
    preUserFunc = Netresearch\RteCKEditorImage\Controller\ImageRenderingController->renderImageAttributes
}

Issue: Image Dimensions Not Preserved 

Symptoms:

• Aspect ratio distorted
• Images stretched or squashed

Cause: Missing or incorrect dimension attributes

Solution:

Ensure both width and height are rendered:

lib.parseFunc_RTE.tags.img {
    current = 1
    preUserFunc = Netresearch\RteCKEditorImage\Controller\ImageRenderingController->renderImageAttributes
    stdWrap {
        wrap = <div class="rte-image">|</div>
    }
}

Issue: CSS Classes Not Applied 

Symptoms:

• Custom classes missing from output
• Styles not visible in frontend
• Classes work in backend but not frontend

Cause: HTMLparser configuration stripping classes

Solution:

lib.parseFunc_RTE.nonTypoTagStdWrap.HTMLparser {
    keepNonMatchedTags = 1
    tags.img {
        allowedAttribs = class,src,alt,title,width,height
        fixAttrib.class.list = your-allowed-classes
    }
}

Issue: Data Attributes Visible in Frontend 

Symptoms:

• data-htmlarea-file-uid visible in HTML
• Internal attributes exposed

Cause: HTMLparser configuration missing

Solution:

lib.parseFunc_RTE.nonTypoTagStdWrap.HTMLparser.tags.img.fixAttrib {
    data-htmlarea-file-uid.unset = 1
    data-htmlarea-file-table.unset = 1
    # Keep zoom attributes for popup/lightbox rendering
    # data-htmlarea-zoom.unset = 1
    data-title-override.unset = 1
    data-alt-override.unset = 1
}

Issue: Image Links Not Working 

Symptoms:

• Clickable images don't work
• Links stripped from output
• JavaScript conflicts

Cause: Link processing configuration

Solution:

lib.parseFunc_RTE {
    tags.a = TEXT
    tags.a {
        current = 1
        typolink {
            parameter.data = parameters:href
            title.data = parameters:title
            ATagParams.data = parameters:allParams
        }
    }
}

Issue: Lightbox/Zoom Not Working 

Symptoms:

• data-htmlarea-zoom attribute present but zoom doesn't work
• Lightbox not triggering

Cause: Missing JavaScript or CSS for lightbox

Solution:

1. Ensure Zoom Attribute Rendered:

lib.parseFunc_RTE.tags.img {
    current = 1
    preUserFunc = Netresearch\RteCKEditorImage\Controller\ImageRenderingController->renderImageAttributes
}

2. Include Lightbox Library:

Add your preferred lightbox library (e.g., Fancybox, Lightbox2, PhotoSwipe)

3. Initialize Lightbox:

// Example with Fancybox
document.querySelectorAll('img[data-htmlarea-zoom]').forEach(img => {
    const link = document.createElement('a');
    link.href = img.src.replace(/\/_processed_\/.*/, '/' + img.dataset.htmlareaZoom);
    link.setAttribute('data-fancybox', 'gallery');
    img.parentNode.insertBefore(link, img);
    link.appendChild(img);
});

Issue: Images Not Responsive 

Symptoms:

• Images overflow container on mobile
• Fixed width prevents scaling
• No srcset generated

Cause: Missing responsive configuration

Solution:

/* Basic responsive images */
.rte img {
    max-width: 100%;
    height: auto;
    display: block;
}

For advanced responsive images with srcset, configure image processing:

lib.parseFunc_RTE.tags.img {
    current = 1
    preUserFunc = Netresearch\RteCKEditorImage\Controller\ImageRenderingController->renderImageAttributes
}

Issue: Old Images Still Displayed 

Symptoms:

• Updated images not showing
• Old version cached
• Changes visible in backend but not frontend

Solution:

1. Clear TYPO3 Caches:

./vendor/bin/typo3 cache:flush

2. Clear Browser Cache:

   • Hard reload: Ctrl+Shift+R (Windows/Linux)
   • Hard reload: Cmd+Shift+R (Mac)
3. Clear Processed Images:

# Remove all processed images
rm -rf fileadmin/_processed_/*

4. Verify Cache Configuration:

config {
    sendCacheHeaders = 1
    cache_period = 86400
}

Check Generated HTML 

View page source and inspect image markup:

<!-- Expected output -->
<img src="fileadmin/_processed_/.../image.jpg"
     alt="Description"
     width="800"
     height="600"
     class="your-class" />

Verify TypoScript Processing 

# Enable TypoScript debugging
config {
    debug = 1
    admPanel = 1
}

Check Browser Network Tab 

1. Open DevTools (F12)
2. Go to Network tab
3. Filter by images

4. Check for:

   • 404 errors
   • Slow loading
   • Wrong paths

Inspect CSS 

/* Check for conflicts */
.rte img {
    /* Ensure no display:none or visibility:hidden */
}

Monitor Console Errors 

Look for JavaScript errors that might affect image rendering:

// Common issues
- Failed to load resource
- CORS errors
- JavaScript blocking rendering

Issue: Slow Editor Loading 

Symptoms:

• CKEditor takes long time to initialize
• Image browser slow to open

Causes:

1. Large number of files in file browser
2. Unoptimized image processing settings
3. Network latency
4. Browser resource constraints

Solutions:

1. Optimize Image Processing:

// LocalConfiguration.php
$GLOBALS['TYPO3_CONF_VARS']['GFX']['jpg_quality'] = 85;
$GLOBALS['TYPO3_CONF_VARS']['GFX']['processor_effects'] = false;  // If not needed

2. Reduce Maximum Dimensions:

RTE.default.buttons.image.options.magic {
    maxWidth = 1200  # Instead of 1920
    maxHeight = 800  # Instead of 9999
}

3. Limit File Browser Results:

Configure file mounts to show only relevant directories:

# User TSConfig
options.folderTree.uploadFieldsInLinkBrowser = 0
options.pageTree.showPageIdWithTitle = 0

Issue: Image Selection Dialog Slow 

Symptoms:

• Modal takes long time to open
• Thumbnails load slowly
• Browser becomes unresponsive

Causes:

1. Too many files in directory
2. Large unprocessed images
3. Missing thumbnail cache

Solutions:

1. Organize Files into Subdirectories:

   • Group images by category
   • Use year/month folder structure
   • Keep directories under 100 files
2. Pre-generate Thumbnails:

# Generate missing thumbnails
./vendor/bin/typo3 cleanup:missingfiles
./vendor/bin/typo3 cleanup:previewlinks

3. Optimize File Storage:

# Limit file selection to specific folders
options.defaultUploadFolder = 1:fileadmin/user_upload/

Issue: Slow Page Load Due to Images 

Symptoms:

• Pages load slowly
• Large images not processed
• High bandwidth usage

Causes:

1. Original large images served instead of processed versions
2. No image compression
3. Missing lazy loading
4. Too many images on page

Solutions:

1. Enable Image Processing:

// LocalConfiguration.php
$GLOBALS['TYPO3_CONF_VARS']['GFX'] = [
    'processor_enabled' => true,
    'processor' => 'ImageMagick',
    'jpg_quality' => 85,
];

2. Configure Reasonable Maximum Dimensions:

RTE.default.buttons.image.options.magic {
    maxWidth = 1920
    maxHeight = 1080
}

3. Implement Lazy Loading:

lib.parseFunc_RTE.tags.img {
    current = 1
    preUserFunc = Netresearch\RteCKEditorImage\Controller\ImageRenderingController->renderImageAttributes
    stdWrap.replacement {
        10 {
            search = <img
            replace = <img loading="lazy"
        }
    }
}

4. Enable Browser Caching:

# .htaccess
<IfModule mod_expires.c>
    ExpiresActive On
    ExpiresByType image/jpeg "access plus 1 year"
    ExpiresByType image/png "access plus 1 year"
    ExpiresByType image/webp "access plus 1 year"
</IfModule>

Issue: Excessive Bandwidth Usage 

Symptoms:

• High server bandwidth consumption
• Slow site on mobile devices
• Large page sizes

Solutions:

1. Use WebP Format:

// LocalConfiguration.php
$GLOBALS['TYPO3_CONF_VARS']['GFX']['processor_allowUpscaling'] = false;
$GLOBALS['TYPO3_CONF_VARS']['GFX']['processor_stripColorProfileByDefault'] = true;

2. Implement Progressive JPEG:

$GLOBALS['TYPO3_CONF_VARS']['GFX']['processor_interlace'] = true;

3. Compress Images:

$GLOBALS['TYPO3_CONF_VARS']['GFX']['jpg_quality'] = 80;

Issue: Image Processing Timeouts 

Symptoms:

• 500 errors when uploading images
• Processing hangs
• Timeouts in backend

Causes:

1. Insufficient PHP memory
2. Low execution time limits
3. Slow image processor
4. Very large source images

Solutions:

1. Increase PHP Limits:

// php.ini or LocalConfiguration.php
memory_limit = 512M
max_execution_time = 300
upload_max_filesize = 20M
post_max_size = 20M

2. Optimize Image Processor:

// LocalConfiguration.php
$GLOBALS['TYPO3_CONF_VARS']['GFX']['processor_path_lzw'] = '';
$GLOBALS['TYPO3_CONF_VARS']['GFX']['processor_colorspace'] = 'RGB';

3. Limit Upload Size:

# Page TSConfig
RTE.default.buttons.image.options.magic {
    maxFileSize = 5000  # 5MB in KB
}

Issue: Processed Images Directory Growing 

Symptoms:

• Large _processed_/ directory
• Disk space issues
• Duplicate processed images

Causes:

1. Old processed images not cleaned up
2. Multiple versions of same image
3. Unused processed files accumulating

Solutions:

1. Clean Old Processed Files:

# Remove processed files older than 30 days
find fileadmin/_processed_ -type f -mtime +30 -delete

2. Implement Automated Cleanup:

// LocalConfiguration.php
$GLOBALS['TYPO3_CONF_VARS']['GFX']['processor_allowTemporaryMasksAsPng'] = false;

3. Schedule Cleanup Task:

Create a scheduler task to regularly clean old processed images:

# Cron job example (runs weekly)
0 2 * * 0 find /path/to/fileadmin/_processed_ -type f -mtime +30 -delete

Issue: Large Database Size 

Symptoms:

• Database growing rapidly
• sys_refindex table very large
• Slow queries

Causes:

1. Excessive soft reference entries
2. Orphaned records
3. Unoptimized indexes

Solutions:

1. Rebuild Reference Index:

./vendor/bin/typo3 referenceindex:update

2. Clean Up Orphaned Records:

-- Find images in deleted content
SELECT uid, bodytext
FROM tt_content
WHERE deleted = 1 AND bodytext LIKE '%data-htmlarea-file-uid%';

3. Optimize Tables:

OPTIMIZE TABLE sys_refindex;
OPTIMIZE TABLE tt_content;

Issue: Slow Reference Index Updates 

Symptoms:

• Reference index update takes long time
• High CPU usage during updates

Solutions:

1. Batch Update References:

# Update in smaller batches
./vendor/bin/typo3 referenceindex:update --check

2. Schedule Off-Peak Updates:

Run reference index updates during low-traffic periods:

# Cron job (runs at 3 AM)
0 3 * * * /path/to/vendor/bin/typo3 referenceindex:update

Issue: Excessive Cache Invalidation 

Symptoms:

• Caches cleared too frequently
• Slow page regeneration
• High server load

Causes:

1. Aggressive cache clearing
2. Content changes trigger full cache clear
3. Misconfigured cache tags

Solutions:

1. Optimize Cache Configuration:

// LocalConfiguration.php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['pages'] = [
    'backend' => \TYPO3\CMS\Core\Cache\Backend\RedisBackend::class,
    'options' => [
        'hostname' => 'localhost',
        'database' => 0,
        'port' => 6379,
    ],
];

2. Use Cache Tags Effectively:

config {
    cache_period = 86400
    sendCacheHeaders = 1
}

3. Implement Selective Cache Clearing:

# Clear only specific cache groups
./vendor/bin/typo3 cache:flush --group=pages

Issue: Slow Image Loading from CDN 

Symptoms:

• Images load slowly despite CDN
• Inconsistent loading times
• Failed CDN requests

Solutions:

1. Configure Proper CDN:

config {
    absRefPrefix = /
    baseURL = https://cdn.yourdomain.com/
}

2. Use HTTP/2:

Ensure your server supports HTTP/2 for multiplexing

3. Implement Preconnect:

<link rel="preconnect" href="https://cdn.yourdomain.com">
<link rel="dns-prefetch" href="https://cdn.yourdomain.com">

Performance Monitoring 

1. Enable TYPO3 Admin Panel:

config.admPanel = 1

2. Monitor Image Processing:

# Check processing time
./vendor/bin/typo3 backend:test:imageprocessing

3. Track Page Load Times:

Use browser DevTools Network tab to monitor:

• Image load times
• TTFB (Time to First Byte)
• Total page load time

Database Query Profiling 

-- Find slow queries
SHOW PROCESSLIST;

-- Analyze reference index queries
EXPLAIN SELECT * FROM sys_refindex WHERE tablename='tt_content';

Image Processing Profiling 

# Time image processing
time ./vendor/bin/typo3 backend:test:imageprocessing

# Monitor processed files
watch -n 5 "ls -lh fileadmin/_processed_/ | wc -l"

Image Optimization Checklist 

✓ Configure reasonable maximum dimensions:

RTE.default.buttons.image.options.magic {
    maxWidth = 1920
    maxHeight = 1080
}

✓ Enable image processing:

$GLOBALS['TYPO3_CONF_VARS']['GFX']['processor_enabled'] = true;

✓ Set appropriate JPEG quality:

$GLOBALS['TYPO3_CONF_VARS']['GFX']['jpg_quality'] = 85;

✓ Implement lazy loading:

<img loading="lazy" src="..." />

✓ Use browser caching:

ExpiresActive On
ExpiresByType image/jpeg "access plus 1 year"

✓ Regular cleanup of processed files:

find fileadmin/_processed_ -type f -mtime +30 -delete

✓ Monitor disk space and database size

✓ Optimize images before upload (recommend to editors)

Server Optimization Checklist 

✓ Adequate PHP memory: 512M minimum

✓ Fast image processor: ImageMagick or GraphicsMagick

✓ Redis/Memcached for caching

✓ HTTP/2 support enabled

✓ CDN for static assets

✓ Regular database optimization

✓ Scheduled cleanup tasks

System Understanding 

• Learn the architecture → System Architecture
• Understand data flow → Design Patterns & Integration
• Extend the system → Design Patterns & Integration

Integration Reference 

• TYPO3 Core integration → Design Patterns & Integration
• CKEditor integration → CKEditor Plugin Development
• Backend APIs → API Documentation