---
title: "Configuration file (ext_localconf.php)"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:extension-conventions-configuration-files@main"
source: "ExtensionArchitecture/BestPractises/ConfigurationFiles.rst"
rendered: "2026-09-17T18:20:57+00:00"
---

# Configuration file (ext_localconf.php) {#configuration-file-ext-localconf-php}

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

Using the ext_tables.php file in extensions is deprecated.

The file [`ext_localconf.php`](../FileStructure/ExtLocalconf.md#file-extension-ext-localconf-php)
contains configuration used by the system and in
requests. It should therefore be optimized for speed.

See [File structure](https://docs.typo3.org/permalink/t3coreapi:extension-files-locations@main) for a full list of file and
directory names typically used in extensions.

> [!WARNING]
> The content of the file [`ext_localconf.php`](../FileStructure/ExtLocalconf.md#file-extension-ext-localconf-php) **must not** be wrapped in a
> local namespace by extension authors. This would lead to nested namespaces
> causing PHP errors that can only be solved by clearing the caches via the
> Install Tool.

## Rules and best practices {#rules-and-best-practices}

As a rule of thumb: Your [`ext_localconf.php`](../FileStructure/ExtLocalconf.md#file-extension-ext-localconf-php)
file must be designed in a way
that it 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 file's global scope -
    that would make the cached script concept break.
-   You **must not** rely on the PHP constant `__FILE__` for detection of
    the 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, for example,
    `\TYPO3\CMS\Core\Utility\GeneralUtility::getFileAbsFileName()` or
    `\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::extPath()`.
-   You **must not** wrap the file in a local namespace. This will result in
    nested namespaces.

    **Diff of EXT:my_extension/ext_localconf.php**

    ```diff
    -namespace {
    -}
    ```
-   You **can** use `use` statements:

    **Diff of EXT:my_extension/ext_localconf.php**

    ```diff
    // you can use use:
    +use TYPO3\CMS\Core\Resource\Security\FileMetadataPermissionsAspect;
    +
    +$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_tcemain.php']['processDatamapClass'][] =
    +   FileMetadataPermissionsAspect::class;
    // Instead of the full class name:
    -$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_tcemain.php']['processDatamapClass'][] =
    -   \TYPO3\CMS\Core\Resource\Security\FileMetadataPermissionsAspect::class;
    ```
-   You **can** use `declare(strict_types=1)` and similar directives which
    must be placed at the very top of files. They will be stripped and added
    once in the concatenated cache file.

    **Diff of EXT:my_extension/ext_localconf.php**

    ```diff
    // You can 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 the removed `TYPO3_MODE` or
    `TYPO3_REQUESTTYPE` constants (for example,
    `if (TYPO3_MODE === 'BE')`) or use the
    `\TYPO3\CMS\Core\Http\ApplicationType` enum within these files as
    it limits the functionality to cache the whole configuration of the system.
    Any extension author should remove the checks, and re-evaluate if these
    context-depending checks could go inside the hooks / caller function
    directly, for example, do not:

    **Diff of EXT:my_extension/ext_localconf.php**

    ```diff
    // do NOT do this:
    -if (TYPO3_MODE === 'BE')
    ```
-   You **should** check for the existence of the constant
    `defined('TYPO3') or die();`
    at the top of file [`ext_localconf.php`](../FileStructure/ExtLocalconf.md#file-extension-ext-localconf-php)
    right after the use statements 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.

    **EXT:my_extension/ext_localconf.php**

    ```php
    <?php

    declare(strict_types=1);

    // put this at top of every ext_tables.php and ext_localconf.php right after
    // the use statements
    defined('TYPO3') or die();

    ```
-   You **must** use the extension name (for example, "tt_address") instead of
    `$_EXTKEY` within the two configuration files as this variable is no
    longer loaded automatically.

The following example contains the complete code:

**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();

```

Additionally, it is possible to extend TYPO3 in a lot of different ways (adding
[TCA](https://docs.typo3.org/m/typo3/reference-tca/main/en-us/Index.html#start), [backend routes](https://docs.typo3.org/permalink/t3coreapi:backend-routing@main),
[Symfony console commands](https://docs.typo3.org/permalink/t3coreapi:symfony-console-commands@main), etc), which do not
need to touch these files.

> [!TIP]
> `\TYPO3\CMS\Core\Package\PackageManager::getActivePackages()` contains
> information about whether the module is loaded as *local* or *system* type
> in the `packagePath` key, including the proper paths you might use, absolute
> and relative.