Ein sauberes Contao 5 Bundle Setup ist das Fundament jeder erfolgreichen Erweiterung. Ein Haus, das auf Sand gebaut ist, stürzt beim ersten Sturm ein. Bei Software ist es genauso. Viele Entwickler scheitern, weil sie nicht wissen, wo genau sie anfangen sollen und versuchen, alte Contao 4 Strukturen in die neue Welt zu pressen.

In diesem ersten Teil unserer Masterclass kümmern wir uns um das korrekte Contao 5 Bundle Setup. Wir gießen ein Fundament aus Stahlbeton für unser Strandkorb-Buchungssystem (BeachsideBundle).

Das ist der Plan:

Die Entwicklungsumgebung vorbereiten (Wo liegen die Dateien?).
Die PSR-4 Ordnerstruktur anlegen.
Die composer.json konfigurieren.
Das Bundle via Manager Plugin registrieren.

Lass uns die IDE öffnen.

Voraussetzungen & der Speicherort

Bevor wir eine Zeile Code schreiben, brauchen wir eine laufende Contao 5 Installation. Ich gehe davon aus, dass du bereits eine frische Contao-Instanz lokal installiert hast (idealerweise mit DDEV, XAMPP oder Herd).

Falls nicht: Installiere dir jetzt eine leere Contao 5 Version. Wenn du fertig bist, sieht dein Projekt-Ordner (das Root-Verzeichnis) ungefähr so aus:

/mein-contao-projekt
├── /assets
├── /config
├── /public      (oder /web)
├── /system
├── /var
├── /vendor
├── composer.json
└── ...

Wo legen wir jetzt unser Bundle ab? Wir arbeiten nicht im /vendor Ordner (dort liegen nur fertige Pakete von Dritten). Wir arbeiten auch nicht in /system/modules (das ist veraltet).

Für ein sauberes Contao 5 Bundle Setup erstellen wir im Hauptverzeichnis einen neuen Ordner namens src. Das ist der Standard-Ort für lokalen Code in Symfony-Anwendungen.

Dein Ziel-Verzeichnis ist also: /mein-contao-projekt/src/.

Exkurs: Lokal vs. Public (Packagist) Vielleicht fragst du dich: „Warum laden wir das nicht gleich hoch?“ Aktuell nutzen wir den src-Ordner als unsere lokale Werkstatt. Das ist der Standard-Weg für private Projekte oder während der Entwicklung.

Aber keine Sorge: Wenn unser Bundle fertig und poliert ist, können wir es veröffentlichen. In einem Bonus-Teil (Teil 11) dieser Serie zeige ich dir exakt, wie du deinen Code aus src extrahierst, auf GitHub pusht und via Packagist der ganzen Welt zur Verfügung stellst. Dann landet er bei anderen Usern ganz professionell im vendor-Ordner.

Fürs Erste bleiben wir aber hier lokal und halten die Wege kurz.

1. Die Architektur für das Contao 5 Bundle Setup

Um Konflikte mit dem standardmäßigen Autoloading von Contao zu vermeiden, entwickeln wir wiederverwendbare Pakete am besten außerhalb des globalen /src-Verzeichnisses der Hauptanwendung. Wir erstellen stattdessen auf der Root-Ebene deines Projekts einen Ordner namens /packages.

Wir nennen unseren Namensraum (Namespace) Acme (als Platzhalter für deine Firma) und das Bundle BeachsideBundle. Erstelle folgende Ordnerstruktur in deinem Projekt:

/mein-contao-projekt
├── /packages                  <-- Ordner auf Root-Ebene erstellen!
│   └── /BeachsideBundle       <-- Unser Bundle-Root
│       ├── /config
│       │   └── services.yaml
│       ├── /src               <-- Der innere PHP-Code-Ordner
│       │   ├── /ContaoManager
│       │   │   └── Plugin.php
│       │   ├── /DependencyInjection
│       │   │   ├── BeachsideExtension.php
│       │   │   └── Configuration.php
│       │   └── BeachsideBundle.php
│       └── composer.json
└── /src                       <-- Bleibt unangetastet für die Hauptanwendung

Jetzt haben wir den physischen Ort für unseren Code geschaffen.

