php-initial-avatar-generator

Install the package using Composer to add it to your PHP project.

composer require lasserafn/php-initial-avatar-generator

To serve avatars dynamically in HTML, create a PHP endpoint (e.g., avatar.php) that accepts a name parameter via $_GET, generates the image, and streams it with the correct Content-Type header. Then, reference this endpoint in your <img> tags.

<?php
require 'vendor/autoload.php'; 

use LasseRafn\InitialAvatarGenerator\InitialAvatar;

header('Content-Type: image/png');

$avatar = new InitialAvatar();
$name = isset($_GET['name']) ? $_GET['name'] : 'Default User';

$image = $avatar->name($name)->generate();
echo $image->stream('png', 100);
exit;

<!-- In your HTML --> <img src="avatar.php?name=John Doe" alt="Avatar for John Doe" width="100" height="100">

To generate an avatar, instantiate InitialAvatar, chain configuration methods to define the look and feel, and finally call generate() for a raster image or generateSvg() for a vector image.

Example: Standard Raster Avatar

use LasseRafn\InitialAvatarGenerator\InitialAvatar;

$avatar = new InitialAvatar();
$image = $avatar->size(128)
                ->rounded(true)
                ->autoColor()
                ->generate('Jane Doe');

$image->save('avatar.png');

Example: Custom SVG Avatar

use LasseRafn\InitialAvatarGenerator\InitialAvatar;

$avatar = new InitialAvatar();
$svg = $avatar->size(48)
              ->background('#f0e9e9')
              ->color('#8b5d5d')
              ->generateSvg('John Doe');

// $svg is an instance of SVG\SVG

To generate a standard avatar image, instantiate LasseRafn\InitialAvatarGenerator\InitialAvatar, provide a name using the name() method, and call generate(). The returned object is an instance of Intervention Image, allowing you to stream, download, or encode the result.

$avatar = new LasseRafn\InitialAvatarGenerator\InitialAvatar();

$image = $avatar->name('Lasse Rafn')->generate();

// Stream the image as a PNG with 100% quality
return $image->stream('png', 100);

If you need vector graphics instead of a raster image, use the generateSvg() method followed by toXMLString() to get the raw SVG XML.

$avatar = new LasseRafn\InitialAvatarGenerator\InitialAvatar();

echo $avatar->name('Lasse Rafn')->generateSvg()->toXMLString();

You can render specific FontAwesome (v5) icons instead of initials by using the glyph() method. You must also set the font to a FontAwesome file (e.g., FontAwesome5Free-Regular-400.otf included in the package) to ensure the icon renders correctly.

// Render a red avatar with a white 'user' icon (unicode: f007)
return $avatar->glyph('f007')
              ->font('/fonts/FontAwesome5Free-Regular-400.otf')
              ->color('#fff')
              ->background('#ff0000')
              ->generate()
              ->stream('png', 100);

You can specify custom fonts or enable automatic script detection.

• AutoFont: Uses lasserafn/php-string-script-language to detect the script (e.g., Arabic, Chinese, Thai) and select a compatible font.
• Custom Font: Pass a path to a .ttf or .otf file. If an integer (1-5) is passed, it uses a GD internal font.
• SVG Font Name: Use fontName() to set the font family for SVG generation.

// Enable automatic script detection
$image = $avatar->autoFont()->generate();

// Use a specific font file
$image = $avatar->font('/fonts/OpenSans-Semibold.ttf')->generate();

// Set font name for SVGs
$image = $avatar->fontName('Arial, Helvetica, sans-serif')->generate();

The php-initial-avatar-generator relies on the intervention/image library. To ensure compatibility, your PHP environment must have one of the following image libraries installed and enabled:

• GD Library (version 2.0 or higher)
• Imagick PHP extension (version 6.5.7 or higher)

You can switch between image processing drivers and change the avatar shape.

• Drivers: Use gd() or imagick().
• Rounding: Use rounded() to create circular/rounded avatars. It is recommended to chain smooth() to avoid pixelated edges, though this may be slower.

// Use Imagick driver with smooth rounded edges
$image = $avatar->imagick()->rounded()->smooth()->generate();

The InitialAvatar class provides a fluent API to customize the generated avatar. Most methods can be chained together.

$avatar->name('Lasse Rafn')
    ->length(2)           // Number of initials to use (default: 2)
    ->fontSize(0.5)       // Font size as fraction of image size (default: 0.5)
    ->size(96)             // Sets both width and height (default: 48)
    ->background('#8BC34A') // Background color (default: #f0e9e9)
    ->color('#fff')        // Font color (default: #8b5d5d)
    ->generate();

Use the generateSvg() method to create an avatar as an SVG\SVG instance. You can optionally pass a name directly to the method to override any previously set name.

This is useful for web applications where scalable vector graphics are preferred over raster images.

$avatar = new InitialAvatar();
$svg = $avatar->generateSvg('John Doe');

The generator supports different languages for name translation.

Important: You must call language($language) before calling name($name) to ensure the correct translator is initialized.

Supported languages include en, tr, and zh-CN. You can add custom translators using addTranslators($translatorMap).

// Correct usage pattern
$avatar->language('zh-CN')->name('张三');

// Adding custom translators
$avatar->addTranslators([
    'fr' => 'App\Translators\FrTranslator',
    'zh-TW' => 'App\Translators\ZhTWTranslator'
]);