ADR-004: Canonical RTE Image src Storage Convention 

Summary 

The extension persists every RTE image src in canonical site-root-relative form with a leading slash (/fileadmin/x). This contract is enforced symmetrically on both ends of the data flow: the storage write path (ImageTagBuilder::makeRelativeSrc) and the validator's strict-equality comparison (RteImageReferenceValidator::srcMatchesPublicUrl). Slashless (fileadmin/x) and protocol-relative (//cdn.example.com/x) forms are out-of-contract: slashless is detected as a defect and repaired; protocol-relative is treated as an external CDN reference and passes through unchanged.

Context 

A series of regressions exposed an implicit contract that had never been written down:

• #778 reported that getPublicUrl() for the Local FAL driver returns slashless (fileadmin/x) while the RTE stored leading-slash (/fileadmin/x). The validator's naïve string-compare flagged the stored value as SrcMismatch and "fixed" it by stripping the leading slash — silently breaking frontend rendering on every page.
• The first attempt at #778 (#779) made the comparison tolerant: both slashless and leading-slash were accepted as equivalent. This stopped the over-correction but turned the validator blind to a different defect.
• #837 surfaced that defect: older upgrade:run versions had stripped the leading slash from existing storage. validate --fix was the intended repair tool but, after the over-correction in #779, it silently treated the broken value as already-correct.
• #839 tightened the validator to strict equality, restoring repair.
• #840 closed the loop: ImageTagBuilder::makeRelativeSrc was still producing slashless on save in some paths, which meant fresh inserts would be flagged + rewritten by the next validate run. The storage side now normalises to leading-slash for every local input.

The decision below codifies the convention so it does not get re-broken.

Decision Drivers 

TYPO3 v12+ does not emit ``<base href>``.

config.baseURL was deprecated and removed. Modern TYPO3 uses site configuration's base key for routing; the rendered HTML carries no <base href> tag. A browser therefore resolves slashless src against the current page URL — broken on every non-root page.

Storage and rendering must be decoupled cleanly.

The storage convention should be independent of where the install is served from (root vs subpath). TYPO3's standard mechanism for this is config.absRefPrefix: a leading-slash storage value is prefixed at render time. This keeps every install layout identical at the database level.

Two write paths must not disagree.

The editor saves through RteImageProcessor ➜ ImageTagBuilder::makeRelativeSrc. The validator/listener writes through RteImageReferenceValidator::fix() and UpdateImageReferences. If these two paths produce different canonical forms, every save-then-validate cycle creates spurious rewrites.

External references must be preserved bit-for-bit.

Protocol-relative (//cdn.example.com/...), scheme URLs (http://, https://, data:, mailto:) reference assets outside the site's FAL. The contract must not coerce them into a site-root-relative form.

Decision 

1. Canonical storage form. Every local image src is persisted with a leading slash: /fileadmin/.... Slashless storage (fileadmin/...) is treated as a defect and repaired to the canonical form.
2. External references pass through unchanged. Scheme URLs and protocol-relative URLs are detected via the RFC 3986 scheme grammar pattern ^(?:[a-z][a-z0-9+.\-]*:|//) (PHP PCRE form: #…#i) and returned as-is.
3. Write paths agree. Both ImageTagBuilder::makeRelativeSrc and the validator's repair path (normalizePublicUrl ➜ srcMatchesPublicUrl ➜ applyFixes) produce the same canonical leading-slash output.
4. Subpath installs use ``config.absRefPrefix``. The prefix is prepended at render time by TYPO3 Core. Storage stays canonical across root and subpath installs. See Frontend Issues for setup.
5. Empty ``siteUrl`` is a safety valve. When the editor save path is invoked without a resolved site URL (CLI, certain test contexts), makeRelativeSrc returns the input unchanged. This prevents accidental rewrites in contexts where the site identity is unknown.

Out of Scope 

• Emitting ``<base href>``. Removed from TYPO3 Core in v9.5 and never restored; the extension does not attempt to bring it back.
• Sub-path rendering at the HTML layer. Delegated to config.absRefPrefix, a standard TYPO3 mechanism. The extension does not duplicate this functionality.
• Per-site validation context. The validator does not currently inject sitePath to compute per-site expected forms. The contract above makes this unnecessary: storage is uniform across sites.
• Path canonicalisation. makeRelativeSrc does not collapse .. or . segments. The FAL UID round-trip plus the validator's strict-equality check (RteImageReferenceValidator::srcMatchesPublicUrl) reject any src that does not match a real file's normalised public URL, so a smuggled /../../etc/passwd cannot point at content that the FAL would not have served anyway. Whitespace is trimmed up-front to prevent WHATWG-URL bypass of the scheme-grammar guard.
• HTML output escaping. makeRelativeSrc returns raw text; the caller (ImageTagBuilder::build(), ultimately Fluid) is responsible for HTML-attribute escaping. See the @security block on the method docblock.

Consequences