PHPackages                             daikazu/laratone - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. daikazu/laratone

ActiveLibrary[Database & ORM](/categories/database)

daikazu/laratone
================

Simple API for managing color libraries in you Laravel application.

v5.0.0(5mo ago)2672MITPHPPHP ^8.4CI failing

Since Apr 4Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/daikazu/laratone)[ Packagist](https://packagist.org/packages/daikazu/laratone)[ Docs](https://github.com/daikazu/laratone)[ GitHub Sponsors](https://github.com/Daikazu)[ RSS](/packages/daikazu-laratone/feed)WikiDiscussions master Synced yesterday

READMEChangelog (10)Dependencies (14)Versions (14)Used By (0)

[  ![Logo for Laratone](art/header-light.png)](https://mikewall.dev)Laratone
========

[](#laratone)

[![Latest Version on Packagist](https://camo.githubusercontent.com/42797979895355b461a7a8d3382206e1d359d679fd251374ee7451f93fdea955/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6461696b617a752f6c617261746f6e652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/daikazu/laratone)[![GitHub Tests Action Status](https://camo.githubusercontent.com/84c07c994e25eff2d1c9a2872d965d5ca6dc8629fe9af8ec06d6cdec1ea0cfcf/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6461696b617a752f6c617261746f6e652f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/daikazu/laratone/actions?query=workflow%3Arun-tests+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/88219a22268d68e3571d3942bffad1cf7f3b254b7414ec366f141efcd1de1475/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6461696b617a752f6c617261746f6e652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/daikazu/laratone)

Laratone is a comprehensive Laravel package for managing color libraries and swatches in your applications. It provides an easy-to-use API for storing, retrieving, and managing color data, with built-in support for various color formats (HEX, RGB, CMYK, LAB, OKLCH) and popular color libraries.

Features
--------

[](#features)

- Multiple built-in color libraries (Solid Coated, GuangShun Thread, HC Twill)
- **Auto-calculation of RGB, CMYK, LAB, and OKLCH from hex values**
- **Find closest matching colors** using LAB or OKLCH distance algorithms
- Configurable white point reference for LAB color calculations
- Automatic color data caching with configurable TTL
- Easy color book management and seeding
- Flexible REST API with filtering, sorting, and pagination
- Type-safe color value casting (LAB, RGB, CMYK, OKLCH)
- Full PHP 8.4 support with strict typing throughout

Requirements
------------

[](#requirements)

- PHP 8.4 or higher
- Laravel 12.x or greater

> **Note:** For PHP 8.3 / Laravel 11 support, use version 4.x of this package.

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require daikazu/laratone
```

### Publish Configuration and Migrations

[](#publish-configuration-and-migrations)

Publish the configuration file:

```
php artisan vendor:publish --tag="laratone-config"
```

Publish and run the migrations:

```
php artisan vendor:publish --tag="laratone-migrations"
php artisan migrate
```

Configuration
-------------

[](#configuration)

The published config file (`config/laratone.php`) contains the following options:

```
return [
    // Table prefix for Laratone tables
    'table_prefix' => 'laratone_',

    // Cache duration in seconds for color books and colors
    'cache_time' => 3600,

    // Reference white point for LAB color calculations
    // Options: 'D50' (print), 'D55', 'D65' (daylight, default), 'D75'
    'white_point' => 'D65',

    // Default algorithm for finding closest colors: 'lab' or 'oklch'
    'default_match_algorithm' => 'lab',

    // Maximum number of colors that can be returned by find-closest
    'max_match_limit' => 100,
];
```

### White Point Options

[](#white-point-options)

When RGB, CMYK, LAB, or OKLCH values are not provided, they are automatically calculated from the hex value. LAB calculations require a reference white point (illuminant). OKLCH is a perceptually uniform color space and does not require white point configuration.

ValueDescriptionUse Case`D50`Warm white (~5000K)Print/graphic arts`D55`Mid-morning daylight (~5500K)Photography`D65`Standard daylight (~6500K)**Default**, web/screen`D75`North sky daylight (~7500K)Scientific applicationsUsage
-----

[](#usage)

### Seeding Color Books

[](#seeding-color-books)

Laratone comes with several pre-built color libraries:

- `ColorBookPlusSolidCoated`
- `ColorBookPlusSolidCoated336NewColors`
- `ColorBookMetallicCoated`
- `ColorBookPlusMetallicCoated`
- `GuangShunThreadColors`
- `HCTwillColors`

#### Seed All Color Books

[](#seed-all-color-books)

```
php artisan laratone:seed
```

#### Seed Specific Color Books

[](#seed-specific-color-books)

```
php artisan laratone:seed ColorBookPlusSolidCoatedSeeder
```

#### Import Custom Color Books

[](#import-custom-color-books)

```
php artisan laratone:seed --file ./mycolorbookfile.json
```

Example Color Book format:

```
{
  "name": "My Custom Color Book",
  "data": [
    {
      "name": "Custom Color 1",
      "hex": "FEDD00"
    },
    {
      "name": "Custom Color 2",
      "hex": "FF5500",
      "lab": "88.19,-6.97,111.73",
      "rgb": "254,221,0",
      "cmyk": "0,1,100,0",
      "oklch": "0.7206,0.1654,56.72"
    }
  ]
}
```

> **Note:** Only `name` and `hex` are required. RGB, CMYK, LAB, and OKLCH values are optional and will be auto-calculated from hex if not provided. If you have official color values (e.g., Solid Coated LAB values), include them to use those instead of calculated values.

REST API
--------

[](#rest-api)

### Color Books

[](#color-books)

List all available color books:

```
GET /api/laratone/colorbooks
```

ParameterRequiredDescriptionDefaultsortNoSort by name (asc/desc)-### Colors

[](#colors)

Get colors from a specific color book:

```
GET /api/laratone/colorbook/{slug}
```

ParameterRequiredDescriptionDefaultsortNoSort by name (asc/desc)-limitNoLimit number of results-randomNoRandomize results (1/true)false> **Note:** When using `random=true`, results are not cached to ensure different results on each request.

### Find Closest Colors

[](#find-closest-colors)

Find the closest matching colors in a color book to a target color:

```
GET /api/laratone/colorbook/{slug}/find-closest
```

ParameterRequiredDescriptionDefaulthexYesTarget color (6-char hex, with or without #)-limitNoNumber of closest colors to return1algorithmNoDistance algorithm: `lab` or `oklch`lab**Example Request:**

```
GET /api/laratone/colorbook/color-book-plus-solid-coated/find-closest?hex=FF5500&limit=3&algorithm=lab
```

**Example Response:**

```
{
  "target_hex": "FF5500",
  "algorithm": "lab",
  "matches": [
    {
      "name": "Orange 021 C",
      "hex": "FE5000",
      "distance": 1.2345,
      "rgb": {"r": 254, "g": 80, "b": 0},
      "cmyk": {"c": 0, "m": 69, "y": 100, "k": 0},
      "lab": {"l": 57.29, "a": 67.22, "b": 68.88},
      "oklch": {"l": 0.6279, "c": 0.2577, "h": 29.23}
    }
  ]
}
```

#### Distance Algorithms

[](#distance-algorithms)

AlgorithmDescriptionBest For`lab`CIE76 Delta E in LAB color spaceGeneral color matching, industry standard`oklch`Perceptually uniform cylindrical distanceModern applications, consistent perception### Rate Limiting & Custom Middleware

[](#rate-limiting--custom-middleware)

Laratone routes use a `laratone` middleware alias that does nothing by default. You can replace it with your own middleware to add rate limiting, authentication, or other functionality.

To add rate limiting, define the `laratone` middleware alias in your application's bootstrap:

```
// bootstrap/app.php (Laravel 11+)
->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'laratone' => \Illuminate\Routing\Middleware\ThrottleRequests::class . ':60,1',
    ]);
})
```

Or in a service provider:

```
// app/Providers/AppServiceProvider.php
use Illuminate\Routing\Router;

public function boot(Router $router): void
{
    $router->aliasMiddleware('laratone', \App\Http\Middleware\YourCustomMiddleware::class);
}
```

You can create a custom middleware class that combines multiple behaviors:

```
// app/Http/Middleware/LaratoneApiMiddleware.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Routing\Middleware\ThrottleRequests;

class LaratoneApiMiddleware extends ThrottleRequests
{
    public function handle($request, Closure $next, $maxAttempts = 60, $decayMinutes = 1, $prefix = '')
    {
        // Add custom logic here (authentication, logging, etc.)
        return parent::handle($request, $next, $maxAttempts, $decayMinutes, $prefix);
    }
}
```

Programmatic Usage
------------------

[](#programmatic-usage)

Laratone provides a simple API for managing colors programmatically:

```
use Daikazu\Laratone\Facades\Laratone;

// Get all color books with colors
$colorBooks = Laratone::colorBooks();

// Get a specific color book by slug
$colorBook = Laratone::colorBookBySlug('color-book-plus-solid-coated');

// Create a new color book
$newColorBook = Laratone::createColorBook('My New Color Book');

// Create with custom slug
$newColorBook = Laratone::createColorBook('My Color Book', 'custom-slug');

// Add a single color to a color book (only hex required)
$color = Laratone::addColorToBook($colorBook, [
    'name' => 'New Color',
    'hex' => 'FF0000',
]);

// Or with explicit values (these take precedence over calculated values)
$color = Laratone::addColorToBook($colorBook, [
    'name' => 'Solid Coated Red',
    'hex' => 'FF0000',
    'lab' => '53.23,80.11,67.22',  // Official Solid Coated LAB value
]);

// Add multiple colors at once
$colors = Laratone::addColorsToBook($colorBook, [
    ['name' => 'Red', 'hex' => 'FF0000'],
    ['name' => 'Green', 'hex' => '00FF00'],
    ['name' => 'Blue', 'hex' => '0000FF'],
]);

// Get all colors from a color book
$colors = Laratone::getColorsFromBook($colorBook);

// Update a color
Laratone::updateColor($color, ['name' => 'Updated Color Name']);

// Delete a color
Laratone::deleteColor($color);

// Find closest matching colors to a target hex
$closest = Laratone::findClosestColors($colorBook, 'FF5500');
// Returns the single closest color by default

// Find multiple closest colors with specific algorithm
$closest = Laratone::findClosestColors(
    colorBook: $colorBook,
    targetHex: 'FF5500',
    limit: 5,
    algorithm: 'oklch'  // or 'lab' (default)
);

// Each result includes a distance value
foreach ($closest as $color) {
    echo "{$color->name}: {$color->distance}";
}

// Clear cache manually
Laratone::clearCache();
```

Working with Color Models
-------------------------

[](#working-with-color-models)

Color values are automatically cast to associative arrays when accessed. If a value wasn't stored in the database, it will be **automatically calculated from the hex value**:

```
use Daikazu\Laratone\Models\Color;

$color = Color::first();

// Access color values as arrays
$color->hex;   // 'FF0000' (required, always stored)
$color->rgb;   // ['r' => 255, 'g' => 0, 'b' => 0] (stored or calculated)
$color->lab;   // ['l' => 53.23, 'a' => 80.11, 'b' => 67.22] (stored or calculated)
$color->cmyk;  // ['c' => 0, 'm' => 100, 'y' => 100, 'k' => 0] (stored or calculated)
$color->oklch; // ['l' => 0.6279, 'c' => 0.2577, 'h' => 29.23] (stored or calculated)

// Access the parent color book
$colorBook = $color->colorBook;
```

### Auto-Calculation Behavior

[](#auto-calculation-behavior)

- **Hex is required** - All colors must have a hex value
- **Other values are optional** - RGB, CMYK, LAB, and OKLCH are calculated from hex if not provided
- **Stored values take precedence** - If you provide explicit values (e.g., official Solid Coated LAB), those are used instead of calculated values
- **LAB uses white point config** - Calculated LAB values use the `white_point` setting from your config
- **OKLCH is perceptually uniform** - OKLCH does not require white point configuration and provides consistent perceptual color representation

Caching
-------

[](#caching)

Laratone automatically caches color book and color data to improve performance. The cache works with any Laravel cache driver, including file, database, Redis, and Memcached.

Cache is automatically cleared when:

- Creating a new color book
- Adding, updating, or deleting colors

To manually clear the cache:

```
php artisan laratone:clear-cache
```

Or programmatically:

```
Laratone::clearCache();
```

Upgrading
---------

[](#upgrading)

See [UPGRADE.md](UPGRADE.md) for upgrade instructions between major versions.

Testing
-------

[](#testing)

```
composer test
```

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Mike Wall](https://github.com/daikazu)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

50

—

FairBetter than 95% of packages

Maintenance70

Regular maintenance activity

Popularity17

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity88

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~258 days

Recently: every ~462 days

Total

12

Last Release

166d ago

Major Versions

v0.0.6 → v1.0.02018-09-07

v1.0.2 → v2.0.02020-06-15

v2.0.1 → v3.0.02024-06-11

v3.0.0 → v4.0.02025-04-29

v4.0.1 → v5.0.02026-01-15

PHP version history (6 changes)0.0.1PHP >=5.5.5

v1.0.0PHP >=7.0

v2.0.0PHP >=7.2

v3.0.0PHP ^8.2

v4.0.0PHP ^8.3

v5.0.0PHP ^8.4

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/4039367?v=4)[Mike Wall](/maintainers/daikazu)[@daikazu](https://github.com/daikazu)

---

Top Contributors

[![daikazu](https://avatars.githubusercontent.com/u/4039367?v=4)](https://github.com/daikazu "daikazu (95 commits)")

---

Tags

databaselaravel-packagepackagistseedlaravelswatcheslaratone

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/daikazu-laratone/health.svg)

```
[![Health](https://phpackages.com/badges/daikazu-laratone/health.svg)](https://phpackages.com/packages/daikazu-laratone)
```

###  Alternatives

[spatie/laravel-pdf

Create PDFs in Laravel apps

1.0k4.3M43](/packages/spatie-laravel-pdf)[wnx/laravel-backup-restore

A package to restore database backups made with spatie/laravel-backup.

213389.8k2](/packages/wnx-laravel-backup-restore)[spatie/laravel-model-flags

Add flags to Eloquent models

4551.2M4](/packages/spatie-laravel-model-flags)[clickbar/laravel-magellan

This package provides functionality for working with the postgis extension in Laravel.

438834.4k1](/packages/clickbar-laravel-magellan)[rawilk/profile-filament-plugin

Profile & MFA starter kit for filament.

3913.7k](/packages/rawilk-profile-filament-plugin)[lacodix/laravel-model-filter

A Laravel package to filter, search and sort models with ease while fetching from database.

17555.1k](/packages/lacodix-laravel-model-filter)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)