In den vergangenen Modulen haben wir eine komplette Strandkorb-Buchungsstrecke im Frontend aufgebaut. Wenn du nun dem Administrator eine moderne Kommandozentrale bieten willst, ist Contao 5 Backend Custom Routing der wichtigste Baustein für deinen Erfolg. Aktuell sieht der Vermieter nach dem Login nur die Standard-Listenansicht des Data Container Arrays (DCA), die wir in Teil 3 konfiguriert haben.

Das DCA ist fantastisch für standardisierte CRUD-Operationen (Create, Read, Update, Delete) und nimmt uns das Schreiben endloser Formulare ab. Aber: Das DCA ist kein Tool zur Datenvisualisierung. Wenn der Vermieter auf einen Blick wissen will, wie viele Buchungen heute anstehen, wie hoch der monatliche Umsatz ist oder welche Strandkörbe aktuell defekt sind, stößt das DCA an seine architektonischen Grenzen. Die moderne und updatesichere Lösung für dieses Problem lautet: Contao 5 Backend Custom Routing in Kombination mit individuellen Symfony Controllern.

Die Architektur-Evolution: Von BE_MOD zu Symfony Routes

Wenn du aus der Contao 3 oder frühen Contao 4 Welt kommst, kennst du wahrscheinlich noch das Array $GLOBALS['BE_MOD'] in der config.php. Um ein eigenes Modul ins Backend zu bringen, hat man dort eine Callback-Klasse definiert, die ein wildes Gemisch aus HTML und PHP-Logik zurückgegeben hat.

Mit Contao 5.x ändert sich das grundlegend. Contao ist nun eine waschechte Symfony-Applikation. Das Backend ist nicht länger eine abgeschottete Legacy-Insel, sondern wird von demselben mächtigen Routing-System gesteuert wie der Rest der Applikation.

Die 3 Säulen eines modernen Contao 5 Backends:

Der Backend-Controller: Eine ganz normale Symfony Controller-Klasse, die über PHP 8 Attribute (#[Route]) definiert wird. Die Magie passiert über den Scope: Indem wir der Route den Parameter _scope => 'backend' mitgeben, weiß Contao, dass diese Route durch die Backend-Firewall geschützt werden muss (nur eingeloggte Admins/User haben Zugriff) und das Backend-Theme geladen wird.
Das Backend-Twig-Template: Wir schreiben kein HTML mehr per echo in den Code. Wir nutzen Twig. Contao 5 liefert ein Basis-Template (@Contao/backend/layout.html.twig), in das wir uns einklinken können. So sieht unser Dashboard sofort aus wie ein nativer Teil von Contao (inklusive Header, Sidebar und Footer).
Der KnpMenu-Builder: Um unseren neuen Controller in der linken dunklen (oder hellen) Backend-Navigation sichtbar zu machen, nutzen wir einen Event Subscriber. Wir klinken uns in das contao.backend_menu_build Event ein und fügen unseren Menüpunkt programmatisch und typsicher hinzu.

Der Plan für dieses Modul

Wir werden durch gezieltes Contao 5 Backend Custom Routing eine echte Kommandozentrale für unsere Strandkorb-Applikation bauen:

Wir erstellen den DashboardController, der Daten über Doctrine aggregiert (Umsatz, heutige Anreisen).
Wir integrieren die Route nahtlos in das Contao Backend-Menü.
Wir bauen ein modernes Twig-Template, das die Daten ansprechend als Dashboard-Cards visualisiert.
Wir schauen uns an, wie wir Custom Assets (CSS/JS) ins Backend laden, um interaktive Diagramme (z.B. Chart.js) zu rendern.

Architektonische Darstellung des Contao 5 Custom Backend Routings mit Symfony

1. Der Backend Controller: Zentrale für Daten und Logik

In der klassischen Contao-Entwicklung war das Erstellen einer eigenen Backend-Seite oft ein steiniger Weg. Man musste DCA-Dateien (Data Container Array) manipulieren, globale $GLOBALS['BE_MOD'] Arrays anpassen und unübersichtliche Callback-Klassen schreiben, die HTML-Code per echo ausgaben.

Mit Contao 5 Backend Custom Routing lassen wir dieses Legacy-Konzept hinter uns. Wir nutzen exakt dieselben Mechanismen, die Symfony-Entwickler weltweit verwenden: Einen einfachen, sauberen Controller.

Wir erstellen nun unseren DashboardController. Seine Aufgabe: Er soll aus unserer Booking-Tabelle (die wir in Teil 4 erstellt haben) alle anstehenden Buchungen von heute auslesen und den Gesamtumsatz des Monats berechnen. Diese aggregierten Daten übergibt er dann an ein Twig-Template.

Erstelle die Datei /src/BeachsideBundle/src/Controller/Backend/DashboardController.php:

PHP

<?php

namespace Acme\BeachsideBundle\Controller\Backend;

use Acme\BeachsideBundle\Repository\BookingRepository;
use Contao\CoreBundle\Controller\AbstractBackendController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

/**
 * Durch das Attribut #[Route] definieren wir die URL.
 * %contao.backend.route_prefix% wird dynamisch durch '/contao' ersetzt.
 * Der _scope => 'backend' ist der wichtigste Teil für Contao!
 */
#[Route(
    '%contao.backend.route_prefix%/beachside-dashboard', 
    name: 'beachside_backend_dashboard', 
    defaults: ['_scope' => 'backend']
)]
class DashboardController extends AbstractBackendController
{
    public function __construct(
        private readonly BookingRepository $bookingRepository
    ) {
    }

