README

Highly Customizable Identicon Generator for PHP.

Installation

Get it through composer cli.

composer require hedronium/avity

Getting Started

use Hedronium\Avity\Avity;

$avity = Avity::init()->generate()->jpg()->toBrowser();

Thats it thats all you really need to generate an Identicon. The above code will generate an Identicon based on Random values.

Basic Customization

Customizing Image Dimensions

You can call the height($value) and width($value) method on the Avity instance after initialization. Like:

$avity = Avity::init();
$avity->height(600)->width(500); // Long Vertical Identicon. WOW!

$avity->generate()->jpg()->toBrowser();

Yes, its a Fluent API, method chaining is cool!

Customizing Background & Foreground Color

$avity = Avity::init();

$avity->style()->background(20, 20, 40)
->foreground(100, 240, 255);

Both the methods accept $r, $g, $b parameters.

Customizing the Grid

$avity = Avity::init();

$avity->rows(3)->columns(3); // 3x3 Grid

Padding

$avity = Avity::init();

$avity->padding(100); //100px padding

Style Specific Customizations.

Often the style class used has specific methods that customize its behaviour which are not directly available on the Avity object for such cases the style instance can be fetched with the style() method on the Avity instance.

Like:

$avity = Avity::init();

$avity->style()->variedColor()->spacing(10); // `spacing()` & `variedColor()` is a style specific method

Controlling the Output

Output Format

Avity can output as jpg, png or gif

Avity::init()->generate()->jpg()->toBrowser();
Avity::init()->generate()->png()->toBrowser();
Avity::init()->generate()->gif()->toBrowser();

Output Quality

The quality of the generated image may also be set. Give it a number between 1 and 100. (Only aplicable for jpg & png)

Avity::init()->generate()->jpg()->quality(80)->toBrowser();

Output To Browser

Avity::init()->generate()->jpg()->toBrowser();

Output To File

Avity::init()->generate()->jpg()->toFile('/server/potato.jpg');

Generators

Generators are objects that generate numbers. These numbers are used by Layouts to set blocks onto the grid.

To use a different generator you can pass in an associative array of options with the generator key and the class bane as the value. Like:

$avity = Avity::init([
    'generator' => \Hedronium\Avity\Generators\Hash::class
]);

available classes:

\Hedronium\Avity\Generators\Hash (default)
\Hedronium\Avity\Generators\Random

The Hash Generator

Once you got the generator setup like above to pass in a value to hash you can call hash() on the Avity instance. (it can be anything, like the user's username or email address or id)

$avity = Avity::init([
    'generator' => \Hedronium\Avity\Generators\Hash::class
]);

$avity->hash('I like Bananas.'); // I really like bananas

This will generate the same identicon each time you give it the same value to hash.

Layouts

Layout objects use Generator objects to set blocks onto the grid. Avity comes with 3 built in Layout classes:

\Hedronium\Avity\Layouts\VerticalMirror (default)
\Hedronium\Avity\Layouts\HorizontalMirror
\Hedronium\Avity\Layouts\DiagonalMirror

changing the layout class

$avity = Avity::init([
    'layout' => \Hedronium\Avity\Layouts\DiagonalMirror::class
]);

Styles

Style objects use Layout objects to draw the grid onto a canvas. Avity comes with 4 built in Style classes:

\Hedronium\Avity\Styles\Square (default)
\Hedronium\Avity\Styles\SquareCircle
\Hedronium\Avity\Styles\Circle
\Hedronium\Avity\Styles\Triangle

changing the style class

$avity = Avity::init([
    'layout' => \Hedronium\Avity\Styles\Triangle::class
]);

spacing()

All built in Style classes have a spacing(_int_ $value) method that can be used to set the space between blocks. Like:

$avity = Avity::init();
$avity->style()->spacing(30);

variedColor()

This ones a fun method available to all default Style classes. Just call it and see the magic happen. Like:

$avity = Avity::init();
$avity->style()->variedColor();

Advanced Customization

Custom Generator

A generator class should always extend Hedronium\Avity\Generator example:

<?php
use Hedronium\Avity\Generator;

/**
 * A Generator that uses php's `rand()` function.
 */
class YourRandGenerator extends Generator
{
    public function next($x, $y)
    {
        // You could use the $x & $y values to
        // return something specific but usually it souldn't matter.

        return rand();
    }
}

Using a custom generator

$avity = Avity::init([
    'generator' => YourRandGenerator::class
]);

Take construction into your own hands.

$avity = Avity::init([
    'generator' => function () {
        return new YourRandGenerator('Please be very random.');
    }
]);

Custom Layouts

A generator class should always extend Hedronium\Avity\Layout

<?php
use Hedronium\Avity\Layout;

/**
 * A Generator that uses php's `rand()` function.
 */
class NoMirror extends Layout
{
    public function drawGrid(array $values)
    {
        // Sometimes, some style objects are not binary
        // they may draw more than one shape of block
        // thus the `$values` variable is passed in by the style.

        $grid = [];
        for ($y = 0; $y < $this->rows; $y++) {
            $grid[$y] = [];

            for ($x = 0; $x < $this->columns; $x++) {

                // should draw takes the `$values` and
                // returns a value based on
                // generator output

                $grid[$y][$x] = $this->shouldDraw($values);
            }
        }

        return $grid;
    }
}

Please check the source code for more details. (We promise its simple and readable.)

Using a custom layout

$avity = Avity::init([
    'generator' => NoMirror::class
]);

take construction into your own hands.

$avity = Avity::init([
    'generator' => function ($generator) {
        return new NoMirror($generator, 'POTATO');
    }
]);

the callback receive the generator instance as it's very likely that you will be generating the grid based on the generaotr output.

hedronium / avity

Maintainers

Details