Environment Indicator

Extension key: typo3_environment_indicator
Package name: konradmichalik/typo3-environment-indicator
Version: 3.2
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

A quick overview about the main features provided by this extension.

Learn more about this extension

Installation

Instructions on how to install this extension and which TYPO3 and PHP versions are currently supported.

Getting started

Configuration

Learn how to configure the extension in various ways. This includes extension configuration and the usage of the configuration utility.

View configuration options

Indicators

Indicators are the main feature of this extension. They are used to show e.g. the current application context in the frontend and backend.

Indicator overview

Triggers

Triggers are conditions that can be used to show or hide the environment indicator in the frontend and backend.

Trigger overview

Developer corner

A quick overview of the possibilities for extending the extension

Deep dive into classes & concepts

Introduction

What does it do?

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

Note

These environment indicators are mainly for development purposes (e.g. distinguishing between different test systems) and will not show in production environments.

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.

Example — Backend with several environment indicators

Description	Frontend	Backend
Frontend Hint: Adds an informative hint to the frontend showing the website title and current environment.	✔️
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 favicon: Modifies the favicon for frontend and backend based on the original favicon, current environment and your configuration.	✔️	✔️
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.		✔️
Modified frontend image: Modifies the frontend image based on the original image, current environment and your configuration.	✔️
Backend theme (experimental): Colors the entire TYPO3 v14+ backend (primary color, header, sidebar) based on the environment.		✔️

Support

There are several ways to get support for this extension:

GitHub: https://github.com/konradmichalik/typo3-environment-indicator/issues

License

This extension is licensed under GNU General Public License 2.0 (or later).

Installation

Requirements

Version	TYPO3	PHP
3.x	13.4 - 14.x	8.2 - 8.5
2.x	11.5 - 13.4	8.1 - 8.4

Additional requirements:

ImageDriver: GD, Imagick or libvips

Installation

Require the extension via Composer (recommended):

composer require konradmichalik/typo3-environment-indicator

Or download it from the TYPO3 extension repository.

Configuration

Note

TypoScript configuration is only necessary if you want to use the frontend hint.

Site Set (Recommended)

Important

Starting with version 3.0, Site Sets are required for the frontend TypoScript configuration. The legacy static TypoScript include is no longer supported.

Add the site set as a dependency in your site configuration:

config/sites/<identifier>/config.yaml

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

Static Include (Version 2.x only)

Deprecated since version 3.0

The static TypoScript include is deprecated and removed in version 3.0. Please use Site Sets instead.

Alternatively, include the static TypoScript template via the Template module by adding "Environment Indicator" under Include static (from extensions).

Or directly import it in your sitepackage:

Configuration/TypoScript/setup.typoscript

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

Image Support

Only the following favicon image formats are supported: https://image.intervention.io/v3/introduction/formats

Due to the wide distribution of .ico and .svg files, these images are also supported.

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*

See also

See the Example for the complete configuration.

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

Go to Admin Tools > Settings > Extension Configuration
Choose typo3_environment_indicator

The extension currently provides the following configuration options:

General

general.imageDriver

Type: option
Default: "gd"

Intervention Image supports "GD Library", "Imagick" and "libvips" to process images internally. You may choose one of them according to your PHP configuration. Options are "gd", "imagick" and "vips".

general.defaultConfiguration

Type: boolean
Default: 1

Enable the default configuration for the environment indicators. If you want to configure the environment indicators by yourself, set this to false. See Configuration.

Frontend

frontend.favicon

Type: boolean
Default: 1

Enable the favicon generation in frontend context

frontend.context

Type: boolean
Default: 1

Enable the context frontend hint

frontend.image

Type: boolean
Default: 1

Enable the image generation in frontend context

Backend

backend.favicon

Type: boolean
Default: 1

Enable the favicon generation in backend context

backend.logo

Type: boolean
Default: 1

Enable the logo generation in backend context

backend.context

Type: boolean
Default: 1

Enable the context item within the backend toolbar

backend.contextProduction

Type: boolean
Default: 1

Enable the backend toolbar item / backend topbar also in production context

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.

ext_localconf.php

\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.

ext_localconf.php

\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 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:

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 position of the frontend hint. Default is top left. Possible values are bottom left,bottom right, top left, top right.

Frontend Image

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

The image path can be adjusted via the ImageViewHelper:

Custom fluid template

<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')}

See also

View the sources on GitHub:

ImageViewHelper

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,
                ],
            ])
        ])
    ]
);

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:

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.

Note

The backend toolbar item is a feature, which can also be shown in production context. Use the extension settings to enable, disable or restrict it.

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:

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',
        ])
    ]
);

Note

The backend topbar is a feature, which can also be shown in production environments. Use the extension settings to enable, disable or restrict it.

Backend theme

New in version 3.1

This indicator requires TYPO3 v14 or later.

Warning

This feature is experimental. The TYPO3 backend CSS framework is currently considered internal API. While the overridden CSS custom properties are stable within TYPO3 v14, they may change in future major versions.

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:

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%'.

ext_localconf.php - Full configuration example

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%',
        ]),
    ],
);

Note

This indicator requires TYPO3 v14 or later. On TYPO3 v13 and below, the indicator is silently ignored.