    public function __invoke(): Response
    {
        // 1. Daten über das Doctrine Repository aggregieren
        // (Diese Methoden würden wir im BookingRepository implementieren)
        $todayArrivals = $this->bookingRepository->findArrivalsByDate(new \DateTimeImmutable('today'));
        $monthlyRevenue = $this->bookingRepository->calculateRevenueForMonth(new \DateTimeImmutable('first day of this month'));
        $activeChairsCount = $this->bookingRepository->countActiveRentals();

        // 2. Das Backend-Template rendern und Daten übergeben
        return $this->render('@AcmeBeachside/backend/dashboard.html.twig', [
            'arrivals' => $todayArrivals,
            'revenue'  => $monthlyRevenue,
            'active_chairs' => $activeChairsCount,
            // Optionale Meta-Daten für den Header
            'title'    => 'Strandkorb Dashboard',
        ]);
    }
}

Die Magie hinter dem Code analysieren

Warum ist dieser Ansatz so revolutionär für Contao-Entwickler?

_scope => 'backend': Das ist das absolute Schlüsselelement beim Contao 5 Backend Custom Routing. Symfony kennt standardmäßig keinen Unterschied zwischen Frontend und Backend. Durch diesen Scope-Parameter im Route-Attribut passieren in Contao im Hintergrund drei Dinge vollautomatisch:
- Die Route wird hinter die Backend-Firewall gelegt. Wenn du die URL aufrufst und nicht eingeloggt bist, leitet dich Contao sofort zur /contao/login Maske um.
- Das Backend-Theme (CSS, JavaScript, Icons) wird geladen.
- Der Contao Request-Context wird auf "Backend" gesetzt (wichtig für Insert-Tags oder Spracheinstellungen).
%contao.backend.route_prefix%: Anstatt die Route hart auf /contao/beachside-dashboard zu setzen, nutzen wir diesen Parameter. Das ist eine Best Practice, da Administratoren die Backend-URL aus Sicherheitsgründen in der config/config.yaml ändern können (z.B. auf /admin-login). Unsere Route passt sich automatisch an!
AbstractBackendController: Indem wir von dieser Contao-Core-Klasse erben (anstelle des generischen Symfony AbstractController), stellen wir sicher, dass spezielle Contao-Abhängigkeiten (wie CSRF-Token für Backend-Formulare oder das Backend-User-Objekt) sofort verfügbar sind.

Wir haben jetzt eine funktionierende URL, die von der Contao-Firewall geschützt ist und echte Datenbank-Daten sammelt. Wenn wir die URL (deinedomain.de/contao/beachside-dashboard) jetzt direkt im Browser aufrufen würden, bekämen wir allerdings einen Fehler: Wir haben das Twig-Template noch nicht angelegt, und im linken Backend-Menü fehlt der Button, um das Dashboard überhaupt anzuklicken.

Genau darum kümmern wir uns im nächsten Schritt: Wir bauen unseren Controller tief in die linke Hauptnavigation von Contao ein.

Datenfluss eines Symfony Backend Controllers in Contao mit Scope-Authentifizierung

2. Die Backend-Navigation erweitern (KnpMenu)

In Contao 5 wird das Backend-Menü nicht mehr starr über ein statisches Array aufgebaut, sondern über die mächtige KnpMenuBundle Bibliothek von Symfony generiert. Der große Vorteil: Das Menü wird dynamisch zur Laufzeit erstellt. Das bedeutet, wir können uns über das Event-System von Symfony genau in dem Moment einklinken, in dem Contao den Navigationsbaum aufbaut, und unseren eigenen Menüpunkt (einen sogenannten Node oder Knoten) hinzufügen.

Das Event, auf das wir hören müssen, lautet contao.backend_menu_build.

(H2) 3. Den Event Listener programmieren

