konradmichalik/typo3-letter-avatar

TYPO3 extension, which generates colorful backend user avatars using name initials letter.

1.0.1 2025-05-22 11:29 UTC

Requires

• php: ^8.1
• typo3/cms-core: ^11.0 || ^12.0 || ^13.0

Requires (Dev)

• armin/editorconfig-cli: ^2.0
• bk2k/bootstrap-package: ^15.0
• ergebnis/composer-normalize: ^2.44
• friendsofphp/php-cs-fixer: ^3.52
• helhum/typo3-console: ^8.1
• helmich/typo3-typoscript-lint: ^3.2
• roave/security-advisories: dev-latest
• saschaegerer/phpstan-typo3: ^1.10
• ssch/typo3-rector: ^2.10
• symfony/translation: ^6.3 || ^7.0
• typo3/cms-base-distribution: ^11.0 || ^12.0 || ^13.0
• typo3/cms-lowlevel: ^11.0 || ^12.0 || ^13.0

Suggests

• ext-gd: Image processing library for avatar generation
• ext-gmagick: Image processing library for avatar generation
• ext-imagick: Image processing library for avatar generation

GPL-2.0-or-later

• Konrad Michalik

README

TYPO3 extension typo3_letter_avatar

This TYPO3 extension generates colorful backend user avatars using name initials letter.

Features

• Generates out-of-the-box colorful avatars for backend users
• Easily customizable and flexible configuration
• Provides different predefined color modes and themes
• Supports frontend user avatars with an additional viewhelper

Requirements

• TYPO3 >= 11.5 & PHP 8.1+

Installation

Composer

composer require konradmichalik/typo3-letter-avatar

TER

Download the zip file from TYPO3 extension repository (TER).

Setup

Set up the extension after the installation:

vendor/bin/typo3 extension:setup --extension=typo3_letter_avatar

The extension will automatically generate avatars for all existing backend users.

Configuration

Use the out-of-the-box configuration available in the extension settings or customize it in your own extension.

Extension Configuration

Use the extension configuration under Admin Tools > Settings > Extension Configuration > typo3_letter_avatar for the following options:

• Color mode: Select the color mode for the avatar generation. Available modes:
  • STRINGIFY: Creates a random color based on the name.
  • RANDOM: Randomly selected colors. See available color pairs.
  • THEME: Select this mode to choose a predefined color theme.
  • PAIRS: Randomly selected color pairs. See available color pairs.
  • CUSTOM: Custom colors defined in the configuration. Only available via the custom configuration.
• Theme: Only for color mode "Theme". Select the color theme (collection of foreground and background colors) for the avatar generation. See available themes.
• Font: Select the desired font for the letter avatar generation. Choose between several various font (types).

Custom

The default configuration can be easily overridden in your own extension. You can use the following code snippet to create a custom configuration:

// add custom theme
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['typo3_letter_avatar']['configuration']['themes']['customTheme'] = [
    'foregrounds' => [
        '#FFFFFF',
        '#000000',
        '#333333',
        '#FFFAFA',
        '#F5F5F5',
    ],
    'backgrounds' => [
        '#1E90FF',
        '#32CD32',
        '#FF4500',
        '#FFD700',
        '#8A2BE2',
    ],
];

// set custom theme
// warning: this will override the extension setting
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['typo3_letter_avatar']['configuration']['theme'] = 'customTheme'

Usage

The extension works for backend users out of the box.

Reusage

If you want to use it for other use cases, you can use the following code snippet to generate an avatar image:

// Generate avatar entity
$avatar = \KonradMichalik\Typo3LetterAvatar\Image\Avatar::create(
    name: 'Konrad Michalik',
    mode: KonradMichalik\Typo3LetterAvatar\Enum\ColorMode::RANDOM
);
// Save avatar image to default path
$avatar->save();
// Get web path of generated image
$avatar->getWebPath();

Note

See available parameters in the AbstractImageProvider

ViewHelper

You can use the KonradMichalik\Typo3LetterAvatar\ViewHelpers\AvatarViewHelper to generate an letter avatar image path in your Fluid templates, e.g. for frontend users:

<html xmlns:letter="http://typo3.org/ns/KonradMichalik/Typo3LetterAvatar/ViewHelpers">

<img src="{letter:avatar(name: 'John Doe')}" alt="Avatar of John Doe" />

Note

See available arguments in the AvatarViewHelper.

Console Command

Once the avatars are generated, you can use the console command to clear all avatars and implicitly regenerate them. Use the following console command to clear the generated avatars:

vendor/bin/typo3 avatar:clear

EventListener

You can use the BackendUserAvatarConfigurationEvent to modify the avatar configuration according to the current backend user:

<?php

declare(strict_types=1);

namespace Vendor\Package\EventListener;

use KonradMichalik\Typo3LetterAvatar\Enum\ColorMode;
use KonradMichalik\Typo3LetterAvatar\Event\BackendUserAvatarConfigurationEvent;

class ModifyLetterAvatarEventListener
{
    public function __invoke(BackendUserAvatarConfigurationEvent $event): void
    {
        $backendUser = $event->getBackendUser();
        
        /*
         * Example: If the backend user is an admin, set the CUSTOM color mode and define custom colors.
         */ 
        if ($backendUser['admin'] === 1) {
            $configuration = $event->getConfiguration();
            $configuration['mode'] = ColorMode::CUSTOM;
            $configuration['foreground'] = '#000000';
            $configuration['background'] = '#FFFFFF';
            
            $event->setConfiguration($configuration);
        }
    }
}

Note

Remember to register the event listener.

Development

Use the following ddev command to easily install all supported TYPO3 versions for locale development.

ddev install all

Credits

This project is highly inspired by similar open source projects like avatar and letter-avatar.

The fonts used in the extension are licensed under SIL Open Font License and Apache License, Version 2.0.

License

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