Lernseite · Werkzeuge, Standards und Community

Das Handwerk rund um den Code: Aufbau, Versionen, Qualität und Community

Stand 15. November 2026 · TYPO3 14.3 LTS · ca. 18 Min. Lesezeit

In diesem Kurs geht es um das Handwerk rund um den Code. Du begleitest ein Team, das seine Extension my_extension als Version 1.0.0 veröffentlichen will. Unterwegs lernst du den Aufbau einer Extension, Composer und Versionsnummern, guten Code und seine automatische Prüfung. Zum Schluss geht es um Dokumentation und darum, wie du bei TYPO3 mitmachst.

Der Aufbau einer Extension

Jede Extension hat einen weltweit eindeutigen Extension-Key, bei uns my_extension. Er besteht aus Kleinbuchstaben, Ziffern und Unterstrichen. Dazu kommt ein Composer-Paketname, bei uns my-vendor/my-extension.

Seit TYPO3 14 ist die composer.json die einzige Pflichtdatei, auch im Classic Mode ohne Composer. Alle anderen Dateien sind optional, ihre Namen sind aber fest vergeben.

my_extension/ composer.json einzige Pflichtdatei ext_localconf.php bei jedem Request Classes/ PHP-Klassen nach PSR-4 Configuration/ TCA, Icons, Module, Sets Resources/Private/ Templates, Sprache: privat Resources/Public/ CSS, JS, Bilder: öffentlich Tests/ Unit, Functional Documentation/ Handbuch in reST Alles außer composer.json ist optional.
Was wohin gehört. Nur Resources Public ist von außen erreichbar.
  • In Classes/ liegen die PHP-Klassen, bei Extbase etwa Controller/ und Domain/Model/.
  • In Resources/Public/ liegen CSS, JavaScript, Bilder und Icons, die der Webserver ausliefern soll.
  • In Resources/Private/ liegen Templates, Layouts, Partials und Sprachdateien. Sie sollen von außen gerade nicht abrufbar sein.
  • Dateien, die erst zur Laufzeit entstehen, gehören nicht in die Extension, sondern nach typo3temp/.

Der Ordner Configuration. Für eine eigene, neue Tabelle legst du das TCA direkt in Configuration/TCA/ ab. Die Datei heißt wie die Tabelle und gibt das TCA-Array zurück. TYPO3 lädt alle Dateien dieses Ordners selbst. Änderst du eine fremde Tabelle, etwa mit einem neuen Feld in tt_content, gehört das in den Unterordner Overrides, also nach TCA/Overrides/tt_content.php. Eine Datei tt_content.php direkt im Ordner TCA würde die ganze Tabelle ersetzen. Die Datei ext_tables.sql beschreibt nur die Datenbankstruktur.

Weitere feste Namen in Configuration/:

  • Icons.php registriert die Icons. Früher geschah das in der ext_localconf.php.
  • Backend/Modules.php registriert Backend-Module, Backend/Routes.php und Backend/AjaxRoutes.php die Backend-Routen.
  • RequestMiddlewares.php registriert Middlewares.
  • Site Sets liegen unter Configuration/Sets, jedes in einem eigenen Unterordner mit einer config.yaml. Der Ordner config/sites gehört dagegen zum Projekt.

Alte Dateien. Die ext_emconf.php ist seit TYPO3 14.2 veraltet, die ext_tables.php seit 14.3. Version und Abhängigkeiten stehen jetzt in der composer.json.

Die ext_localconf.php ist optional. TYPO3 lädt sie bei jedem Request, auch auf der Kommandozeile. Sie kommt nach settings.php und additional.php. Dann sind Class-Loader, Package-Manager, Cache-Manager, Log-Manager und Error-Handler aber schon erzeugt. Eine Log-Konfiguration, ein eigener Error- oder Exception-Handler oder Einstellungen am Cache-Manager wirken dort also nicht. Solche Werte gehören in config/system/additional.php.

Die composer.json und die Namensräume

So sieht die composer.json unserer Extension aus:

