Environment Indicator 

Extension key

typo3_environment_indicator

Package name

konradmichalik/typo3-environment-indicator

Version

3.5

Language

en

Author

Konrad Michalik & contributors

License

This extension documentation is published under the CC BY-NC-SA 4.0 (Creative Commons) license.

This extension provides several features to show an environment indicator in the TYPO3 frontend and backend.

Introduction 

Features 

Combine trigger and indicator classes to show the environment in the TYPO3 frontend and backend. The extension provides several trigger and indicator classes out of the box. You can also create your own trigger and indicator classes.

Frontend + Backend 

Icon	Preview	Description
		Modified favicon: Modifies the favicon for frontend and backend based on the original favicon, current environment and your configuration.
		Page title: Prefix or suffix the page title in frontend and backend with the current application context.

Frontend 

Icon	Preview	Description
		Frontend Hint: Adds an informative hint to the frontend showing the website title and current environment.
		Modified frontend image: Modifies the frontend image based on the original image, current environment and your configuration.

Backend 

Icon	Preview	Description
		Backend toolbar item: Adds an informative item to the backend toolbar showing the current environment.
		Backend topbar: Colors the backend header topbar according to the environment.
		Modified backend logo: Modifies the backend logo based on the original logo, current environment and your configuration.
		Dashboard widget: Render a dashboard widget according to the environment.
		Backend theme (experimental): Colors the entire TYPO3 v14+ backend (primary color, header, sidebar) based on the environment.
		Backend login: Shows a colored environment badge directly on the backend login screen.

Misc 

Icon	Preview	Description
		CLI banner: Prints a colored environment banner to the console before a command runs.
		Mail subject prefix: Prepends the environment to the subject of every mail sent through the TYPO3 Mailer API.

Installation 

composer require konradmichalik/typo3-environment-indicator

base: 'https://example.com/'
rootPageId: 1
dependencies:
  - konradmichalik/typo3-environment-indicator

@import 'EXT:typo3_environment_indicator/Configuration/TypoScript/setup.typoscript'

Configuration 

The extension is ready to use without any further setup.

By default the following environment are preset:

• Production/Standby
• Production/Staging
• Production/Stage
• Testing*
• Development*

You can adapt the extension to your needs, switch single features on and off and influence the presentation of the indicators.

If you want to add your own indicators, you should disable the default configuration within the extension configuration.

Extension configuration 

1. Go to Admin Tools > Settings > Extension Configuration
2. Choose typo3_environment_indicator

The extension currently provides the following configuration options:

Handler 

The Handler class is used to register the indicators and triggers in the TYPO3 backend. The class provides a static method addIndicator() to add the indicators and triggers to the system.

See the configuration for triggers and indicators.

\KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler::addIndicator(
    triggers: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\FrontendUserGroup(1,2)
    ],
    indicators: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator\Backend\Topbar([
            'color' => '#00ACC1',
        ]),
    ]
);

Indicators 

Indicators are hints about the current environment that are shown discreetly in the frontend and/or backend.

You can combine multiple indicators.

\KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler::addIndicator(
    triggers: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\ApplicationContext('Development'),
    ],
    indicators: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator\Favicon([
            new \KonradMichalik\Typo3EnvironmentIndicator\Image\Modifier\TextModifier([
                'text' => 'TEST',
                'color' => '#f39c12',
                'stroke' => [
                    'color' => '#ffffff',
                    'width' => 3,
                ],
            ])
        ]),
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator\Frontend\Hint([
            'color' => '#FFF176',
        ]),
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator\Backend\Topbar([
            'color' => '#00ACC1',
        ]),
    ]
);

The following indicators are available:

Frontend + Backend 

Icon	Indicator	Description
	Favicon	Modify the favicon for frontend and backend based on the original favicon, the current application context and your configuration.
	Page Title	Prefix or suffix the page title in frontend and backend with the current application context.
	Console	Print a styled environment badge to the browser console in frontend and backend.

Frontend 

Icon	Indicator	Description
	Frontend Hint	Adds an informative hint to the frontend showing the website title and the current application context.
	Frontend Image	Modify a frontend image based on the original image, the current application context and your configuration.
	Frontend HTTP Header	Add a configurable HTTP response header with the current application context to frontend responses.
	Frontend Robots	Send an X-Robots-Tag header to keep non-production environments out of search engines.
	Console	Print a styled environment badge to the browser console on page load.

Backend 

Icon	Indicator	Description
	Backend toolbar item	Adds an informative item with the current application context to the backend toolbar.
	Backend topbar	Colorize the backend header topbar regarding the application context.
	Backend Logo	Modify the backend logo based on the original logo, the current application context and your configuration.
	Dashboard Widget	Render a dashboard widget according to the environment.
	Backend theme (experimental)	Colorize the entire TYPO3 v14+ backend (primary color, header, sidebar) based on the environment.
	Backend Login	Show a colored environment badge directly on the backend login screen.

