README

A Laravel package for handling hex colour values in Eloquent models with validation and type safety.

Installation

Install the package via Composer:

composer require danjohnson95/eloquent-colours

The service provider will be automatically registered.

Requirements

• PHP ^8.3
• Laravel ^12.0

Usage

Migration

Use the colourRgb() Blueprint macro to add a colour column to your migration:

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up()
    {
        Schema::create('products', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->colourRgb('primary_color');
            $table->colourRgb('secondary_color')->nullable();
            $table->timestamps();
        });
    }
};

This creates a string column with a length of 7 characters (for #RRGGBB format).

Model

Use the Colour cast in your Eloquent model to automatically validate and handle hex colour values:

namespace App\Models;

use DanJohnson95\EloquentColours\Casts\Colour;
use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    protected $fillable = [
        'name',
        'primary_color',
        'secondary_color',
    ];

    protected function casts(): array
    {
        return [
            'primary_color' => Colour::class,
            'secondary_color' => Colour::class,
        ];
    }
}

Working with Colours

// Create a product with a colour
$product = Product::create([
    'name' => 'Widget',
    'primary_color' => '#FF5733',
]);

// Access the colour value
echo $product->primary_color; // #FF5733

// Update the colour
$product->update([
    'primary_color' => '#3498DB',
]);

// The cast validates hex values automatically
$product->primary_color = '#INVALID'; // Throws InvalidArgumentException

Colour Entity

You can also work with the Colour entity directly:

use DanJohnson95\EloquentColours\Entities\Colour;

// Create a colour from hex
$colour = Colour::makeFromHex('#FF5733');

// Validate hex values
Colour::isValidHex('#FF5733'); // true
Colour::isValidHex('FF5733');  // true (# is optional)
Colour::isValidHex('#XYZ123'); // false

// Convert to string
echo $colour; // #FF5733
echo $colour->hex; // #FF5733

Testing

composer test

License

The MIT License (MIT). Please see the LICENSE file for more information.

Author

Dan Johnson - github@danjohnson.xyz