Wir erstellen nun eine Klasse, die dieses Event abfängt. Dank der modernen PHP 8 Attribute in Contao 5 brauchen wir dafür keine komplizierte services.yaml Konfiguration mehr. Das Attribut #[AsEventListener] reicht völlig aus.

Erstelle die Datei /src/BeachsideBundle/src/EventListener/BackendMenuSubscriber.php:

PHP

<?php

namespace Acme\BeachsideBundle\EventListener;

use Acme\BeachsideBundle\Controller\Backend\DashboardController;
use Contao\CoreBundle\Event\MenuEvent;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\RequestStack;

// Wir klinken uns in den Aufbau des Backend-Menüs ein.
// Wichtig: Wir setzen die Priorität auf einen negativen Wert (-255),
// damit die Standard-Kategorien (wie 'content') bereits existieren,
// wenn unser Code ausgeführt wird.
#[AsEventListener(event: 'contao.backend_menu_build', priority: -255)]
class BackendMenuSubscriber
{
    public function __construct(
        private readonly RequestStack $requestStack
    ) {
    }

    public function __invoke(MenuEvent $event): void
    {
        // 1. Den Menü-Baum (Tree) und die Factory aus dem Event holen
        $tree = $event->getTree();
        $factory = $event->getFactory();

        // 2. Wir suchen die Kategorie 'content' (Inhalte), um uns dort einzuhängen.
        // Du könntest alternativ auch eine komplett neue Hauptkategorie erstellen.
        $contentNode = $tree->getChild('content');

        if (null === $contentNode) {
            return;
        }

        // 3. Unseren neuen Menüpunkt (Node) generieren
        // Wir verknüpfen ihn direkt mit der Klasse unseres Controllers!
        $node = $factory
            ->createItem('beachside_dashboard', [
                'route' => DashboardController::class,
            ])
            ->setLabel('🏖️ Strandkorb Dashboard')
            ->setLinkAttribute('title', 'Zur Strandkorb Kommandozentrale')
            ->setLinkAttribute('class', 'beachside-dashboard-icon');

        // 4. Den aktiven Status (Current State) berechnen
        // Wir prüfen, ob der aktuelle Request von unserem Controller stammt.
        // Wenn ja, markieren wir den Menüpunkt als 'aktiv' (er wird im Backend hervorgehoben).
        $request = $this->requestStack->getCurrentRequest();
        if ($request !== null) {
            $currentController = $request->attributes->get('_controller');
            $node->setCurrent($currentController === DashboardController::class);
        }

        // 5. Den Node als erstes Element in die Kategorie 'content' einfügen
        // addChild fügt es am Ende an. Mit reorderChildren könnten wir es sortieren.
        $contentNode->addChild($node);
    }
}

Analyse: Warum ist das so robust?

Dieser Ansatz ist ein Meisterwerk der Contao 5 Backend Custom Routing Architektur:

Keine Hardcoded URLs: Schau dir das Array im createItem an: 'route' => DashboardController::class. Wir tippen hier keine URL wie /contao/beachside-dashboard ein. KnpMenu ist intelligent genug, um Symfony nach der URL zu fragen, die zum DashboardController gehört. Wenn du die Route in Iteration 2 jemals änderst, passt sich das Menü automatisch an!
Sichere Active-States: Nichts ist nerviger in eigenen Backend-Modulen als kaputte "Aktiv"-Zustände in der Navigation. Da wir den aktuellen Request ($request->attributes->get('_controller')) gegen unsere Controller-Klasse prüfen, ist der Menüpunkt immer 100% zuverlässig hervorgehoben, wenn der User sich auf dem Dashboard befindet.
Positionierung: Da wir eine Priorität von -255 für unseren Event Listener definiert haben, garantieren wir, dass der Contao-Core sein Basis-Menü bereits aufgebaut hat. Wir können uns also gefahrlos über $tree->getChild('content') in den existierenden Baum einklinken.

Nach dem Leeren des Caches (contao-console cache:clear) wirst du beim nächsten Login ins Contao Backend in der linken Navigation unter "Inhalte" den neuen Eintrag "🏖️ Strandkorb Dashboard" sehen.

Wenn du jetzt darauf klickst, ruft Contao unseren Controller auf. Da wir aber das Twig-Template noch nicht geschrieben haben, wird dir Symfony eine "Template not found"-Fehlermeldung werfen. Das ist unser perfekter Übergang für den nächsten Schritt.

KnpMenu Event Subscriber fügt einen neuen Knoten in die Contao Backend-Navigation ein

4. Die View: Das Backend Twig-Template

