Study guide · Tools, Standards and Community

The craft around the code: structure, versions, quality and community

As of November 15, 2026 · TYPO3 14.3 LTS · about 20 min read

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.

my_extension/ composer.json the only required file ext_localconf.php loaded on every request Classes/ PHP classes via PSR-4 Configuration/ TCA, icons, modules, sets Resources/Private/ templates, labels: private Resources/Public/ CSS, JS, images: public Tests/ unit, functional Documentation/ manual in reST Everything except composer.json is optional.
What goes where. Only Resources Public can be reached from outside.
  • Classes/ holds the PHP classes, for Extbase for example Controller/ and Domain/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.php registers the icons. In the past this was done in ext_localconf.php.
  • Backend/Modules.php registers backend modules, Backend/Routes.php and Backend/AjaxRoutes.php register backend routes.
  • RequestMiddlewares.php registers middlewares.
  • Site sets live under Configuration/Sets, each in its own subfolder with a config.yaml. The folder config/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 composer.json of my_extension. It names the package, the type and the license. Under require are PHP and TYPO3, under require-dev PHPStan and the testing framework. Then come the PSR-4 autoloading and, under extra, the extension key.

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\ContentObjectRenderer
Three examples of file path and namespace. The file CsvReader in the folder Service Import becomes MyVendor MyExtension Service Import CsvReader. In the Core, the ContentObjectRenderer lives in the namespace TYPO3 CMS Frontend ContentObject.

The namespace TYPO3\CMS is reserved for the Core. An extension by the company Acme with the key my_shop therefore puts its controllers into Acme\MyShop\Controller.

Composer in everyday work

Which exact version was installed is recorded in composer.lock.

  • composer install installs exactly the versions from composer.lock. You use it for deployment and in CI.
  • composer update resolves the version ranges again and rewrites composer.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 audit checks the installed packages against databases of known security vulnerabilities. One of them is the GitHub Advisory Database, which also lists the TYPO3 advisories.
  • composer outdated only shows which packages have newer versions. It does not tell you whether your version has a vulnerability.
  • composer validate only checks whether composer.json is 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.

2.4.1 Major Minor Patch Bug fix patch increases 2.4.2 New feature, compatible minor increases, patch to 0 2.5.0 Breaking change major increases, rest to 0 3.0.0 Everything right of the raised part becomes 0.
Which part increases tells you how safe an update is.
  • 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.0
Caret 14.3 allows every version from 14.3.0 up to below 15.0.0. Tilde 14.3.0 only allows 14.3.0 up to below 14.4.0, so only patches.

TYPO3 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\CMS\Core\Information 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(); // 14
Code example. In TYPO3 14.3.7, getVersion returns the full number 14.3.7, getBranch the branch 14.3 and getMajorVersion the number 14.

If 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_types declaration 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);
Code example. The extension throws an InvalidArgumentException with the message Unknown mode and the timestamp 1727349820 as its code.

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(): array
Code example. The DocBlock above the method findUpcoming uses the return tag to say that it returns a list of Conference objects. The native return type is array.

PHP 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:

  • @param names the type and name of a parameter, @return the return value.
  • @var describes properties and variables, @throws thrown exceptions, and @see points to another place.
  • @internal says: not public API, may change without deprecation. PHP does not enforce this. It is a hint to other developers.
  • @deprecated marks 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 .editorconfig file. You add it under require-dev.
  • PHP_CodeSniffer consists of phpcs for checking and phpcbf for 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 --diff
Two calls of PHP-CS-Fixer. The first one fixes locally. The second one runs in CI with dry-run and diff: it shows the deviations and makes the job fail without changing any files.

Static 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`.
A reST example. The heading is overlined and underlined with equals signs. Then come an anchor, the code-block directive for PHP with indented code and, at the end, a reference with the ref role.
  • 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-block directive with the language php.
  • The content of a directive depends on indentation.
  • You point to other places with the ref role.

Markdown is simpler and typical for a README file.

## Second-level heading

- A list item
1. A numbered item

[TYPO3](https://typo3.org)
![Logo](logo.png)
A Markdown example. Two hash signs make a second-level heading. Lists start with a hyphen, an asterisk or a number with a dot. A link is text in square brackets followed by the address in round brackets. An image looks the same, with an exclamation mark in front.

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.

1 Create a ticket forge.typo3.org 2 Push the patch to Gerrit review.typo3.org, linked to the ticket 3 Review and tests others review, CI runs 4 Merge by the Core Team also into older branches The Core repository on GitHub is only a mirror.
Forge collects the tickets, Gerrit reviews the code.

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.3
A commit message following the Core conventions. The subject line starts with BUGFIX in square brackets. After an explanation come the lines Resolves with the ticket number and Releases with main and 14.3.

Key points

  • Since TYPO3 14, composer.json is the only mandatory file, and the extension key sits under extra.
  • Public files go to Resources/Public/. Your own tables get their TCA in Configuration/TCA/, and you change foreign tables in the subfolder Overrides.
  • composer install follows the lock file, composer update rewrites 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. Typo3Version returns 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.

As of: November 15, 2026 (TYPO3 14.3 LTS)

Sources:

  • TYPO3 Explained 14.3, chapter Extension Architecture (file structure, composer.json, ext_localconf.php)
  • TYPO3 Explained 14.3, Coding Guidelines (PHP, YAML, TypoScript, XLIFF) and the Version API
  • How to document (docs.typo3.org/m/typo3/docs-how-to-document), reStructuredText and render-guides
  • TYPO3 Contribution Guide (Forge, Gerrit, commit messages)
  • semver.org 2.0.0, Composer documentation (version constraints, install, update, audit)
  • TYPO3 14.3 source code (typo3/cms-core), checked for Typo3Version and the changelogs on ext_emconf.php, ext_tables.php and XLIFF
  • Learning objectives TYPO3 CMS Certified Developer 14 LTS

This study guide was written with AI and checked against the sources.

Certifications & exams

Which exam comes next?

You can already practise for 51 exams, and 16 are up for a vote. See all certifications with their official information, cast your vote or suggest your exam.

See all certifications