srhinow/contao-page-images-bundle

Set one or more images central per page in Contao CMS. This is a Fork from 'Ruudt/contao-page_images' and updated for >=Contao 5.3 and >=PHP 8.3

3.0.0 2026-04-25 20:52 UTC

Requires

• php: ^8.3
• contao/core-bundle: ^5.3

GPL-3.0-or-later

• Ruud Walraven
• Sven Rhinow

• image
• contao
• pageimage
• backend modul

README

Assign one or more images to pages in Contao CMS. Images are inherited by subpages unless explicitly disabled.

This is a fork of Ruudt/contao-page_images, rewritten for Contao 5.3+ and PHP 8.3+.

Requirements

• PHP ^8.3
• Contao ^5.3

Installation

composer require srhinow/contao-page-images-bundle

After installation run php bin/console contao:migrate to set up the database tables.

Architecture

Database tables

Table	Purpose
tl_pageimages	Image categories (each defines a "slot" in the layout, with a default image and size settings)
tl_pageimages_items	Assignments of images to specific pages
tl_pageimages_pages	Junction table — stores which pages each item applies to

Backend module

Located under Content → Page images in the Contao back end.

1. Create a category (tl_pageimages) — give it a name and configure the default image size and a fallback image.
2. Add items (tl_pageimages_items) — select images and assign them to one or more pages. Optionally add a text overlay and control subpage inheritance.

Frontend module

Module type: Page images (page_images).

Field	Description
Page image category	Which category to display
Page image template	Template to use for rendering (pageimages_*)
Number of images	1 = first, 0 = all, random = random single, N = first N

Image resolution / inheritance

When the module renders for a page, PageImagesService walks up the page tree:

1. Look for an item assigned directly to the current page.
2. If none, walk up to the parent page (unless an item has Prevent inheritance enabled).
3. If nothing is found anywhere in the tree, use the category's default image.

Templates

Template	Description
mod_page_images.html.twig	Outer module wrapper — renders pageimage if has_pageimage is true
pageimages_default.html.twig	Renders the images with optional text overlay; uses contao_figure()

Custom templates must be placed in templates/ and must start with pageimages_.

Hooks

The compilePageImages hook fires after images are resolved:

$GLOBALS['TL_HOOKS']['compilePageImages'][] = [MyClass::class, 'myMethod'];

Signature: myMethod(Template $template, array $pageImages, ModuleModel $model): void

User permissions

Two permission keys are registered for back-end users and groups:

Key	Description
pageimages_categories	Which categories the user may access
pageimages_categoriesp	Operations allowed: create, delete

Running tests

Tests must be run from the main Contao installation:

vendor/bin/phpunit -c vendor/srhinow/contao-page-images-bundle/phpunit.xml.dist