---
title: "ext_localconf.php"
manual: "TYPO3 Explained"
version: "14.3"
permalink: "https://docs.typo3.org/permalink/t3coreapi:ext-localconf-php@14.3"
source: "ExtensionArchitecture/FileStructure/ExtLocalconf.rst"
rendered: "2026-10-01T15:20:05+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@14.3).

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

## 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@14.3), [XCLASSes](https://docs.typo3.org/permalink/t3coreapi:xclasses@14.3) 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@14.3))
-   time zone
-   memory limit
-   locales
-   stream wrapper
-   [error handler](https://docs.typo3.org/permalink/t3coreapi:error-handling-extending@14.3)
-   Icon registration. Icons should be registered in
    [Icons.php](https://docs.typo3.org/permalink/t3coreapi:extension-configuration-icons-php@14.3).

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@14.3) 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@14.3):

**config/system/additional.php | typo3conf/system/additional.php**

```php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['debugExceptionHandler'] =
    \MyVendor\MyExtension\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@14.3), [XCLASSes](https://docs.typo3.org/permalink/t3coreapi:xclasses@14.3)
    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@14.3)
-   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@14.3)

### 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
<?php

declare(strict_types=1);

use MyVendor\MyExtension\MyClass;

defined('TYPO3') or die();

// Add your code here
MyClass::doSomething();

```

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