Search by

uxf / page-builder

uxf

UXF Page Builder - CMS page/section versioning system

Package info

gitlab.com/uxf/page-builder

Issues

Type:symfony-bundle

pkg:composer/uxf/page-builder

Statistics

Installs: 30

Dependents: 0

Suggesters: 0

Stars: 0

3.90.0 2026-11-18 14:39 UTC

This package is auto-updated.

Last update: 2026-11-18 13:48:04 UTC


README

Symfony bundle for pages built from sections: pages and their revisions, sections and shared sections, publishing and scheduled publishing, previews, the REST API for the backoffice editors and the public read API.

The bundle holds no section types. The project defines them (request class with #[SectionField] attributes, a SectionContentMapper and a response) and registers its layouts, groups and languages in a registry JSON.

Frontend counterparts: @uxf/page-builder (contract), @uxf/page-builder-cms (backoffice editors) and @uxf/page-builder-web (renderer, editor iframe, previews).

Install in a project

composer require uxf/page-builder

The bundle needs uxf/core, uxf/datagrid, symfony/security-bundle and a Symfony security setup that resolves Symfony\Component\Security\Core\User\UserInterface to a concrete user entity (e.g. via uxf/security or uxf/cms).

Setup

Register the bundle in config/bundles.php:

UXF\PageBuilder\UXFPageBuilderBundle::class => ['all' => true],

Import its routes in config/routes.php:

$routingConfigurator->import('@UXFPageBuilderBundle/config/routes.php');

The routes are /api/cms/page-builder/* (editors) and /api/app/page-builder/* (public read API). The editors' routes (the bundle's Controller\Admin controllers, under whatever path the project mounts them) need the editor_role (default ROLE_ADMIN) on top of the project's access_control; keep the project's ^/api/cms rule too.

Configuration

$containerConfigurator->extension('uxf_page_builder', [
    // role allowed to publish, unpublish and archive; other admins edit drafts only
    'publisher_role' => 'ROLE_ROOT',
    // role every editors' route needs; null turns the bundle's check off
    'editor_role' => 'ROLE_ADMIN',
    // the project's registry JSON (layouts, groups, section types, languages), the one source of it;
    // null = nothing is restricted
    'registry' => '%kernel.project_dir%/config/page-builder/registry.json',
    // `uxf:page-builder:schema-gen` writes section-schemas.json and registry.json into each directory
    'gen' => [
        'destinations' => [
            '%kernel.project_dir%/../web/src/generated/page-builder-schema',
            '%kernel.project_dir%/../backoffice/src/generated/page-builder-schema',
        ],
    ],
    // where `uxf:page-builder:make-section` creates a new section type (these are the defaults)
    'make_section' => [
        'directory' => '%kernel.project_dir%/src/PageBuilderZone/SectionContent',
        'namespace' => 'App\PageBuilderZone\SectionContent',
    ],
]);

Add the bundle sources to the hydrator map sources, so the section requests and the bundle DTOs share one map:

$containerConfigurator->extension('uxf_hydrator', [
    'map_sources' => [
        __DIR__ . '/../../src',
        __DIR__ . '/../../vendor/uxf/page-builder/src',
    ],
]);

Database

The bundle ships no migrations. Generate them in the project after installing or upgrading the bundle:

bin/console doctrine:migrations:diff
bin/console doctrine:migrations:migrate

Generated clients

The backoffice client comes from the project's uxf_gen hook area. Include the page builder paths in its pattern:

'hook' => [
    'areas' => [
        'admin' => [
            'path_pattern' => '/^\/api\/(app\/page-builder|admin|cms)/',
            'output' => 'swr',
            'destination' => '%kernel.project_dir%/../backoffice/src/generated/api.ts',
        ],
    ],
],

The web's types of the section outputs come from a second area with only the render endpoint (output: empty): its union of the public outputs (PageBuilderSectionContentPublicOutput) types the web's section components.

bin/console uxf:page-builder:schema-gen (in the project's make gen, next to uxf:grid-gen and uxf:form-gen) writes the section schemas (section-schemas.json, from the section requests) and the registry (registry.json) into each gen.destinations directory. Like the grid and form schemas, the apps generate their TypeScript from them: uxf-page-builder-generator of @uxf/page-builder writes registry.ts (registry, ProjectSectionType) and section-schemas.ts (sectionSchemas), run from the apps' yarn gen. The registry JSON stays in api/ (the API reads it, and its image is built from api/ alone); nothing has to copy it into the apps.

The registry is read and checked during cache:warmup: a missing or broken file fails the deploy, not the first request.

Section types

bin/console uxf:page-builder:make-section quote --label=Citace creates the request, the response, the public response and the mapper of a type with one translatable title, all keyed by the type, and prints its registry entry with an example in every language. Then add the type to the registry and to the groups that take it, add its fields, run make gen and write the web component.

The type string is the key everywhere: #[HydratorMapKey] on the three DTOs, their $type default, #[AsTaggedItem(index:)] on the mapper, the registry key and its example.type. Stored content is never migrated: mapToOutput gives a field added later a default.

Section fields

Each constructor parameter of a section request carries #[SectionField]; its PHP type and the attribute make the field of the schema (form, API validation, generated types). The input is inferred unless input: names one:

PHP typeInputValue
string, ?string, a value object (Email, DateTimeImmutable)text (or textarea, url, wysiwyg, image explicitly)a string
any type but array + options: (a string, a backed enum)selectan option value
boolcheckboxa boolean
int, floatnumber (min:, max:; int allows whole numbers only)a number
array + options:multi-selecta list of option values
array + input: SectionInput::TEXT_LISTtext-lista list of strings
a class with #[SectionField] constructor parametersgroup: those fields, once (required and the item counts belong to the fields)an object
array + itemClass:items: the item class's fields in each item (minItems:, maxItems:, required: = at least one)a list of objects
Mapthe input of the value, translatable: one value per languagean object by language

A group or items field is never translatable itself; its fields are, one by one, so the items keep one order and count in every language. It may hold one more group or items, which holds plain fields only. Annotate the list for the hydrator (@param list<FaqItem> $items). SELECT and MULTI_SELECT only accept the values of options. A url takes https://…, http://…, a path /… or an anchor #….

The parameter's default is the value of a new section (int $count = 3, string $variant = 'light', an enum case). A translatable field cannot have one (a Map is not a constant expression); ?Map $subtitle = null makes it optional, so the API also accepts a request without it, e.g. from a form made before the field was added.

visibleWhen and requiredWhen read a sibling: a section field, a field of the same group or of the same item. The requiredWhen of a translatable field may read a translatable sibling and then holds in each language apart: #[SectionField('Odpověď', requiredWhen: new FieldNotEmpty('question'))] requires the answer in the languages that have the question.

Page URLs

A page has a URL in each language (the jsonb column urls of the revision, looked up with JSONB_CONTAINS), so it can be /o-nas in Czech and /about-us in English. A URL is unique among pages within its language; the same path may lead to different pages in different languages. The language prefix of the web (/en/…) is the project's routing, not part of the URL.

A new page needs one URL (usually in the default language); the others can wait. Publishing needs a URL in every language of the registry the page is not hidden in. A duplicated page, a restored revision and an unarchived page get <url>-2, <url>-3, … in each language where another page has taken the URL meanwhile.

Public read API

RouteAnswer
GET /api/app/page-builder/public/page-by-url?url=/o-nas&lang=csthe page published at the URL in the language (a relative URL, UrlRelative), for the web's catch-all route
GET /api/app/page-builder/public/page/{page}?lang=csthe same by the page's id
GET /api/app/page-builder/public/preview/{token}?lang=csa revision shared through a time-limited link

The page answer carries the page's id, layout (the registry layout the web arranges the sections by), url (in the language), alternates (the page's URL in every language it is served in, for hreflang and the language switcher), the meta data in the language, noIndex and the sections with their public output. A URL without a published page in the language, a language outside the registry and a page hidden in the language answer 404.

Shared contract

test-cases/ holds the files the npm packages share: section-validation.json (the section validation cases both sides run) and api-routes.json (the routes the packages call, checked against the bundle's router by ApiRoutesContractTest). Change them together with @uxf/page-builder in fe-monorepo.

Scheduled publishing

bin/console uxf:page-builder:publish-scheduled publishes approved page and shared section revisions whose scheduled time has passed. It carries #[CronJob('* * * * *')] (uxf/cms), an optional integration: when uxf/cms is installed, it lands in the project's crontab once the bundle sources are among the cron sources:

$containerConfigurator->extension('uxf_cms', [
    'cron' => [
        'sources' => [__DIR__ . '/../../src', __DIR__ . '/../../vendor/uxf/page-builder/src'],
        'destinations' => [__DIR__ . '/../../crontab'],
    ],
]);

Then run bin/console uxf:cron-gen and run the crontab with supercronic. The command takes a lock (symfony/lock), so overlapping runs skip.

Without uxf/cms, add the command to the project's crontab by hand instead:

* * * * * bin/console uxf:page-builder:publish-scheduled

License

MIT