Configuration files

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.

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

    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.

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

    • Registering hooks or any simple array assignments to $TYPO3_CONF_VARS options
    • Registering additional Request Handlers within the Bootstrap
    • Adding any PageTSconfig or Default TypoScript via ExtensionManagementUtility APIs
    • Registering Extbase Command Controllers
    • 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

  • 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 gets usually included later within the request and after TCA information is loaded, and a Backend User is authenticated as well.

    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)

    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.

    It is heavily recommended to AVOID any checks on 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.

    Additionally, it is recommend to 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 should be kept within an extensions ext_emconf.php.

    See any system extension for best practice on this behaviour.

  • $TYPO3_LOADED_EXT[extensionKey] contains information about whether the module is loaded as local, global or system type, including the proper paths you might use, absolute and relative.

  • Your ext_tables.php and ext_localconf.php file must be designed so that they can safely be read and subsequently imploded into one single file with all the other configuration scripts!

  • You must never use a "return" statement in the files global scope - that would make the cached script concept break.

  • You must never use a "use" statement in the files global scope - that would make the cached script concept break and could conflict with other extensions.

  • You should not rely on the PHP constant __FILE__ for detection of include path of the script - the configuration might be executed from a cached script and therefore such information should be derived from e.g. \TYPO3\CMS\Core\Utility\GeneralUtility::getFileAbsFileName() or ExtensionManagementUtility::extPath().

Best practice for ext_tables.php and ext_localconf.php

It is a good practice to use call_user_func with an closure function. The following example contains the complete code:

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

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

In most cases, the file ext_tables.php is no longer needed, since most of the code can be placed in ConfigurationTCA*.php files.