---
title: "ext_localconf.php"
manual: "TYPO3 Explained"
version: "11.5"
permalink: "https://docs.typo3.org/permalink/t3coreapi:ext-localconf-php@11.5"
source: "ExtensionArchitecture/FileStructure/ExtLocalconf.rst"
rendered: "2026-10-21T15:30:00+00:00"
---

> [!WARNING]
> **Attention**
>
> TYPO3 v11 has reached end-of-life as of October 31th 2024 and
> is no longer being maintained. Use the version switcher on the top
> left of this page to select documentation for a supported version of TYPO3.
>
> Need more time before upgrading?
> You can purchase Extended Long Term Support (ELTS) for TYPO3 v11 here:
> [TYPO3 ELTS](https://typo3.com/services/extended-support-elts).

# `ext_localconf.php` {#ext-localconf-php}

*-- optional*

`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` files of loaded extensions are
included right  *after* the files `typo3conf/LocalConfiguration.php`
and `typo3conf/AdditionalConfiguration.php` during TYPO3
[bootstrap](https://docs.typo3.org/permalink/t3coreapi:bootstrapping@11.5).

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@11.5).

## Should not be used for {#should-not-be-used-for}

While you *can* put functions and classes into `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@11.5), [XCLASSes](https://docs.typo3.org/permalink/t3coreapi:xclasses@11.5) 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@11.5))
-   time zone
-   memory limit
-   locales
-   stream wrapper
-   [error handler](https://docs.typo3.org/permalink/t3coreapi:error-handling-extending@11.5)

This would not work because the extension files `ext_localconf.php` are
included (`loadTypo3LoadedExtAndExtLocalconf`) after the creation of the
mentioned objects in the [Bootstrap](https://docs.typo3.org/permalink/t3coreapi:bootstrapping@11.5) class.

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

Example:

[Register an exception handler](https://docs.typo3.org/permalink/t3coreapi:error-handling-extending@11.5):

**typo3conf/AdditionalConfiguration.php**

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

<!-- TODO: no Markdown rendering for "deprecated" -->

Icons should be registered in Icons.php.See also: IconRegistry

## Should be used for {#should-be-used-for}

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

-   Registering [hooks](https://docs.typo3.org/permalink/t3coreapi:hooks-concept@11.5), [XCLASSes](https://docs.typo3.org/permalink/t3coreapi:xclasses@11.5)
    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@11.5)
-   Adding any [page TSconfig](https://docs.typo3.org/m/typo3/reference-tsconfig/11.5/en-us/UsingSetting/PageTSconfig.html#pagesettingdefaultpagetsconfig)
-   Adding any [user TSconfig](https://docs.typo3.org/m/typo3/reference-tsconfig/11.5/en-us/UsingSetting/UserTSconfig.html#usersettingdefaultusertsconfig)
-   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@11.5)

### Examples {#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 skeleton of the `ext_localconf.php` looks like this:

**EXT:site_package/ext_localconf.php**

```php
<?php
// all use statements must come first
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

// Prevent Script from being called directly
defined('TYPO3') or die();

// encapsulate all locally defined variables
(function () {
    // Add your code here
})();
```

Read [why the check for the TYPO3 constant is necessary](https://docs.typo3.org/permalink/t3coreapi:globals-constants-typo3@11.5).

#### Adding default page TSconfig {#adding-default-page-tsconfig}

Default page TSconfig can be added inside `ext_localconf.php`, see
[Setting the Page TSconfig globally](https://docs.typo3.org/m/typo3/reference-tsconfig/11.5/en-us/UsingSetting/PageTSconfig.html#pagesettingdefaultpagetsconfig):

**EXT:site_package/ext_localconf.php**

```php
//use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

ExtensionManagementUtility::addPageTSConfig();
```

Page TSconfig available via static files can be added inside
`Configuration/TCA/Overrides/pages.php`, see
[Static Page TSconfig](https://docs.typo3.org/m/typo3/reference-tsconfig/11.5/en-us/UsingSetting/PageTSconfig.html#pagesettingstaticpagetsconfigfiles):

**EXT:site_package/Configuration/TCA/Overrides/pages.php**

```php
ExtensionManagementUtility::registerPageTSConfigFile();
```

#### Adding default user TSconfig {#adding-default-user-tsconfig}

As for default page TSconfig, user TSconfig can be added inside
`ext_localconf.php`, see:
[Setting default user TSconfig](https://docs.typo3.org/m/typo3/reference-tsconfig/11.5/en-us/UsingSetting/UserTSconfig.html#usersettingdefaultusertsconfig):

**EXT:site_package/ext_localconf.php**

```php
//use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

ExtensionManagementUtility::addUserTSConfig();
```