Misc 

Icon	Indicator	Description
	CLI Banner	Print a colored environment banner to stderr before an interactive console command runs.
	Mail Subject Prefix	Prepend the current application context to the subject of every mail sent through the TYPO3 Mailer API.

Favicon 

The favicon of the frontend or backend context will be modified regarding the environment and the associated configuration.

<html xmlns:env="http://typo3.org/ns/KonradMichalik/Typo3EnvironmentIndicator/ViewHelpers"
    data-namespace-typo3-fluid="true">

{f:uri.resource(path:'EXT:your_extension/Resources/Public/Favicon/favicon.png') -> env:favicon()}
{env:favicon(favicon:'EXT:your_extension/Resources/Public/Favicon/favicon.png')}

Backend 

For the backend, the favicon will be fetched by the extension configuration of $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['backend']['backendFavicon'].

Warning

SVG favicons (and backend logos) are rasterized to PNG before modification. During rasterization, embedded <image> references inside the SVG are resolved and loaded. Only use SVG source files from trusted locations as indicator base images — an untrusted SVG could reference arbitrary local or remote resources.

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;
use KonradMichalik\Typo3EnvironmentIndicator\Enum\Scope;
use KonradMichalik\Typo3EnvironmentIndicator\Image;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Development*'),
    ],
    indicators: [
        // Only modify the frontend favicon
        new Indicator\Favicon(
            configuration: [
                new Image\Modifier\TextModifier([
                    'text' => 'DEV',
                    'color' => '#bd593a',
                ]),
            ],
            scope: Scope::Frontend,
        ),
    ],
);

Modifiers 

The favicon modification configuration can be found in $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['typo3_environment_indicator'].

Add a configured favicon modifier to the desired environment (e.g. Testing) in your ext_localconf.php:

ext_localconf.php

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;
use KonradMichalik\Typo3EnvironmentIndicator\Image;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Testing')
    ],
    indicators: [
        new Indicator\Favicon([
            new Image\Modifier\TextModifier([
                'text' => 'TEST',
                'color' => '#f39c12',
                'stroke' => [
                    'color' => '#ffffff',
                    'width' => 3,
                ],
            ])
        ])
    ]
);

Copied!

The modifiers will be executed one after the other. You can combine them if you want.

The following modifier classes are available:

TextModifier 

This is the default modifier if no own configuration is set.

ext_localconf.php

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;
use KonradMichalik\Typo3EnvironmentIndicator\Image;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Development')
    ],
    indicators: [
        new Indicator\Favicon([
            new Image\Modifier\TextModifier([
                'text' => 'DEV',
                'color' => '#bd593a',
                'stroke' => [
                    'color' => '#ffffff',
                    'width' => 3,
                ],
            ])
        ])
    ]
);

Copied!

Additional optional configuration keys:

• font (string): The font file path for the text. Default is EXT:typo3_environment_indicator/Resources/Public/Fonts/OpenSans-Bold.ttf.
• position (string): The position of the text. Default is top. Possible values are bottom, top.
• stroke (array): Optional stroke configuration for the text outline. If set, it requires the sub-keys color (string) and width (numeric).

See also

View the sources on GitHub:

• TextModifier

TriangleModifier 

Adds a triangle indicator to the favicon.

ext_localconf.php

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;
use KonradMichalik\Typo3EnvironmentIndicator\Image;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Development')
    ],
    indicators: [
        new Indicator\Favicon([
            new Image\Modifier\TriangleModifier([
                'color' => '#bd593a',
            ])
        ])
    ]
);

Copied!

Additional optional configuration keys:

• size (float): The percentage size of the triangle. Default is 0.7.
• position (string): The position of the triangle. Default is bottom right. Possible values are bottom left, bottom right, top left, top right.

See also

View the sources on GitHub:

• TriangleModifier

CircleModifier 

Adds a circle indicator to the favicon.

ext_localconf.php

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;
use KonradMichalik\Typo3EnvironmentIndicator\Image;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Development')
    ],
    indicators: [
        new Indicator\Favicon([
            new Image\Modifier\CircleModifier([
                'color' => '#bd593a',
            ])
        ])
    ]
);

Copied!

Additional optional configuration keys:

• size (float): The percentage size of the circle. Default is 0.4.
• position (string): The position of the circle. Default is bottom right. Possible values are top left, top center, top right, center left, center, center right, bottom left, bottom center, bottom right.
• padding (float): The percentage padding of the circle. Default is 0.1.

See also

View the sources on GitHub:

• CircleModifier

FrameModifier 

Adds a frame around the favicon.