Wenn du in Iteration 3 auf den neuen Menüpunkt "Strandkorb Dashboard" geklickt hast, hat Symfony einen Fehler geworfen, weil die Datei @AcmeBeachside/backend/dashboard.html.twig noch nicht existiert. Das ändern wir jetzt.

Der größte Fehler, den Entwickler beim Contao 5 Backend Custom Routing machen, ist, das Backend-HTML komplett von Grund auf neu zu schreiben. Das führt dazu, dass dein Modul bei jedem Contao-Update (z.B. Darkmode-Anpassungen) kaputt aussieht.

Die Lösung: Wir erben vom offiziellen Contao-Backend-Layout. Dadurch erhalten wir automatisch den Header, die linke Navigation, den Footer und alle Basis-CSS-Klassen des Contao-Cores.

Erstelle die Datei /src/BeachsideBundle/templates/backend/dashboard.html.twig:

Twig

{# Wir erben vom nativen Contao 5 Backend-Layout #}
{% extends "@Contao/backend/layout.html.twig" %}

{# Wir überschreiben den Block 'main', der den Hauptinhaltsbereich darstellt #}
{% block main %}
    
    {# 
       WICHTIG: Wir nutzen die nativen Contao-CSS-Klassen (tl_main_headline etc.), 
       damit sich unser Dashboard nahtlos in das restliche System einfügt. 
    #}
    <div>
        <h1>{{ title|default('Strandkorb Kommandozentrale') }}</h1>
    </div>

    {# 
       Das ist der Hauptcontainer für unseren Inhalt.
       Wir nutzen hier auch das integrierte Contao-Markup für Benachrichtigungen.
    #}
    <div id="tl_messages">
        {% if arrivals|length > 0 %}
            <p>
                Achtung: Heute reisen {{ arrivals|length }} neue Gäste an!
            </p>
        {% endif %}
    </div>

    <div>
        
        {# Unser eigenes Dashboard-Grid (das CSS dafür schreiben wir in Iteration 5) #}
        <div>
            
            <div>
                <div>Heutige Anreisen</div>
                <div>
                    <span>{{ arrivals|length }}</span>
                    <span>Strandkörbe vorzubereiten</span>
                </div>
            </div>

            <div>
                <div>Aktuell am Strand</div>
                <div>
                    <span>{{ active_chairs }}</span>
                    <span>von 150 Körben belegt</span>
                </div>
            </div>

            <div>
                <div>Umsatz (laufender Monat)</div>
                <div>
                    {# 
                       Pro-Tipp: format_currency benötigt das Paket 'twig/intl-extra'.
                       Alternativ: {{ revenue|number_format(2, ',', '.') }} € 
                    #}
                    <span>{{ revenue|format_currency('EUR', {fraction_digit: 0}) }}</span>
                </div>
            </div>

        </div>

    </div>

{% endblock %}

Die Anatomie des Templates verstehen

Lass uns diesen Code analysieren:

{% extends "@Contao/backend/layout.html.twig" %}: Dieser Einzeiler ist pures Gold. Er sagt Symfony: "Nimm das komplette Contao-Backend-Grundgerüst. Kümmere dich um den Darkmode, lade die Contao-Icons, render die Menüs – ich will nur den Mittelteil austauschen."
{% block main %}: Dies ist der definierte Twig-Block im Contao Core-Template, der für den Inhaltsbereich rechts neben der Navigation reserviert ist.
tl_main_headline & tl_info: Wer Contao kennt, kennt das Präfix tl_ (Table). Wenn wir diese Core-Klassen verwenden, sieht unsere Überschrift exakt so aus wie die Überschriften in der Artikelverwaltung. Auch die Hinweis-Boxen (tl_info, tl_error) übernehmen automatisch das korrekte Styling des aktiven Backend-Themes.
Daten-Bindung: Die Variablen arrivals, active_chairs und revenue haben wir in Iteration 2 in unserem Controller definiert und an dieses Template übergeben. Twig rendert diese nun sicher aus.

Wenn du jetzt im Backend auf deinen Menüpunkt klickst, siehst du dein Dashboard! Es hat die Navigation, es hat den Header, es zeigt deine Daten.

Aber ein Problem bleibt: Unsere eigenen Klassen wie beachside-dashboard-grid oder dashboard-card haben noch kein CSS. Die Karten kleben unschön untereinander, anstatt sich in einem modernen Grid anzuordnen. Außerdem wollen wir vielleicht ein JavaScript-Chart (z.B. Chart.js) einbinden, um die Umsätze der letzten 12 Monate als Kurve darzustellen.

Wie wir eigene CSS- und JavaScript-Dateien (Assets) in unser Contao 5 Backend Custom Routing einschleusen, zeige ich dir im nächsten Schritt.

Visuelle Darstellung, wie ein eigenes Twig-Template in das Contao Backend Layout injiziert wird

5. Assets einbinden: Der moderne Weg in Contao 5

In der alten Contao-Welt hast du eigene CSS- oder JavaScript-Dateien oft mühsam über $GLOBALS['TL_CSS'] oder $GLOBALS['TL_JAVASCRIPT'] in DCA-Dateien eingeschleust. Das Problem: Diese Skripte wurden dann oft auf jeder Backend-Seite geladen, auch wenn sie dort gar nicht gebraucht wurden, was die Performance des Backends verschlechtert hat.

Beim Contao 5 Backend Custom Routing haben wir die volle Kontrolle. Da wir ein eigenes Twig-Template haben, das vom Contao-Core-Layout erbt, können wir gezielt die Twig-Blöcke für Stylesheets und Skripte überschreiben.

6. Das Twig-Template erweitern

Wir öffnen unsere Datei templates/backend/dashboard.html.twig aus Iteration 4 und fügen ganz oben (direkt unter dem extends-Befehl) die Blöcke für unsere Assets hinzu:

Twig

{% extends "@Contao/backend/layout.html.twig" %}

{# 1. Eigene CSS-Dateien laden #}
{% block stylesheets %}
    {# Ganz wichtig: parent() aufrufen, sonst fehlt das komplette Contao-CSS! #}
    {{ parent() }}
    
    {# Wir nutzen die Symfony asset() Funktion #}
    <link rel="stylesheet" href="{{ asset('bundles/acmebeachside/css/dashboard.css') }}">
{% endblock %}

{# 2. Eigene JavaScript-Dateien laden (z.B. für ein Umsatz-Diagramm) #}
{% block javascripts %}
    {{ parent() }}
    
    {# Externe Bibliothek laden (Chart.js) #}
    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
    
    {# Unser eigenes Skript laden #}
    <script src="{{ asset('bundles/acmebeachside/js/dashboard.js') }}"></script>
{% endblock %}

{% block main %}
    {# ... hier bleibt unser Code aus Iteration 4 ... #}
    
    {# Wir fügen in unserem Grid noch einen Platzhalter für das Diagramm hinzu: #}
    <div>
        <div>
            <canvas id="revenueChart" width="400" height="150"></canvas>
        </div>
    </div>
{% endblock %}

7. Wo müssen die Dateien liegen? (Symfony Asset Management)

Du siehst im Code den Pfad bundles/acmebeachside/.... Wenn du ein eigenes Contao-Bundle (wie unser AcmeBeachsideBundle) entwickelst, legst du deine CSS- und JS-Dateien im Ordner src/Resources/public/ (bzw. public/ in neueren Bundle-Strukturen) ab.

Ordnerstruktur:

/src/BeachsideBundle/public/css/dashboard.css
/src/BeachsideBundle/public/js/dashboard.js

Der entscheidende Schritt: Damit der Webbrowser diese Dateien erreichen kann, müssen sie in den zentralen public/-Ordner deiner Contao-Installation gespiegelt werden. Das erledigt Symfony automatisch für dich, wenn du folgenden Befehl ausführst:

Bash

composer install
# oder explizit:
vendor/bin/contao-console assets:install

Symfony erstellt nun einen Symlink (eine Verknüpfung) von public/bundles/acmebeachside/ zu deinem Bundle.

8. Das CSS und JavaScript (Beispiel)

In der dashboard.css können wir nun unser CSS Grid definieren:

CSS

.beachside-dashboard-grid {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
    gap: 20px;
    margin-top: 20px;
}
.dashboard-card {
    background: var(--bg-color); /* Nutzt Contao Darkmode Variablen! */
    border: 1px solid var(--border-color);
    border-radius: 6px;
    padding: 20px;
    box-shadow: 0 2px 4px rgba(0,0,0,0.05);
}
.metric-huge {
    font-size: 2.5rem;
    font-weight: bold;
    color: #ff6600; /* Unser Neon-Orange */
}

In der dashboard.js initialisieren wir Chart.js:

JavaScript

document.addEventListener('DOMContentLoaded', function() {
    const ctx = document.getElementById('revenueChart');
    if (ctx) {
        new Chart(ctx, {
            type: 'bar',
            data: {
                labels: ['Mai', 'Juni', 'Juli', 'August'],
                datasets: [{
                    label: 'Umsatz in €',
                    data: [1200, 3500, 4800, 5200],
                    backgroundColor: '#ff6600'
                }]
            }
        });
    }
});

Mit diesem Setup sieht unser Backend-Dashboard nicht nur fantastisch aus, es ist auch hochgradig interaktiv. Die Trennung ist sauber: PHP beschafft die Daten (Controller), Twig baut das HTML, CSS sorgt für das Layout und JS für die Interaktivität.

Im nächsten Schritt widmen wir uns der Sicherheit. Was passiert, wenn ein normaler Redakteur (ohne Admin-Rechte) das Dashboard aufruft? Wir müssen Berechtigungen definieren!

Darstellung des Symfony Asset Managements, bei dem Bundle-Dateien in den Public-Ordner gespiegelt werden

9. Das Sicherheitsproblem beim Custom Routing

In der alten Contao-Welt (mit klassischen DCA-Modulen) hast du in den Benutzergruppen im Backend einfach Checkboxen angeklickt, um festzulegen, wer ein Modul sehen darf.

Beim Contao 5 Backend Custom Routing haben wir dieses Konstrukt verlassen. Wir haben eine direkte Symfony-Route gebaut. Zwar schützt der Parameter _scope => 'backend' davor, dass unangemeldete Gäste (Frontend-Besucher) die Seite sehen, aber jeder eingeloggte Backend-Nutzer (auch ein reiner News-Redakteur ohne Admin-Rechte) könnte aktuell die URL /contao/beachside-dashboard aufrufen und unsere sensiblen Umsatzdaten sehen!

Wir müssen unser Dashboard absichern. In einer modernen Symfony-Architektur nutzen wir dafür das Attribut #[IsGranted].

10. Den Controller absichern

Wir öffnen unseren DashboardController aus Iteration 2 und fügen genau eine Zeile Code hinzu. Für dieses Beispiel sagen wir: Nur Administratoren (ROLE_ADMIN) dürfen das Dashboard aufrufen.

(Hinweis: Für feinere Rechte könntest du auch eigene Contao-Voter programmieren, z.B. prüfen ob der User Zugriff auf die Tabelle tl_booking hat, aber für ein globales Dashboard ist ROLE_ADMIN oft die erste Wahl).

PHP

<?php

namespace Acme\BeachsideBundle\Controller\Backend;

use Contao\CoreBundle\Controller\AbstractBackendController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\Security\Http\Attribute\IsGranted; // <-- NEU

#[Route('%contao.backend.route_prefix%/beachside-dashboard', name: 'beachside_backend_dashboard', defaults: ['_scope' => 'backend'])]
#[IsGranted('ROLE_ADMIN')] // <-- DIESE ZEILE IST DIE MAGIE!
class DashboardController extends AbstractBackendController
{
    // ... restlicher Code ...
}

Wenn sich nun ein normaler Redakteur anmeldet und die URL manuell im Browser eintippt, wirft Symfony sofort eine 403 Access Denied (Zugriff verweigert) Exception. Das Dashboard ist sicher!

11. Die Navigation dynamisch ausblenden

Wir haben ein neues Problem geschaffen: Der Controller ist jetzt geschützt, aber unser Event Listener aus Iteration 3 (BackendMenuSubscriber) fügt den Menüpunkt "🏖️ Strandkorb Dashboard" immer noch für jeden in die linke Navigation ein. Klickt der Redakteur darauf, sieht er eine rote Fehlermeldung. Das ist schlechte User Experience (UX).

Wir müssen unseren BackendMenuSubscriber so umbauen, dass er den Menüpunkt nur dann in den Navigationsbaum einhängt, wenn der User auch die Rechte dafür hat. Dazu injizieren wir den AuthorizationCheckerInterface von Symfony.

Öffne /src/BeachsideBundle/src/EventListener/BackendMenuSubscriber.php:

PHP

<?php

namespace Acme\BeachsideBundle\EventListener;

use Acme\BeachsideBundle\Controller\Backend\DashboardController;
use Contao\CoreBundle\Event\MenuEvent;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\RequestStack;
use Symfony\Component\Security\Core\Authorization\AuthorizationCheckerInterface; // <-- NEU

#[AsEventListener(event: 'contao.backend_menu_build', priority: -255)]
class BackendMenuSubscriber
{
    public function __construct(
        private readonly RequestStack $requestStack,
        private readonly AuthorizationCheckerInterface $security // <-- NEU injiziert
    ) {
    }

    public function __invoke(MenuEvent $event): void
    {
        // 1. Sicherheitsprüfung BEVOR wir etwas tun!
        // Hat der User NICHT die Rolle Admin? Dann brich sofort ab!
        if (!$this->security->isGranted('ROLE_ADMIN')) {
            return;
        }

        // 2. Den Menü-Baum holen
        $tree = $event->getTree();
        $contentNode = $tree->getChild('content');

        if (null === $contentNode) {
            return;
        }

        // ... restlicher Code zum Erstellen des Menüpunkts aus Iteration 3 ...
    }
}

Das perfekte Zusammenspiel

Dies ist die absolute Best Practice für Contao 5 Backend Custom Routing:

Backend-Firewall (_scope): Verhindert den Zugriff ohne Login.
Controller-Security (#[IsGranted]): Schützt die eigentliche Datenverarbeitung (die Logik-Schicht) vor unautorisierten eingeloggten Nutzern.
Menu-Security (AuthorizationChecker): Schützt die Präsentations-Schicht (UX), indem Elemente, auf die der User keinen Zugriff hat, gar nicht erst gerendert werden.

Dein Dashboard ist jetzt nicht nur funktional und visuell ansprechend, sondern auch auf Enterprise-Niveau abgesichert.

Im nächsten Schritt widmen wir uns einer weiteren Anforderung: Wie können wir innerhalb unseres Custom Controllers Formulare verarbeiten (z.B. ein Filter-Formular "Zeige Umsätze von Jahr X")? Hier nutzen wir wieder unser Wissen aus Teil 8!

Abstrakte Darstellung der Sicherheitsmechanismen und Autorisierung im Contao Backend

12. Das Dashboard interaktiv machen

Aktuell zeigt unser DashboardController statisch den Umsatz des aktuellen Monats an. Was aber, wenn der Strandkorb-Vermieter wissen möchte, wie der Umsatz im Vorjahr war? Er braucht einen Filter.

In der alten Contao-DCA-Welt bedeutete das oft das mühsame Konfigurieren von "Panel Layouts" (Filter, Sortierung, Suche). Da wir uns aber im Contao 5 Backend Custom Routing befinden und einen echten Symfony-Controller nutzen, können wir auf das mächtigste Tool für Benutzereingaben zurückgreifen: Symfony Forms (die wir bereits in Teil 8 gemeistert haben).

Da ein Filter den Zustand der Seite nicht verändert (es wird nichts in die Datenbank geschrieben, nur gelesen), nutzen wir für das Formular die HTTP-Methode GET.

13. Den Controller um ein Formular erweitern

Wir passen unseren DashboardController an. Wir injizieren die FormFactoryInterface und werten den aktuellen Request aus.

(Tipp: Für komplexe Formulare würdest du wieder eine eigene FormType-Klasse anlegen. Für diesen simplen Jahres-Filter bauen wir das Formular direkt im Controller auf.)

PHP

<?php

namespace Acme\BeachsideBundle\Controller\Backend;

use Acme\BeachsideBundle\Repository\BookingRepository;
use Contao\CoreBundle\Controller\AbstractBackendController;
use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
use Symfony\Component\Form\Extension\Core\Type\SubmitType;
use Symfony\Component\Form\FormFactoryInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\Security\Http\Attribute\IsGranted;

#[Route('%contao.backend.route_prefix%/beachside-dashboard', name: 'beachside_backend_dashboard', defaults: ['_scope' => 'backend'])]
#[IsGranted('ROLE_ADMIN')]
class DashboardController extends AbstractBackendController
{
    public function __construct(
        private readonly BookingRepository $bookingRepository,
        private readonly FormFactoryInterface $formFactory // <-- NEU
    ) {
    }

    public function __invoke(Request $request): Response // <-- Request injiziert
    {
        // 1. Das Filter-Formular erstellen
        $form = $this->formFactory->createBuilder()
            ->setMethod('GET') // Wichtig für Filter-Formulare!
            ->add('year', ChoiceType::class, [
                'label' => 'Umsatzjahr wählen:',
                'choices' => [
                    '2024' => 2024,
                    '2025' => 2025,
                    '2026' => 2026,
                ],
                'data' => (int) date('Y'), // Vorauswahl: aktuelles Jahr
            ])
            ->add('filter', SubmitType::class, ['label' => 'Filtern'])
            ->getForm();

        // 2. Den Request an das Formular übergeben
        $form->handleRequest($request);

        // 3. Den ausgewählten Wert auslesen (Fallback auf aktuelles Jahr)
        $selectedYear = (int) date('Y');
        if ($form->isSubmitted() && $form->isValid()) {
            $selectedYear = $form->get('year')->getData();
        }

        // 4. Daten basierend auf dem Filter aus der Datenbank holen
        $yearlyRevenue = $this->bookingRepository->calculateRevenueForYear($selectedYear);
        $todayArrivals = $this->bookingRepository->findArrivalsByDate(new \DateTimeImmutable('today'));

        // 5. Template rendern
        return $this->render('@AcmeBeachside/backend/dashboard.html.twig', [
            'form'     => $form->createView(), // Formular an Twig übergeben
            'revenue'  => $yearlyRevenue,
            'arrivals' => $todayArrivals,
            'year'     => $selectedYear,
            'title'    => 'Strandkorb Kommandozentrale',
        ]);
    }
}

14. Das Formular im Twig-Template rendern

Jetzt müssen wir das Formular nur noch in unserer dashboard.html.twig ausgeben. Da wir das nativ ins Contao Backend integrieren, nutzen wir die Standard-Formular-Funktionen von Twig. Contao kümmert sich im Backend-Theme automatisch um ein rudimentär passendes Styling für Inputs und Buttons.

Öffne deine templates/backend/dashboard.html.twig und füge den Formular-Block über dem Grid ein:

Twig

{% extends "@Contao/backend/layout.html.twig" %}

{% block main %}
    <div>
        <h1>{{ title }}</h1>
    </div>

    {# NEU: Der Filter-Bereich #}
    <div>
        {{ form_start(form, {'attr': {'class': 'tl_form'}}) }}
            
            <div>
                <div>
                    {{ form_label(form.year) }}<br>
                    {{ form_widget(form.year, {'attr': {'class': 'tl_select'}}) }}
                </div>
                <div>
                    {{ form_widget(form.filter, {'attr': {'class': 'tl_submit'}}) }}
                </div>
            </div>
            
        {{ form_end(form) }}
    </div>

    {# ... unser Grid aus Iteration 4 ... #}
    <div>
        <div>
            <div>Jahresumsatz ({{ year }})</div>
            <div>
                <span>{{ revenue|format_currency('EUR', {fraction_digit: 0}) }}</span>
            </div>
        </div>
    </div>
{% endblock %}

Warum ist das so elegant?

Wenn der Vermieter nun im Backend im Dropdown das Jahr "2025" auswählt und auf "Filtern" klickt, lädt die Seite neu. Da wir als Methode GET definiert haben, ändert sich die URL oben im Browser zu: /contao/beachside-dashboard?year=2025

Das ist ein massiver Vorteil des Contao 5 Backend Custom Routing:

Bookmarks: Der Admin kann sich diese URL als Lesezeichen abspeichern und landet direkt beim Umsatzbericht für 2025.
Einfachheit: Wir müssen keine Contao-Spezialvariablen (?do=...&act=...) abfangen. Wir arbeiten mit reinstem Symfony HTTP-Request-Handling.
Sicherheit: Da wir das Formular mit ChoiceType definiert haben, blockiert Symfony automatisch jeden Versuch, wenn jemand die URL manipuliert (z.B. ?year=DROP TABLE). Wenn der Wert nicht im Array der konfigurierten Jahre existiert, ist $form->isValid() false und der Controller fällt sicher auf das Default-Jahr zurück.

Dein Dashboard ist jetzt nicht nur sicher und visuell ansprechend, sondern voll interaktiv.

Interaktive Datenfilterung durch Symfony Forms im Contao Backend

15. Best Practices für komplexe Backend-Module

Du hast nun ein voll funktionsfähiges, sicheres und interaktives Dashboard gebaut. Um dein Contao 5 Backend Custom Routing auch in großen und langlebigen Projekten wartbar zu halten, solltest du folgende Best Practices verinnerlichen:

Thin Controller, Fat Service: Dein Controller (DashboardController) sollte nur den Request entgegennehmen, das Formular verarbeiten und Variablen an Twig übergeben. Schreibe niemals komplexe SQL-Queries direkt in den Controller. Nutze dafür, wie in unserem Beispiel, Doctrine Repositories (BookingRepository) oder eigene Services. Das macht deinen Code testbar und wiederverwendbar.
Übersetzungen (I18n) konsequent nutzen: Anstatt 'title' => 'Strandkorb Kommandozentrale' hart in den Controller zu schreiben, solltest du den Symfony Translator nutzen. Lege eine messages.de.yaml an und nutze im Controller $this->translator->trans('backend.dashboard.title') oder im Twig-Template direkt {{ 'backend.dashboard.title'|trans }}. So machst du dein Dashboard sofort mehrsprachig für internationale Redakteure.
DCA und Custom Routes kombinieren: Das DCA und eigene Controller sind keine Feinde! Du kannst in deinem Dashboard-Grid z. B. einen Button "Letzte Buchung bearbeiten" einbauen. Der Link führt dann einfach auf die native DCA-Route: /contao?do=booking&act=edit&id=42. So nutzt du das Dashboard für die Analyse und das DCA für die reine Datenpflege.

Architektonisches Diagramm zur Synergie zwischen Contao DCA, Custom Routing und Doctrine ORM

#dashboard

Contao 5 Backend Dashboards & Custom Routing