Environment Indicator

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

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

Frontend Hint: Adds an informative hint to the frontend showing the website title and the current application context.

Backend toolbar: item: Adds an informative item with the current application context to the backend toolbar.

Modified favicon: Modify the favicon for frontend and backend based on the original favicon, the current application context and your configuration.

Support

There are several ways to get support for this extension:

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

License

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

Installation

Requirements

PHP 8.1 - 8.4
TYPO3 11.5 LTS - 13.4 LTS
ImageMagick
- Required for the .ico favicon file modification

Installation

Require the extension via Composer (recommended):

composer require konradmichalik/typo3-environment-indicator

Or download it from the TYPO3 extension repository.

Configuration

Include the static TypoScript template "Environment Indicator" or directly import it in your sitepackage:

Configuration/TypoScript/setup.typoscript

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

Configuration

The extension is ready to use without any further setup.

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

Learn what configuration options are available on the following pages:

Extension configuration

Go to Admin Tools > Settings > Extension Configuration
Choose typo3_environment_indicator

The extension currently provides the following configuration options:

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

Backend

backend.favicon

Type: boolean
Default: 1

Enable the favicon 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 also in production context

backend.contextProductionUserGroups

Type: string
Default: 1

Restrict the backend user groups that are shown the toolbar item in the production context (comma separated list of group ids)

Frontend Hint

The frontend hint will show the current application context 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