ext_localconf.php

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;
use KonradMichalik\Typo3EnvironmentIndicator\Image;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Development')
    ],
    indicators: [
        new Indicator\Favicon([
            new Image\Modifier\FrameModifier([
                'color' => '#bd593a',
            ])
        ])
    ]
);

Copied!

Additional optional configuration keys:

• borderSize (float): The border size of the frame. Default is 5.

See also

View the sources on GitHub:

• FrameModifier

ReplaceModifier 

Replace the original favicon with a custom one regarding the environment.

ext_localconf.php

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;
use KonradMichalik\Typo3EnvironmentIndicator\Image;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Development')
    ],
    indicators: [
        new Indicator\Favicon([
            new Image\Modifier\ReplaceModifier([
                'path' => 'EXT:sitepackage/Resources/Public/Icons/favicon.png',
            ])
        ])
    ]
);

Copied!

See also

View the sources on GitHub:

• ReplaceModifier

OverlayModifier 

Overlay an additional image to the original favicon regarding the environment.

ext_localconf.php

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;
use KonradMichalik\Typo3EnvironmentIndicator\Image;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Development')
    ],
    indicators: [
        new Indicator\Favicon([
            new Image\Modifier\OverlayModifier([
                'path' => 'EXT:sitepackage/Resources/Public/Icons/favicon.png',
            ])
        ])
    ]
);

Copied!

Additional configuration keys (required by the modifier, but provided via default configuration):

• size (float): The percentage size of the overlay. Default is 0.5.
• position (string): The position of the overlay. Default is bottom right. Possible values are top left, top center, top right, center left, center, center right, bottom left, bottom center, bottom right.
• padding (float): The percentage padding of the overlay. Default is 0.1.

See also

View the sources on GitHub:

• OverlayModifier

ColorizeModifier 

Colorize the original favicon with a specific color regarding the environment.

Warning

This modifier is only available with "Imagick" image driver.

ext_localconf.php

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;
use KonradMichalik\Typo3EnvironmentIndicator\Image;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Development')
    ],
    indicators: [
        new Indicator\Favicon([
            new Image\Modifier\ColorizeModifier([
                'color' => '#039BE5',
            ])
        ])
    ]
);

Copied!

Additional optional configuration keys:

• opacity (float): Controls the opacity of the colorization. Default is 1.
• brightness (integer): Controls the brightness of the colorization. Possible values are from -100 to 100.
• contrast (integer): Controls the contrast of the colorization. Possible values are from -100 to 100.

See also

View the sources on GitHub:

• ColorizeModifier

Note

If you want to modify the image to your own need, implement a custom modifier class and add it to the configuration.

Frontend Hint 

The frontend hint will show the current environment information and the website title as clickable note in the upper right corner.

You can adjust the color of the hint in your ext_localconf.php:

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Testing')
    ],
    indicators: [
        new Indicator\Frontend\Hint([
            'color' => '#bd593a',
        ])
    ]
);

Additional optional configuration keys:

• text (string): The text of the hint. Default is the website title.
• position (string): The corner the hint starts in. Default is top left. Possible values are top left, top right, bottom left and bottom right. Any other value falls back to the default.
• description (string): An optional description. When set, it is appended to the hint's tooltip (title attribute). Default is empty.

Moving the hint out of the way 

New in version 3.5

Dragging the hint to another corner and closing it for the session were added in TYPO3 Environment Indicator 3.5.

Warning

This version also removed the internal ContextUtility::getPositionX() and getPositionY() userFuncs in favor of a single getPositionClass() . A stale TypoScript cache still referencing the removed userFuncs causes a 500 error, so flush the TYPO3 caches right after updating.

The hint is positioned relative to the viewport, so it stays visible while scrolling. If it covers something you need to see, drag it to another corner: on release it snaps to whichever of the four corners is nearest.

The chosen corner is stored in localStorage and takes precedence over the configured position from then on. Because Web Storage is scoped per origin, every environment remembers its own corner independently.

Frontend Image 

The frontend image will be modified regarding the environment and the associated configuration.

The image path can be adjusted via the ImageViewHelper:

<html xmlns:env="http://typo3.org/ns/KonradMichalik/Typo3EnvironmentIndicator/ViewHelpers"
    data-namespace-typo3-fluid="true">

{f:uri.resource(path:'EXT:your_extension/Resources/Public/Image/Default.png') -> env:image()}
{env:image(path:'EXT:your_extension/Resources/Public/Image/Default.png')}

Modifiers 

The frontend image modification is identical to the favicon modification. You can use the same modifiers and configuration.

ext_localconf.php

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;
use KonradMichalik\Typo3EnvironmentIndicator\Image;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Testing')
    ],
    indicators: [
        new Indicator\Frontend\Image([
            new Image\Modifier\TextModifier([
                'text' => 'TEST',
                'color' => '#f39c12',
                'stroke' => [
                    'color' => '#ffffff',
                    'width' => 3,
                ],
            ])
        ])
    ]
);

