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. They contain configuration used by the system on almost
every request. They should therefore be optimized for speed.
See Files and Locations for a full list of file and directory names typically used in extensions.
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 ext_localconf.php
, 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
calling
\TYPO3\CMS\Extbase\Utility\ExtensionUtility::registerPlugin()
. They should go inConfiguration/TCA/Overrides/tt_content.php
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']
optionsRegistering additional request handlers within the Bootstrap
Adding any PageTSconfig
Adding default TypoScript via
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility
APIsRegistering scheduler tasks
Adding reports to the reports module
Registering icons to the IconRegistry
Registering services via the Service API
Configuring plugin via
\TYPO3\CMS\Extbase\Utility\ExtensionUtility::configurePlugin()
deprecated
Registering Extbase Command Controllers (Extbase command controllers are deprecated since TYPO3 9. Use symfony commands as explained in Symfony Console Commands (cli))
Examples¶
Put a file called ext_localconf.php
in the main directory of your
Extension. It does not need to be registered anywhere but will be loaded
automatically as soon as the extension is installed.
The skeletton of the ext_localconf.php
looks like this:
<?php
// Prevent Script from beeing called directly
defined('TYPO3_MODE') || die();
// encapsulate all locally defined variables
(function () {
// Add your code here
})();
Adding default PageTSconfig¶
Default PageTSconfig can be added inside ext_localconf.php
, see
Setting the Page TSconfig globally:
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addPageTSConfig();
PageTSconfig available via static files can be added inside
Configuration/TCA/Overrides/pages.php
, see
Static Page TSconfig:
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::registerPageTSConfigFile();
Adding default UserTSconfig¶
As for default PageTSconfig, UserTSconfig can be added inside
ext_localconf.php
, see:
Setting default user TSconfig:
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addUserTSConfig();
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.
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 inConfiguration/TCA/Overrides/tablename.php
calling
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addStaticFile()
as this might break the frontend. They should go inConfiguration/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 cached.
Should Be Used For¶
These are the typical functions that should be placed inside ext_tables.php
Registering of Backend modules or Adding a new Main Module :ref: 'Example <extension-configuration-files-backend-module>'
Adding Context-Sensitive-Help to fields (via
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addLLrefForTCAdescr()
) ExampleAdding TCA descriptions (via
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addLLrefForTCAdescr()
)Adding table options via
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::allowTableOnStandardPages()
ExampleRegistering a scheduler tasks Scheduler Task Example
Assignments to the global configuration arrays
$GLOBALS['TBE_STYLES']
and$GLOBALS['PAGES_TYPES']
Extending the Backend User Settings
Examples¶
Put the following in a file called ext_tables.php
in the main directory of your extension. The
file does not need to be registered but will be loaded automatically:
<?php
defined('TYPO3_MODE') || die();
(function () {
// Add your code here
})();
Registering a Backend Module¶
You can register a new Backend Module for your extension via ExtensionUtility::registerModule()
:
\TYPO3\CMS\Extbase\Utility\ExtensionUtility::registerModule(
'Vendor.ExtensionName', // Vendor dot Extension Name in CamelCase
'web', // the main module
'mysubmodulekey', // Submodule key
'bottom', // Position
[
'MyController' => 'list,show,new',
],
[
'access' => 'user,group',
'icon' => 'EXT:my_extension/ext_icon.svg',
'labels' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang_statistics.xlf',
]
);
For more information on Backend Modules see Backend Module API.
Adding Context Sensitive Help to fields¶
Add the following to your extensions ext_tables.php in order to add Context Sensitive Help for the corresponding field:
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addLLrefForTCAdescr(
'tx_domain_model_foo',
'EXT:myext/Resources/Private/Language/locallang_csh_tx_domain_model_foo.xlf'
);
For more information see Context-Sensitive-Help.
Allowing a tables records to be added to Standard pages¶
By default new records of tables may only be added to Sysfolders in TYPO3. If you need to allow new records of your table to be added on Standard pages call:
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::allowTableOnStandardPages(
'tx_myextension_domain_model_mymodel'
);
Registering a scheduler Task¶
Scheduler tasks get registered in the ext_tables.php as well. Note that the Sysext "scheduler" has to be installed for this to work.
// Add caching framework garbage collection task
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['scheduler']['tasks'][\TYPO3\CMS\Scheduler\Task\CachingFrameworkGarbageCollectionTask::class] = array(
'extension' => 'your_extension_key',
'title' => 'LLL:EXT:your_extension_key/locallang.xlf:cachingFrameworkGarbageCollection.name',
'description' => 'LLL:EXT:your_extension_key/locallang.xlf:cachingFrameworkGarbageCollection.description',
'additionalFields' => \TYPO3\CMS\Scheduler\Task\CachingFrameworkGarbageCollectionAdditionalFieldProvider::class
);
For more information see the documentation of the Sys-Extension scheduler.
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!
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
insideext_localconf.php
orext_tables.php
since this can lead to conflicts with otheruse
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
orTYPO3_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 ofext_tables.php
andext_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') 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') || 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 thepackagePath
key, including the proper paths you might use, absolute and relative.