\KonradMichalik\Typo3EnvironmentIndicator\Utility\ConfigurationUtility::configByContext(
    applicationContext: 'Development',
    frontendHintConfiguration: [
        '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.

Backend toolbar item

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

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

ext_localconf.php

\KonradMichalik\Typo3EnvironmentIndicator\Utility\ConfigurationUtility::configByContext(
    applicationContext: 'Development',
    backendToolbarConfiguration: [
        'color' => '#bd593a',
    ]
);

Additional optional configuration keys:

text (string): The text of the toolbar item. Default is the application context.
icon (string): The icon of the toolbar item. Default is information-application-context.
index (int): The positioning index of the toolbar item. Default is 0.

Note

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

Favicon

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

Favicon Example

Inhaltsverzeichnis

local
depth: 2

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

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 application context (e.g. Testing) in your ext_localconf.php:

ext_localconf.php

\KonradMichalik\Typo3EnvironmentIndicator\Utility\ConfigurationUtility::configByContext(
    applicationContext: 'Testing',
    faviconModifierConfiguration: [
        \KonradMichalik\Typo3EnvironmentIndicator\Image\TextModifier::class =>
        [
            '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.

Note

If you want to specify the frontend or backend favicon separately, you can add the another parameter for the request context faviconModifierFrontendConfiguration or faviconModifierBackendConfiguration to the configByContext() method.

The following modifier classes are available:

TextModifier

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

ext_localconf.php

\KonradMichalik\Typo3EnvironmentIndicator\Utility\ConfigurationUtility::configByContext(
    applicationContext: 'Development',
    faviconModifierConfiguration: [
        \KonradMichalik\Typo3EnvironmentIndicator\Image\TextModifier::class =>
        [
            '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 bottom. Possible values are bottom, top.

See also

View the sources on GitHub:

TextModifier

TriangleModifier

Adds a triangle indicator to the favicon.

ext_localconf.php

\KonradMichalik\Typo3EnvironmentIndicator\Utility\ConfigurationUtility::configByContext(
    applicationContext: 'Development',
    faviconModifierConfiguration: [
        \KonradMichalik\Typo3EnvironmentIndicator\Image\TriangleModifier::class =>
        [
            '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

\KonradMichalik\Typo3EnvironmentIndicator\Utility\ConfigurationUtility::configByContext(
    applicationContext: 'Development',
    faviconModifierConfiguration: [
        \KonradMichalik\Typo3EnvironmentIndicator\Image\CircleModifier::class =>
        [
            '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 bottom left,

bottom right, top left, top 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

\KonradMichalik\Typo3EnvironmentIndicator\Utility\ConfigurationUtility::configByContext(
    applicationContext: 'Development',
    faviconModifierConfiguration: [
        \KonradMichalik\Typo3EnvironmentIndicator\Image\FrameModifier::class =>
        [
            '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 application context.

ext_localconf.php

\KonradMichalik\Typo3EnvironmentIndicator\Utility\ConfigurationUtility::configByContext(
    applicationContext: 'Development',
    faviconModifierConfiguration: [
        \KonradMichalik\Typo3EnvironmentIndicator\Image\ReplaceModifier::class =>
        [
            '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 application context.

ext_localconf.php

\KonradMichalik\Typo3EnvironmentIndicator\Utility\ConfigurationUtility::configByContext(
    applicationContext: 'Development',
    faviconModifierConfiguration: [
        \KonradMichalik\Typo3EnvironmentIndicator\Image\OverlayModifier::class =>
        [
            'path' => 'EXT:sitepackage/Resources/Public/Icons/favicon.png',
        ]
    ],
);

Additional optional configuration keys:

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 bottom left,

bottom right, top left, top right. - padding (float): The percentage padding of the overlay. Default is 0.1.

See also

View the sources on GitHub:

OverlayModifier

ColorizeModifier

Overlay an additional image to the original favicon regarding the application context.

ext_localconf.php

\KonradMichalik\Typo3EnvironmentIndicator\Utility\ConfigurationUtility::configByContext(
    applicationContext: 'Development',
    faviconModifierConfiguration: [
        \KonradMichalik\Typo3EnvironmentIndicator\Image\ColorizeModifier::class =>
        [
            '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.

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

use Intervention\Image\Geometry\Factories\RectangleFactory;
use Intervention\Image\Interfaces\ImageInterface;

class CustomModifier extends AbstractModifier implements ModifierInterface {

    public function modify(ImageInterface &$image): void
    {
        // Modify the image
    }

    public function getRequiredConfigurationKeys(): array
    {
        // Return the required configuration keys
    }
}

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']).

Configuration Utility

Generally the whole configuration can be found in $GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['typo3_environment_indicator']. You can/should use the ConfigurationUtility::configByContext() to easily add necessary configuration for the environment indicator.

ext_localconf.php

// Add a colorized favicon modifier, add a colorful backend toolbar item and unset the frontend hint for the Development context
\KonradMichalik\Typo3EnvironmentIndicator\Utility\ConfigurationUtility::configByContext(
    applicationContext: 'Development',
    faviconModifierConfiguration: [
        \KonradMichalik\Typo3EnvironmentIndicator\Image\ColorizeModifier::class =>
        [
            'color' => '#039BE5',
        ]
    ],
    faviconModifierFrontendConfiguration: [
        \KonradMichalik\Typo3EnvironmentIndicator\Image\ColorizeModifier::class =>
        [
            'opacity' => 0.5 // Change just the opacity for the frontend favicon configuration
        ]
    ],
    frontendHintConfiguration: null, // Unset frontend hint for Development context
    backendToolbarConfiguration: [
        'color' => '#039BE5',
    ]
);

class ConfigurationUtility

Fully qualified name: \KonradMichalik\Typo3EnvironmentIndicator\Utility\ConfigurationUtility

Utility class to easily configure the environment indicators.

configByContext ( $applicationContext, $frontendHintConfiguration = [], $backendToolbarConfiguration = [], $faviconModifierConfiguration = [], $faviconModifierFrontendConfiguration = [], $faviconModifierBackendConfiguration = [])

Simple function to update the status of a record.

param string $applicationContext: Name of the TYPO3 application context.
param array|null $frontendHintConfiguration: Configuration for the frontend hint. Set to null to unset the configuration.
param array|null $backendToolbarConfiguration: Configuration for the backend toolbar item. Set to null to unset the configuration.
param array|null $faviconModifierConfiguration: Configuration for the favicon modification. This configuration applies to frontend and backend. Set to null to unset the configuration.
param array|null $faviconModifierFrontendConfiguration: Frontend configuration for the favicon modification. Set to null to unset the configuration.
param array|null $faviconModifierBackendConfiguration: Frontend configuration for the favicon modification. Set to null to unset the configuration.
returntype: void