Copied!

Frontend HTTP Header 

Besides the visual indicators, an environment marker on HTTP level is useful for the "developer view": debugging, curl checks, uptime monitoring and browser extensions can identify the environment without parsing the page.

The indicator adds a configurable header to every frontend response:

X-TYPO3-Environment: Development

You can register the indicator in your ext_localconf.php:

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Development*')
    ],
    indicators: [
        new Indicator\Frontend\HttpHeader()
    ]
);

Additional optional configuration keys:

• name (string): The header name. Default is X-TYPO3-Environment.
• value (string): The header value. Default is %context%. The placeholder %context% is replaced with the current application context.

A name or value that is not valid per 9110 is ignored and logged as a warning, so a misconfiguration cannot break frontend rendering.

The environment HTTP header can be disabled globally via the extension configuration.

Frontend Robots 

Accidentally indexed staging environments are a common and expensive problem: duplicate content competing with the live site, internal drafts surfacing in search results, and clean-up work that takes weeks. This indicator signals the environment to crawlers so non-production content does not end up in search engines in the first place.

It adds an X-Robots-Tag header to every frontend response:

X-Robots-Tag: noindex, nofollow

You can register the indicator in your ext_localconf.php:

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Testing/Staging')
    ],
    indicators: [
        new Indicator\Frontend\Robots()
    ]
);

Additional optional configuration keys:

• content (string): The header value. Default is noindex, nofollow. A value that is not valid per 9110 is ignored and logged as a warning.

The X-Robots-Tag header can be disabled globally via the extension configuration.

Console 

Developers usually have the browser console open anyway. This indicator prints a styled environment badge to the console on every page load — more subtle than the visible Frontend Hint, but unambiguous for the "developer view", and it never covers page content.

DEVELOPMENT

The badge is printed in the frontend and in the backend, so the environment stays identifiable while working in a module as well.

You can register the indicator in your ext_localconf.php:

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Development*')
    ],
    indicators: [
        new Indicator\General\Console([
            'color' => '#bd593a',
        ])
    ]
);

Additional optional configuration keys:

• text (string): The badge text. Default is %context%, which is replaced with the current application context. An empty text disables the badge.
• color (string): The badge background color. Default is #767676. The text color is derived automatically for optimal contrast.

The console badge can be disabled per scope via the extension configuration: frontend.console and backend.console.

Backend toolbar item 

The backend toolbar item will show the current project version and environment.

You can adjust the color of the toolbar item in your ext_localconf.php:

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Testing')
    ],
    indicators: [
        new Indicator\Backend\Toolbar([
            'color' => '#bd593a',
        ])
    ]
);

Additional optional configuration keys:

• text (string): The text of the toolbar item. Default is the application context.
• icon (array): The icon configuration of the toolbar item. Expects a nested array with a context key. Default is ['context' => 'information-application-context'].
• index (int): The positioning index of the toolbar item. Default is 0.
• description (string): An optional description. When set, it is appended to the toolbar item's tooltip (title attribute). Default is empty.

Backend topbar 

The backend toolbar item will show the current project version and environment.

You can adjust the color of the topbar in your ext_localconf.php:

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Testing')
    ],
    indicators: [
        new Indicator\Backend\Topbar([
            'color' => '#bd593a',
        ])
    ]
);

Additional optional configuration keys:

• description (string): An optional description. When set, it is shown as a tooltip (title attribute) on the colored topbar. Plain text only. Default is empty.

Backend Logo 

The backend logo will be modified regarding the environment and the associated configuration. This can be used to e.g. show the current environment in the website logo.

The backend logo will be fetched by the extension configuration of $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['backend']['backendLogo'].

Modifiers 

The backend logo modification is identical to the favicon modification. You can use the same modifiers and configuration.

ext_localconf.php

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;
use KonradMichalik\Typo3EnvironmentIndicator\Image;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Testing')
    ],
    indicators: [
        new Indicator\Backend\Logo([
            new Image\Modifier\TextModifier([
                'text' => 'TEST',
                'color' => '#f39c12',
                'stroke' => [
                    'color' => '#ffffff',
                    'width' => 3,
                ],
            ])
        ])
    ]
);

Copied!

Dashboard Widget 

The dashboard widget can be placed to the TYPO3 backend dashboard. It shows the current environment regarding the configuration.

The widget is registered with its own icon (identifier environment-indicator-widget), which is shown in the widget selection dialog:

You can adjust the widget configuration in your ext_localconf.php:

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Development/Text')
    ],
    indicators: [
        new Indicator\Backend\Widget([
            'color' => '#bd593a',
        ])
    ]
);

