Dein Design gehört in eine eigene Extension
Zusammengeklickte Konfiguration lebt in einer Datenbank, die niemand zusammen mit dem Code sichert. Ein Site Package liegt im Repository und ist nach dem nächsten Upgrade noch da.
KI-generiertDieses Bild wurde mit KI erzeugt · Yves Hoppe / KI / cmt
Konfiguration in der Datenbank lässt sich nicht ausrollen
Am Anfang funktioniert der bequeme Weg. Das TypoScript steht in einem Template-Datensatz, die Backend-Layouts sind Datensätze im Seitenbaum, das Stylesheet liegt irgendwo unter fileadmin. Alles davon lebt in der Datenbank oder neben der Installation, und beides landet nicht in derselben Sicherung wie der Code. Solange es genau eine Umgebung gibt, fällt das nicht auf.
Auffallen tut es beim zweiten System. Die Testumgebung weicht in Punkten ab, die niemand aufzählen kann, weil sie über Monate zusammengeklickt wurden. Eine Änderung lässt sich nicht überprüfen, weil es keinen Vergleich zweier Stände gibt, und nicht zurücknehmen, weil es keinen vorherigen gibt. Der einzige Weg zurück ist ein Datenbankauszug, der die Inhalte gleich mit zurückdreht.
Beim Versionswechsel kommt der Rest dazu. Wer Dateien innerhalb einer fremden Extension bearbeitet hat, verliert sie beim nächsten Composer-Lauf, und zwar ohne Rückfrage. Wer sein TypoScript über mehrere Template-Datensätze im Seitenbaum verteilt hat, muss vor dem Upgrade erst herausfinden, welcher davon überhaupt noch greift.
KI-generiertDieses Bild wurde mit KI erzeugt · Yves Hoppe / KI / cmt
Von der leeren Installation zum eigenen Paket
Die Reihenfolge ist nicht beliebig. Jeder Schritt setzt voraus, dass der vorherige nachweislich funktioniert, sonst suchst du später an drei Stellen gleichzeitig.
- 1
Verzeichnis anlegen und als Extension anmelden
In einer Composer-Installation liegt das Paket üblicherweise unter packages und trägt einen Extension-Schlüssel aus Kleinbuchstaben und Unterstrichen. Die composer.json des Pakets weist den Typ typo3-cms-extension aus und meldet den Namensraum an. Damit Composer das Verzeichnis überhaupt findet, gehört in die composer.json der Installation ein Repository vom Typ path, das auf packages zeigt, danach wird das Paket mit composer require eingebunden. Wer ohne Composer arbeitet, braucht statt alledem die klassische Beschreibungsdatei ext_emconf.php.
Geschafft, wenn: In einer Composer-Installation ist das Paket eingebunden, sobald composer require durchgelaufen ist, und taucht danach in der Erweiterungsverwaltung als installiert auf. Ohne Composer erscheint es dort als inaktiv und wird an dieser Stelle aktiviert.
- 2
Die Verzeichnisse für Fluid einziehen
Unter Resources/Private entstehen Layouts, Templates und Partials, unter Resources/Public liegen Stylesheets, Skripte und Bilder, die der Browser lädt. Anfangs reicht eine einzige Layoutdatei und eine Seitenvorlage, alles Weitere kommt später dazu.
Geschafft, wenn: Die Struktur steht, auch wenn zunächst nur zwei Dateien darin liegen.
- 3
TypoScript hinterlegen
Setup und Constants kommen als eigene Dateien unter Configuration/TypoScript. Im Setup legst du das Seitenobjekt an, hängst darunter ein FLUIDTEMPLATE und trägst die Pfadlisten ein, die auf deine eigenen Verzeichnisse zeigen. Die Werte, die später jemand ändern soll, gehören in die Constants, nicht mitten ins Setup.
Geschafft, wenn: Im Modul TypoScript zeigt Aktives TypoScript unter dem Seitenobjekt deine eigenen Pfade und nicht mehr die mitgelieferten.
- 4
Die Konfiguration einbinden
Bis TYPO3 12 wird das TypoScript als statisches Template angemeldet und anschließend im Template-Datensatz der Startseite ausgewählt. Seit TYPO3 13.1 gibt es dafür Site Sets: Unter Configuration/Sets liegt ein Verzeichnis mit einer config.yaml, die dem Set einen Namen und eine Beschriftung gibt, daneben setup.typoscript, constants.typoscript, page.tsconfig und die Dateien für die Einstellungen. Aktiviert wird es in der Site-Konfiguration über den Eintrag dependencies.
Geschafft, wenn: Deine Konfiguration greift, ohne dass jemand im Seitenbaum einen Datensatz anlegen oder auswählen musste.
- 5
Backend-Layouts festlegen
Ein Backend-Layout beschreibt die Spalten einer Seite. Es lässt sich als Datensatz im Seitenbaum anlegen oder als Datei über die Seiten-TSconfig ausliefern, was für ein Site Package der passendere Weg ist. Wichtig sind die Spaltennummern: Es sind dieselben, mit denen deine Fluid-Seite die Inhalte einsammelt.
Geschafft, wenn: In den Seiteneigenschaften lässt sich das Layout auswählen, und die Spalten heißen dort genauso, wie das Template sie anspricht.
- 6
Mit der Site-Konfiguration verbinden
Unter config/sites/<identifier>/config.yaml stehen die Einstiegsadresse, die Sprachen, die Fehlerbehandlung und, in neueren Installationen, die Abhängigkeit zu deinem Site Set. Diese Datei gehört mit ins Repository, sie ist Teil der Konfiguration und keine Umgebungssache.
Geschafft, wenn: Die Website rendert über dein Paket, und die vollständige Konfiguration liegt als Text vor, den jemand lesen kann.
- 7
Trennen, was nicht ins Paket gehört
Redaktionelle Inhalte und die von der Redaktion hochgeladenen Dateien bleiben außen vor, ebenso Zugangsdaten und alles Umgebungsabhängige, das unter config/system in settings.php und additional.php steht. Fremde Extensions werden als Abhängigkeit deklariert und nicht in das eigene Paket kopiert.
Geschafft, wenn: Eine frische Installation plus dein Paket plus ein Datenbankauszug ergibt exakt diese Website und nicht ungefähr diese Website.
Vier Bestandteile im Paket und zwei daneben
- 01 Die composer.json meldet das Verzeichnis als TYPO3-Extension an.
- 02 Configuration nimmt TypoScript, TCA-Ergänzungen und ab 13.1 das Site Set auf.
- 03 Resources/Private hält Layouts, Templates und Partials für Fluid bereit.
- 04 Resources/Public enthält Stylesheets, Skripte, Schriften und Icons.
- 05 Daneben liegt die Site-Konfiguration unter config/sites, die trotzdem ins Repository gehört.
- 06 Nicht dazu gehören Zugangsdaten unter config/system und alles, was die Redaktion hochlädt.
Was du nach dem Umbau anders machen kannst
Ein Site Package verschiebt keine Arbeit, es verschiebt den Ort. Alles Gestaltende wandert aus der Datenbank in Dateien, die in derselben Versionsverwaltung liegen wie der übrige Code, und ist damit zum ersten Mal überprüfbar.
Alles Gestaltende an einer Stelle
Vorlagen, TypoScript, Backend-Layouts, CSS und Icons liegen in einem einzigen Verzeichnis. Die Frage, wo eine bestimmte Einstellung herkommt, hat danach eine Antwort, die sich mit einer Textsuche finden lässt.
Änderungen werden überprüfbar
Jede Anpassung ist ein Unterschied zwischen zwei Ständen, den jemand lesen, kommentieren und zurücknehmen kann. Das ist bei zusammengeklickter Konfiguration grundsätzlich nicht möglich.
Eine zweite Umgebung in Minuten
Repository klonen, Abhängigkeiten installieren, Datenbank einspielen, fertig. Die Testumgebung entspricht danach der Live-Umgebung, statt ihr nur ungefähr zu ähneln.
Upgrades bleiben planbar
Beim Versionswechsel steht fest, was von euch stammt und was mitgeliefert wurde. Das reduziert die Arbeit auf die eigenen Dateien, statt eine gewachsene Installation Stück für Stück zu untersuchen.
Die Site-Konfiguration liegt ebenfalls als Datei vor
Domain, Sprachen, Fehlerbehandlung und Routing stehen unter config/sites in einer YAML-Datei. Sie gehört ins selbe Repository, auch wenn sie technisch außerhalb der Extension liegt.
Site Sets bündeln die Einbindung
Seit TYPO3 13.1 liefert ein Paket seine Konfiguration als Site Set aus, das in der Site-Konfiguration als Abhängigkeit eingetragen wird. Der Umweg über einen Template-Datensatz im Seitenbaum entfällt damit.
KI-generiertDieses Bild wurde mit KI erzeugt · Yves Hoppe / KI / cmt
Warum die Datenbank der falsche Ort ist
Der Unterschied zwischen den beiden Ablagen ist nicht technisch, sondern organisatorisch. Code in Dateien lässt sich vergleichen, kommentieren, zurücknehmen und auf ein zweites System übertragen. Konfiguration in Datensätzen kann nichts davon. Sie lässt sich nur exportieren und importieren, und dabei kommen die Inhalte mit, die man gerade nicht übertragen wollte.
Das zeigt sich beim ersten Zwischenfall. Eine Layoutänderung sieht live falsch aus, und die Frage lautet, was gestern anders war. Bei Dateien ist das eine Minute Arbeit. Bei einem Template-Datensatz gibt es die Antwort nicht, weil niemand einen Zwischenstand aufgehoben hat.
Deshalb ist das Site Package weniger eine Technik als eine Entscheidung darüber, wo die Wahrheit über die Website steht. Alles, was zum Erscheinungsbild und zur Struktur gehört, steht in Dateien. Alles, was Redaktion ist, steht in der Datenbank. Diese Grenze sauber zu ziehen, ist der eigentliche Gewinn.
Was in das Verzeichnis gehört
Unter Configuration liegen die TypoScript-Dateien, TCA-Ergänzungen für angepasste Felder und, in neueren Installationen, das Site Set. Unter Resources/Private liegen die Fluid-Verzeichnisse Layouts, Templates und Partials sowie die Sprachdateien für Beschriftungen. Unter Resources/Public liegt alles, was der Browser lädt.
Für die Verbindung zwischen Backend-Layout und Ausgabe gibt es genau eine Klammer, nämlich die Spaltennummer. Dein Fluid-Template holt die Inhaltselemente einer Spalte über eine Datenaufbereitung im TypoScript, die auf diese Nummer filtert. Wenn eine Spalte im Backend existiert, aber im Frontend nichts erscheint, liegt der Fehler fast immer zwischen diesen beiden Zahlen.
Ein Punkt, der gern übersehen wird: Auch die Beschriftungen gehören ins Paket. Texte, die aus dem Template kommen, in Sprachdateien zu legen, kostet am Anfang zehn Minuten und erspart beim späteren Anlegen einer zweiten Sprache eine Suchaktion durch sämtliche Vorlagen.
Statisches Template oder Site Set
Der klassische Weg meldet die TypoScript-Dateien als statisches Template an, das anschließend im Template-Datensatz der Startseite ausgewählt wird. Das funktioniert weiterhin und ist in bestehenden Installationen der Normalfall. Der Haken daran: Ein Teil der Einbindung steht wieder in der Datenbank, nämlich die Auswahl selbst und die Reihenfolge, in der mehrere statische Templates zusammenkommen.
Seit TYPO3 13.1 gibt es Site Sets. Ein Set ist ein Verzeichnis unter Configuration/Sets mit einer config.yaml, die Name und Beschriftung trägt und andere Sets als Abhängigkeit einbinden kann. Daneben dürfen setup.typoscript, constants.typoscript, page.tsconfig, settings.yaml und settings.definitions.yaml liegen. Aktiviert wird das Set in der Site-Konfiguration über den Eintrag dependencies, damit steht auch die Einbindung als Datei fest.
Für ein neues Projekt auf aktuellem Stand ist der Weg über Sets der geradere, weil er den letzten Rest Konfiguration aus der Datenbank holt. Für eine bestehende Installation gilt kein Handlungsdruck, beide Wege lassen sich sogar nebeneinander betreiben, während man Stück für Stück umzieht.
Was nicht ins Paket gehört
Umgebungsabhängiges bleibt draußen. Datenbankzugang, Mailversand und Anwendungskontext stehen unter config/system in settings.php und additional.php und unterscheiden sich zwischen Test und Live. Wer sie ins Paket zieht, hat beim nächsten Ausrollen die Zugangsdaten der Testumgebung auf dem Live-System.
Redaktionelle Dateien bleiben ebenfalls draußen. Bilder, die jemand über das Backend hochgeladen hat, gehören in die Dateiablage und werden mit den Inhalten gesichert, nicht mit dem Code. Ins Paket gehören nur Dateien, die zum Erscheinungsbild gehören und ohne Redaktion existieren, etwa Icons, Schriften und Platzhalterbilder.
Fremde Extensions werden als Abhängigkeit in der composer.json deklariert. Sie in das eigene Paket zu kopieren, um eine Kleinigkeit zu ändern, ist die teuerste aller Abkürzungen: Die Kopie bekommt keine Sicherheitsupdates mehr, und in ein paar Monaten weiß niemand mehr, an welcher Stelle sie vom Original abweicht.
Dazu passende Kurse
Wer das Paket einmal von Grund auf gebaut hat, spart sich später viel Suchen, und genau darauf zielen TYPO3-Kurse für die Umsetzung im Projekt .
Wie sicher bist du beim Thema wirklich?
Lesen fühlt sich schnell nach Können an. Ein kurzer Test zeigt dir, was davon schon sitzt und wo sich ein Kurs lohnt. Kostenlos, ohne Anmeldung, mit einer Erklärung zu jeder Antwort.
Wo du genau das übst
Sehr kompetente und freundliche Trainerin. Die Inhalte wurden gut strukturiert und anhand von anschaulichen Beispielen vermittelt.
Häufige Fragen
Muss ich programmieren können, um ein Site Package zu bauen?
Kann ich ein bestehendes Projekt nachträglich umstellen?
Was ist der Unterschied zwischen Site Package und Site-Konfiguration?
Brauche ich dafür zwingend Composer?
Deine Ansprechpartner
Du bist dir nicht sicher, welcher Kurs oder welches Level zu dir passt? Wir beraten dich persönlich und kostenlos.
Yves Hoppe
Weiterbildung & Beratung
Hilft dir, aus dem TYPO3-Programm den passenden Kurs für deinen Stand zu finden.
Norbert Jansen
Beratung & Inhouse
Plant mit dir Inhouse-Trainings, die auf eure Abläufe und euren Datenbestand zugeschnitten sind.
Ein Paket, das den nächsten Versionswechsel übersteht
Bei cmt baust du ein Site Package von der leeren Installation bis zur fertigen Seitenausgabe auf und siehst dabei, welche Entscheidung dich beim Upgrade später Zeit kostet.