{
  "name": "my-vendor/my-extension",
  "type": "typo3-cms-extension",
  "description": "Conferences - Manage conferences and talks",
  "license": "GPL-2.0-or-later",
  "require": {
    "php": "^8.2",
    "typo3/cms-core": "^14.3"
  },
  "require-dev": {
    "phpstan/phpstan": "^2.0",
    "typo3/testing-framework": "^9.0"
  },
  "autoload": {
    "psr-4": { "MyVendor\\MyExtension\\": "Classes/" }
  },
  "extra": {
    "typo3/cms": { "extension-key": "my_extension" }
  }
}
Die composer.json von my_extension. Sie nennt Paketname, Typ und Lizenz. Unter require stehen PHP und TYPO3, unter require-dev PHPStan und das Testing Framework. Dazu kommen das PSR-4-Autoloading und unter extra der Extension-Key.

Der Extension-Key steht unter extra, im Schlüssel typo3/cms und darin unter extension-key. Seit TYPO3 14 erkennt TYPO3 eine Extension nur mit diesem Eintrag und einem Typ, der mit typo3-cms- beginnt. Der Paketname im Feld name ist nicht der Extension-Key. Er folgt den Composer-Regeln mit Vendor und Bindestrich. Auch das Feld type enthält den Key nicht. Titel und Beschreibung liest TYPO3 seit Version 14 aus description.

Laufzeit oder Entwicklung? Unter require stehen die Pakete, die deine Extension zur Laufzeit braucht. Unter require-dev stehen Werkzeuge nur für Entwicklung und Tests, etwa PHPUnit, PHPStan und die Coding Standards.

Namensräume. Der Eintrag unter autoload folgt PSR-4. Der Namensraum ist das Präfix plus der Pfad unterhalb von Classes/. Der Ordner Classes selbst taucht nicht auf. Aus dem Extension-Key wird UpperCamelCase ohne Unterstriche, aus my_extension also MyExtension.

Classes/Controller/ConferenceController.php
  -> MyVendor\MyExtension\Controller\ConferenceController
Classes/Service/Import/CsvReader.php
  -> MyVendor\MyExtension\Service\Import\CsvReader
typo3/sysext/frontend/Classes/ContentObject/ContentObjectRenderer.php
  -> TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer
Drei Beispiele für Dateipfad und Namensraum. Aus der Datei CsvReader im Ordner Service Import wird MyVendor MyExtension Service Import CsvReader. Im Core liegt der ContentObjectRenderer im Namensraum TYPO3 CMS Frontend ContentObject.

Der Namensraum TYPO3\CMS ist dem Core vorbehalten. Eine Extension der Firma Acme mit dem Key my_shop legt ihre Controller also nach Acme\MyShop\Controller.

Composer im Alltag

Welche Version genau installiert wurde, hält die composer.lock fest.

  • composer install installiert genau die Versionen aus der composer.lock. Das nimmst du beim Deployment und in der CI.
  • composer update löst die Versionsbereiche neu auf und schreibt die composer.lock neu.

Auf dem Live-Server brauchst du keine Entwicklungswerkzeuge. Mit composer install --no-dev installiert Composer nur die Pakete aus require. Willst du nur den Core aktualisieren, nennst du das Paket typo3/cms-core beim Update und hängst --with-dependencies an. Dann kommen seine Abhängigkeiten mit, sonst nichts. Ohne Paketnamen würde composer update alles aktualisieren.

Drei Befehle verwechselt man leicht:

  • composer audit gleicht die installierten Pakete mit Datenbanken bekannter Sicherheitslücken ab. Dazu gehört die GitHub Advisory Database, in der auch die TYPO3-Advisories stehen.
  • composer outdated zeigt nur, welche Pakete neuere Versionen haben. Ob deine Version eine Lücke hat, sagt er nicht.
  • composer validate prüft nur, ob die composer.json gültig ist.

Gute Praxis: Gib Versionsbereiche an, die kompatible Updates zulassen. Prüfe regelmäßig mit composer audit, am besten in der CI. Spiele Updates in kleinen Schritten ein und teste danach.

Versionsnummern und die Versions-API

Fast alle PHP-Pakete folgen Semantic Versioning. Eine Version hat drei Stellen: Major, Minor und Patch.

