---
title: "Feature toggle API"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:feature-toggles@main"
source: "ApiOverview/FeatureToggleApi/Index.rst"
modified: "2026-09-17T05:14:57+00:00"
---

# Feature toggle API

TYPO3 provides an API class for creating so-called "feature toggles". Feature
toggles provide an easy way to add new implementations of features next to their
legacy version. By using a feature toggle, the integrator or site administrator
can decide when to switch to the new feature.

The API checks against a system-wide option array within
`$GLOBALS['TYPO3_CONF_VARS']['SYS']['features']` which an integrator or
admininistrator can set in the `config/system/settings.php` file. Both
TYPO3 Core and extensions can provide alternative functionality for a certain
feature.

Examples for features are:

-   Throw exceptions in new code instead of just returning a string message as
    error message.
-   Disable obsolete functionality which might still be used, but slows down the
    system.
-   Enable alternative "page not found" handling for an installation.

****Table of Contents****

-   [Naming of feature toggles](https://docs.typo3.org/permalink/t3coreapi:naming-of-feature-toggles@main)
-   [Using the API as extension author](https://docs.typo3.org/permalink/t3coreapi:using-the-api-as-extension-author@main)
-   [Core feature toggles](https://docs.typo3.org/permalink/t3coreapi:core-feature-toggles@main)
-   [Enable / disable feature toggle](https://docs.typo3.org/permalink/t3coreapi:enable-disable-feature-toggle@main)
-   [Feature toggles in TypoScript](https://docs.typo3.org/permalink/t3coreapi:feature-toggles-in-typoscript@main)
-   [Feature toggles in Fluid](https://docs.typo3.org/permalink/t3coreapi:feature-toggles-in-fluid@main)

## Naming of feature toggles

Feature names should NEVER be named "enable" or have a negation, or contain
versions or years. It is recommended to use "lowerCamelCase" notation for the
feature names.

Bad examples:

-   `enableFeatureXyz`
-   `disableOverlays`
-   `schedulerRevamped2018`
-   `useDoctrineQueries`
-   `disablePreparedStatements`
-   `disableHooksInFE`

Good examples:

-   `extendedRichtextFormat`
-   `nativeYamlParser`
-   `inlinePageTranslations`
-   `typoScriptParserIncludesAsXml`
-   `nativeDoctrineQueries`

## Using the API as extension author

For extension authors, the API can be used for any custom feature provided by an
extension.

To register a feature and set the default state, add the following to the
[`ext_localconf.php`](../../ExtensionArchitecture/FileStructure/ExtLocalconf.md#file-extension-ext-localconf-php) file of your extension:

**EXT:some_extension/ext_localconf.php**

```php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['features']['myFeatureName'] ??= true; // or false;
```

To check if a feature is enabled, use this code:

**EXT:some_extension/Classes/SomeClass.php**

```php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension;

use TYPO3\CMS\Core\Configuration\Features;

final class SomeClass
{
  public function __construct(
    private readonly Features $features,
  ) {}

  public function doSomething(): void
  {
    if ($this->features->isFeatureEnabled('myFeatureName')) {
      // do custom processing
    }

    // ...
  }
}

```

> [!WARNING]
> **Attention**
>
> Currently, only the Core features can be (de-)activated in the Install Tool.
>
> To change the setting for your extension feature either use
> `config/system/settings.php` or `config/system/additional.php`
> files like:
>
> **config/system/additional.php | typo3conf/system/additional.php**
>
> ```php
> $GLOBALS['TYPO3_CONF_VARS']['SYS']['features']['myFeatureName'] = true;
> ```

The name can be any arbitrary string, but an extension author should prefix the
feature with the extension name as the features are global switches which
otherwise might lead to naming conflicts.

## Core feature toggles

Some examples of feature toggles in the TYPO3 Core:

-   `redirects.hitCount`: Enables hit statistics in the redirects backend module
-   `security.backend.enforceReferrer`: If on, HTTP referrer headers are enforced
    for backend and install tool requests to mitigate potential same-site

request forgery attacks.

> [!NOTE]
> **New in version 14.2**

-   `extbase.enableHistoryTracking`: Enables tracking of history for Extbase
    domain entities by listening to Extbase persistence events and storing them
    in the `sys_history` table. If enabled, it is enabled for all extbase
    entities but can be disabled for individual extbase storage tables in
    their TCA:

**EXT:my_extension/Configuration/TCA/tx_myextension_domain_model_blog.php (excerpt)**

```php
<?php

declare(strict_types=1);

return [
  'ctrl' => [
    'title' => 'my_extension.messages:my_title',
    'label' => 'uid',
    'tstamp' => 'tstamp',
    'crdate' => 'crdate',
    'delete' => 'deleted',
    // ...
    'extbase' => [
      'enableHistoryTracking' => false,
    ],
  ],
  'columns' => [
    // ...
  ],
];

```

> [!NOTE]
> Enabling history tracking can create many history entries
> for extbase entities. They will also be mixed with regular editorial
> changes to extbase entities performed in the TYPO3 backend (FormEngine).

> [!IMPORTANT]
> All differences to data in Extbase entities are now logged, and the initial
> logging will contain all properties. Take note that this can affect
> GDPR / DSGVO / security-related data storage precautions, and data might need to be
> regularly pruned. It might be advisable to turn off history tracking for
> tables with "private" data. Because of this, the feature toggle
> is set to "false" by default, so an instance-wide opt-in for this is required.

## Enable / disable feature toggle

Features can be toggled in the **System > Settings** module via
**Feature Toggles**:

![Feature toggles in module System > Settings](../../Images/ManualScreenshots/AdminTools/FeatureToggles.png)

Internally, the changes are written to `config/system/settings.php`:

**config/system/settings.php**

```php
<?php

return [
  'SYS' => [
    'features' => [
      'redirects.hitCount' => true,
    ],
  ],
];

```

> [!NOTE]
> If the `config/system/settings.php` file is write-protected an info
> box is rendered. In that case, all input fields are disabled and the save
> button is not available.

## Feature toggles in TypoScript

One can check whether a feature is enabled in TypoScript with the function
`feature()`:

**EXT:some_extension/Configuration/Sets/SomeExtension/setup.typoscript**

```typoscript
[feature("unifiedPageTranslationHandling")]
    # This condition matches if the feature toggle "unifiedPageTranslationHandling" is true
[END]
```

## Feature toggles in Fluid

The [Feature ViewHelper \<f:feature>](https://docs.typo3.org/other/typo3/view-helper-reference/main/en-us/Global/Feature.html#typo3-fluid-feature) can be used to check for a feature in a Fluid
template:

**EXT:my_extension/Resources/Private/Templates/SomeTemplate.fluid.html**

```html
<f:feature name="unifiedPageTranslationHandling">
   This is being shown if the flag is enabled
</f:feature>
```