Lernseite · Werkzeuge, Standards und Community
Das Handwerk rund um den Code: Aufbau, Versionen, Qualität und Community
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.
- In
Classes/liegen die PHP-Klassen, bei Extbase etwaController/undDomain/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.phpregistriert die Icons. Früher geschah das in derext_localconf.php.Backend/Modules.phpregistriert Backend-Module,Backend/Routes.phpundBackend/AjaxRoutes.phpdie Backend-Routen.RequestMiddlewares.phpregistriert Middlewares.- Site Sets liegen unter
Configuration/Sets, jedes in einem eigenen Unterordner mit einerconfig.yaml. Der Ordnerconfig/sitesgehö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" }
}
}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\ContentObjectRendererDer Namensraum TYPO3\ ist dem Core vorbehalten. Eine Extension der Firma Acme mit dem Key my_shop legt ihre Controller also nach Acme\.
Composer im Alltag
Welche Version genau installiert wurde, hält die composer.lock fest.
composer installinstalliert genau die Versionen aus dercomposer.lock. Das nimmst du beim Deployment und in der CI.composer updatelöst die Versionsbereiche neu auf und schreibt diecomposer.lockneu.
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 auditgleicht die installierten Pakete mit Datenbanken bekannter Sicherheitslücken ab. Dazu gehört die GitHub Advisory Database, in der auch die TYPO3-Advisories stehen.composer outdatedzeigt nur, welche Pakete neuere Versionen haben. Ob deine Version eine Lücke hat, sagt er nicht.composer validateprüft nur, ob diecomposer.jsongü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.
- 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.0TYPO3-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\ 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(); // 14Unterstü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_typesmit 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);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(): arrayPHP 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:
@paramnennt Typ und Name eines Parameters,@returnden Rückgabewert.@varbeschreibt Eigenschaften und Variablen,@throwsgeworfene Exceptions,@seeverweist auf eine andere Stelle.@internalsagt: keine öffentliche API, kann sich ohne Deprecation ändern. PHP setzt das nicht durch, es ist ein Hinweis an andere Entwickler.@deprecatedmarkiert 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 unterrequire-devein. - PHP_CodeSniffer besteht aus
phpcszum Prüfen undphpcbfzum 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 --diffStatische 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`.- Ü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-blockmit 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)
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.
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.3Das Wichtigste in Kürze
- Seit TYPO3 14 ist die
composer.jsondie einzige Pflichtdatei, der Extension-Key steht unterextra. - Öffentliche Dateien gehören nach
Resources/Public/. Eigene Tabellen bekommen ihr TCA inConfiguration/TCA/, fremde Tabellen ändert man im UnterordnerOverrides. composer installfolgt der Lock-Datei,composer updateschreibt 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.
Typo3Versionliefert 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.