Download the PHP package netresearch/rte-ckeditor-image without Composer

RTE CKEditor Image — Image Support for CKEditor 5 in TYPO3

A TYPO3 extension that restores and modernises rich-text image handling for TYPO3 v13.4 LTS and v14.3 LTS, built on CKEditor 5 with full File Abstraction Layer (FAL) integration, image processing, accessibility metadata, and content security in mind.

Table of Contents

• Why this extension exists
• Features at a glance
• Requirements
• Installation
• Configuration
• Usage recipes
• Documentation
• Security
• Development
• Verifying releases
• Contributing
• License & credits

Why this extension exists

TYPO3 intentionally removed rich-text image handling from the core in TYPO3 v10. Editors lost the ability to insert FAL-backed images into bodytext via the rich-text editor — the recommended path became dedicated image content elements, which is not always what an editorial workflow needs.

This extension fills that gap without recreating the legacy rtehtmlarea behaviour wholesale. Images inserted from the rich-text editor go through the same Magic Images processing pipeline integrators already know from TSConfig: cropping, scaling, quality multipliers, lazy-loading, captions, and inline links. The CKEditor 5 plugin handles upcast/downcast cleanly, the backend uses TYPO3's modern file browser, and the rendered frontend output passes through TYPO3's parseFunc / Fluid template chain so site themes (Bootstrap Package, custom sitepackages, Content Blocks) can override it.

If your editorial workflow needs inline images inside paragraphs — with alt text, captions, links, popups, alignment, and high-DPI rendering — and you do not want to give up FAL or content security, this is the extension for you.

Features at a glance

Editor experience

• TYPO3 FAL integration — native file browser with full File Abstraction Layer support and the standard CKEditor 5 dialog.
• Image properties dialog — width, height, alt, title, with automatic aspect-ratio locking.
• Quality selector — choose No Scaling, Standard (1.0x), Retina (2.0x), Ultra (3.0x), or Print (6.0x) per image; persisted as data-quality so behaviour is reproducible across re-edits.
• True inline images — cursor positioning before/after the image, mid-paragraph insertion, and round-trip-safe save/load.
• SVG support — intelligent dimension extraction from viewBox and width/height attributes; original vectors used as-is.

Frontend rendering

