Download the PHP package web-systems/gutenberg-bundle without Composer

GutenbergBundle

The WordPress block editor (Gutenberg) as a Symfony form field.

Add one field to a form and editors get the real block editor — the upstream @wordpress/block-editor packages, not a re-implementation. Content is stored as ordinary block markup, rendered on the front end with one Twig call, and extended with custom blocks that are written entirely in PHP.

Why block markup

The field's value is the same string WordPress stores: HTML annotated with block delimiters.

Static blocks carry their own markup, so rendering them costs nothing on the server. Dynamic blocks store attributes only and are rendered by PHP at request time. Content stays portable: it can be moved to or from WordPress unchanged.

Installation

Register the bundle (Flex does this for you) and import the routes it needs for server-side previews, media and translations:

Publish the editor assets:

If Doctrine is installed, register the bundle's migrations and run them — they create the revision and reusable-block tables:

The bundle works without Doctrine too; revisions and reusable blocks are then simply absent.

Using the field

Plain Symfony forms

The field is a TextareaType underneath: the value stays a plain string, validation and persistence work as usual, and the form degrades to a textarea when JavaScript is unavailable. The editor bundle is attached automatically, so a hand-written admin panel needs no extra work.

EasyAdmin

The field attaches its own CSS and JS, so configureAssets() stays untouched. Register the form theme in the CRUD controller so the widget is picked up:

Rendering on the front end

In PHP, depend on ContentRendererInterface:

Custom blocks

A custom block is one PHP class and one Twig template. There is no JavaScript to write and no asset to rebuild: the editor reads the field schema at runtime and generates the inspector panel, while the canvas shows the real server-rendered output.

Available field types: text, textarea, richText, html, number, range, toggle, select, color, image, url. Pass inContent: true to edit a field directly on the canvas instead of in the sidebar.

The icon argument takes a name from @wordpress/icons in camelCase or kebab-case (listView, list-view), one of the common Dashicon slugs, which are mapped to their SVG equivalents, or raw <svg> markup. Bare Dashicon slugs alone would render nothing: Dashicons are a font shipped with WordPress core, not with any npm package, so an unmapped name falls back to the default block icon rather than to an empty space.

Blocks are ordinary services, so they may inject anything:

Set innerBlocks: true on #[AsBlock] to let editors nest other blocks inside; the rendered children arrive in the template as inner.

Inspect what is registered:

Theme colours and typography

The editor has no theme of its own: the palette, the gradients and the font sizes it offers all come from configuration, and reach both the core blocks and the controls of your own blocks.

Colours land in the editor as a theme palette (__experimentalFeatures.color.palette.theme), which is what the Colour panel of core blocks and the color() field of custom blocks both read.

Picking a preset does not write the value into the markup — Gutenberg writes a class:

The bundle therefore generates the stylesheet that gives those classes meaning, the same custom properties and !important preset rules WordPress builds from theme.json. It is emitted by gutenberg_front_assets() and injected into the editor canvas, so a colour chosen while editing is the colour a visitor sees. Set preset_styles: false if your own stylesheet already defines has-*-color, has-*-background-color, has-*-border-color, has-*-gradient-background and has-*-font-size. WordPress' own default palette is deliberately absent — it lives in the theme.json that a WordPress install provides and this bundle does not — so what you configure is exactly what editors see. Set custom_colors: false to remove the free colour picker and keep documents on brand.

Reusable blocks

A reusable block is a fragment saved once and referenced from many documents; editing it updates every page that uses it. It is stored the way WordPress stores a synced pattern, so the markup travels between the two systems unchanged:

Creating one from the editor

Select the blocks to reuse, open the block's Options menu (⋮) and choose Create pattern. The selection is saved under the name you give it and replaced in place by a reference, so the document ends up holding <!-- wp:block {"ref":N} /--> and the new block is immediately available in the inserter.

Managing them

With Doctrine and EasyAdmin installed the bundle registers a management screen at /admin/reusable-block automatically. Saved blocks appear in the editor's inserter under their own category, each by name, and the canvas previews them server-side.

Turn the built-in screen off when your application ships its own — EasyAdmin refuses two CRUD controllers that share a short class name:

Applications without EasyAdmin drive ReusableBlockRepository from their own panel; the entity is WebSystems\GutenbergBundle\Entity\ReusableBlock with a title, a slug and content. References resolve by numeric id or by slug, and a block that references itself, directly or through another one, is stopped by the render-depth guard rather than looping.

Interface language

The editor ships in English and is translated with the official WordPress.org language packs.

Block titles, descriptions and category names are translated as well: their source is block.json, which WordPress translates while building its registry, so the bundle passes them through the catalogue as each block registers.

The catalogue is written to var/gutenberg/translations/ and served to the editor over a cacheable endpoint. The locale defaults to %kernel.default_locale%; set web_systems_gutenberg.editor.locale to override it. Right-to-left locales are detected automatically, but you must point assets.editor_styles at editor-rtl.css yourself.

Keeping the editor up to date

The editor is built from published @wordpress/* packages.

Rebuilding requires Node.js and is only needed by whoever maintains the package; installing the bundle from Packagist ships the built assets.

Extension points

Every part of the pipeline is an interface with a tagged implementation, so behaviour is added by registering a service rather than by patching the bundle.

Configuration reference

Security

The endpoints under the imported prefix (/_gutenberg by convention) render blocks, list and accept media, and expose the editor configuration. Put them behind your firewall:

Setting web_systems_gutenberg.security.access_role adds a second check inside the bundle, for defence in depth or for applications that do not use access_control.

Block content is trusted HTML, exactly as in WordPress: whoever can use the editor can emit markup. Restrict the editor to trusted roles, or narrow editor.allowed_blocks.

License

MIT.