2.4.1 Major Minor Patch Fehlerbehebung Patch steigt 2.4.2 Neue Funktion, kompatibel Minor steigt, Patch auf 0 2.5.0 Inkompatible Änderung Major steigt, Rest auf 0 3.0.0 Rechts von der erhöhten Stelle steht danach 0.
Welche Stelle steigt, sagt dir, wie gefahrlos ein Update ist.
  • Patch steigt bei Fehlerbehebungen. Solche Updates kannst du gefahrlos einspielen.
  • Minor steigt bei neuen Funktionen, die bestehenden Code nicht brechen. Bekommt eine Methode einen zusätzlichen optionalen Parameter, wird aus 3.4.2 also 3.5.0. Patch springt dabei auf null.
  • Major steigt bei inkompatiblen Änderungen. Entfernst du eine öffentliche Methode, wird aus 3.4.2 die Version 4.0.0.

Eine Vorabversion trägt einen Zusatz mit Bindestrich, etwa alpha. Die Version 1.0.0 alpha hat deshalb einen niedrigeren Rang als 1.0.0. Versionen, die mit null beginnen, gelten als instabil, ihre öffentliche API darf sich jederzeit ändern. Build-Metadaten zählen für den Rang nicht.

Composer-Bedingungen bauen darauf auf. Der Zirkumflex vertraut darauf, dass Minor-Versionen kompatibel bleiben. Die Tilde erlaubt nur Erhöhungen an der letzten angegebenen Stelle.

^14.3     erlaubt 14.3.0 bis unter 15.0.0
~14.3.0   erlaubt 14.3.0 bis unter 14.4.0
Zirkumflex 14.3 erlaubt alle Versionen ab 14.3.0 bis unter 15.0.0. Tilde 14.3.0 erlaubt nur 14.3.0 bis unter 14.4.0, also nur Patches.

TYPO3-Versionen. Eine Hauptversion erscheint in mehreren Sprint-Releases. Die letzte davon wird die LTS-Version mit langer Pflege. Bei TYPO3 14 ist das 14.3, erschienen im April 2026 und laut Roadmap gepflegt bis Ende Juni 2029. Danach bietet die TYPO3 GmbH kostenpflichtigen Extended Long Term Support an. Vorsicht: Bei TYPO3 12 und 13 endete die LTS-Version noch auf Punkt 4. TYPO3 14 braucht mindestens PHP 8.2 und unterstützt PHP bis 8.5. Das gilt auch für das PHP auf der Kommandozeile des Servers, denn dort laufen Composer und die TYPO3-Befehle.

Die Version im Code. Die Klasse Typo3Version im Namensraum TYPO3\CMS\Core\Information liefert die laufende Version. Du bekommst sie per Dependency Injection, mit GeneralUtility::makeInstance() oder einfach mit new.

$version = new Typo3Version();
$version->getVersion();      // '14.3.7'
$version->getBranch();       // '14.3'
$version->getMajorVersion(); // 14
Codebeispiel. In TYPO3 14.3.7 liefert getVersion die volle Nummer 14.3.7, getBranch den Zweig 14.3 und getMajorVersion die Zahl 14.

Unterstützt eine Extension TYPO3 13 und 14 zugleich, verzweigt sie mit getMajorVersion(). Die alte Konstante TYPO3_version gibt es nicht mehr. VersionNumberUtility hilft nur beim Umwandeln und Vergleichen von Versionsnummern.

Auf der Kommandozeile zeigt vendor/bin/typo3 --version die Versionsnummer, dahinter steckt dieselbe Klasse. composer show typo3/cms-core zeigt die installierte Version des Core-Pakets mit Details.

Die TYPO3 Coding Guidelines

Die Coding Guidelines sind für Beiträge zum Core Pflicht und werden dort automatisch geprüft. Extensions sollen ihnen ebenfalls folgen. Grundlage für PHP ist PER Coding Style, die Weiterentwicklung von PSR-12.

Für jede PHP-Datei gilt:

  • Direkt nach dem öffnenden PHP-Tag und vor dem Namensraum steht die Anweisung strict_types mit dem Wert 1. Sie muss die erste Anweisung sein, sonst bricht PHP ab. Neue Dateien haben sie immer.
  • Am Dateiende steht kein schließendes PHP-Tag.
  • Eingerückt wird mit vier Leerzeichen. Die Zeilenenden sind Unix-Zeilenenden.
  • Eine Encoding-Deklaration ist ausdrücklich verboten.

