PHP Avatar Library

The PHP library provides an API identical to the JavaScript library. It requires PHP 8.2 or higher. The same seed and style definition will produce byte-identical SVGs in both implementations.

Installation

You need two packages: the core library dicebear/core and the avatar style definitions dicebear/styles.

composer require dicebear/core dicebear/styles

Usage

<?php

use Composer\InstalledVersions;
use DiceBear\Style;
use DiceBear\Avatar;

$basePath = InstalledVersions::getInstallPath('dicebear/styles');
$definition = json_decode(file_get_contents($basePath . '/src/lorelei.json'), true);

$style = new Style($definition);
$avatar = new Avatar($style, [
  'seed' => 'Alice',
  // ... other options
]);

$svg = (string) $avatar;

Each avatar style comes with several options. You can find them on the details page of each avatar style.

INFO

We provide a large number of avatar styles from different artists. The avatar styles are licensed under different licenses that the artists can choose themselves. For a quick overview we have created an license overview for you.

Deterministic avatars

The seed option is the key to generating deterministic avatars. The same seed will always produce the same avatar:

$avatar1 = new Avatar($style, ['seed' => 'user-123']);
$avatar2 = new Avatar($style, ['seed' => 'user-123']);

(string) $avatar1 === (string) $avatar2; // true

Classes

Avatar

The main class for generating avatars. Accepts a Style instance (or raw definition array) and optional options.

use DiceBear\Avatar;

$avatar = new Avatar($style, [
  // ... options
]);

Style

An immutable wrapper around a style definition. Reuse it when generating multiple avatars from the same style.

use DiceBear\Style;
use DiceBear\Avatar;

$style = new Style($definition);

$avatar1 = new Avatar($style, ['seed' => 'Alice']);
$avatar2 = new Avatar($style, ['seed' => 'Bob']);

OptionsDescriptor

Describes all valid options for a given style. Useful for building UIs or validating user input.

use DiceBear\Style;
use DiceBear\OptionsDescriptor;

$descriptor = new OptionsDescriptor(new Style($definition));
$fields = $descriptor->toJSON();

Methods

__toString() / toString()

Return type: string

Returns the avatar as SVG in XML format. The __toString() magic method allows using the avatar directly in string contexts.

$avatar = new Avatar($style, ['seed' => 'Alice']);

$svg = (string) $avatar;
// or
$svg = $avatar->toString();

toJSON()

Return type: array{svg: string, options: array}

Returns an associative array with the SVG and the resolved options.

$avatar = new Avatar($style, ['seed' => 'Alice']);

$json = $avatar->toJSON();

// $json['svg']     → '<svg>...</svg>'
// $json['options'] → ['seed' => 'Alice', ...]

toDataUri()

Return type: string

Returns the avatar as data URI.

$avatar = new Avatar($style, ['seed' => 'Alice']);

$dataUri = $avatar->toDataUri();

// <img src="<?= $dataUri ?>" alt="Avatar" />

Core options

The core options are identical to the JavaScript library. See the JS Library core options for the full reference. Here are the options in PHP syntax:

$avatar = new Avatar($style, [
  'seed' => 'Alice',
  'flip' => 'horizontal',          // 'none', 'horizontal', 'vertical', 'both'
  'rotate' => 10,                  // -360 to 360, or [min, max] range
  'scale' => 0.9,                  // 0 to 10 (1 = original), or [min, max] range
  'borderRadius' => 50,            // 0-50 (50 = circle)
  'size' => 128,
  'translateX' => 0,               // -1000 to 1000 (percent of canvas width)
  'translateY' => 0,               // -1000 to 1000 (percent of canvas height)
  'idRandomization' => true,
  'title' => 'User Avatar',
  'fontFamily' => 'Arial',         // or ['Arial', 'Helvetica']
  'fontWeight' => 700,             // 1-1000
  'backgroundColor' => ['#b6e3f4', '#c0aede'],
  'backgroundColorFill' => 'solid', // 'solid', 'linear', 'radial'
]);

Dynamic component and color options also work the same way. See the JS Library documentation for all available patterns.

Examples

Avatar with custom background

$avatar = new Avatar($style, [
  'seed' => 'Alice',
  'backgroundColor' => ['#b6e3f4', '#c0aede', '#d1d4f9'],
]);

Fixed size avatar

$basePath = InstalledVersions::getInstallPath('dicebear/styles');
$definition = json_decode(file_get_contents($basePath . '/src/bottts.json'), true);

$style = new Style($definition);
$avatar = new Avatar($style, [
  'seed' => 'robot-42',
  'size' => 128,
  'borderRadius' => 50, // circular avatar
]);

Avatar with transformations

$basePath = InstalledVersions::getInstallPath('dicebear/styles');
$definition = json_decode(file_get_contents($basePath . '/src/avataaars.json'), true);

$style = new Style($definition);
$avatar = new Avatar($style, [
  'seed' => 'Jane',
  'flip' => 'horizontal',
  'rotate' => 10,
  'scale' => 0.9,
  'translateY' => 5,
]);

Multiple avatars on the same page

When rendering multiple avatars on the same page, use idRandomization to prevent SVG ID conflicts:

$users = ['alice', 'bob', 'charlie'];

$avatars = array_map(function (string $user) use ($style) {
  return (string) new Avatar($style, [
    'seed' => $user,
    'idRandomization' => true,
  ]);
}, $users);

Weighted variant selection

$avatar = new Avatar($style, [
  'seed' => 'Alice',
  'topVariant' => ['short01' => 2, 'short02' => 2, 'long01' => 1],
]);