Attention

TYPO3 v9 has reached its end-of-life September 30th, 2021 and is not maintained by the community anymore. Looking for a stable version? Use the version switch on the top left.

You can order Extended Long Term Support (ELTS) here: TYPO3 ELTS.

Configuration Files (ext_tables.php & ext_localconf.php)¶

Files ext_tables.php and ext_localconf.php are the two most important files for the execution of extensions within TYPO3.

These files contain configuration used by the system on almost every request. Therefore, they should be optimized for speed.

Only add these files if your extension requires any of the configuration described below.

Important

Since the ext_tables.php and ext_localconf.php of every extension will be concatenated together by TYPO3, you MUST follow some rules, such as not use use or declare(strict_types=1) inside these files, see Rules and best practices.

ext_localconf.php¶

-- optional

ext_localconf.php is always included in global scope of the script, either frontend or backend.

Should Not Be Used For¶

While you can put functions and classes into the script, it is a really bad practice because such classes and functions would always be loaded. It is better to have them included only as needed.

Registering hooks or signals, XCLASSes or any simple array assignments to $GLOBALS['TYPO3_CONF_VARS'] options will not work for the following:

class loader

package manager

cache manager

configuration manager

log manager (= Logging Framework)

time zone

memory limit

locales

stream wrapper

error handler

This would not work because the extension files ext_localconf.php are included (loadTypo3LoadedExtAndExtLocalconf) after the creation of the mentioned objects in the Bootstrap class.

In most cases, these assignments should be placed in typo3conf/AdditionalConfiguration.php.

Example:

Register an exception handler in typo3conf/AdditionalConfiguration.php:

$GLOBALS['TYPO3_CONF_VARS']['SYS']['debugExceptionHandler'] = \Vendor\Ext\Error\PostExceptionsOnTwitter::class;

Should Be Used For¶

These are the typical functions that extension authors should place within ext_localconf.php

Registering hooks or signals, XCLASSes or any simple array assignments to $GLOBALS['TYPO3_CONF_VARS'] options
Registering additional Request Handlers within the Bootstrap
Adding any PageTSconfig or Default TypoScript via ExtensionManagementUtility APIs
Registering Scheduler Tasks
Adding reports to the reports module
Adding slots to signals via Extbase's SignalSlotDispatcher
Registering Icons to the IconRegistry
Registering Services via the Service API

deprecated

Registering Extbase Command Controllers (Extbase command controllers are deprecated since TYPO3 9. Use symfony commands as explained in Symfony Console Commands (cli))

ext_tables.php¶

-- optional

ext_tables.php is not always included in the global scope of the frontend context.

This file is only included when

a TYPO3 Backend or CLI request is happening
or the TYPO3 Frontend is called and a valid Backend User is authenticated

This file usually gets included later within the request and after TCA information is loaded, and a Backend User is authenticated as well.

Hint

In many cases, the file ext_tables.php is no longer needed, since TCA definitions must be placed in Configuration/TCA/*.php files nowadays.

Should Not Be Used For¶

TCA configurations for new tables. They should go in Configuration/TCA/tablename.php
TCA overrides of existing tables. They should go in Configuration/TCA/Overrides/tablename.php
calling \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addToInsertRecords() as this might break the frontend. They should go in Configuration/TCA/Overrides/tablename.php
calling \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile() as this might break the frontend. They should go in Configuration/TCA/Overrides/sys_template.php

For a descriptions of the changes for TCA (compared to older TYPO3 versions), please see the blogpost "Cleaning the hood: TCA" by Andreas Fernandez

More information can be found in the blogpost "Good practices in extensions (use TYPO3 blog).

Hint

ext_tables.php is not cached. The files in Configuration/TCA are cached.

Should Be Used For¶

These are the typical functions that should be placed inside ext_tables.php

Registering of Backend modules or Backend module functions
Adding Context-Sensitive-Help docs via ExtensionManagementUtility API
Adding TCA descriptions (via ExtensionManagementUtility::addLLrefForTCAdescr())
Adding table options via ExtensionManagementUtility::allowTableOnStandardPages
Assignments to the global configuration arrays $TBE_STYLES and $PAGES_TYPES
Adding new fields to User Settings ("Setup" Extension)

Rules and best practices¶

The following apply for both ext_tables.php and ext_localconf.php.

Important

Since the ext_tables.php and ext_localconf.php of every extension will be concatenated together by TYPO3, you MUST follow some rules, such as not use use or declare(strict_types=1) inside these files. More information below:

As a rule of thumb: Your ext_tables.php and ext_localconf.php files must be designed in a way that they can safely be read and subsequently imploded into one single file with all configuration of other extensions!

These files contain configuration used by the system on almost every request. Therefore, they should be optimized for speed.

You MUST NOT use a return statement in the files global scope - that would make the cached script concept break.
You MUST NOT rely on the PHP constant __FILE__ for detection of include path of the script - the configuration might be executed from a cached file with a different location and therefore such information should be derived from e.g. \TYPO3\CMS\Core\Utility\GeneralUtility::getFileAbsFileName() or \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::extPath().
You MUST NOT use use inside ext_localconf.php or ext_tables.php since this can lead to conflicts with other use in files of other extensions.

// do NOT use use:
-use TYPO3\CMS\Core\Resource\Security\FileMetadataPermissionsAspect;
-
-$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_tcemain.php']['processDatamapClass'][] = FileMetadataPermissionsAspect::class;
 // Use the full class name instead:
+$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_tcemain.php']['processDatamapClass'][] = \TYPO3\CMS\Core\Resource\Security\FileMetadataPermissionsAspect::class;

You MUST NOT use declare(strict_types=1) and similar directives which must be placed at the very top of files: once all files of all extensions are merged, this condition is not fulfilled anymore leading to errors. So these must never be used here.

// do NOT use declare strict and other directives which MUST be placed at the top of the file
-declare(strict_types=1)

You MUST NOT check for values of TYPO3_MODE or TYPO3_REQUESTTYPE constants (e.g. if (TYPO3_MODE === 'BE')) within these files as it limits the functionality to cache the whole systems' configuration. Any extension author should remove the checks if not explicitly necessary, and re-evaluate if these context-depending checks could go inside the hooks / caller function directly., e.g. do not do:

// do NOT do this:
-if (TYPO3_MODE === 'BE')

You SHOULD check for the existence of the constants defined('TYPO3_MODE') or die(); at the top of ext_tables.php and ext_localconf.php files to make sure the file is executed only indirectly within TYPO3 context. This is a security measure since this code in global scope should not be executed through the web server directly as entry point.

<?php
// put this at top of every ext_tables.php and ext_localconf.php
defined('TYPO3_MODE') or die();

You SHOULD use the extension name (e.g. "tt_address") instead of $_EXTKEY within the two configuration files as this variable will be removed in the future. This also applies to $_EXTCONF.
However, due to limitations to TER, the $_EXTKEY option MUST be kept within an extension's ext_emconf.php.
You SHOULD use a directly called closure function to encapsulate all locally defined variables and thus keep them out of the surrounding scope. This avoids unexpected side-effects with files of other extensions.

The following example contains the complete code:

<?php
defined('TYPO3_MODE') or die();

(function () {
    // Add your code here
})();

Additionally, it is possible to extend TYPO3 in a lot of different ways (adding TCA, Backend Routes, Symfony Console Commands etc) which do not need to touch these files.

Additional tips:

TYPO3\CMS\Core\Package\PackageManager::getActivePackages() contains information about whether the module is loaded as local or system type in the packagePath key, including the proper paths you might use, absolute and relative.