YAML, TypoScript und JavaScript werden mit zwei Leerzeichen eingerückt. Auch die XLIFF-Sprachdateien des Core nutzen seit TYPO3 14 zwei Leerzeichen statt Tabs. Tabs verwendet der Core nicht mehr.

Exception-Codes. Im Core trägt jede Exception als zweiten Parameter einen eigenen ganzzahligen Code: den Unix-Zeitstempel des Moments, in dem die Zeile geschrieben wurde.

throw new \InvalidArgumentException('Unknown mode', 1727349820);
Codebeispiel. Die Extension wirft eine InvalidArgumentException mit dem Text Unknown mode und dem Zeitstempel 1727349820 als Code.

Der Code taucht in Fehlermeldungen und Logs auf. Mit einer einzigen Suche findest du so die werfende Stelle. Ein Text ist als Code in PHP nicht erlaubt, und HTTP-Statuscodes wären nicht eindeutig.

DocBlocks: was sie können und was nicht

Ein DocBlock ist ein Kommentar, der mit einem Schrägstrich und zwei Sternchen beginnt. Nur am zweiten Sternchen erkennen IDEs, phpDocumentor und PHPStan, dass es Dokumentation ist. Ein normaler Blockkommentar mit einem Sternchen wird nicht ausgewertet.

/**
 * Returns all conferences that have not started yet.
 *
 * @return list<Conference>
 */
public function findUpcoming(): array
Codebeispiel. Der DocBlock über der Methode findUpcoming sagt mit dem Tag return, dass sie eine Liste von Conference-Objekten liefert. Der native Rückgabetyp ist array.

PHP selbst kennt nur den Typ array. Was darin steckt, sagt der DocBlock. Eine Liste ist ein Array mit fortlaufenden Schlüsseln ab null. Für andere Schlüssel schreibst du array mit Schlüssel- und Werttyp. Die Form Conference mit eckigen Klammern ist die ältere, ungenauere Kurzform und als nativer Typ nicht gültig. In Extbase beschreibst du so auch, was in einem ObjectStorage liegt.

Die wichtigsten Tags:

  • @param nennt Typ und Name eines Parameters, @return den Rückgabewert.
  • @var beschreibt Eigenschaften und Variablen, @throws geworfene Exceptions, @see verweist auf eine andere Stelle.
  • @internal sagt: keine öffentliche API, kann sich ohne Deprecation ändern. PHP setzt das nicht durch, es ist ein Hinweis an andere Entwickler.
  • @deprecated markiert veralteten Code.

Die Schreibweisen returns und exception sind keine Standard-Tags.

Eine Methode abkündigen. Der Tag @deprecated informiert nur IDEs und Werkzeuge. Damit Aufrufe im Deprecation-Log erscheinen, ruft die Methode zusätzlich trigger_error() mit der Stufe E_USER_DEPRECATED auf. Eine Exception wäre falsch, denn sie würde den Aufruf abbrechen.

Weglassen kannst du einen DocBlock ganz oder teilweise, wenn die nativen Typen für Parameter und Rückgabewert schon alles sagen. Sinnvoll bleibt er für genauere Typen, Exceptions und Begründungen.

Code-Stil und statische Analyse

Ein einheitlicher Code-Stil regelt die Form, nicht das Verhalten. Prüft ein Werkzeug den Stil automatisch, zeigen Diffs und Reviews nur inhaltliche Änderungen statt Formatierung. Und Code aus vielen Händen liest sich einheitlich und ist leichter zu warten.

  • PHP-CS-Fixer prüft und korrigiert. TYPO3 liefert seine Regeln im Paket typo3/coding-standards, zusammen mit einer .editorconfig. Du bindest es unter require-dev ein.
  • PHP_CodeSniffer besteht aus phpcs zum Prüfen und phpcbf zum Korrigieren.

Lokal korrigierst du mit dem Befehl fix. In der CI soll das Werkzeug nur melden, nicht ändern.

vendor/bin/php-cs-fixer fix
vendor/bin/php-cs-fixer fix --dry-run --diff
Zwei Aufrufe von PHP-CS-Fixer. Der erste korrigiert lokal. Der zweite läuft in der CI mit dry-run und diff: Er zeigt die Abweichungen und lässt den Job scheitern, ohne Dateien zu ändern.