Additional optional configuration keys:

• text (string): The text of the widget. Default is the application context.
• icon (string): The icon of the widget. Default is information-application-context.
• textSize (string): The text size of the widget. Default is 20px.
• description (string): An optional description shown as an additional paragraph in the widget body. Plain text only (HTML is escaped). Default is empty.

The dashboard widget can not disappear, if no configuration is set. It is always shown in the backend dashboard.

Backend theme 

The backend theme indicator colors the entire TYPO3 backend by overriding CSS custom properties introduced with the TYPO3 v14 Fresh theme. Instead of modifying individual elements, it sets the primary accent color and scaffold variables, which automatically cascade through the backend UI - including the topbar, sidebar, buttons, active states, and focus rings.

This works with all TYPO3 backend themes (Fresh, Modern, Classic) and supports both light and dark mode.

You can adjust the theme in your ext_localconf.php:

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Development*'),
    ],
    indicators: [
        new Indicator\Backend\Theme([
            'color' => '#bd593a',
        ]),
    ],
);

Configuration keys:

• color (string): The primary accent color as hex value. Required.
• scaffoldHeader (bool): Whether to color the backend header. Default is true.
• scaffoldSidebar (bool): Whether to color the backend sidebar. Default is true.
• neutralMix (string): The neutral tinting strength as CSS percentage value. Default is '15%'.

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Development*'),
    ],
    indicators: [
        new Indicator\Backend\Theme([
            'color' => '#bd593a',
            'scaffoldHeader' => true,
            'scaffoldSidebar' => true,
            'neutralMix' => '20%',
        ]),
    ],
);

Backend Login 

All other backend indicators only take effect after login (topbar, toolbar, logo, theme). Yet the moment with the highest risk of confusion is the login itself — anyone who accidentally logs into live instead of staging only notices afterwards. The backend login indicator closes this gap by showing a colored environment badge directly on the backend login screen.

The badge is injected via a listener on the ModifyPageLayoutOnLoginProviderSelectionEvent . It is attached directly to the login card (above the logo, or below the card footer), matching the card's rounded corners and font. If the login card markup is not found — e.g. with an alternative login provider (OIDC/SSO extensions) — it falls back to a full-width banner at the top or bottom of the page.

You can register the indicator in your ext_localconf.php:

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Production/Staging')
    ],
    indicators: [
        new Indicator\Backend\Login([
            'text' => 'Staging',
            'color' => '#00ACC1',
        ])
    ]
);

Additional optional configuration keys:

• text (string): The badge text. Default is the current application context.
• color (string): The badge background color as a hex value. Default is #bd593a. The text color is calculated automatically for optimal contrast.
• position (string): The badge position, top or bottom. Default is top.
• description (string): An optional descriptive line shown below the badge text (e.g. "Data is overwritten nightly from live").

The backend login badge can be disabled globally via the extension configuration.

Page Title 

The favicon indicator fails exactly where editors and developers work a lot: pinned tabs (favicon too small or hidden), bookmarks, browser history and task switchers. A prefix or suffix in the <title> — e.g. [STAGING] Page title — makes the environment instantly recognizable in all of these contexts. It is a perfect complement to the favicon indicator.

The indicator works in both frontend and backend:

• Frontend: a middleware decorates the final <title> after the PageTitle API has resolved, so all existing page title providers (including SEO extensions) remain untouched.
• Backend: the document title is prefixed/suffixed client-side. A MutationObserver re-applies the decoration on backend SPA navigation (module switches), so the prefix persists.

You can register the indicator in your ext_localconf.php:

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Production/Staging')
    ],
    indicators: [
        new Indicator\General\PageTitle([
            'prefix' => '[%context%] ',
        ])
    ]
);

Additional optional configuration keys:

• prefix (string): Prepended to the page title (e.g. [STAGING] ). Default is [%context%] . The placeholder %context% is replaced with the current application context.
• suffix (string): Appended to the page title. Also supports the %context% placeholder. Default is empty.

The page title indicator can be disabled per context via the extension configuration (frontend.pageTitle and backend.pageTitle).

CLI Banner 

The classic "wrong SSH terminal" scenario is the CLI counterpart to the original motivation of this extension: running an import, a custom deployment command or impexp:import on the live system instead of staging. The CLI banner prints an environment banner with a colored background to stderr before a console command runs, e.g. a cyan bar reading 🚦 STAGING — project.example.dev.

The banner is printed via a listener on the Symfony Console ConsoleCommandEvent , so it appears before the command is executed. It is written to stderr, so parsed stdout output (JSON, CSV) stays untouched.

You can register the indicator in your ext_localconf.php:

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Production/Staging')
    ],
    indicators: [
        new Indicator\Cli\Banner([
            'text' => 'STAGING',
            'color' => 'cyan',
        ])
    ]
);

