index.rst 4.13 KB
Newer Older
Anton Smirnov's avatar
Anton Smirnov committed
1
MonsterID
2
#########
Anton Smirnov's avatar
Anton Smirnov committed
3

Anton Smirnov's avatar
Anton Smirnov committed
4
|Packagist| |GitLab| |GitHub| |Bitbucket| |Gitea|
Anton Smirnov's avatar
Anton Smirnov committed
5

Anton Smirnov's avatar
Anton Smirnov committed
6
7
8
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.
Anton Smirnov's avatar
Anton Smirnov committed
9

Anton Smirnov's avatar
Anton Smirnov committed
10
11
|Monster Example|

12
.. |Monster Example| image:: images/example.png
Anton Smirnov's avatar
Anton Smirnov committed
13

Anton Smirnov's avatar
Anton Smirnov committed
14
MonsterID was inspired by a post by `Don Park`_ and the `Combinatoric Critters`_.
Anton Smirnov's avatar
Anton Smirnov committed
15

Anton Smirnov's avatar
Anton Smirnov committed
16
Installation
17
============
Anton Smirnov's avatar
Anton Smirnov committed
18
19
20

Install it with Composer

Anton Smirnov's avatar
Anton Smirnov committed
21
22
.. code:: bash

Anton Smirnov's avatar
Anton Smirnov committed
23
24
   composer require 'sandfoxme/monsterid:^2.1'

Anton Smirnov's avatar
Anton Smirnov committed
25
.. warning:: Version 2.0.0 uses bad random generation and therefore is not recommended
Anton Smirnov's avatar
Anton Smirnov committed
26
27

Usage
28
29
30
31
=====

Function-style
--------------
Anton Smirnov's avatar
Anton Smirnov committed
32

Anton Smirnov's avatar
Anton Smirnov committed
33
Get PNG as a string:
34

Anton Smirnov's avatar
Anton Smirnov committed
35
.. code-block:: php
36

Anton Smirnov's avatar
Anton Smirnov committed
37
    <?php
Anton Smirnov's avatar
Anton Smirnov committed
38

Anton Smirnov's avatar
Anton Smirnov committed
39
    use function SandFox\MonsterID\build_monster;
Anton Smirnov's avatar
Anton Smirnov committed
40

Anton Smirnov's avatar
Anton Smirnov committed
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
    // output to browser
    header('Content-type: image/png');
    echo build_monster('email@example.com', 150);

Put PNG to a stream:

.. code-block:: php

    <?php

    use function SandFox\MonsterID\stream_monster;

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

Anton Smirnov's avatar
Anton Smirnov committed
58
59
60
61
62
63
64
    // more efficient output to browser
    $stream = fopen('php://temp', 'r+');
    stream_monster($stream, 'email@example.com', 150);
    rewind($stream);
    fpassthru($stream);
    fclose($stream);

Anton Smirnov's avatar
Anton Smirnov committed
65
66
67
68
69
70
71
72
Export GD object:

.. code-block:: php

    <?php

    use function SandFox\MonsterID\build_monster_gd;

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

79
80
81
Object-style
------------

Anton Smirnov's avatar
Anton Smirnov committed
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
.. code-block:: php

    <?php

    use SandFox\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());

Upgrade from 1.x
================

* Expect different images to be generated
* Namespace ``SandFoxMe\MonsterID`` is removed, use ``SandFox\MonsterID``
* Object style changes
107

Anton Smirnov's avatar
Anton Smirnov committed
108
  .. code-block:: php
109

Anton Smirnov's avatar
Anton Smirnov committed
110
        <?php
Anton Smirnov's avatar
Anton Smirnov committed
111

Anton Smirnov's avatar
Anton Smirnov committed
112
        use SandFox\MonsterID\Monster;
Anton Smirnov's avatar
Anton Smirnov committed
113

Anton Smirnov's avatar
Anton Smirnov committed
114
115
116
117
        // 1.x
        (new Monster('email@example.com'))->build(150);
        // 2.x
        (new Monster('email@example.com', 150))->getImage();
Anton Smirnov's avatar
Anton Smirnov committed
118

Anton Smirnov's avatar
Anton Smirnov committed
119
120
  * Size parameter moved to the constructor
  * ``build()`` is now ``getImage()``
Anton Smirnov's avatar
Anton Smirnov committed
121

122
123
124
125
126
127
License
=======

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

Anton Smirnov's avatar
Anton Smirnov committed
128
129
130
Upgraded and maintained by `Anton "Sand Fox" Smirnov <SandFox_>`_.

Original implementation can be found `here <upstream_>`_.
Anton Smirnov's avatar
Anton Smirnov committed
131

Anton Smirnov's avatar
Anton Smirnov committed
132
133
134
135
136
.. _Don Park:               http://www.docuverse.com/blog/donpark/2007/01/18/visual-security-9-block-ip-identification
.. _Combinatoric Critters:  http://www.levitated.net/bones/walkingFaces/index.html
.. _Andreas Gohr:           http://www.splitbrain.org
.. _MIT License:            https://opensource.org/licenses/MIT
.. _SandFox:                https://sandfox.me/
Anton Smirnov's avatar
Anton Smirnov committed
137
.. _upstream:               https://github.com/splitbrain/monsterID
138

139
.. |Packagist|  image:: https://img.shields.io/packagist/v/sandfoxme/monsterid.svg?style=flat-square
Anton Smirnov's avatar
Anton Smirnov committed
140
   :target:     https://packagist.org/packages/sandfoxme/monsterid
141
.. |GitHub|     image:: https://img.shields.io/badge/get%20on-GitHub-informational.svg?style=flat-square&logo=github
Anton Smirnov's avatar
Anton Smirnov committed
142
   :target:     https://github.com/arokettu/monsterid
143
.. |GitLab|     image:: https://img.shields.io/badge/get%20on-GitLab-informational.svg?style=flat-square&logo=gitlab
Anton Smirnov's avatar
Anton Smirnov committed
144
   :target:     https://gitlab.com/sandfox/monsterid
145
.. |Bitbucket|  image:: https://img.shields.io/badge/get%20on-Bitbucket-informational.svg?style=flat-square&logo=bitbucket
Anton Smirnov's avatar
Anton Smirnov committed
146
   :target:     https://bitbucket.org/sandfox/monsterid
147
.. |Gitea|      image:: https://img.shields.io/badge/get%20on-Gitea-informational.svg?style=flat-square&logo=gitea
Anton Smirnov's avatar
Anton Smirnov committed
148
   :target:     https://sandfox.org/sandfox/monsterid