MonsterID

MonsterID is a method to generate a unique monster image based upon a certain identifier (IP address, email address, whatever). It can be used to automatically provide personal avatar images in blog comments or other community services.

MonsterID was inspired by a post by Don Park and the Combinatoric Critters.

Installation

Install it with Composer

composer require 'arokettu/monsterid'

Documentation

Usage

Simple image generation

Function-style

Get PNG as a string:

<?php

use function Arokettu\MonsterID\build_monster;

// output to browser
header('Content-type: image/png');
echo build_monster('email@example.com', 150);

Put PNG to a stream:

<?php

use function Arokettu\MonsterID\stream_monster;

// save to file
$stream = fopen('avatar.png', 'w');
stream_monster($stream, 'email@example.com', 150);
fclose($stream);

// more efficient output to browser
$stream = fopen('php://temp', 'r+');
stream_monster($stream, 'email@example.com', 150);
rewind($stream);
fpassthru($stream);
fclose($stream);

Export GD object:

<?php

use function Arokettu\MonsterID\build_monster_gd;

// convert it to a different format for example
$gd = build_monster_gd('email@example.com', 150); // a copy of the internal gd object
header('Content-type: image/avif');
imageavif($gd);
imagedestroy($gd); // it's your responsibility to destroy the resource (PHP < 8.0)

Monster object

<?php

use Arokettu\MonsterID\Monster;

$monster = new Monster('email@example.com', 150);

// output it to browser
header('Content-type: image/png');
echo $monster->getImage();

// save it to file
$monster->writeToStream(fopen('avatar.png', 'w'));

// gd
header('Content-type: image/avif');
imageavif($monster->getGdImage());

Random sequences

New in version 2.2.

The library supports 3 random number generators:

• Version 1: Mersenne Twister based. It generates the same images as MonsterID v1 and the original implementation did in PHP 7.2+. (7.1 may be glitchy, rand() in earlier versions was not MT based and is not reproducible)

• Version 2 (was default in MonsterID 2): Xorshift32 based, as implemented in MonsterID 2.1+

• Version 3 (default): native PHP Xoshiro256** based sequence. Recommended if you use PHP 8.2+

Also the lib provides \Arokettu\MonsterID\Randomizer\FactoryInterface that you can use to implement your own.

Note

Monster object will be serializable if your factory implementation is. All default factories are serializable.

Setting a default factory globally

<?php

use Arokettu\MonsterID\Config;
use Arokettu\MonsterID\Randomizer\DefaultV1Factory;
use Arokettu\MonsterID\Randomizer\DefaultV2Factory;
use Arokettu\MonsterID\Randomizer\DefaultV3Factory;

Config::setRandomizerFactory(); // reset to default (currently V2)
Config::setRandomizerFactory(new DefaultV1Factory()); // set V1
Config::setRandomizerFactory(new DefaultV2Factory()); // set V2
Config::setRandomizerFactory(new DefaultV3Factory()); // set V3

All Monster objects created after the config change will use the specified factory if not explicitly passed.

Passing explicitly

Object constructor and all functions support passing $rngFactory explicitly:

<?php

use Arokettu\MonsterID\Monster;
use Arokettu\MonsterID\Randomizer\DefaultV3Factory;

use function Arokettu\MonsterID\build_monster;

use const Arokettu\MonsterID\MONSTER_DEFAULT_SIZE;

$image = (new Monster('test@example.com', MONSTER_DEFAULT_SIZE, new DefaultV3Factory()))
    ->getImage();
// or
$image = build_monster('test@example.com', MONSTER_DEFAULT_SIZE, new DefaultV3Factory());

Upgrade Notes

Upgrade from 2.x

• The package was renamed to arokettu/monsterid

  • Old versions were published under the new name without any changes

• The namespace was changed to Arokettu\MonsterID

  • 1.4.0 and 2.3.0 were released with Arokettu\MonsterID support for old branches

• V3 generator is now default

  • Pass V2 generator explicilty or set it in global config:

    <?php
    
    use Arokettu\MonsterID\Config;
    use Arokettu\MonsterID\Randomizer\DefaultV2Factory;
    
    use function Arokettu\MonsterID\build_monster;
    
    require 'vendor/autoload.php';
    
    build_monster('my@email', rngFactory: new DefaultV2Factory());
    
    // or
    
    Config::setRandomizerFactory(new DefaultV2Factory());
    

• build() method was removed

Upgrade from 1.x

• Expect different images to be generated

  • Use V1 RNG factory in MonsterID 2.2+ for partial compatibility

• Namespace SandFoxMe\MonsterID is removed, use SandFox\MonsterID

• Object style changes:

  <?php
  
  use SandFox\MonsterID\Monster;
  
  // 1.x (deprecated in 1.3.0, removed in 3.0.0)
  (new Monster('email@example.com'))->build(150);
  // 2.x
  (new Monster('email@example.com', 150))->getImage();
  

  • Size parameter moved to the constructor

  • build() is now getImage()

License

All graphics were created by Andreas Gohr. The source code and the graphics are provided under the MIT License.

Upgraded and maintained by Anton “Sand Fox” Smirnov.

Original implementation can be found here.