Additional optional configuration keys:

• text (string): The banner text. Default is the current application context.
• color (string): The banner background color. Accepts a named ANSI color (e.g. cyan, red, yellow) or a hex value (e.g. #00ACC1, rendered on truecolor terminals) and is combined with bold white text. Default is no color (plain text, no background).
• icon (string): A leading glyph. Default is 🚦.
• commands (array): A whitelist of command name patterns (fnmatch syntax, e.g. ['site:*', 'impexp:*']). If set, the banner is only printed for matching commands. Default is empty (the banner is printed for all commands).

The CLI banner is opt-in and disabled by default — enable it globally via the extension configuration.

Mail Subject Prefix 

Test and staging systems regularly send real emails — form submissions, workflow notifications, scheduler reports. Recipients often cannot tell whether a mail originates from the live system or a test system. The mail subject prefix indicator prepends the environment to the subject of every mail sent through the TYPO3 Mailer API (e.g. [Staging] Your registration), so the origin is visible at first glance in every inbox.

The prefix is applied via a listener on the BeforeMailerSentMessageEvent , covering all mails sent via TYPO3's Mailer API (frontend forms, backend notifications, scheduler tasks).

You can register the indicator in your ext_localconf.php:

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Testing')
    ],
    indicators: [
        new Indicator\Mail\SubjectPrefix([
            'prefix' => '[%context%] ',
        ])
    ]
);

Additional optional configuration keys:

• prefix (string): The prefix prepended to the mail subject. Default is [%context%] . The placeholder %context% is replaced with the current application context.
• header (string): If set, an additional mail header with this name and the application context as value is added (e.g. X-Environment: Testing) for filtering/tooling. Default is empty (no header is added).

The mail subject prefix can be disabled globally via the extension configuration.

Triggers 

Triggers act as conditions and are used to define when environment indicators should be shown.

You can combine multiple different triggers within a single Handler::addIndicator() call. All triggers must return true (AND logic) for the associated indicators to activate.

\KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler::addIndicator(
    triggers: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\ApplicationContext('Development'),
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\Admin()
    ],
    indicators: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator\Backend\Topbar([
            'color' => '#00ACC1',
        ]),
    ]
);

There are several triggers available, which can be used to show the indicators in different contexts.

Admin 

The Admin trigger is used to show the indicators in the TYPO3 backend for admin users.

\KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler::addIndicator(
    triggers: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\Admin()
    ],
    indicators: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator\Backend\Topbar([
            'color' => '#00ACC1',
        ]),
    ]
);

Application Context 

The ApplicationContext trigger is used to show the indicators in the TYPO3 backend for a specific application context.

\KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler::addIndicator(
    triggers: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\ApplicationContext('Development*', 'Testing')
    ],
    indicators: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator\Backend\Topbar([
            'color' => '#00ACC1',
        ]),
    ]
);

The configuration supports multiple context names as separate arguments. The context names support glob-style wildcard patterns (using PHP's fnmatch()). The * wildcard matches any number of characters and the ? wildcard matches a single character. For example, Development* will match all contexts that start with Development, such as Development, Development/Local, Development/DDEV, etc.

Backend User Group 

The BackendUserGroup trigger is used to show the indicators in the TYPO3 backend for specific backend user groups.

\KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler::addIndicator(
    triggers: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\BackendUserGroup(1,2)
    ],
    indicators: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator\Backend\Topbar([
            'color' => '#00ACC1',
        ]),
    ]
);

The configuration supports multiple group IDs as separate arguments. The trigger passes if the current backend user is a member of any of the specified groups (OR logic).

Color Scheme 

The ColorScheme trigger is used to show the indicators depending on the color scheme (light, dark or auto) the backend user has selected.

This is mainly useful for image-based indicators such as Backend Logo or Favicon. Those indicators are rendered into a raster image, so a single fixed appearance cannot adapt to the backend theme on its own. Registering one configuration per color scheme produces a separate image for each.

\KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler::addIndicator(
    triggers: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\ApplicationContext('Development*'),
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\ColorScheme('light', 'auto')
    ],
    indicators: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator\Backend\Logo([
            new \KonradMichalik\Typo3EnvironmentIndicator\Image\Modifier\TextModifier([
                'text' => 'DEV',
                'color' => '#000000',
            ]),
        ]),
    ]
);

\KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler::addIndicator(
    triggers: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\ApplicationContext('Development*'),
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\ColorScheme('dark')
    ],
    indicators: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator\Backend\Logo([
            new \KonradMichalik\Typo3EnvironmentIndicator\Image\Modifier\TextModifier([
                'text' => 'DEV',
                'color' => '#ffffff',
            ]),
        ]),
    ]
);

