Download the PHP package daikazu/laratone without Composer

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

• 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

• 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

You can install the package via composer:

Publish Configuration and Migrations

Publish the configuration file:

Publish and run the migrations:

Configuration

The published config file (config/laratone.php) contains the following 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.

Usage

Seeding Color Books

Laratone comes with several pre-built color libraries:

• ColorBookPlusSolidCoated
• ColorBookPlusSolidCoated336NewColors
• ColorBookMetallicCoated
• ColorBookPlusMetallicCoated
• GuangShunThreadColors
• HCTwillColors

Seed All Color Books

Seed Specific Color Books

Import Custom Color Books

Example Color Book format:

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

Color Books

List all available color books:

Colors

Get colors from a specific color book:

Note: When using random=true, results are not cached to ensure different results on each request.

Find Closest Colors

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

Example Request:

Example Response:

Distance Algorithms

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:

Or in a service provider:

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

Programmatic Usage

Laratone provides a simple API for managing colors programmatically:

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:

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

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:

Or programmatically:

Upgrading

See UPGRADE.md for upgrade instructions between major versions.

Testing

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Mike Wall
• All Contributors

License

The MIT License (MIT). Please see License File for more information.