Design: Improve / Rewrite the ToArray conversion 

3.1 Core Record API (since 13.0, enhanced 13.3) 

RecordFactory::createResolvedRecordFromDatabaseRow() already converts raw DB rows into rich objects (Feature #103581, "Automatically transform TCA field values for record objects"):

• relations → Record, LazyRecordCollection, FileReference, LazyFileReferenceCollection, Folder, LazyFolderCollection
• datetime → DateTimeImmutable
• link → TypolinkParameter
• flex → FlexFormFieldValues
• json → array

Insight: We already feed Record objects into our converter. The Record API does the object resolution — our job is only the array shaping. Nothing to gain from replacing this part; it is the right input.

3.2 Core Schema API (since 13.0!) — the important one 

TYPO3CMSCoreSchema* is the Core-native replacement for the ContentBlocks definitions we use:

Key finding: The Schema API exists in both TYPO3 13 and 14. A rewrite based on it does not need a "v13 legacy / v14 only" split! The property_exists() version hacks exist only because we construct ContentBlocks internals — if we stop doing that, the hacks disappear.

3.3 Core PSR-14 events in the Record pipeline 

• RecordCreationEvent — fired when a Record is created from a row. Tempting, but rejected as main mechanism: modifications there affect every consumer of the Record API (Fluid templates, other processors), not only the headless JSON output. Side effects we do not want.

3.4 TYPO3 14 specifics worth using 

• lib.parseFunc / lib.parseFunc_RTE are always provided by ext:frontend (since 13.2, default removed from fluid_styled_content in 14 — Breaking-107438). Our richtext path can rely on them being present.
• System Resource API (Feature-107537) — URL generation, not needed for FileReference public URLs, but relevant if we ever support EXT: resources.
• No breaking changes in Schema/Record API that affect this rewrite.

3.5 What we still need ContentBlocks for 

Two things have no Core equivalent:

1. Identifier mapping: ContentBlocks maps DB column tx_ext_my_field → Content Block field identifier my_field. Core TCA only knows the column name. Dropping this would change every consumer's JSON contract (breaking).

   1. headless.php: resolving the Content Block folder via ContentBlockRegistry::getContentBlockExtPath().

→ ContentBlocks stays a dependency, but only behind two narrow interfaces.

3.6 Real-world usage analysis (cms-netzbewegung-v5-2025, production site) 

Investigated the example project (/var/www/vhosts/cms-netzbewegung-v5-2025) and its JSON response (https://cms.netzbewegung-v5-2025.local/de/).

Setup:

• TYPO3 13.4.32, content-blocks 1.6.1, headless 4.7.3, b13/container 3.1.12 → the main consumer is on v13. Confirms V2 (unified 13/14); a v14-only rewrite would not serve production.
• Wiring lives in nb_frontend_api (TypoScript set): dataProcessing chains per block, nb-container-json for container columns (colPos 201/202 → left/right), extbase plugins as USER_INT (separate path).
• JSON wrapper {"id":…,"type":"netzbewegung_headline","colPos":0,"data":{…}} is built by nb_frontend_api/headless around our processor output.

headless.php reality check: 13 headless.php files exist, all 13 do the same thing: generate responsive image variants (mobile, mobile2x, desktop, desktop2x, … webp, widths like 883c) via a static ThumbnailUtility (which internally abuses the Fluid ImageViewHelper!). Per block, per mode — dozens of hardcoded width configs.

→ Strongest finding for the rewrite: built-in, declarative image processing on File/FileReference fields would eliminate  all headless.php files. ext:headless FileUtility + ProcessingConfiguration already implements exactly this (TypoScript-style strings like width=883c,fileExtension=webp).

Contracts confirmed in production JSON (must not break):

• Link fields: url, target, type, title, config, attr (+ null for empty links) — our TypolinkParameterToArray output
• FileReference: id, alt, title, publicUrl (+ thumbnails added per block in headless.php)
• Collections (items, buttons) with prefixField: false identifiers
• Basics includes (Netzbewegung/Appearance), useExistingField (space_after_class), custom collection tables (tx_nb_buttons), prefixType: full → tx_nb_* columns
• Alphabetically sorted keys in data (our ksort — consumers see it)
• richtext bodytext rendered with custom parseFunc classes (p-text …)
• processAdditionalDataProcessors is actively used (nb-job-cards-dynamic etc. via TypoScript dataProcessing.20 { as = cards })

3.7 How others do "object → array/JSON" 

Option A — Normalizer registry (Symfony-Serializer-style, hand-rolled) ★ recommended 

RecordNormalizer (entry, uses RecordFactory output)
 └─ NormalizerChain::normalize($value, Context)
     iterates registered Normalizers, first `supports()` wins

Normalizers (one per type, DI-registered, tagged):
  ScalarNormalizer            null/int/string/float/array-plain
  DateTimeNormalizer          → W3C (configurable format)
  RecordNormalizer            → recursion + system-field stripping + key mapping
  FileReferenceNormalizer     → crop/processing + publicUrl (reuses ext:headless FileUtility?)
  FileReferenceCollectionNormalizer
  FolderCollectionNormalizer
  RecordCollectionNormalizer  → per item, resolves target schema via ActiveRelation
  CategoryCollectionNormalizer
  FlexFormNormalizer
  TypolinkNormalizer
  UnknownTypeNormalizer       → explicit: log + null (no silent drops)

• Field-level shaping (password blanking, richtext parseFunc) becomes a separate FieldValueTransformer phase driven by Schema field type + config — no longer mixed into the type dispatch.
• ContentBlocksIdentifierMapper + HeadlessPhpProcessor behind interfaces.
• Normalizers get real DI (no makeInstance).

Pros: testable units, open for site-packages to register own normalizers (the actual headless use case), no version hacks. Cons: more classes ( 12), slight indirection.

Option B — Schema-driven single converter 

One SchemaArrayConverter service: walks Record->toArray(), asks TcaSchema for each field's TableColumnType + configuration and converts in one (still large) method. Replaces instanceof chains with the enum, but stays monolithic and hard to extend by third parties.

Pros: compact. Cons: extensibility only via events; the switch survives.

Option C — Hook into Core RecordCreationEvent 

Modify values at Record creation so Record->toArray() is already JSON-ready.

Pros: least own code. Cons: global side effects on all Record consumers, no per-response shaping. Rejected.

Option D — JsonSerializable value wrappers 

Wrap rich objects in lazy JsonSerializable adapters; json_encode triggers conversion.

Pros: elegant. Cons: key mapping/k_sort/strip/events fight the pattern; hard stack traces. Rejected.

Cross-cutting decision — ContentBlocks usage 

Version strategy 

headless.yaml sketch (decision 2 + 6) 

# ContentBlocks/ContentElements/image/headless.yaml
fields:
  image:
    processing:
      mobile:     "width=883c,fileExtension=webp"
      mobile2x:   "width=1766c,fileExtension=webp"
      desktop:    "width=1564c,fileExtension=webp"
      desktop2x:  "width=3128c,fileExtension=webp"

# per-site override (nb_frontend_api / site package)
tt_content.netzbewegung_image.fields.data.dataProcessing.10 {
    options {
        processing {
            image {
                desktop = width=1600c,fileExtension=webp
            }
        }
    }
}

Processing strings reuse the ext:headless FileUtility/ProcessingConfiguration syntax, so output URLs match what headless consumers already get from FilesProcessor etc.