Study guide · Tools, Standards and Community
The craft around the code: structure, versions, quality and community
This course is about the craft around the code. You follow a team that wants to release its extension my_extension as version 1.0.0. Along the way you learn how an extension is structured, how Composer and version numbers work, and how to write good code and check it automatically. Finally, it covers documentation and how you can contribute to TYPO3.
How an extension is structured
Every extension has a globally unique extension key, in our case my_extension. It consists of lowercase letters, digits and underscores. On top of that comes a Composer package name, in our case my-vendor/my-extension.
Since TYPO3 14, composer.json is the only mandatory file, even in classic mode without Composer. All other files are optional, but their names are reserved.
Classes/holds the PHP classes, for Extbase for exampleController/andDomain/Model/.Resources/Public/holds CSS, JavaScript, images and icons that the web server should deliver.Resources/Private/holds templates, layouts, partials and language files. They must not be reachable from outside.- Files created at runtime do not belong in the extension. They go to
typo3temp/.
The Configuration folder. For your own new table, you put the TCA directly into Configuration/TCA/. The file is named after the table and returns the TCA array. TYPO3 loads every file in this folder on its own. If you change a foreign table, for example with a new field in tt_content, that belongs in the subfolder Overrides, so in TCA/Overrides/tt_content.php. A file tt_content.php directly in the TCA folder would replace the whole table. The file ext_tables.sql only describes the database structure.
More reserved names in Configuration/:
Icons.phpregisters the icons. In the past this was done inext_localconf.php.Backend/Modules.phpregisters backend modules,Backend/Routes.phpandBackend/AjaxRoutes.phpregister backend routes.RequestMiddlewares.phpregisters middlewares.- Site sets live under
Configuration/Sets, each in its own subfolder with aconfig.yaml. The folderconfig/sites, on the other hand, belongs to the project.
Old files. ext_emconf.php has been deprecated since TYPO3 14.2, and ext_tables.php since 14.3. Version and dependencies now live in composer.json.
The ext_localconf.php file is optional. TYPO3 loads it on every request, including the command line. It comes after settings.php and additional.php. By then, however, the class loader, package manager, cache manager, log manager and error handler already exist. So a log configuration, a custom error or exception handler, or cache manager settings have no effect there. Such values belong in config/system/additional.php.
composer.json and namespaces
This is the composer.json of our extension:
{
"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" }
}
}The extension key sits under extra, in the key typo3/cms, and there under extension-key. Since TYPO3 14, an extension is only recognized with this entry and a type that starts with typo3-cms-. The package name in the name field is not the extension key. It follows Composer rules with a vendor and a hyphen. The type field does not contain the key either. Since version 14, TYPO3 reads the title and description from description.
Runtime or development? Under require you list the packages your extension needs at runtime. Under require-dev you list tools only used for development and tests, such as PHPUnit, PHPStan and the coding standards.
Namespaces. The entry under autoload follows PSR-4. The namespace is the prefix plus the path below Classes/. The Classes folder itself does not appear. The extension key becomes UpperCamelCase without underscores, so my_extension becomes 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\ContentObjectRendererThe namespace TYPO3\ is reserved for the Core. An extension by the company Acme with the key my_shop therefore puts its controllers into Acme\.
Composer in everyday work
Which exact version was installed is recorded in composer.lock.
composer installinstalls exactly the versions fromcomposer.lock. You use it for deployment and in CI.composer updateresolves the version ranges again and rewritescomposer.lock.
On the live server you do not need development tools. With composer install --no-dev, Composer only installs the packages from require. If you only want to update the Core, you name the package typo3/cms-core in the update and add --with-dependencies. Its dependencies come along, nothing else. Without a package name, composer update would update everything.
Three commands are easy to mix up:
composer auditchecks the installed packages against databases of known security vulnerabilities. One of them is the GitHub Advisory Database, which also lists the TYPO3 advisories.composer outdatedonly shows which packages have newer versions. It does not tell you whether your version has a vulnerability.composer validateonly checks whethercomposer.jsonis valid.
Good practice: Use version ranges that allow compatible updates. Check regularly with composer audit, ideally in CI. Apply updates in small steps and test afterwards.
Version numbers and the Version API
Almost all PHP packages follow Semantic Versioning. A version has three parts: major, minor and patch.
- Patch increases for bug fixes. You can apply such updates safely.
- Minor increases for new features that do not break existing code. If a method gets an additional optional parameter, 3.4.2 becomes 3.5.0. Patch is reset to zero.
- Major increases for breaking changes. If you remove a public method, 3.4.2 becomes 4.0.0.
A pre-release carries a suffix after a hyphen, such as alpha. Version 1.0.0 alpha therefore has a lower precedence than 1.0.0. Versions starting with zero are considered unstable, and their public API may change at any time. Build metadata is ignored for precedence.
Composer constraints build on this. The caret trusts that minor versions stay compatible. The tilde only allows increases in the last part you specify.
^14.3 allows 14.3.0 up to below 15.0.0
~14.3.0 allows 14.3.0 up to below 14.4.0TYPO3 versions. A major version comes out in several sprint releases. The last of them becomes the LTS version with long-term support. For TYPO3 14 this is 14.3, released in April 2026 and maintained until the end of June 2029 according to the roadmap. After that, TYPO3 GmbH offers paid Extended Long Term Support. Careful: for TYPO3 12 and 13, the LTS version still ended in point 4. TYPO3 14 requires at least PHP 8.2 and supports PHP up to 8.5. This also applies to the PHP on the server's command line, because Composer and the TYPO3 commands run there.
The version in code. The class Typo3Version in the namespace TYPO3\ returns the running version. You get it through dependency injection, with GeneralUtility::makeInstance(), or simply with new.
$version = new Typo3Version();
$version->getVersion(); // '14.3.7'
$version->getBranch(); // '14.3'
$version->getMajorVersion(); // 14If an extension supports TYPO3 13 and 14 at the same time, it branches with getMajorVersion(). The old constant TYPO3_version no longer exists. VersionNumberUtility only helps to convert and compare version numbers.
On the command line, vendor/bin/typo3 --version shows the version number, backed by the same class. composer show typo3/cms-core shows the installed version of the Core package with details.
The TYPO3 coding guidelines
The coding guidelines are mandatory for Core contributions and are checked automatically there. Extensions should follow them too. The basis for PHP is the PER Coding Style, the successor of PSR-12.
Every PHP file follows these rules:
- Right after the opening PHP tag, before the namespace, comes the
strict_typesdeclaration with the value 1. It must be the first statement, otherwise PHP aborts. New files always have it. - There is no closing PHP tag at the end of the file.
- Indentation uses four spaces. Line endings are Unix line endings.
- An encoding declaration is explicitly forbidden.
YAML, TypoScript and JavaScript are indented with two spaces. Since TYPO3 14, the XLIFF language files of the Core also use two spaces instead of tabs. The Core no longer uses tabs.
Exception codes. In the Core, every exception carries its own integer code as the second parameter: the Unix timestamp of the moment the line was written.
throw new \InvalidArgumentException('Unknown mode', 1727349820);The code shows up in error messages and logs. With a single search you find the place that threw it. A string is not allowed as a code in PHP, and HTTP status codes would not be unique.
DocBlocks: what they can and cannot do
A DocBlock is a comment that starts with a slash and two asterisks. Only the second asterisk tells IDEs, phpDocumentor and PHPStan that this is documentation. A normal block comment with one asterisk is not evaluated.
/**
* Returns all conferences that have not started yet.
*
* @return list<Conference>
*/
public function findUpcoming(): arrayPHP itself only knows the type array. The DocBlock says what is inside. A list is an array with consecutive keys starting at zero. For other keys you write array with a key type and a value type. The form Conference with square brackets is the older, less precise shorthand and is not valid as a native type. In Extbase you also use this to describe what is stored in an ObjectStorage.
The most important tags:
@paramnames the type and name of a parameter,@returnthe return value.@vardescribes properties and variables,@throwsthrown exceptions, and@seepoints to another place.@internalsays: not public API, may change without deprecation. PHP does not enforce this. It is a hint to other developers.@deprecatedmarks outdated code.
The spellings returns and exception are not standard tags.
Deprecating a method. The @deprecated tag only informs IDEs and tools. For calls to appear in the deprecation log, the method additionally calls trigger_error() with the level E_USER_DEPRECATED. An exception would be wrong, because it would abort the call.
You can omit a DocBlock completely or partially if the native types for parameters and return value already say everything. It stays useful for more precise types, exceptions and explanations.
Code style and static analysis
A consistent coding style governs form, not behavior. If a tool checks the style automatically, diffs and reviews show only content changes instead of formatting. And code written by many people reads consistently and is easier to maintain.
- PHP-CS-Fixer checks and fixes. TYPO3 ships its rules in the package
typo3/coding-standards, together with an.editorconfigfile. You add it underrequire-dev. - PHP_CodeSniffer consists of
phpcsfor checking andphpcbffor fixing.
Locally you fix with the fix command. In CI, the tool should only report, not change anything.
vendor/bin/php-cs-fixer fix
vendor/bin/php-cs-fixer fix --dry-run --diffStatic analysis examines code for errors without executing it. It finds, for example, calls to methods that do not exist, arguments with the wrong type or dead code. Well-known tools are PHPStan, Psalm and SonarQube. PHPUnit and Xdebug, on the other hand, run the code, which is dynamic analysis.
PHPStan has a level from 0 to 10. It defines how strictly PHPStan checks. Level 0 checks basics such as unknown classes. Higher levels also check return types, possible null values and the mixed type.
Documenting with reStructuredText and Markdown
The official TYPO3 documentation is mainly written in reStructuredText, reST for short. For an extension it lives in the Documentation/ folder, with Index.rst as the entry point and the settings file guides.xml. You render it locally with the Docker container render-guides of the TYPO3 documentation. It replaced the former Sphinx rendering with Settings.cfg.
============
Installation
============
.. _installation:
.. code-block:: php
$version = new Typo3Version();
See :ref:`installation`.- Headings are underlined or overlined with characters such as equals signs or hyphens.
- Directives start with two dots and end with two colons. For PHP code you use the
code-blockdirective with the language php. - The content of a directive depends on indentation.
- You point to other places with the
refrole.
Markdown is simpler and typical for a README file.
## Second-level heading
- A list item
1. A numbered item
[TYPO3](https://typo3.org)
In Markdown, code blocks sit between three backticks. The notation with two dots and two colons, on the other hand, belongs to reST. CommonMark is the precisely specified base of Markdown. GitHub Flavored Markdown adds tables, task lists and automatically detected links, among other things. That is why the same document looks different depending on the renderer.
phpDocumentor reads classes, methods and DocBlock tags. From them it generates navigable API documentation in HTML.
The community and how to contribute
The TYPO3 ecosystem includes:
- The TYPO3 Association, a non-profit member organization. It funds and coordinates further development.
- TYPO3 GmbH, which offers additional services, for example Extended Long Term Support.
- The TYPO3 Extension Repository, TER for short, at extensions.typo3.org. Extensions are published there and on Packagist.
The TYPO3 slogan is “Inspiring people to share”. The Core is published under the GNU General Public License version 2 or any later version. The copyright notice in every Core file refers to it.
Reporting a bug. Bugs and tasks belong in the issue tracker Forge at forge.typo3.org. Never report security vulnerabilities in public. Send them confidentially to the Security Team.
Submitting a patch. Code changes to the Core go through Gerrit at review.typo3.org. There they pass review and tests. The GitHub repository is only a mirror. The subject line of the commit message starts with a type in square brackets, such as BUGFIX, FEATURE, TASK or DOCS. At the bottom there is a Resolves line with the number of the Forge ticket, or Related for a ticket that is only related. A Releases line names the target branches.
[BUGFIX] Prevent empty slug for translated pages
Translated pages without a title no longer get an empty slug.
Resolves: #12345
Releases: main, 14.3Key points
- Since TYPO3 14,
composer.jsonis the only mandatory file, and the extension key sits underextra. - Public files go to
Resources/Public/. Your own tables get their TCA inConfiguration/TCA/, and you change foreign tables in the subfolderOverrides. composer installfollows the lock file,composer updaterewrites it.- Patch means bug fix, minor means new compatible feature, major means breaking change.
- TYPO3 14 LTS is 14.3, with PHP 8.2 to 8.5.
Typo3Versionreturns version, branch and major version. - PHP files start with strict types, end without a closing tag and use four spaces.
- PHP-CS-Fixer only checks in CI, and you introduce PHPStan with a baseline and a rising level.
- Bugs belong on Forge, patches go to Gerrit.
Terms
- Baseline
- List of known PHPStan errors that are not reported for now.
- CI
- Continuous integration, the automatic checks on every push or pull request.
- DocBlock
- Comment starting with two asterisks that tools evaluate.
- Extension key
- Globally unique name of an extension, such as my_extension.
- Forge
- Issue tracker of the TYPO3 Core.
- Gerrit
- Review system for Core patches.
- LTS
- Long Term Support, for TYPO3 14 that is version 14.3.
- TER
- TYPO3 Extension Repository at extensions.typo3.org.