Extension points

What an application implements, replaces or relies on. Every port has a Doctrine adapter registered when the kernel has DoctrineBundle; without it, the application provides the six persistence ports itself, by aliasing each interface to its own service.

Persistence ports

DimensionContentRepository

Phil\ContentBundle\Domain\Repository\DimensionContentRepository — loads and stores the rows of a root. Doctrine adapter: DoctrineDimensionContentRepository.

Invariants an adapter keeps:

• one row per (root, stage, version, locale or none); a second row of the same dimension is refused by the store (a unique constraint), never silently kept;
• a row removed and a row of the same dimension added are written in that order when ContentTransaction::flush() is called between them;
• find() and findAll() see the rows added and removed in the running transaction once it has flushed.

RouteRepository

Phil\ContentBundle\Domain\Repository\RouteRepository — Doctrine adapter: DoctrineRouteRepository.

Invariant: at most one route per (resource key, locale, slug), and at most one current route per root and locale (the second is kept by RouteUpdater, which retires the previous current route).

ContentRootRepository

Phil\ContentBundle\Domain\Repository\ContentRootRepository — Doctrine adapter: DoctrineContentRootRepository.

Invariant: find($this->referenceOf($root)) returns $root.

PublishedRowRepository

Phil\ContentBundle\Domain\Repository\PublishedRowRepository — reads the published rows of a kind in a few queries, whatever the number of roots: what the sitemap, the feeds and an application's lists read. Doctrine adapter: DoctrinePublishedRowRepository.

A PublishedRowQuery names the resource key and the locale, then:

The Doctrine adapter reads a page in two queries: the localized rows with their roots (the highest version by a correlated MAX over the (root_id, stage) prefix of the unique index), then the shared rows of those roots in one IN list, the roots' identifiers bound as their own DBAL type stores them.

ContentTransaction

Phil\ContentBundle\Application\Persistence\ContentTransaction — Doctrine adapter: DoctrineContentTransaction.

Invariant: all of an operation or nothing is kept.

ContentRootFactory

Phil\ContentBundle\Application\Content\ContentRootFactory — Doctrine adapter: ConstructorContentRootFactory, which calls the root's constructor without arguments.

An application whose roots take constructor arguments aliases this interface to its own factory:

namespace App\Content;

use Phil\ContentBundle\Application\Content\ContentRootFactory;
use Phil\ContentBundle\Domain\Content\ContentRoot;
use Symfony\Component\DependencyInjection\Attribute\AsAlias;

#[AsAlias(ContentRootFactory::class)]
final readonly class SiteContentRootFactory implements ContentRootFactory
{
    public function __construct(private CurrentSite $site)
    {
    }

    public function create(string $resourceKey): ContentRoot
    {
        return match ($resourceKey) {
            'news' => new News($this->site->id()),
            'static_page' => new StaticPage($this->site->id()),
        };
    }
}

An adapter without Doctrine

Without DoctrineBundle, alias the six ports in config/services.yaml:

services:
    Phil\ContentBundle\Domain\Repository\DimensionContentRepository: '@App\Content\Storage\Rows'
    Phil\ContentBundle\Domain\Repository\RouteRepository: '@App\Content\Storage\Routes'
    Phil\ContentBundle\Domain\Repository\ContentRootRepository: '@App\Content\Storage\Roots'
    Phil\ContentBundle\Domain\Repository\PublishedRowRepository: '@App\Content\Storage\PublishedRows'
    Phil\ContentBundle\Application\Persistence\ContentTransaction: '@App\Content\Storage\Transaction'
    Phil\ContentBundle\Application\Content\ContentRootFactory: '@App\Content\Storage\Factory'

The pipeline, the publication services and ContentManager then work over them. The controller, the Twig functions and the console commands are only registered with DoctrineBundle.

Content classes

ContentRoot and DimensionContent

Domain\Content\ContentRoot is all the pipeline needs of a root: createDimensionContent(DimensionKey): DimensionContent, a new, empty row of the application's own row class attached to the root, used as the target of merges and copies so that the result carries the same capabilities. Domain\Content\DimensionContent is a row: root(): ContentRoot and dimension(): DimensionKey.

With the Doctrine adapters, roots extend AbstractContentRoot and rows extend AbstractDimensionContent (storage.md); with adapters of the application, any class implementing the two interfaces works.

Pipeline stages

DataMapper, Merger and Normalizer (Phil\ContentBundle\Application\Pipeline) are tagged by autoconfiguration; their contracts are in pipeline.md. Rules an application stage keeps:

• a data mapper handles one capability, ignores rows that lack it, honours "absent key changes nothing, null clears", and writes keys no other mapper writes;
• a merger copies only what its source sets, and never reads anything but $source and $target; it runs for aggregation and for copies (publication, forks), so a capability without a merger is neither read nor published;
• a normalizer returns an empty array for a row without its capability, and keys no other normalizer returns (ContentNormalizer refuses a repeated key with a LogicException).

An application capability

namespace App\Content\Capability;

interface EventDatesCapable
{
    public function getStartsAt(): ?\DateTimeImmutable;
    public function setStartsAt(?\DateTimeImmutable $startsAt): void;
}

