--- title: "ext_localconf.php" manual: "TYPO3 Explained" version: "13.4" permalink: "https://docs.typo3.org/permalink/t3coreapi:ext-localconf-php@13.4" source: "ExtensionArchitecture/FileStructure/ExtLocalconf.rst" rendered: "2026-10-01T12:09:27+00:00" --- # `ext_localconf.php` {#ext-localconf-php} - **ext_localconf.php** - *Scope:* extension - *Path (Composer):* packages/my_extension/ext_localconf.php - *Path (Classic):* typo3conf/ext/my_extension/ext_localconf.php `ext_localconf.php` is always included in global scope of the script, in the frontend, backend and CLI context. It should contain additional configuration of `$GLOBALS['TYPO3_CONF_VARS']`. This file contains hook definitions and plugin configuration. It must not contain a PHP encoding declaration. All [`ext_localconf.php`](#file-extension-ext-localconf-php) files of loaded extensions are included right *after* the files `config/system/settings.php` and `config/system/additional.php` during TYPO3 [bootstrap](https://docs.typo3.org/permalink/t3coreapi:bootstrapping@13.4). Pay attention to the rules for the contents of these files. For more details, see the [section below](https://docs.typo3.org/permalink/t3coreapi:extension-configuration-files@13.4). ## Should not be used for {#ext-localconf-php-no-usage} While you *can* put functions and classes into [`ext_localconf.php`](#file-extension-ext-localconf-php), it considered bad practice because such classes and functions would *always* be loaded. Move such functionality to services or utility classes instead. Registering [hooks](https://docs.typo3.org/permalink/t3coreapi:hooks-concept@13.4), [XCLASSes](https://docs.typo3.org/permalink/t3coreapi:xclasses@13.4) 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](https://docs.typo3.org/permalink/t3coreapi:logging@13.4)) - time zone - memory limit - locales - stream wrapper - [error handler](https://docs.typo3.org/permalink/t3coreapi:error-handling-extending@13.4) - Icon registration. Icons should be registered in [Icons.php](https://docs.typo3.org/permalink/t3coreapi:extension-configuration-icons-php@13.4). This would not work because the extension files [`ext_localconf.php`](#file-extension-ext-localconf-php) are included (`loadTypo3LoadedExtAndExtLocalconf`) after the creation of the mentioned objects in the [Bootstrap](https://docs.typo3.org/permalink/t3coreapi:bootstrapping@13.4) class. In most cases, these assignments should be placed in `config/system/additional.php`. Example: [Register an exception handler](https://docs.typo3.org/permalink/t3coreapi:error-handling-extending@13.4): **config/system/additional.php | typo3conf/system/additional.php** ```php $GLOBALS['TYPO3_CONF_VARS']['SYS']['debugExceptionHandler'] = \Vendor\Ext\Error\PostExceptionsOnTwitter::class; ``` ## Should be used for {#ext-localconf-php-usage} These are the typical functions that extension authors should place within [`ext_localconf.php`](#file-extension-ext-localconf-php) - Registering [hooks](https://docs.typo3.org/permalink/t3coreapi:hooks-concept@13.4), [XCLASSes](https://docs.typo3.org/permalink/t3coreapi:xclasses@13.4) or any simple array assignments to `$GLOBALS['TYPO3_CONF_VARS']` options - Registering additional Request Handlers within the [Bootstrap](https://docs.typo3.org/permalink/t3coreapi:bootstrapping@13.4) - Adding any [page TSconfig](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/UsingSettingTSconfig/PageTSconfig.html#pagesettingdefaultpagetsconfig) - Adding default TypoScript via `\TYPO3\CMS\Core\Utility\ExtensionManagementUtility` APIs - Registering Scheduler Tasks - Adding reports to the reports module - Registering Services via the [Service API](https://docs.typo3.org/permalink/t3coreapi:services-developer-service-api@13.4) ### Examples {#ext-localconf-php-example} Put a file called [`ext_localconf.php`](#file-extension-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 skeleton of the [`ext_localconf.php`](#file-extension-ext-localconf-php) looks like this: **EXT:my_extension/ext_localconf.php** ```php Page TSconfig in a file EXT:some_extension/Configuration/page.tsconfig is loaded globally. Put all page TSconfig that must always be loaded into file [`EXT:some_extension/Configuration/page.tsconfig`](Configuration/PageTsconfig.md#file-extension-configuration-page-tsconfig). If your extension should also be compatible with TYPO3 v11, you can additionally load it in the [`ext_localconf.php`](#file-extension-ext-localconf-php): [Global page TSconfig, compatible with TYPO3 11 and 12](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/UsingSettingTSconfig/PageTSconfig.html#page-tsconfig-v11-v12): Page TSconfig that can be added in the page settings should be added in the file [`Configuration/TCA/Overrides/pages.php`](Configuration/TCA/Index.md#file-extension-configuration-tca-overridessomefile-php), see [Static page TSconfig](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/UsingSettingTSconfig/PageTSconfig.html#pagesettingstaticpagetsconfigfiles). #### Adding default user TSconfig {#adding-default-user-tsconfig} The method \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addUserTSConfig() will be removed with TYPO3 v14.0. Use Configuration/user.tsconfig instead.Extensions with compatibility for both TYPO3 v12 and v13 should keep the old way and switch to the Configuration/user.tsconfig file when v12 support is dropped. As for default page TSconfig, user TSconfig can be added inside [`ext_localconf.php`](#file-extension-ext-localconf-php), see: [Setting default user TSconfig](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/UsingSettingTSconfig/UserTSconfig.html#usersettingdefaultusertsconfig): **EXT:my_extension/ext_localconf.php** ```php