• Magic Images pipeline — the same cropping, scaling, and processing as rtehtmlarea, configurable via Page TSConfig.
• Lazy loading — honours TYPO3's native loading="lazy" / eager / auto configuration.
• Custom styles — image styles integrated with the CKEditor 5 style system and GeneralHtmlSupport.
• Fluid template overrides — every fragment (figure, link, popup, caption) is a Fluid partial that themes can override; figcaption width is constrained to the image automatically.
• Table images — images inside CKEditor 5 tables get the full processing chain (max-width, zoom, t3:// link resolution).

Integrity & maintenance

• Automatic softref tracking — RTE image references are registered with the reference index across all RTE-enabled fields, so file moves, renames, and deletions stay consistent.
• Image validation CLI — rte_ckeditor_image:validate detects broken references, nested link wrappers, and stale paths; --fix repairs them.
• Upgrade wizard — runs the same validation as an Install Tool wizard for one-shot repair after major upgrades.
• Preview renderer — images stay visible in the page module preview, with explicit warnings when a reference is broken.
• Content Blocks support — a ViewHelper renders RTE image previews inside Content Blocks backend templates.

Quality & security

• PSR-14 events for extensibility at every rendering decision point.
• Defense-in-depth security: caption XSS sanitization, file-visibility validation, URL protocol allowlist (http, https, mailto, tel, t3), SVG sanitization, SSRF protection on external image fetch, and style-attribute exclusion.
• PHPStan level 10, strict-rules, deprecation-rules, phpat architecture rules — zero baseline errors.
• SLSA Level 3 provenance attestation, signed release tags, OpenSSF Best Practices participation.

Requirements

The CKEditor 5 plugin auto-integrates with GeneralHtmlSupport for image styles — no extra config required.

Version compatibility

The main branch targets the current TYPO3 LTS releases. Earlier TYPO3 versions are served by dedicated, version-pinned branches. Composer selects the right series automatically from your installed TYPO3 version, or you can pin it explicitly (e.g. composer require netresearch/rte-ckeditor-image:^12.0).

The TYPO3_12 and main branches use CKEditor 5 (matching TYPO3 core's CKEditor 5 integration from v12 onward); the TYPO3_11 and TYPO3_10 branches use the legacy CKEditor 4. The features described below target main (TYPO3 v13/v14).

Installation

1. Install via Composer

2. Enable the Site Set

Activating the shipped Site Set wires up both the backend RTE preset (with the insertimage button) and the frontend TypoScript for image processing in one step. Add the extension to your site's config.yaml:

Using Bootstrap Package or another theme extension? List netresearch/rte-ckeditor-image after them in your dependencies, so the RTE preset wins the load order.

3. (Alternative) Manual TypoScript import

If you prefer to manage TypoScript load order yourself rather than rely on Site Sets:

4. (Optional) Custom RTE preset

If you maintain your own RTE preset and want to inject the image plugin into it:

Configuration

The extension ships with sensible defaults — most installations need zero configuration. The four most commonly tuned settings live in Extension Configuration (Admin Tools → Settings → Extension Configuration → rte_ckeditor_image):

The full reference — every option, every edge case — lives in the manual: see Advanced Configuration.

Image src storage convention

RTE image src is persisted in canonical site-root-relative form (/fileadmin/image.jpg, with a leading slash). Slashless storage (fileadmin/image.jpg) is treated as a defect and repaired by the validator — modern TYPO3 does not emit <base href>, so a slashless src resolves against the current page URL in the browser and breaks on every non-root page. External references (https://…, data:…, //cdn.example.com/…) pass through unchanged.

Subpath installs (TYPO3 served from /~user/, /subsite/, etc.) must set config.absRefPrefix = /subsite/. TYPO3's render chain prepends it to leading-slash paths at output time, so storage stays identical to a site-root install.

See ADR-004: Image src Storage Convention for the full rationale.

Usage recipes

The snippets below cover the configuration questions that arrive most often. The manual covers each topic in depth.

Set maximum width / height

Magic Images obey the limits configured in Page TSConfig. Defaults are conservative — raise them for editorial sites with large hero images:

If TSConfig from a custom template extension does not take effect, place the settings directly on the root page record.

Lightbox via fluid_styled_content

Default CSS class for every RTE image

Native browser lazy loading

See Feature 90426 (Native lazy loading) for the underlying TYPO3 behaviour.

Image Quality selector

The image dialog includes a Quality dropdown that lets editors trade file size against pixel density per image:

The choice is stored in the data-quality HTML attribute, so it survives re-edits and is reproducible across environments. See the Image Quality Selector documentation for technical details, use cases, and the migration guide from legacy noScale.

Skip processing globally (legacy noScale)

For all-original-images integrations (newsletter exports, PDF-bound content), keep originals globally:

The modern, per-image equivalent is the Quality selector set to No Scaling — better UX, same effect (data-quality="none"). Processing is skipped automatically when requested dimensions equal the original, when the file is an SVG, or when Quality is set to No Scaling.

Restrict allowed file extensions

By default the extensions listed in $GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext'] are allowed. Override per RTE preset:

Documentation

This project maintains a single source of truth — the manual published on docs.typo3.org — supplemented by AI-readable context inside the repository.

Official manual — docs.typo3.org

The published manual is the canonical reference for integrators, administrators, and editors. It covers installation, configuration, integration, troubleshooting, the developer API, the CKEditor 5 plugin internals, and the architecture decision records.

📘 docs.typo3.org/p/netresearch/rte-ckeditor-image

Source: Documentation/ (reStructuredText, automatically built and published).

In-repository guides

• AGENTS.md — development guide, build commands, code standards, and PR checklist (audience: humans and AI agents).
• CONTRIBUTING.md — contribution workflow, commit conventions, review process.
• SECURITY.md — security policy and coordinated disclosure.
• Documentation/AGENTS.md — TYPO3 documentation system guide.
• claudedocs/ (gitignored) — AI development context generated per session.

Security

This extension implements defense-in-depth security at every boundary where untrusted RTE content reaches a renderer or a storage path:

• Caption XSS prevention — all editor-supplied captions are sanitized via ImageResolverService::sanitizeCaption().
• File visibility validation — files in non-public storages are blocked at render time.
• URL protocol allowlist — only http:, https:, mailto:, tel:, t3: pass; javascript:, vbscript:, data:text/html are rejected.
• SVG sanitization — SVG data URIs are routed through TYPO3 Core's SvgSanitizer.
• SSRF protection — the external image fetcher (when fetchExternalImages is on) refuses private IPs and DNS-rebinding payloads.
• Style attribute exclusion — style is excluded from the allowed HTML attribute list to prevent CSS injection.
• Whitespace-smuggling hardening — <img src> values are stripped of leading ASCII whitespace before protocol-relative checks, blocking " //evil.com/x.jpg"-style payloads (CWE-20 / CWE-176, defense-in-depth).

Responsibilities delegated to TYPO3 Core (and not re-implemented here): SVG file upload sanitization, file extension and MIME validation, and image-processing security inside GraphicalFunctions. See ADR-003: Security Responsibility Boundaries for the full division.

To report a vulnerability, please follow SECURITY.md. Do not open public issues for security findings.

Development

DDEV environment (recommended for full backend testing)

The repository ships a complete DDEV setup with TYPO3 v13 and v14 side-by-side, Bootstrap Package preinstalled, and rendered documentation served locally:

The DDEV environment is preconfigured for testing image insertion in the RTE, click-to-enlarge behaviour, caption WYSIWYG editing, image alignment, and image-style application.

Local development (no DDEV)

The full development guide — code standards, CI matrix, PR checklist, security boundaries — lives in AGENTS.md.

Quality gates

• PHPStan level 10 with phpstan-strict-rules, phpstan-deprecation-rules, and phpat architecture rules — zero baseline errors.
• PHP-CS-Fixer (@Symfony ruleset, risky rules enabled).
• Rector for automated TYPO3 modernization (ssch/typo3-rector).
• PHPUnit unit and functional suites with SQLite-backed functional tests.
• Playwright E2E suite running against both v13 and v14 in CI.
• Infection mutation testing.
• php-fuzzer fuzz harnesses for ImageAttributeParser and RteImageSoftReferenceParser.
• CI matrix: PHP 8.2 / 8.3 / 8.4 / 8.5 × TYPO3 ^13.4 / ^14.3 — 8 combinations for build, plus blocking E2E on v13 and v14.

Verifying releases

Every release tag is GPG-signed and ships with SLSA Level 3 provenance attestation for supply-chain integrity.

Verify tag signature

Verify SLSA provenance

See SLSA for the framework overview and the attestations index for this project's published provenance.

Distribution channels

• Composer — packagist.org/packages/netresearch/rte-ckeditor-image (recommended)
• TYPO3 Extension Repository (TER) — extensions.typo3.org/extension/rte_ckeditor_image (auto-published via GitHub Actions on tag)
• GitHub Releases — releases (source archives + provenance attestations)

Contributing

Contributions of code, documentation, translations, and bug reports are welcome. The extension is currently translated into 31 languages via Crowdin.

Before opening a PR, please:

1. Read Conventional Commits, validated by commitlint).
2. Run make ci locally to mirror the pre-commit and CI checks.
3. Add tests for new code paths — unit, functional, or E2E as appropriate.
4. Keep PRs focused (~300 net LOC is a good target).

This project follows the SECURITY.md.

License & credits

Licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).

Developed and maintained by Netresearch DTT GmbH.

Repository home: github.com/netresearch/t3x-rte_ckeditor_image.