Wichtiger Hinweis zur Struktur: In einer früheren Version dieses Artikels lag das Bundle direkt unter /src/BeachsideBundle. Da Contao den /src-Ordner der App standardmäßig vollautomatisch scannt, führt die zusätzliche Einbindung als lokales Composer-Repository zu doppelten Klassen-Registrierungen (Cannot redeclare class). Die Auslagerung nach /packages löst dieses Problem sauber.

2. Die `composer.json`: Das Herzstück

Erstelle nun direkt im Hauptverzeichnis deines Bundles (also unter packages/BeachsideBundle/) die Datei composer.json. Diese Datei teilt Composer mit, wie das Paket heißt, welche Abhängigkeiten es hat und wo sich der PHP-Code für das Autoloading befindet.

Da unser Bundle nun isoliert im packages-Ordner liegt, bleibt die Struktur innerhalb des Pakets wunderbar sauber.

Füge folgenden Inhalt in die packages/BeachsideBundle/composer.json ein:

JSON

{
    "name": "acme/beachside-bundle",
    "description": "Ein professionelles Strandkorb-Buchungssystem für Contao 5",
    "type": "contao-bundle",
    "license": "MIT",
    "require": {
        "php": "^8.1",
        "contao/core-bundle": "^5.0",
        "symfony/framework-bundle": "^6.0"
    },
    "autoload": {
        "psr-4": {
            "Acme\\BeachsideBundle\\": "src/"
        }
    },
    "extra": {
        "contao-manager-plugin": "Acme\\BeachsideBundle\\ContaoManager\\Plugin"
    }
}

Der Profi-Tipp: Achte auf den Bereich extra. Hier sagen wir dem Contao Manager (und der Console), wo unsere Plugin-Klasse liegt. Wenn du das vergisst, wird dein Bundle nie geladen.

Erklärung zum Autoloading: Der Eintrag "Acme\\BeachsideBundle\\": "src/" bedeutet: Wenn PHP nach Klassen im Namespace Acme\BeachsideBundle sucht, schaut Composer in den Ordner src/ relativ zur Position dieser composer.json. In unserer neuen Struktur zeigt das also exakt auf packages/BeachsideBundle/src/, wo deine Bundle-Logik und der ContaoManager liegen.

Nachdem du die composer.json im Bundle erstellt hast, sagst du der Contao-Hauptanwendung in deren composer.json über ein path-Repository, wo das Paket liegt, und installierst es lokal:
Bash
composer config repositories.beachside-bundle path "packages/BeachsideBundle"
composer require acme/beachside-bundle:@dev

3. Das Contao Manager Plugin: Der Türsteher

Damit Symfony die Service-Konfiguration des Bundles findet, lädt die Extension-Klasse die Konfigurationsdatei. Da sich unsere Datei im Ordnerstruktur-Zweig /packages/BeachsideBundle/src/DependencyInjection/BeachsideExtension.php befindet, navigieren wir mit __DIR__ . '/../../config' exakt in den /config-Ordner unseres Bundles.

Achte zudem darauf, dass die Datei auf .yaml (und nicht fälschlicherweise auf .yml) endet, um Ladeprobleme im Dependency Injection Container zu vermeiden:

Ein Stecker wird in eine Buchse gesteckt, System fährt hoch

PHP

<?php

namespace Acme\BeachsideBundle\DependencyInjection;

use Symfony\Component\Config\FileLocator;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Extension\Extension;
use Symfony\Component\DependencyInjection\Loader\YamlFileLoader;

class BeachsideExtension extends Extension
{
    public function load(array $configs, ContainerBuilder $container): void
    {
        $loader = new YamlFileLoader(
            $container,
            new FileLocator(__DIR__ . '/../../config')
        );

        $loader->load('services.yaml'); // Nutzt die korrekte Dateiendung .yaml
    }
}

Was passiert hier? Wir sagen Contao: "Lade mein BeachsideBundle, aber bitte erst nachdem der ContaoCoreBundle geladen wurde." Das ist wichtig, damit wir Core-Funktionen überschreiben oder nutzen können.

4. Die Bundle-Klasse und Extension: Symfony Magic

Jetzt wird es kurz etwas abstrakt, aber das ist der Standard-Weg in Symfony. Wir brauchen zwei Klassen, um den Container zu konfigurieren.

