Jdenticon PHP API

Rendering

Icons can be rendered to SVG and PNG. Both formats are supported without requiring any PHP extension. However if the ImageMagick extension is available it will be used.

If you are running a PHP-version < 7 ImageMagick is recommended for performance reasons when rendering PNG icons. On PHP 7 and later there is no large performance difference between the internal PNG renderer vs. ImageMagick (when using a PHP precompiler).

Jdenticon does not support rendering using GD due to the lack of proper antialiasing in GD.

Class Jdenticon\Identicon

Identicon options

The following options are available to the Identicon class. The options can either be set using magic properties, or by passing the options in an associative array to the constructor or the setOptions method.

PropertyTypeDescription
hashstringA binary string containing the hash that the icon will be generated from. The string must cotnain at least 6 bytes.
valuemixedThe value will be converted to a UTF8 encoded string and then hashed using SHA1. The icon will be generated from this hash.
sizenumericSets the size of the icon in pixels. The size should be at least 1 pixel. Remember that large icons takes a lot of time to rasterize.
styleJdenticon\IdenticonStyle | arrayContaining styling options for this icon. When setting this option you can choose between specifying an IdenticonStyle instance, or an associative array containing IdenticonStyle options.
iconGeneratorJdenticon\Rendering\IconGeneratorAn icon generator creates shapes out of a hash and pass them on to a Jdenticon\Rendering\RendererInterface. If you want to customize what shapes are rendered in the icon, create a new class inheriting from IconGenerator and override the renderForeground and/or renderBackground methods.

The following example shows multiple ways how to set options of the Identicon class.

<?php
include_once("vendor/autoload.php");

// Associative array to the constructor
$icon = new \Jdenticon\Identicon(array(
    'size' => 50,
    'value' => 'John Doe'
));

// Magic properties
$icon->size = 50;
$icon->value = 'John Doe';

// Public setters
$icon->setSize(50);
$icon->setValue('John Doe');
__constructor($options = null)

Creates a new Identicon. Optionally an associative array containing identicon options can be passed to the constructor.

draw(Jdenticon\Rendering\RendererInterface $renderer, Jdenticon\Rendering\Rectangle $rect) => void

Draws this icon using a specified renderer.

This method is only intended for usage with custom renderers. A custom renderer could as an example render an Identicon in a file format not natively supported by Jdenticon. To implement a new file format, implement \Jdenticon\Rendering\RendererInterface.

displayImage($imageFormat = 'png') => void

Renders the icon directly to the page output.

The $imageFormat parameter specifies the format of the generated icon. Supported formats are 'png' and 'svg'.

The method will set the 'Content-Type' HTTP header. You are recommended to set an appropriate 'Cache-Control' header before calling this method to ensure the icon is cached client side.

The method won't call exit() or die(). Be sure not to write any output to the client before or after this method is called, as it will most likely corrupt the icon.

getImageData($imageFormat = 'png') => binary string

Renders the icon and returns the icon data as a binary string.

The $imageFormat parameter specifies the format of the generated icon. Supported formats are 'png' and 'svg'.

Remember to set an appropriate Content-Type when writing the image data to the output. Alternatively use the displayImage method that will also write the icon to the output.

getImageDataUri($imageFormat = 'png') => string

Renders the icon and returns the icon as a data URI.

The $imageFormat parameter specifies the format of the generated icon. Supported formats are 'png' and 'svg'.

It is recommended to avoid using this method unless really necessary, since it will effectively disable client caching of generated icons, and will also cause the same icon to be rendered multiple times, when used multiple times on a single page.

Class Jdenticon\IdenticonStyle

IdenticonStyle options

The following options are available to the IdenticonStyle class. The options can either be set using magic properties, or by passing the options in an associative array to the constructor or the setOptions method.

PropertyTypeDescription
huesarray(integer)A list of allowed hues specified in degrees that can be used in icons. Only a single hue per icon will be used. If no hue is specified, all hues are allowed.
backgroundColorJdenticon\Color | stringThe background color of the entire icon, including the padding. The color is specified as a CSS3 color.
paddingfloatThe padding of the icon in percent in the range [0, 0.4].
colorSaturationfloatSaturation of colored identicon shapes specified in the range [0, 1].
grayscaleSaturationfloatSaturation of the originally grayscale identicon shapes specified in the range [0, 1].
colorLightnessarray(float, float)Lightness of colored identicon shapes. The value is specified as an array containing the minimum and maximum lightness in the range [0, 1], e.g. array(0.3, 0.5).
grayscaleLightnessarray(float, float)Lightness of the originally grayscale identicon shapes. The value is specified as an array containing the minimum and maximum lightness in the range [0, 1], e.g. array(0.3, 0.5).

The following example shows multiple ways how to set options of the IdenticonStyle class.

<?php
include_once("vendor/autoload.php");

// Associative array to the constructor
$icon = new \Jdenticon\IdenticonStyle(array(
    'backgroundColor' => 'rgba(255, 128, 0, 0.8)',
    'hues' => array(321)
));

// Magic properties
$icon->backgroundColor = 'rgba(255, 128, 0, 0.8)';
$icon->hues = array(321);

// Public setters
$icon->setBackgroundColor('rgba(255, 128, 0, 0.8)');
$icon->setHues(array(321));
__constructor($options = null)

Creates a new IdenticonStyle. Optionally an associative array containing style options can be passed to the constructor.