Iris Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require ozdemirburak/iris

Add to composer.json if using Laravel's autoloader:

"autoload": {
    "psr-4": {
        "App\\": "app/",
        "OzdemirBurak\\Iris\\": "vendor/ozdemirburak/iris/src/"
    }
}

Run composer dump-autoload.

2. First Use Case: Convert a hex color to RGB in a Blade template:

   use OzdemirBurak\Iris\Color\Hex;
   $hexColor = new Hex('#3a86ff');
   $rgbColor = $hexColor->toRgb();
   

   Output in Blade:

   <div style="background-color: rgb({{ $rgbColor->red() }}, {{ $rgbColor->green() }}, {{ $rgbColor->blue() }});">
   

Where to Look First

• Color Classes: src/Color/ directory for all supported formats (Hex, Hsl, Rgb, etc.).
• Factory: src/Color/Factory.php for dynamic color parsing.
• Manipulation Methods: Check BaseColor trait for shared methods like saturate(), lighten(), etc.

Implementation Patterns

1. Color Conversion Workflows

Pattern: Chain conversions for dynamic theming.

// Convert CMYK to HSL for UI adjustments
$cmyk = new Cmyk('cmyk(0,100,0,0)');
$hsl = $cmyk->toHsl();
$adjustedHsl = $hsl->saturate(10)->lighten(5);
$hex = $adjustedHsl->toHex();

Laravel Integration:

// Store converted colors in config
config(['theme.primary' => (new Hex('#2d3748'))->toHsl()->toArray()]);

2. Dynamic Theming with Gradients

Pattern: Generate color palettes for UI components.

// Create a gradient for a progress bar
$gradient = (new Hex('#4f46e5'))->gradient(new Hex('#7c3aed'), 5);
$progressColors = collect($gradient)->map(fn($color) => $color->toHex());

Usage in Blade:

@foreach ($progressColors as $color)
    <div style="background: {{ $color }}; width: 20%;"></div>
@endforeach

3. Alpha Handling for Transparency

Pattern: Manage transparency in CSS/JS.

// Convert RGBA to Hexa for CSS
$rgba = new Rgba('rgba(255, 99, 132, 0.5)');
$hexa = $rgba->toHexa();
$cssColor = $hexa->__toString(); // '#ff638480'

Laravel Mix/PostCSS:

// Use in PostCSS for dynamic opacity
module.exports = {
  plugins: [
    require('postcss-hexrgba')({
      format: 'hex8', // Outputs #RRGGBBAA
    }),
  ],
};

4. Factory for Unknown Inputs

Pattern: Parse user-uploaded colors safely.

// Handle untrusted color inputs (e.g., from DB/API)
$color = Factory::init(request('color_input'));
if ($color->isValid()) {
    $adjusted = $color->saturate(5)->toHex();
} else {
    $adjusted = new Hex('#000000'); // Fallback
}

5. OKLCH for Perceptual Uniformity

Pattern: Use OKLCH for colorblind-friendly designs.

// Convert to OKLCH for accessibility checks
$oklch = (new Hex('#e74c3c'))->toOklch();
$lightness = $oklch->lightness();
$isAccessible = $lightness > 50; // Simplified check

Laravel Validation:

use Illuminate\Validation\Rule;

$validator = Validator::make($request->all(), [
    'color' => [
        'required',
        Rule::function('accessible', function ($attribute, $value, $fail) {
            $oklch = Factory::init($value)->toOklch();
            if ($oklch->lightness() < 40) {
                $fail('Color must be light enough for readability.');
            }
        }),
    ],
]);

Gotchas and Tips

1. Alpha Precision Pitfalls

• Issue: Floating-point alpha values (e.g., 0.3) may convert to unexpected hex values.

  $rgba = new Rgba('rgba(255, 0, 0, 0.3)');
  $hexa = $rgba->toHexa(); // May output '#ff00004d' (0.3 ≈ 76/255)
  

• Fix: Use alphaRaw() for debugging:

  $rawAlpha = $rgba->alphaRaw(); // Returns 0.30000000000000004
  

2. CMYK Conversion Quirks

• Issue: CMYK to RGB may produce non-integer values, which Iris rounds.

  $cmyk = new Cmyk('cmyk(10, 20, 30, 40)');
  $rgb = $cmyk->toRgb();
  // RGB values may not be exact due to rounding (e.g., 123 instead of 122.5)
  

• Fix: Use values() to inspect raw values before conversion.

3. Gradient Edge Cases

• Issue: Multi-color gradients require pivot colors for smooth transitions.

  // Bad: No pivot → abrupt jumps
  $gradient = (new Hex('#ff0000'))->gradient(new Hex('#00ff00'), 3);
  
  // Good: Add pivot for smooth green-yellow transition
  $gradient = (new Hex('#ff0000'))->gradient([
      new Hex('#ffff00'),
      new Hex('#00ff00')
  ], 5);
  

• Tip: Use ->values() to debug gradient steps.

4. OKLCH Limitations

• Issue: OKLCH ignores alpha (e.g., oklch(50% 0.1 30 / 0.5) → alpha dropped).

  $oklch = new Oklch('oklch(50% 0.1 30 / 0.5)');
  echo $oklch->alpha(); // 1.0 (ignored)
  

• Workaround: Convert to RGBA first, then manipulate alpha:

  $rgba = (new Oklch('oklch(50% 0.1 30)'))->toRgba()->alpha(0.5);
  

5. Cloning and Mutation

• Gotcha: clone() creates a shallow copy—mutations affect the original if properties are references.

  $original = new Hex('#ff0000');
  $cloned = $original->clone();
  $cloned->red(0); // $original->red() may also change if not properly cloned!
  

• Fix: Use unserialize() for deep cloning:

  $cloned = unserialize(serialize($original));
  

6. Performance Tips

• Cache Conversions: Store converted colors in Laravel's cache.

  $cacheKey = 'color_'.$hexColor->__toString();
  $cachedRgb = Cache::remember($cacheKey, now()->addHours(1), function() use ($hexColor) {
      return $hexColor->toRgb();
  });
  

• Batch Processing: Use collect() for bulk operations:

  $colors = collect(['#ff0000', '#00ff00']);
  $hslColors = $colors->map(fn($hex) => (new Hex($hex))->toHsl());
  

7. Debugging Tools

• Dump Color Values:

  dd((new Hex('#ff5733'))->toArray()); // ['hex' => '#ff5733', 'rgb' => [255, 87, 51], ...]
  

• Validate Inputs:

  $color = Factory::init($input);
  if (!$color->isValid()) {
      throw new \InvalidArgumentException("Invalid color: {$input}");
  }
  

8. Extending Iris

• Custom Color Spaces: Extend BaseColor trait to