masilia / ibexa-blocks
Front-office rendering of pages made of blocks for Ibexa DXP: a content model for templates, field renderers, themes that extend each other, and the pieces every theme shares
Package info
github.com/MasiliaLabs/ibexa-blocks
Type:ibexa-bundle
pkg:composer/masilia/ibexa-blocks
Requires
- php: >=8.3
- ibexa/core: ^5.0
- psr/container: ^1.1 || ^2.0
- psr/log: ^3.0
- symfony/config: ^7.4
- symfony/console: ^7.4
- symfony/dependency-injection: ^7.4
- symfony/http-foundation: ^7.4
- symfony/http-kernel: ^7.4
- symfony/routing: ^7.4
- symfony/yaml: ^7.4
- twig/twig: ^3.0
Requires (Dev)
- masilia/ibexa-sites: ^0.2
- phpunit/phpunit: ^11.5
- symfony/form: ^7.4
- symfony/mailer: ^7.4
- symfony/mime: ^7.4
- symfony/validator: ^7.4
Suggests
- doctrine/doctrine-migrations-bundle: The migration of the newsletter table
- doctrine/orm: The newsletter subscribers (masilia_ibexa_blocks.newsletter)
- gregwar/captcha-bundle: A captcha on the contact forms
- ibexa/fieldtype-matrix: Matrix fields
- ibexa/rich-text: Renders rich text fields
- masilia/editorial-toolbox: In-context editing: the page and its blocks are marked for it
- masilia/ibexa-ai-craft: The assistant builds pages with the blocks of the theme and reads the conventions of this package
- masilia/ibexa-sites: Sets the layout, name, email and address of each site from its registry, and registers the sites that masilia:blocks:site:create makes
- novactive/ezmenumanagerbundle: Menus managed in the admin (NovactiveMenuProvider)
- symfony/form: Contact forms made from a matrix of questions
- symfony/mailer: Contact forms, form submissions and the newsletter
- symfony/mime: Emails of the contact forms and the newsletter
- symfony/validator: Contact forms made from a matrix of questions
Provides
None
Conflicts
None
Replaces
None
README
Front-office rendering of pages made of blocks for Ibexa: a content model for templates, themes that extend each other, and the pieces every theme shares.
masilia/ibexa-blocks is part of a family of packages for Ibexa that work together or alone. See the other packages.
What it is
The front office of an Ibexa site whose pages are made of blocks. A page holds an ordered list of block contents; each block is rendered by a Twig template named after its content type. This package gives templates what they need — a flat, ready-to-use content model — and the pieces every theme shares, so a theme is assets plus templates and nothing else.
Features
- Themes that extend each other: a theme is a folder of templates (
blocks/<type>.twig,cards/<type>.twig,full/<type>.twig…) and atheme.yaml. What a theme does not write comes from the next theme of the design (Ibexa's design engine chain). - One controller renders every page and block; behaviour that differs by block type is a provider, not an
if. - A content model for templates: each field of a block becomes a Twig variable, with value objects for images (and their variations), files, links, text and coordinates.
- The site around the page: layout configuration, menus, languages switcher and full views.
- The content model: the socle of content types (layout, site, home page, page), the content types of the project, and the creation of a site (tree and registration), by console commands.
- List blocks: automatic items (the latest of a type), featured items and "all posts", driven by configuration.
- Search (
/searchand JSON endpoints) with sorts, facets and popular searches. - Forms by mail: contact forms built from a matrix of questions, mailed to the recipients the block names.
- Newsletter with double opt-in (
/api/subscribe, confirmation and unsubscribe links,app_subscribertable). - Theme tooling:
masilia:blocks:themes,masilia:blocks:theme:check,masilia:blocks:theme:create. - Contracts (
Themes,ShownViews,Subscribers,ListPreview…) for the packages that build on it.
Requirements
- PHP 8.3 or later
- Ibexa 5.0 (Symfony 7.4)
Works better with (optional):
masilia/ibexa-sitessets the layout, name and contact of each site from its registrymasilia/editorial-toolboxin-context editing: pages and blocks are marked for itmasilia/ibexa-ai-craftthe assistant builds pages with your blocks
Installation
composer require masilia/ibexa-blocks
-
Enable the bundle in
config/bundles.php:Masilia\Bundle\IbexaBlocks\MasiliaIbexaBlocksBundle::class => ['all' => true],
-
Import the routes. Load them before Ibexa's own, which has a
/searchof its own (files ofconfig/routes/are read in alphabetical order, so a name that sorts first works, e.g.app_masilia_ibexa_blocks.yaml):masilia_ibexa_blocks: resource: '@MasiliaIbexaBlocksBundle/Resources/config/routing.yaml' masilia_ibexa_blocks_newsletter: # only if you use the newsletter resource: '@MasiliaIbexaBlocksBundle/Resources/config/routing_newsletter.yaml'
-
If you use the newsletter, create its table (
doctrine/ormanddoctrine/doctrine-migrations-bundleare needed for that part):php bin/console doctrine:migrations:migrate
With Symfony Flex
The Masilia recipes do the first steps for you. Add their endpoint once to the composer.json of your project, after the one of Ibexa:
"extra": { "symfony": { "endpoint": [ "https://api.github.com/repos/ibexa/recipes/contents/index.json?ref=flex/main", "https://api.github.com/repos/MasiliaLabs/recipes/contents/index.json?ref=flex/main", "flex://defaults" ] } }
Then composer require masilia/ibexa-blocks enables the bundle and writes config/routes/aa_masilia_ibexa_blocks.yaml (loaded before Ibexa's routes) and config/packages/masilia_ibexa_blocks.yaml. What is left is yours: the content model, a theme and a site (masilia:blocks:*), and the newsletter routes if you use it. The manual steps above and below stay valid.
Configuration
masilia_ibexa_blocks: conventions: page_type: page # the content type of a page blocks_field: blocks # the field of a page that holds its blocks items_field: items # the field of a block that holds its child items items_field_by_type: # block types that call it differently info_cards: cards system: my_site_group: layout_remote_id: my_layout_config # the layout of the site (logo, footer) blocks: flatten_fields: true # each field is a Twig variable lists: auto_items: { types: [grid_cards, slider] } featured: { types: [grid_cards] } all_posts: { types: [all_posts] } search: allowed_content_types: [article, page] default_content_types: [article] forms: content_types: [steps_form] from_address: contact@example.org newsletter: enabled: true from_address: contact@example.org
Every key has a default; the full tree is bin/console config:dump-reference masilia_ibexa_blocks. If you use masilia/ibexa-sites, the layout of each site is read from its registry instead of system:.
A theme
templates/themes/my_site/
theme.yaml
blocks/hero_banner.twig
cards/card_item.twig
full/page.twig
# theme.yaml assets: { directory: assets/themes/my_site, entry: my_site, styles: [fa-icons] } favicons: build/images/my_site/icons fonts: ['https://fonts.googleapis.com/css2?family=Inter&display=swap']
Templates are found by the name of their content type; theme.yaml only needs views: for an exception. php bin/console masilia:blocks:theme:check <design> tells you which block type has no template, and masilia:blocks:themes --json gives your Encore build the entries to compile.
Showing pages and blocks
A template is found by the view type and the name of the content type, in the themes of the design:
| View type | Template | What it shows |
|---|---|---|
blocks |
blocks/<type>.twig |
a block of a page |
block_item |
cards/<type>.twig |
an item of a block (a card, a slide...) |
line |
line/<type>.twig |
a line of a list |
embed |
embed/<type>.twig, then line/<type>.twig |
a content embedded in another |
full |
full/<type>.twig |
a page of its own (a page, an article, an event...) |
The view type is block_item, not cards: cards is only the folder. In a block template, show its items with {{ render_blocks(fields.items, {}, 'block_item') }} (a view type that does not exist shows nothing, without an error).
full is not shown by default: masilia_ibexa_blocks.blocks.view_types is [blocks, block_item, line], so a page falls back to the default content view of Ibexa (a dump of its fields) unless your project routes it. Either add the view types you use:
masilia_ibexa_blocks: blocks: view_types: [blocks, block_item, line, embed, full]
so that full/<type>.twig of your theme shows pages (a type that holds blocks and has no template of its own is shown by the page of the package, @MasiliaIbexaBlocks/full/blocks_page.twig), or write your own content_view rule, which always wins.
Where the block contents live: a block is a content of its own, related from the blocks field of a page (relations follow the id of the content, not its place). By convention the blocks of a page are stored in a folder that is a child of that page, named after it: <page name> Blocks ("Home Blocks", "About Blocks"; the suffix is conventions.blocks_folder_suffix). The tree of a site:
site
├── layout_config
├── media folder
└── home_page
├── Home Blocks the blocks of the home
├── About (page)
│ └── About Blocks the blocks of the page
└── ...
home_page is a container for this. The socle says so; a project that installed it before has to allow the change once: masilia:blocks:model:install --allow-container (a type is never changed otherwise). site:init and site:create make the home folder; masilia/ibexa-ai-craft and masilia/editorial-toolbox make a page's folder when they create its first block, and find it by its remote id (the page's remote id and _blocks), so renaming a page changes nothing. The folders of blocks are storage, not pages: their full view answers 404 (a content_view rule of the project still wins). Blocks that exist elsewhere are not moved.
A standalone theme (theme:create --standalone) has no theme below it: it writes stubs for layout/header.twig and layout/footer.twig and sets layout: { notifications: false } in its theme.yaml (remove that line once you add layout/parts/notification.html.twig). --extends=<theme> needs an existing theme with a theme.yaml: standard is only one when your project (or a package that brings the standard design) has it, so on a fresh project start with --standalone.
Content model, themes and sites
Content types are global: Ibexa has one set of types for the whole repository, not one per siteaccess. So the types (blocks, block items, your own content such as articles or events) are defined once, at the level of the project, and shared by all its sites; a theme only brings templates and assets. A library of blocks and a standard design are meant to come as a separate package; this package is the engine.
1. The content model
The package ships the socle:
| Content type | Group | What it is |
|---|---|---|
layout_config |
Configurations | The layout of a site: logo, menus, social links, newsletter, footer |
site |
Configurations | The container of a site: title, domain, description, analytics, maintenance |
home_page |
Content | The home page: a title and its blocks |
page |
Content | A page: a title, a description, its blocks and SEO fields |
Your blocks and content go in config/content_model/*.yaml, one file per type:
identifier: hero_banner group: Blocks # the group of the blocks (conventions.block_group): a block allowed_on: [home_page] # where it can be placed: the types whose blocks field accepts it (page, home_page, both...) names: { eng-GB: Hero banner } name_pattern: '<title>' fields: - { identifier: title, type: ibexa_string, name: Title, required: true, position: 10 } - { identifier: image, type: ibexa_image, name: Image, translatable: false, position: 30 }
Fields take type (an Ibexa field type identifier), name, description, required, searchable, translatable, category, position, settings and validator. A type of another group (Content...) is content of your own, shown by full/<type>.twig and line/<type>.twig. More directories can be listed in masilia_ibexa_blocks.model.directories (a package adds its own by prepending that setting).
php bin/console masilia:blocks:model:install --dry-run # what would be created php bin/console masilia:blocks:model:install # create it php bin/console masilia:blocks:model:sync-blocks # an existing project: place the blocks where they say they go
The command is safe to run again: it creates what is missing and adds the missing fields; it never changes or removes a type or a field that exists, and says so when a field differs from the definition. Field types that are not installed are skipped with a note: the metas field of page and home_page is a Nova SEO field (novaseometas), so without that bundle you read field "metas" skipped: the field type "novaseometas" is not installed, which is expected. Some blocks are meant for the home page, others for the pages, others for both: a block says where it goes with allowed_on, and when the blocks field of that type restricts the types it accepts, the block is added to it. A block that says nothing is left where it is, and a type that does not restrict its blocks field accepts them all. Nothing is ever taken off a list. The names follow the conventions (page_type, home_type, blocks_field, block_group...).
2. A theme per site
A theme is assets plus templates, standalone or inherited through the design engine of Ibexa:
php bin/console masilia:blocks:theme:create acme --extends=standard # only what differs from standard (an existing theme with a theme.yaml) php bin/console masilia:blocks:theme:create solo --standalone # all its templates and styles
Declare it in a design yourself (the list of designs stays yours), for instance ibexa_design_engine.design_list.acme: [acme, standard], write the templates named after the content types (blocks/<type>.twig, cards/, line/, full/), and check it:
php bin/console masilia:blocks:theme:check acme # missing templates, assets, dead files, a theme in no design
3. A site
php bin/console masilia:blocks:site:create "Acme" --domain=acme.example.org --design=acme --language=eng-GB [--admin-host=admin.acme.example.org]
It creates the content tree (container, layout, home page, media folder: site:init does that part alone) and, when masilia/ibexa-sites is installed, registers the site as a draft (root = the home page, the layout, the design, a siteaccess per language, and with --admin-host an admin siteaccess admin_<site> on that host). The registry is asked first: a site it refuses (unknown design, a host already taken...) writes no content. Without ibexa-sites it prints the siteaccess configuration to adapt. It never activates a site, since that serves its hosts: do it from the admin or with masilia:sites:set-status <id> active.
Tests
composer install vendor/bin/phpunit
AI agent skill
This package ships a skill for AI coding agents (Claude Code and other agents that read SKILL.md skills): how to install, configure, operate and troubleshoot masilia/ibexa-blocks. It lives in skills/masilia-ibexa-blocks and comes with the package.
# For the project (committed with it): from the installed package mkdir -p .claude/skills && cp -r vendor/masilia/ibexa-blocks/skills/masilia-ibexa-blocks .claude/skills/ # For all your projects: global mkdir -p ~/.claude/skills && cp -r vendor/masilia/ibexa-blocks/skills/masilia-ibexa-blocks ~/.claude/skills/
Restart the agent (or reload its skills) to pick it up. Update the copy after composer update.
The Masilia packages
| Package | What it does |
|---|---|
masilia/ibexa-admin-kit |
React components in the design of the Ibexa admin, for admin pages |
masilia/ibexa-sites |
A registry of sites that Ibexa serves without a deploy |
masilia/ibexa-ai |
The AI assistant for Ibexa: capabilities, providers, chat, approval flow |
masilia/ibexa-ai-craft |
The assistant builds sites and pages out of blocks |
masilia/ibexa-ai-editor |
AI suggestions and image generation in the content editing form |
masilia/ibexa-blocks |
Front-office rendering of pages made of blocks, with themes |
masilia/editorial-toolbox |
In-context editing toolbar for the front office |
What requires what (Composer installs it for you):
ibexa-sitesrequiresibexa-admin-kitibexa-airequiresibexa-admin-kitibexa-ai-editorrequiresibexa-aiibexa-ai-craftrequiresibexa-ai,ibexa-blocksandibexa-sitesibexa-blocksandeditorial-toolboxrequire none of the others; they are happy to findibexa-sites(and each other) when installed.
Compatibility
| Package version | PHP | Ibexa |
|---|---|---|
latest |
8.3+ | 5.0 |
Download
- Composer (recommended):
composer require masilia/ibexa-blocks— ibexa-blocks on Packagist - Archive of a release: GitHub releases (each release lists what changed)
- Source:
git clone https://github.com/MasiliaLabs/ibexa-blocks.git - What changed between versions: CHANGELOG.md
Support, contributing and security
- Questions and bug reports: GitHub issues
- Pull requests are welcome, see CONTRIBUTING.md
- Security problems: please follow SECURITY.md and do not open a public issue
License
Released under the MIT license. Copyright © 2026 MasiliaLabs.
Ibexa itself is distributed under its own licenses (Ibexa OSS: GPL-2.0), which apply to the project that uses this package. This package is an independent project, not affiliated with or endorsed by Ibexa AS; "Ibexa" is a trademark of its owner.