The configuration supports multiple color schemes as separate arguments. Allowed values are light, dark and auto. Any other value will throw an InvalidArgumentException during construction.

Custom 

The Custom trigger is used to show the indicators in the TYPO3 backend for custom conditions.

\KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler::addIndicator(
    triggers: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\Custom(
            function () {
                return true;
            }
        ),
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\Custom('\YourExtension\YourClass::yourMethod'),
    ],
    indicators: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator\Backend\Topbar([
            'color' => '#00ACC1',
        ]),
    ]
);

The configuration supports a callable function, which is executed to determine if the indicator should be shown. The function should return a boolean value. The function can also be a closure or an anonymous function.

When using a string reference, it must follow the format ClassName::methodName (without parentheses). The referenced method must be public and static. If the method throws an exception during execution, the trigger will return false.

Frontend User Group 

The FrontendUserGroup trigger is used to show the indicators in the TYPO3 Frontend for specific frontend user groups.

\KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler::addIndicator(
    triggers: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\FrontendUserGroup(1,2)
    ],
    indicators: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator\Backend\Topbar([
            'color' => '#00ACC1',
        ]),
    ]
);

The configuration supports multiple group IDs as separate arguments. The trigger passes if the current frontend user is a member of any of the specified groups (OR logic). If no frontend user session is available, the trigger returns false.

IP Address 

The IP trigger is used to show the indicators in the TYPO3 backend for specific IP addresses.

\KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler::addIndicator(
    triggers: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\Ip('127.0.0.1', '192.168.0.0/24')
    ],
    indicators: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator\Backend\Topbar([
            'color' => '#00ACC1',
        ]),
    ]
);

The configuration supports multiple IP addresses as separate arguments. Both IPv4 and IPv6 addresses are supported. CIDR range notation is also supported for both address families (e.g. 192.168.0.0/24 or 2001:db8::/32). Invalid IP formats will throw an InvalidArgumentException during construction.

Theme 

The Theme trigger is used to show the indicators depending on the backend theme (fresh, modern or classic) the backend user has selected.

This is mainly useful together with Color Scheme. The backend theme and the color scheme are independent user settings, and they do not treat each other equally: the classic theme renders the topbar with color-scheme: only dark, so its header stays dark no matter which color scheme is selected. An image based indicator registered only for the light color scheme would then appear on a dark header for those users.

\KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler::addIndicator(
    triggers: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\ApplicationContext('Development*'),
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\ColorScheme('light', 'auto'),
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\Theme('classic')
    ],
    indicators: [
        new \KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator\Backend\Logo([
            // light color scheme, but a dark header — so use the light-on-dark variant
            new \KonradMichalik\Typo3EnvironmentIndicator\Image\Modifier\TextModifier([
                'text' => 'DEV',
                'color' => '#ffffff',
            ]),
        ]),
    ]
);

The configuration supports multiple themes as separate arguments.

Developer corner 

Some kinds of the environment indicators are configurable or can be extended with custom implementations. This section provides an insight into which development options are available and how these can be integrated into the generation process.

Custom triggers and indicators 

Beyond the built-in triggers and indicators, you can create your own implementations to match custom conditions or render custom indicators.

<?php

namespace Vendor\YourExt\Configuration\Trigger;

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger\TriggerInterface;

class MyCustomTrigger implements TriggerInterface
{
    public function __construct(
        private readonly string $expectedValue,
    ) {}

    public function check(): bool
    {
        return getenv('MY_ENV_VAR') === $this->expectedValue;
    }
}

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use Vendor\YourExt\Configuration\Trigger\MyCustomTrigger;

Handler::addIndicator(
    triggers: [
        new MyCustomTrigger('production-cluster-a'),
    ],
    indicators: [
        new Indicator\Backend\Topbar([
            'color' => '#e74c3c',
        ]),
    ],
);

<?php

namespace Vendor\YourExt\Configuration\Indicator;

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator\AbstractIndicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator\IndicatorInterface;

class MyCustomIndicator extends AbstractIndicator implements IndicatorInterface
{
    public function __construct(array $configuration = [])
    {
        parent::__construct($configuration);
    }

    public function getConfiguration(): array
    {
        return $this->configuration;
    }
}

Custom modifiers 

The predefined modifiers are not enough for your use case? No problem! You can easily write your own.

Implement your own image modifier by extending the AbstractModifier class and implementing the ModifierInterface method.

<?php

namespace Vendor\YourExt\Image\Modifier;

use Intervention\Image\Geometry\Factories\RectangleFactory;
use Intervention\Image\Interfaces\ImageInterface;
use KonradMichalik\Typo3EnvironmentIndicator\Image\Modifier\AbstractModifier;
use KonradMichalik\Typo3EnvironmentIndicator\Image\Modifier\ModifierInterface;