Statische Analyse untersucht Code auf Fehler, ohne ihn auszuführen. Sie findet etwa Aufrufe von Methoden, die es nicht gibt, Argumente mit falschem Typ oder toten Code. Bekannte Werkzeuge sind PHPStan, Psalm und SonarQube. PHPUnit und Xdebug führen den Code dagegen aus, das ist dynamische Analyse.

PHPStan hat ein Level von 0 bis 10. Es legt fest, wie streng geprüft wird. Level 0 prüft Grundlegendes wie unbekannte Klassen. Höhere Level prüfen zusätzlich Rückgabetypen, mögliche null-Werte und den Typ mixed.

Dokumentieren mit reStructuredText und Markdown

Die offizielle TYPO3-Dokumentation ist überwiegend in reStructuredText geschrieben, kurz reST. Bei einer Extension liegt sie im Ordner Documentation/, mit Index.rst als Einstieg und der Einstellungsdatei guides.xml. Lokal renderst du sie mit dem Docker-Container render-guides der TYPO3-Dokumentation. Er hat das frühere Sphinx-Rendering mit Settings.cfg abgelöst.

============
Installation
============

.. _installation:

.. code-block:: php

   $version = new Typo3Version();

Siehe :ref:`installation`.
Ein reST-Beispiel. Die Überschrift ist mit Gleichheitszeichen über- und unterstrichen. Es folgen ein Anker, die Direktive code-block für PHP mit eingerücktem Code und am Ende ein Verweis mit der Rolle ref.
  • Überschriften werden mit Zeichen wie Gleichheitszeichen oder Bindestrich unterstrichen oder überstrichen.
  • Direktiven beginnen mit zwei Punkten und enden mit zwei Doppelpunkten. Für PHP-Code nimmst du die Direktive code-block mit der Sprache php.
  • Der Inhalt einer Direktive hängt an der Einrückung.
  • Verweise auf andere Stellen machst du mit der Rolle ref.

Markdown ist einfacher und typisch für eine README-Datei.

## Überschrift zweiter Ebene

- Ein Listenpunkt
1. Ein nummerierter Punkt