A. Die Bundle-Klasse Datei: /src/BeachsideBundle/src/BeachsideBundle.php

PHP

<?php

namespace Acme\BeachsideBundle;

use Symfony\Component\HttpKernel\Bundle\Bundle;

class BeachsideBundle extends Bundle
{
    public function getPath(): string
    {
        return \dirname(__DIR__);
    }
}

Hinweis: getPath() ist wichtig, damit Symfony weiß, wo die Root des Bundles ist (wegen Assets, Templates etc.).

B. Die Extension-Klasse Diese Klasse lädt unsere Konfigurationen. Symfony sucht automatisch nach einer Klasse, die [BundleName]Extension heißt.

Datei: /src/BeachsideBundle/src/DependencyInjection/BeachsideExtension.php

PHP

<?php

namespace Acme\BeachsideBundle\DependencyInjection;

use Symfony\Component\Config\FileLocator;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Extension\Extension;
use Symfony\Component\DependencyInjection\Loader\YamlFileLoader;

class BeachsideExtension extends Extension
{
    public function load(array $configs, ContainerBuilder $container): void
    {
        $loader = new YamlFileLoader(
            $container,
            new FileLocator(__DIR__ . '/../../config')
        );

        $loader->load('services.yaml');
    }
}

5. Services.yaml: Die Schaltzentrale (Dependency Injection)

In deiner packages/BeachsideBundle/config/services.yaml definieren wir, welche Klassen per Autowiring geladen werden sollen. Um spätere Probleme bei der automatischen Erkennung von Doctrine-Entities zu verhindern, optimieren wir den Ressourcen-Pfad wie folgt:

Erstelle /src/BeachsideBundle/config/services.yaml:

Kabel und Verbindungen symbolisieren Dependency Injection

YAML

services:
  _defaults:
    autowire: true        # Automatisch Abhängigkeiten injizieren
    autoconfigure: true   # Automatisch Tags setzen (z.B. für EventListener)
    public: false         # Services sind standardmäßig privat

  # Symfony sagen: Alles im inneren /src-Ordner ist ein Service
  Acme\BeachsideBundle\:
    resource: '../src/'
    exclude:
      - '../src/DependencyInjection/'
      - '../src/ContaoManager/'
      - '../src/BeachsideBundle.php'
      - '../src/Entity/' # Entities werden exklusiv von Doctrine verwaltet

Warum ist das genial? Früher musstest du jede Klasse hier eintragen. Jetzt erstellst du einfach eine PHP-Klasse, und sie ist sofort als Service verfügbar. Das spart Stunden an Arbeit.

6. Installation & Test

Jetzt kommt der Moment der Wahrheit. Wir müssen Composer sagen, dass er dieses lokale Verzeichnis als Repository nutzen soll.

Öffne die Haupt-composer.json deiner Contao-Installation (im Root-Verzeichnis deines Projekts, nicht im Bundle!) und füge das path-Repository hinzu. Falls du bereits ein repositories-Array hast, fügst du das Objekt einfach hinzu:

JSON

"repositories": [
    {
        "type": "path",
        "url": "packages/BeachsideBundle"
    }
]

Um das Bundle nun testweise in deine Contao-Installation zu installieren, führst du folgenden Befehl im Terminal deines Projekt-Roots aus.

Wichtig: Wir hängen ein :@dev an, da lokale Bundles im Entwicklungsstadium noch keine stabilen Versions-Tags besitzen und Composer sie sonst blockieren würde:

Bash

composer require acme/beachside-bundle:@dev

Wenn alles klappt, siehst du grüne Schrift und Composer erstellt einen sauberen Symlink von deinem /packages-Ordner direkt in das /vendor-Verzeichnis deiner Contao-Installation.

Danach kannst du das Contao-Setup aufrufen (z. B. über vendor/bin/contao-setup oder den Contao Manager), um die Datenbank-Tabellen zu aktualisieren und das Bundle final zu aktivieren!

Prüfung: Führe folgenden Befehl aus:

Bash

vendor/bin/contao-console debug:container "Acme\BeachsideBundle"

Wenn hier keine Fehlermeldung kommt, ist dein Bundle offiziell Teil des Systems. Herzlichen Glückwunsch!

#setup

Contao 5 Bundle Setup: Das Fundament für professionelle Erweiterungen