Important

When this indicator is active, the user's theme selection in User Settings > Theme is overridden by the environment color. An info box is displayed in the User Settings to inform the user.

Note

The backend theme indicator can be combined with other backend indicators like Backend toolbar or Backend topbar for maximum visual distinction between environments.

Favicon

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

Favicon Example

Table of Contents

Frontend

For the frontend, the original favicon will either be fetched from the typoscript configuration page.shortcutIcon (see typoscript reference) or can be handled by your own fluid template via the FaviconViewHelper:

Custom fluid template

<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')}

See also

View the sources on GitHub:

FaviconViewHelper

Backend

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

Favicon Examples

Scope

By default, the Favicon indicator applies modifications to both frontend and backend. You can restrict it to a specific application type using the Scope enum:

ext_localconf.php

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,
        ),
    ],
);

Available scope values:

Scope::Global (default): Apply to both frontend and backend.
Scope::Frontend: Apply only to the frontend.
Scope::Backend: Apply only to the backend.

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,
                ],
            ])
        ])
    ]
);

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,
                ],
            ])
        ])
    ]
);

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',
            ])
        ])
    ]
);

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',
            ])
        ])
    ]
);

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',
            ])
        ])
    ]
);

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',
            ])
        ])
    ]
);

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',
            ])
        ])
    ]
);

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',
            ])
        ])
    ]
);

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.

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.

Backend Logo Example

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,
                ],
            ])
        ])
    ]
);

Dashboard Widget

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

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

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.

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

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.

ext_localconf.php

\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.

ext_localconf.php

\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.

ext_localconf.php

\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.

ext_localconf.php

\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).

Custom

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

ext_localconf.php

\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.

ext_localconf.php

\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.

ext_localconf.php

\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.

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.

Table of Contents

Custom triggers

A trigger determines whether a set of indicators should be activated. Implement the TriggerInterface with a single check() method that returns a boolean value.

Classes/Configuration/Trigger/MyCustomTrigger.php

<?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;
    }
}

Then use it in your ext_localconf.php:

ext_localconf.php

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',
        ]),
    ],
);

Note

When multiple triggers are passed to a single Handler::addIndicator() call, all triggers must return true (AND logic) for the indicators to activate. If any trigger throws an exception, it is treated as false.

See also

View the sources on GitHub:

TriggerInterface

Custom indicators

An indicator defines what is rendered when its associated triggers pass. Implement the IndicatorInterface or extend AbstractIndicator.

Classes/Configuration/Indicator/MyCustomIndicator.php

<?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;
    }
}

The AbstractIndicator base class automatically merges global default configuration from $GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['typo3_environment_indicator']['defaults'] if a matching entry for the indicator class exists.

See also

View the sources on GitHub:

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.

Classes/Image/CustomModifier.php

<?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 also

View the sources on GitHub:

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

Note

Having fun with colorful favicons? Use the ColorUtility::getColoredString() function as color entry in your modifier configuration to generate a color based on a string (default is the $GLOBALS['TYPO3_CONF_VARS']['SYS']['sitename']).

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">

Table of Contents

FaviconViewHelper

Processes a favicon path through the configured environment indicator modifiers. If no Favicon indicator is active for the current context, the original path is returned unchanged.

Arguments:

Argument	Type	Description
`favicon`	string	The favicon path. Can also be passed as tag content (inline notation).

Usage:

<!-- 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()}

See also

View the sources on GitHub:

FaviconViewHelper

ImageViewHelper

Processes a frontend image path through the configured environment indicator modifiers. If no Frontend Image indicator is active for the current context, the original path is returned unchanged.

Arguments:

Argument	Type	Description
`_path`	string	The image path. Can also be passed as tag content (inline notation).

Usage:

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

See also

View the sources on GitHub:

ImageViewHelper

TypoScript reference

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

Table of Contents

Condition: enableTechnicalContext()

The enableTechnicalContext() condition function evaluates whether the frontend hint indicator is active for the current environment. It returns true when the frontend context feature is enabled in the extension configuration and a FrontendHint indicator is configured for the current application context.

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

TypoScript objects

The following lib.* objects are registered within the [enableTechnicalContext()] condition block via the included Site Set. They can be used or overridden in your own TypoScript.

Object	Description
`lib.applicationContextTitle`	Returns the current TYPO3 application context (e.g. `Development/DDEV`).
`lib.applicationContextColor`	Returns the configured color of the Frontend Hint indicator.
`lib.applicationContextTextColor`	Returns the optimal text color (black or white) for the configured hint color.
`lib.websiteTitle`	Returns the website title from the site configuration. Falls back to the `text` option of the Frontend Hint if set.
`lib.applicationContextPositionX`	Returns the horizontal position (e.g. `left:0`).
`lib.applicationContextPositionY`	Returns the vertical position (e.g. `top:0`).
`lib.technicalContext`	A `FLUIDTEMPLATE` that renders the complete frontend hint element. This object is automatically added to `page` output.

Overriding objects

You can override any of these objects in your own TypoScript setup:

[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.

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,
                ],
            ]),
        ]),
        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',
        ]),
    ],
);