PHPAutoColor

Simple PHP class for automated coloring with visually distinct colors.

1. Use case

• coloring people's messages in chat by their user name or their user id
• coloring list of latest users actions, on admin dashboard, by user id or username

2. Features

• clever color picking of the most visually distinct colors (generated by CIEDE2000 algorithm)
• maximum and minimum lightness of returned colors can be set
• fast and lightweight
• lots of customization options
• easy debugging with build in error messages

3. Usage

2.1 Installation

    git clone https://github.com/Hurtak/PHPAutoColor.git

Or you can use Composer

    composer require hurtak/phpautocolor:@dev

2.2 Basic setup

    include "PHPAutoColor/src/PHPAutoColor.php";
    $color = new PHPAutoColor();

2.3 Settings (optional)

• customize PHPAutoColor settings or don't do anything and default settings will be used

2.4 Send user id or username, color will be returned

• integers, numbers with decimal points and strings (case sensitive) are accepted

    $color->getColor($userID); // returns "#000"

4. Code example

    <?php

    // data from DB
    $sql = $pdo->prepare("SELECT * FROM actions");
    $sql->execute();
    $userActions = $sql->fetchAll();
   
    // initial setup
    include "PHPAutoColor.php";
    $color = new PHPAutoColor();

    // PHPAutoColor settings (optional)
    $color->setColorType("rgb");
    $color->setColorPickingMethod("dynamic");
    $color->setLightnessLimit("min", 0.3);

    ?>
   
    <table>
   
        <tr>
            <td>id</td>
            <td>user_id</td>
            <td>amount</td>
            <td>date</td>
        </tr>

        <?php foreach ($userActions as $action): ?>
        <tr style="background-color: <?= $color->getColor($action['user_id']) ?>">
            <td><?= $action["id"] ?></td>
            <td><?= $action["user_id"] ?></td>
            <td><?= $action["amount"] ?></td>
            <td><?= $action["date"] ?></td>
        </tr>
        <?php endforeach ?>

    </table>

5. Settings

5.1 getColor($input, $opacity = 1)

• returns string of color in hex format (can be changed, see chapter 5.3)
• on error returns empty string (to display errors list, enable debugging, see chapter 5.6)

5.2 setColorPickingMethod($colorPickingMethod)

• Specifies what color picking method will be used when getColor() is called
• This setting is optional, if you won't call this function, default value will be used

5.3 setColorType($colorType)

• Specifies in what format the color will be returned after calling getColor()
• This setting is optional, if you won't call this function, default value will be used

5.4 setLightnessLimit($type, $lightness)

• Limits the maximum or minimum perceived lightness of colors which will be returned after calling getColor(). For example, you have white background so you don't want getColor() to return white and other very bright colors, so you use setLightnessLimit("max", 0.8)
• setLightnessLimit() can be called twice if you want to set "max" and "min" limit at the same time (difference between maximum and minimum lightness must be bigger or equal to 0.2)
• This setting is optional, if you won't call this function, default value will be used

5.5 setMaximumColors($maximumColors)

• Limits the maximum number of colors with which the PHPAutoColor will work.
• If list of used colors in one instance of PHPAutoColor will hit the $maximumColors limit, we start reusing previously assigned colors
• This setting is optional, if you won't call this function, number of used colors won't be limited

5.6 enableDebugging()

• Enables displaying of detected errors
• If errors occur, empty string is returned from getColor() method
• This setting is optional, if you won't call this function debugging window won't appear

6. List of pregenerated colors

• List of 65 visually most distinct colors generated using CIEDE2000 algorithm
• Colors from this list are used if you use setColorPickingMethod() with "static" (default), "dynamic" or "dynamic-random" parameter