trait EventDatesTrait
{
    private ?\DateTimeImmutable $startsAt = null;

    public function getStartsAt(): ?\DateTimeImmutable { return $this->startsAt; }
    public function setStartsAt(?\DateTimeImmutable $startsAt): void { $this->startsAt = $startsAt; }
}

use Phil\ContentBundle\Application\DataMapper\SubmittedData;
use Phil\ContentBundle\Application\Pipeline\{DataMapper, Merger, Normalizer};
use Phil\ContentBundle\Domain\Content\DimensionContent;
use Phil\ContentBundle\Infrastructure\Doctrine\Mapping\CapabilityMapping;

final class EventDatesCapabilityMapping extends CapabilityMapping
{
    public function capability(): string { return EventDatesCapable::class; }

    protected function fields(): array
    {
        return [['fieldName' => 'startsAt', 'type' => 'datetime_immutable', 'columnName' => 'starts_at', 'nullable' => true]];
    }
}

final readonly class EventDatesDataMapper implements DataMapper
{
    public function map(DimensionContent $unlocalized, DimensionContent $localized, array $data): void
    {
        if ($unlocalized instanceof EventDatesCapable && SubmittedData::has($data, 'startsAt')) {
            $value = SubmittedData::string($data, 'startsAt');
            $unlocalized->setStartsAt(null === $value ? null : new \DateTimeImmutable($value));   // shared by every locale
        }
    }
}

final readonly class EventDatesMerger implements Merger
{
    public function merge(DimensionContent $target, DimensionContent $source): void
    {
        if ($target instanceof EventDatesCapable && $source instanceof EventDatesCapable && null !== $source->getStartsAt()) {
            $target->setStartsAt($source->getStartsAt());
        }
    }
}

final readonly class EventDatesNormalizer implements Normalizer
{
    public function normalize(DimensionContent $content): array
    {
        return $content instanceof EventDatesCapable
            ? ['startsAt' => $content->getStartsAt()?->format(\DATE_RFC3339)]
            : [];
    }
}

With autoconfiguration on, the four services join the bundle's. A field listed by a CapabilityMapping is named after the trait's property; a backed enum property names its class under enumType. A field the row class maps itself is left alone.

Markup ports

MarkupCompiler and HtmlPurifier

Replace either by aliasing the interface to your own service:

namespace App\Content;

use Phil\Markup\HtmlPurifier;
use Phil\Markup\Level;
use Symfony\Component\DependencyInjection\Attribute\AsAlias;
use Symfony\Component\HtmlSanitizer\HtmlSanitizerInterface;

#[AsAlias(HtmlPurifier::class)]
final readonly class StrictPurifier implements HtmlPurifier
{
    public function __construct(private HtmlSanitizerInterface $contentSanitizer)   // a sanitizer of framework.html_sanitizer
    {
    }

    public function purify(string $html, Level $level): string
    {
        return $this->contentSanitizer->sanitize($html);
    }
}

Keep a purifier idempotent — HTML it already purified comes back unchanged — since every body is purified on write and again on read.

BodyConverter

An application that reads more formats, or another level, aliases the port to its own service with #[AsAlias(BodyConverter::class)]. The body it returns is stored as it is: purify its HTML.

ConversionLosses

ContentPublisher refuses a publication whose body loses content, and phil:content:publish and the administration show the losses before publishing (publication.md). Without an implementation, nothing is refused for its losses.

CanonicalAddresses

The page events carry it (publication.md). An application whose pages live on several hosts — a site per tenant — aliases the port to its own service with #[AsAlias(CanonicalAddresses::class)].

PublicationSchedule

An application with its own scheduler implements it, applying publish or unpublish through the phil_content_publication workflow when due (publication.md).

Working copies

WorkingCopyRepository

It writes nothing itself: WorkingCopies and ContentManager::delete() run it inside a ContentTransaction.

Search

ContentDocumentProvider is a DocumentProvider of phil/search-bundle, registered with that bundle. An application that wants other fields decorates it, or writes its own provider for the same live rows and leaves search_index to an index of its own (search.md).

Page events

ContentManager dispatches Phil\Publishing\PagePublished and Phil\Publishing\PageRetired of phil/publishing on the container's event_dispatcher (publication.md). A listener of either follows what readers can see.

RawHtmlPermission

An application that decides by something else than a role — a permission of its own, a voter on the content — aliases the port to its own service with #[AsAlias(RawHtmlPermission::class)]. It answers for the request at work, and holds no state between two requests. RawHtmlAuthorPass wraps whichever service the port names in AuthorRawHtml, so the permission is checked on the author of each revision, a working copy's included, and never on the publisher.

Workflow events

When the container has an event_dispatcher, the workflow named phil_content dispatches the events of symfony/workflow (workflow.phil_content.guard.<transition>, workflow.phil_content.completed.<transition>, …) with the localized draft row as subject. A guard that blocks makes the operation throw TransitionRefused (publication.md).

Service ids, tags and constants

The bundle declares no PHP attribute; the events it dispatches are those of phil/publishing.