{"id":20035830,"url":"https://github.com/daikazu/laratone","last_synced_at":"2026-01-16T23:29:45.861Z","repository":{"id":56961335,"uuid":"127805076","full_name":"daikazu/laratone","owner":"daikazu","description":"Simple API for managing color libraries in you Laravel application.","archived":false,"fork":false,"pushed_at":"2026-01-15T05:19:10.000Z","size":613,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-15T11:55:12.945Z","etag":null,"topics":["database","laravel-package","packagist","seed"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daikazu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"Daikazu"}},"created_at":"2018-04-02T19:51:27.000Z","updated_at":"2025-06-09T13:04:22.000Z","dependencies_parsed_at":"2025-04-29T17:28:09.928Z","dependency_job_id":"a2228c19-60c4-47c3-8375-2d180ede4f86","html_url":"https://github.com/daikazu/laratone","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/daikazu/laratone","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daikazu%2Flaratone","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daikazu%2Flaratone/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daikazu%2Flaratone/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daikazu%2Flaratone/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daikazu","download_url":"https://codeload.github.com/daikazu/laratone/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daikazu%2Flaratone/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28487586,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T22:54:02.790Z","status":"ssl_error","status_checked_at":"2026-01-16T22:50:10.344Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","laravel-package","packagist","seed"],"created_at":"2024-11-13T10:09:26.760Z","updated_at":"2026-01-16T23:29:45.845Z","avatar_url":"https://github.com/daikazu.png","language":"PHP","funding_links":["https://github.com/sponsors/Daikazu"],"categories":[],"sub_categories":[],"readme":"\u003ca href=\"https://mikewall.dev\"\u003e\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"art/header-dark.png\"\u003e\n  \u003cimg alt=\"Logo for Laratone\" src=\"art/header-light.png\"\u003e\n\u003c/picture\u003e\n\u003c/a\u003e\n\n# Laratone\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/daikazu/laratone.svg?style=flat-square)](https://packagist.org/packages/daikazu/laratone)\n[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/daikazu/laratone/run-tests.yml?branch=main\u0026label=tests\u0026style=flat-square)](https://github.com/daikazu/laratone/actions?query=workflow%3Arun-tests+branch%3Amain)\n[![Total Downloads](https://img.shields.io/packagist/dt/daikazu/laratone.svg?style=flat-square)](https://packagist.org/packages/daikazu/laratone)\n\nLaratone 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.\n\n## Features\n\n- Multiple built-in color libraries (Solid Coated, GuangShun Thread, HC Twill)\n- **Auto-calculation of RGB, CMYK, LAB, and OKLCH from hex values**\n- **Find closest matching colors** using LAB or OKLCH distance algorithms\n- Configurable white point reference for LAB color calculations\n- Automatic color data caching with configurable TTL\n- Easy color book management and seeding\n- Flexible REST API with filtering, sorting, and pagination\n- Type-safe color value casting (LAB, RGB, CMYK, OKLCH)\n- Full PHP 8.4 support with strict typing throughout\n\n## Requirements\n\n- PHP 8.4 or higher\n- Laravel 12.x or greater\n\n\u003e **Note:** For PHP 8.3 / Laravel 11 support, use version 4.x of this package.\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require daikazu/laratone\n```\n\n### Publish Configuration and Migrations\n\nPublish the configuration file:\n\n```bash\nphp artisan vendor:publish --tag=\"laratone-config\"\n```\n\nPublish and run the migrations:\n\n```bash\nphp artisan vendor:publish --tag=\"laratone-migrations\"\nphp artisan migrate\n```\n\n## Configuration\n\nThe published config file (`config/laratone.php`) contains the following options:\n\n```php\nreturn [\n    // Table prefix for Laratone tables\n    'table_prefix' =\u003e 'laratone_',\n\n    // Cache duration in seconds for color books and colors\n    'cache_time' =\u003e 3600,\n\n    // Reference white point for LAB color calculations\n    // Options: 'D50' (print), 'D55', 'D65' (daylight, default), 'D75'\n    'white_point' =\u003e 'D65',\n\n    // Default algorithm for finding closest colors: 'lab' or 'oklch'\n    'default_match_algorithm' =\u003e 'lab',\n\n    // Maximum number of colors that can be returned by find-closest\n    'max_match_limit' =\u003e 100,\n];\n```\n\n### White Point Options\n\nWhen 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.\n\n| Value | Description | Use Case |\n|-------|-------------|----------|\n| `D50` | Warm white (~5000K) | Print/graphic arts |\n| `D55` | Mid-morning daylight (~5500K) | Photography |\n| `D65` | Standard daylight (~6500K) | **Default**, web/screen |\n| `D75` | North sky daylight (~7500K) | Scientific applications |\n\n## Usage\n\n### Seeding Color Books\n\nLaratone comes with several pre-built color libraries:\n\n- `ColorBookPlusSolidCoated`\n- `ColorBookPlusSolidCoated336NewColors`\n- `ColorBookMetallicCoated`\n- `ColorBookPlusMetallicCoated`\n- `GuangShunThreadColors`\n- `HCTwillColors`\n\n#### Seed All Color Books\n```bash\nphp artisan laratone:seed\n```\n\n#### Seed Specific Color Books\n```bash\nphp artisan laratone:seed ColorBookPlusSolidCoatedSeeder\n```\n\n#### Import Custom Color Books\n```bash\nphp artisan laratone:seed --file ./mycolorbookfile.json\n```\n\nExample Color Book format:\n```json\n{\n  \"name\": \"My Custom Color Book\",\n  \"data\": [\n    {\n      \"name\": \"Custom Color 1\",\n      \"hex\": \"FEDD00\"\n    },\n    {\n      \"name\": \"Custom Color 2\",\n      \"hex\": \"FF5500\",\n      \"lab\": \"88.19,-6.97,111.73\",\n      \"rgb\": \"254,221,0\",\n      \"cmyk\": \"0,1,100,0\",\n      \"oklch\": \"0.7206,0.1654,56.72\"\n    }\n  ]\n}\n```\n\n\u003e **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.\n\n## REST API\n\n### Color Books\n\nList all available color books:\n\n```http\nGET /api/laratone/colorbooks\n```\n\n| Parameter | Required | Description | Default |\n|-----------|:--------:|-------------|:-------:|\n| sort      | No       | Sort by name (asc/desc) | - |\n\n### Colors\n\nGet colors from a specific color book:\n\n```http\nGET /api/laratone/colorbook/{slug}\n```\n\n| Parameter | Required | Description | Default |\n|-----------|:--------:|-------------|:-------:|\n| sort      | No       | Sort by name (asc/desc) | - |\n| limit     | No       | Limit number of results | - |\n| random    | No       | Randomize results (1/true) | false |\n\n\u003e **Note:** When using `random=true`, results are not cached to ensure different results on each request.\n\n### Find Closest Colors\n\nFind the closest matching colors in a color book to a target color:\n\n```http\nGET /api/laratone/colorbook/{slug}/find-closest\n```\n\n| Parameter | Required | Description | Default |\n|-----------|:--------:|-------------|:-------:|\n| hex       | Yes      | Target color (6-char hex, with or without #) | - |\n| limit     | No       | Number of closest colors to return | 1 |\n| algorithm | No       | Distance algorithm: `lab` or `oklch` | lab |\n\n**Example Request:**\n```http\nGET /api/laratone/colorbook/color-book-plus-solid-coated/find-closest?hex=FF5500\u0026limit=3\u0026algorithm=lab\n```\n\n**Example Response:**\n```json\n{\n  \"target_hex\": \"FF5500\",\n  \"algorithm\": \"lab\",\n  \"matches\": [\n    {\n      \"name\": \"Orange 021 C\",\n      \"hex\": \"FE5000\",\n      \"distance\": 1.2345,\n      \"rgb\": {\"r\": 254, \"g\": 80, \"b\": 0},\n      \"cmyk\": {\"c\": 0, \"m\": 69, \"y\": 100, \"k\": 0},\n      \"lab\": {\"l\": 57.29, \"a\": 67.22, \"b\": 68.88},\n      \"oklch\": {\"l\": 0.6279, \"c\": 0.2577, \"h\": 29.23}\n    }\n  ]\n}\n```\n\n#### Distance Algorithms\n\n| Algorithm | Description | Best For |\n|-----------|-------------|----------|\n| `lab` | CIE76 Delta E in LAB color space | General color matching, industry standard |\n| `oklch` | Perceptually uniform cylindrical distance | Modern applications, consistent perception |\n\n### Rate Limiting \u0026 Custom Middleware\n\nLaratone 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.\n\nTo add rate limiting, define the `laratone` middleware alias in your application's bootstrap:\n\n```php\n// bootstrap/app.php (Laravel 11+)\n-\u003ewithMiddleware(function (Middleware $middleware) {\n    $middleware-\u003ealias([\n        'laratone' =\u003e \\Illuminate\\Routing\\Middleware\\ThrottleRequests::class . ':60,1',\n    ]);\n})\n```\n\nOr in a service provider:\n\n```php\n// app/Providers/AppServiceProvider.php\nuse Illuminate\\Routing\\Router;\n\npublic function boot(Router $router): void\n{\n    $router-\u003ealiasMiddleware('laratone', \\App\\Http\\Middleware\\YourCustomMiddleware::class);\n}\n```\n\nYou can create a custom middleware class that combines multiple behaviors:\n\n```php\n// app/Http/Middleware/LaratoneApiMiddleware.php\nnamespace App\\Http\\Middleware;\n\nuse Closure;\nuse Illuminate\\Routing\\Middleware\\ThrottleRequests;\n\nclass LaratoneApiMiddleware extends ThrottleRequests\n{\n    public function handle($request, Closure $next, $maxAttempts = 60, $decayMinutes = 1, $prefix = '')\n    {\n        // Add custom logic here (authentication, logging, etc.)\n        return parent::handle($request, $next, $maxAttempts, $decayMinutes, $prefix);\n    }\n}\n```\n\n## Programmatic Usage\n\nLaratone provides a simple API for managing colors programmatically:\n\n```php\nuse Daikazu\\Laratone\\Facades\\Laratone;\n\n// Get all color books with colors\n$colorBooks = Laratone::colorBooks();\n\n// Get a specific color book by slug\n$colorBook = Laratone::colorBookBySlug('color-book-plus-solid-coated');\n\n// Create a new color book\n$newColorBook = Laratone::createColorBook('My New Color Book');\n\n// Create with custom slug\n$newColorBook = Laratone::createColorBook('My Color Book', 'custom-slug');\n\n// Add a single color to a color book (only hex required)\n$color = Laratone::addColorToBook($colorBook, [\n    'name' =\u003e 'New Color',\n    'hex' =\u003e 'FF0000',\n]);\n\n// Or with explicit values (these take precedence over calculated values)\n$color = Laratone::addColorToBook($colorBook, [\n    'name' =\u003e 'Solid Coated Red',\n    'hex' =\u003e 'FF0000',\n    'lab' =\u003e '53.23,80.11,67.22',  // Official Solid Coated LAB value\n]);\n\n// Add multiple colors at once\n$colors = Laratone::addColorsToBook($colorBook, [\n    ['name' =\u003e 'Red', 'hex' =\u003e 'FF0000'],\n    ['name' =\u003e 'Green', 'hex' =\u003e '00FF00'],\n    ['name' =\u003e 'Blue', 'hex' =\u003e '0000FF'],\n]);\n\n// Get all colors from a color book\n$colors = Laratone::getColorsFromBook($colorBook);\n\n// Update a color\nLaratone::updateColor($color, ['name' =\u003e 'Updated Color Name']);\n\n// Delete a color\nLaratone::deleteColor($color);\n\n// Find closest matching colors to a target hex\n$closest = Laratone::findClosestColors($colorBook, 'FF5500');\n// Returns the single closest color by default\n\n// Find multiple closest colors with specific algorithm\n$closest = Laratone::findClosestColors(\n    colorBook: $colorBook,\n    targetHex: 'FF5500',\n    limit: 5,\n    algorithm: 'oklch'  // or 'lab' (default)\n);\n\n// Each result includes a distance value\nforeach ($closest as $color) {\n    echo \"{$color-\u003ename}: {$color-\u003edistance}\";\n}\n\n// Clear cache manually\nLaratone::clearCache();\n```\n\n## Working with Color Models\n\nColor 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**:\n\n```php\nuse Daikazu\\Laratone\\Models\\Color;\n\n$color = Color::first();\n\n// Access color values as arrays\n$color-\u003ehex;   // 'FF0000' (required, always stored)\n$color-\u003ergb;   // ['r' =\u003e 255, 'g' =\u003e 0, 'b' =\u003e 0] (stored or calculated)\n$color-\u003elab;   // ['l' =\u003e 53.23, 'a' =\u003e 80.11, 'b' =\u003e 67.22] (stored or calculated)\n$color-\u003ecmyk;  // ['c' =\u003e 0, 'm' =\u003e 100, 'y' =\u003e 100, 'k' =\u003e 0] (stored or calculated)\n$color-\u003eoklch; // ['l' =\u003e 0.6279, 'c' =\u003e 0.2577, 'h' =\u003e 29.23] (stored or calculated)\n\n// Access the parent color book\n$colorBook = $color-\u003ecolorBook;\n```\n\n### Auto-Calculation Behavior\n\n- **Hex is required** - All colors must have a hex value\n- **Other values are optional** - RGB, CMYK, LAB, and OKLCH are calculated from hex if not provided\n- **Stored values take precedence** - If you provide explicit values (e.g., official Solid Coated LAB), those are used instead of calculated values\n- **LAB uses white point config** - Calculated LAB values use the `white_point` setting from your config\n- **OKLCH is perceptually uniform** - OKLCH does not require white point configuration and provides consistent perceptual color representation\n\n## Caching\n\nLaratone automatically caches color book and color data to improve performance. The cache works with any Laravel cache driver, including file, database, Redis, and Memcached.\n\nCache is automatically cleared when:\n- Creating a new color book\n- Adding, updating, or deleting colors\n\nTo manually clear the cache:\n\n```bash\nphp artisan laratone:clear-cache\n```\n\nOr programmatically:\n\n```php\nLaratone::clearCache();\n```\n\n## Upgrading\n\nSee [UPGRADE.md](UPGRADE.md) for upgrade instructions between major versions.\n\n## Testing\n\n```bash\ncomposer test\n```\n\n## Contributing\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) for details.\n\n## Security Vulnerabilities\n\nPlease review [our security policy](../../security/policy) on how to report security vulnerabilities.\n\n## Credits\n\n- [Mike Wall](https://github.com/daikazu)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaikazu%2Flaratone","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaikazu%2Flaratone","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaikazu%2Flaratone/lists"}