The pipeline: data mappers, mergers, normalizers

Three tagged stages read and write the capabilities of a row. Each stage is one service per capability, and a collecting service runs them all.

The bundle tags every service implementing these interfaces by autoconfiguration, and tags its own services the same way, so the application's stages run beside the bundle's. The tag names are the constants PhilContentBundle::DATA_MAPPER_TAG, MERGER_TAG and NORMALIZER_TAG.

submitted data ──DataMapper──▶ draft rows (*, fr) ──Merger──▶ merged row ──Normalizer──▶ array
                                                    (aggregate)

Data mappers

interface DataMapper
{
    /** @param array<string, mixed> $data the submitted values, already validated by the application */
    public function map(DimensionContent $unlocalized, DimensionContent $localized, array $data): void;
}

ContentDataMapper::map($unlocalized, $localized, $data) runs every data mapper over the two draft rows of the dimension being edited. The caller loads or creates the rows and persists them afterwards; ContentEditor does both (publication.md). Each mapper handles one capability, ignores rows that lack it, and decides which of its values are shared and which are per locale. The order of the mappers does not matter, since no two write the same values. A value one mapper refuses stops the whole write before anything is persisted.

Submitted data

The keys are those of the normalized form. An absent key changes nothing; null clears its value, and a string that is empty once trimmed counts as null. That is what lets a form submit only the fields it shows. Strings are trimmed, except bodySource. A value of the wrong type is refused with InvalidContent, naming its key.

There is no data mapper for WorkflowCapable: the place and the publication date are written by the workflow and the publisher, never by submitted data.

SubmittedData holds the readers the data mappers use — has(), string(), untrimmedString(), bool(), stringList(), map() — and an application data mapper may use them to follow the same rules.

Mergers

interface Merger
{
    public function merge(DimensionContent $target, DimensionContent $source): void;
}

ContentAggregator asks the root for a fresh row (createDimensionContent()), then runs every merger over the unlocalized row first and the localized row second, so a value the localized row sets wins over the shared one. Merging never writes onto a stored row. A merger copies only what its source actually sets, and ignores rows that lack its capability.

DimensionContentCopier::copy(DimensionContent $source, DimensionKey $dimension) uses the same mergers to copy a row onto a fresh row of another dimension: publishing copies a draft row to its live twin, forking copies a version to the next. A fresh row has no value, so every capability that has a merger is copied whole; a capability without a merger is not copied, and is not read through the aggregator either.

Normalizers

interface Normalizer
{
    /** @return array<string, mixed> */
    public function normalize(DimensionContent $content): array;
}

ContentNormalizer::normalize($row) runs every normalizer over one merged row and combines their fragments key by key. Two normalizers writing the same key is refused with a LogicException rather than resolved by order: the second would silently hide the first, and which one wins would depend on the order of the services in the container. A normalizer returns an empty array for a row that lacks its capability.

The normalized form

The normalized form is what a template receives as content, what ContentManager::draft() and live() return, and the shape the data mappers read back: a normalized link can be submitted as it is.

Example: reading a draft by hand

use Phil\ContentBundle\Domain\Dimension\{DimensionKey, Stage};
use Phil\LocaleDimensions\{Locale, Version};

$row = $aggregator->aggregate($root, DimensionKey::localized(Locale::fromString('fr'), Stage::Draft, Version::first()));
$data = $normalizer->normalize($row);   // ['excerptTitle' => '…', 'bodyHtml' => '…', …]

ContentManager::draft() and live() do this for you, picking the right version (content-manager.md).