[TYPO3](https://typo3.org)
![Logo](logo.png)
Ein Markdown-Beispiel. Zwei Rautenzeichen machen eine Überschrift zweiter Ebene. Listen beginnen mit Bindestrich, Sternchen oder einer Zahl mit Punkt. Ein Link ist Text in eckigen und Adresse in runden Klammern. Ein Bild sieht genauso aus, mit einem Ausrufezeichen davor.

Codeblöcke stehen in Markdown zwischen drei Backticks. Die Schreibweise mit zwei Punkten und Doppelpunkten gehört dagegen zu reST. CommonMark ist die genau spezifizierte Basis von Markdown. GitHub Flavored Markdown ergänzt unter anderem Tabellen, Aufgabenlisten und automatisch erkannte Links. Deshalb sieht dasselbe Dokument je nach Renderer anders aus.

phpDocumentor liest Klassen, Methoden und DocBlock-Tags. Daraus erzeugt es eine navigierbare API-Dokumentation in HTML.

Die Community und wie du mitmachst

Zum Ökosystem von TYPO3 gehören:

  • Die TYPO3 Association, eine gemeinnützige Mitgliederorganisation. Sie finanziert und koordiniert die Weiterentwicklung.
  • Die TYPO3 GmbH, die ergänzende Dienstleistungen anbietet, zum Beispiel Extended Long Term Support.
  • Das TYPO3 Extension Repository, kurz TER, auf extensions.typo3.org. Dort und auf Packagist werden Extensions veröffentlicht.

Der Leitspruch von TYPO3 lautet „Inspiring people to share“. Der Core steht unter der GNU General Public License in Version 2 oder jeder späteren Version. Darauf verweist der Copyright-Hinweis jeder Core-Datei.

Einen Fehler melden. Fehler und Aufgaben gehören in den Issue Tracker Forge auf forge.typo3.org. Sicherheitslücken meldest du nie öffentlich, sondern vertraulich an das Security Team.

1 Ticket anlegen forge.typo3.org 2 Patch an Gerrit schicken review.typo3.org, mit Ticket verknüpft 3 Review und Tests andere prüfen, die CI läuft 4 Merge durch das Core-Team auch in ältere Zweige Das GitHub-Repository des Core ist nur ein Spiegel.
Forge sammelt die Tickets, Gerrit prüft den Code.

Einen Patch einreichen. Code-Änderungen am Core laufen über Gerrit auf review.typo3.org. Dort durchlaufen sie Review und Tests. Das GitHub-Repository ist nur ein Spiegel. Die Betreffzeile der Commit-Nachricht beginnt mit einem Typ in eckigen Klammern, etwa BUGFIX, FEATURE, TASK oder DOCS. Unten steht eine Zeile Resolves mit der Nummer des Forge-Tickets, bei einem nur verwandten Ticket Related. Dazu kommt eine Zeile Releases mit den Zielzweigen.

[BUGFIX] Prevent empty slug for translated pages

Translated pages without a title no longer get an empty slug.

Resolves: #12345
Releases: main, 14.3
Eine Commit-Nachricht nach Core-Konvention. Die Betreffzeile beginnt mit BUGFIX in eckigen Klammern. Nach einer Erklärung folgen die Zeilen Resolves mit der Ticketnummer und Releases mit main und 14.3.

Das Wichtigste in Kürze

  • Seit TYPO3 14 ist die composer.json die einzige Pflichtdatei, der Extension-Key steht unter extra.
  • Öffentliche Dateien gehören nach Resources/Public/. Eigene Tabellen bekommen ihr TCA in Configuration/TCA/, fremde Tabellen ändert man im Unterordner Overrides.
  • composer install folgt der Lock-Datei, composer update schreibt sie neu.
  • Patch heißt Fehlerbehebung, Minor neue kompatible Funktion, Major Bruch.
  • TYPO3 14 LTS ist 14.3, mit PHP 8.2 bis 8.5. Typo3Version liefert Version, Branch und Hauptversion.
  • PHP-Dateien beginnen mit strict types, enden ohne schließendes Tag und nutzen vier Leerzeichen.
  • PHP-CS-Fixer prüft in der CI nur, PHPStan führt man mit Baseline und steigendem Level ein.
  • Fehler gehören auf Forge, Patches zu Gerrit.

Begriffe

Baseline
Liste bekannter PHPStan-Fehler, die vorerst nicht gemeldet werden.
CI
Continuous Integration, das automatische Prüfen bei jedem Push oder Pull Request.
DocBlock
Kommentar mit zwei Sternchen am Anfang, den Werkzeuge auswerten.
Extension-Key
Weltweit eindeutiger Name einer Extension, etwa my_extension.
Forge
Issue Tracker des TYPO3 Core.
Gerrit
Review-System für Core-Patches.
LTS
Long Term Support, bei TYPO3 14 die Version 14.3.
TER
TYPO3 Extension Repository auf extensions.typo3.org.

Stand: 15. November 2026 (TYPO3 14.3 LTS)

Quellen:

  • TYPO3 Explained 14.3, Kapitel Extension Architecture (File structure, composer.json, ext_localconf.php)
  • TYPO3 Explained 14.3, Coding Guidelines (PHP, YAML, TypoScript, XLIFF) und Kapitel Versions-API
  • How to document (docs.typo3.org/m/typo3/docs-how-to-document), reStructuredText und render-guides
  • TYPO3 Contribution Guide (Forge, Gerrit, Commit-Nachrichten)
  • semver.org 2.0.0, Composer-Dokumentation (Versionsbedingungen, install, update, audit)
  • Quellcode TYPO3 14.3 (typo3/cms-core), geprüft für Typo3Version und die Changelogs zu ext_emconf.php, ext_tables.php und XLIFF
  • Lernzielkatalog TYPO3 CMS Certified Developer 14 LTS

Diese Lernseite ist mit KI erstellt und gegen die Quellen geprüft.

Zertifikate & Prüfungen

Welche Prüfung kommt als Nächstes?

51 Prüfungen kannst du schon üben, über 16 stimmst du gerade ab. Sieh dir alle Zertifikate mit offiziellen Infos an, gib deine Stimme ab oder schlag deine Prüfung vor.

Zur Zertifikatsübersicht