class CustomModifier extends AbstractModifier implements ModifierInterface {

    public function modify(ImageInterface &$image): void
    {
        // Modify the image using $this->configuration
    }

    public function validateConfigurationWithErrors(array $configuration): array
    {
        $errors = [];

        if (!isset($configuration['myRequiredKey'])) {
            $errors[] = 'Missing required configuration key: myRequiredKey';
        }

        return [
            'valid' => [] === $errors,
            'errors' => $errors,
        ];
    }
}

See the Intervention Image documentation for more information about image manipulation.

ViewHelpers 

The extension provides two Fluid ViewHelpers for use in custom templates.

Namespace: http://typo3.org/ns/KonradMichalik/Typo3EnvironmentIndicator/ViewHelpers

Namespace prefix: env

<html xmlns:env="http://typo3.org/ns/KonradMichalik/Typo3EnvironmentIndicator/ViewHelpers"
    data-namespace-typo3-fluid="true">

<!-- As argument -->
{env:favicon(favicon:'EXT:your_extension/Resources/Public/Favicon/favicon.png')}

<!-- As inline pipe -->
{f:uri.resource(path:'EXT:your_extension/Resources/Public/Favicon/favicon.png') -> env:favicon()}

<!-- As inline pipe -->
{f:uri.resource(path:'EXT:your_extension/Resources/Public/Images/logo.png') -> env:image()}

TypoScript reference 

The extension provides TypoScript objects and a condition function that can be used in custom TypoScript configurations.

[enableTechnicalContext()]
page.10 = TEXT
page.10.value = Environment indicator is active
[GLOBAL]

[enableTechnicalContext()]
lib.applicationContextTitle = TEXT
lib.applicationContextTitle.value = My Custom Title
[GLOBAL]

Example 

The following configuration is also the default configuration. This shall show the usage of the extension.

use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Handler;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Indicator;
use KonradMichalik\Typo3EnvironmentIndicator\Configuration\Trigger;
use KonradMichalik\Typo3EnvironmentIndicator\Image;

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Development*'),
    ],
    indicators: [
        new Indicator\Favicon([
            new Image\Modifier\TextModifier([
                'text' => 'DEV',
                'color' => '#bd593a',
                'stroke' => [
                    'color' => '#ffffff',
                    'width' => 3,
                ],
            ]),
        ]),
        new Indicator\Backend\Logo([
            new Image\Modifier\TextModifier([
                'text' => 'DEV',
                'color' => '#bd593a',
                'stroke' => [
                    'color' => '#ffffff',
                    'width' => 3,
                ],
            ]),
        ]),
        new Indicator\Frontend\Hint([
            'color' => '#bd593a',
        ]),
        new Indicator\Backend\Toolbar([
            'color' => '#bd593a',
        ]),
        new Indicator\Backend\Widget([
            'color' => '#bd593a',
        ]),
    ],
);

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Testing*'),
    ],
    indicators: [
        new Indicator\Favicon([
            new Image\Modifier\TextModifier([
                'text' => 'TEST',
                'color' => '#f39c12',
                'stroke' => [
                    'color' => '#ffffff',
                    'width' => 3,
                ],
            ]),
        ]),
        new Indicator\Backend\Logo([
            new Image\Modifier\TextModifier([
                'text' => 'TEST',
                'color' => '#f39c12',
                'stroke' => [
                    'color' => '#ffffff',
                    'width' => 3,
                ],
            ]),
        ]),
        new Indicator\Frontend\Hint([
            'color' => '#f39c12',
        ]),
        new Indicator\Backend\Toolbar([
            'color' => '#f39c12',
        ]),
    ],
);

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Production/Staging', 'Production/Stage'),
    ],
    indicators: [
        new Indicator\Favicon([
            new Image\Modifier\TextModifier([
                'text' => 'STG',
                'color' => '#2f9c91',
                'stroke' => [
                    'color' => '#ffffff',
                    'width' => 3,
                ],
            ]),
        ]),
        new Indicator\Backend\Logo([
            new Image\Modifier\TextModifier([
                'text' => 'STG',
                'color' => '#2f9c91',
                'stroke' => [
                    'color' => '#ffffff',
                    'width' => 3,
                ],
            ]),
        ]),
        new Indicator\Frontend\Hint([
            'color' => '#2f9c91',
        ]),
        new Indicator\Backend\Toolbar([
            'color' => '#2f9c91',
        ]),
    ],
);

Handler::addIndicator(
    triggers: [
        new Trigger\ApplicationContext('Production/Standby'),
    ],
    indicators: [
        new Indicator\Backend\Toolbar([
            'color' => '#2f9c91',
        ]),
    ],
);