Tc Lib Color Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require tecnickcom/tc-lib-color
   

2. Basic Usage:

   use Com\Tecnick\Color\Web;
   
   $color = new Web();
   $rgb = $color->getRgbObjFromHex('#336699');
   echo $rgb->getCssColor(); // Outputs: rgb(51, 102, 153)
   

3. First Use Case: Convert a hex color to HSL for dynamic UI adjustments:

   $hsl = $color->getHslObjFromHex('#336699');
   echo $hsl->getHslString(); // Outputs: hsl(210, 50%, 40%)
   

Where to Look First

• Class Reference: API Docs for method signatures.
• Examples: example/index.php for practical workflows (e.g., PDF/CSS conversions).
• Color Models: Focus on Web, Pdf, or Spot classes based on your pipeline (web vs. PDF).

Implementation Patterns

Core Workflows

1. Color Conversion Pipeline:

   $web = new Web();
   $hex = '#ff5733';
   $rgb = $web->getRgbObjFromHex($hex);
   $cmyk = $rgb->toCmyk(); // Convert to CMYK for PDF
   $lab = $cmyk->toLab();  // Further conversion for color analysis
   

2. PDF-Specific Handling:

   $pdf = new Pdf();
   $spotColor = $pdf->getSpotColorObj('PANTONE 185 C');
   $lab = $spotColor->toLab(); // Convert spot to LAB for consistency
   

3. CSS Integration:

   $cssColor = $rgb->getCssColor(); // Outputs: rgba(255, 87, 51, 1)
   $cssColor = $hsl->getCssColor(); // Outputs: hsla(12, 100%, 50%, 1)
   

Laravel-Specific Patterns

1. Service Provider Binding:

   // app/Providers/AppServiceProvider.php
   public function register()
   {
       $this->app->singleton(Web::class, function ($app) {
           return new Web();
       });
   }
   

2. Helper Methods:

   // app/Helpers/ColorHelper.php
   if (!function_exists('hexToRgb')) {
       function hexToRgb(string $hex): array {
           $color = app(Web::class);
           $rgb = $color->getRgbObjFromHex($hex);
           return [$rgb->getRed(), $rgb->getGreen(), $rgb->getBlue()];
       }
   }
   

3. Dynamic Theming:

   // In a Blade template
   <div style="background-color: {{ hexToRgb($themeColor)->toCssRgb() }}">
   

4. Form Request Validation:

   // app/Http/Requests/UpdateThemeRequest.php
   public function rules()
   {
       return [
           'primary_color' => 'required|hex_color', // Custom rule
       ];
   }
   

5. Color-Based Conditional Logic:

   // app/Services/ColorAnalyzer.php
   public function isDarkColor(string $hex): bool
   {
       $rgb = app(Web::class)->getRgbObjFromHex($hex);
       $luminance = 0.2126 * $rgb->getRed() + 0.7152 * $rgb->getGreen() + 0.0722 * $rgb->getBlue();
       return $luminance < 128;
   }
   

Gotchas and Tips

Pitfalls

1. Floating-Point Precision:

   • CMYK/LAB conversions may introduce rounding errors. Use round() or toString() methods to normalize outputs:

     $lab = $cmyk->toLab();
     echo $lab->getLString(); // Use string methods for consistency
     

2. Hex Input Validation:

   • The library assumes valid hex inputs (e.g., #336699). Sanitize user inputs:

     if (!preg_match('/^#[a-f0-9]{6}$/i', $hex)) {
         throw new \InvalidArgumentException('Invalid hex color');
     }
     

3. PDF Spot Color Limitations:

   • Spot colors (e.g., PANTONE) require exact matches. Use Pdf::getSpotColorObj() with predefined names:

     $spot = $pdf->getSpotColorObj('PANTONE 185 C');
     if (!$spot) {
         throw new \RuntimeException('Unsupported spot color');
     }
     

4. Alpha Channel Handling:

   • RGBA/HSL/A colors default to 1.0 (fully opaque). Explicitly set alpha if needed:

     $rgba = $web->getRgbObjFromHex('#33669980'); // 80 = 50% opacity
     

Debugging Tips

1. Inspect Intermediate Values:

   $rgb = $web->getRgbObjFromHex('#336699');
   dump([
       'Red' => $rgb->getRed(),
       'Green' => $rgb->getGreen(),
       'Blue' => $rgb->getBlue(),
       'Hex' => $rgb->getHex(),
   ]);
   

2. Compare Conversions:

   $hex = '#336699';
   $rgb = $web->getRgbObjFromHex($hex);
   $hsl = $rgb->toHsl();
   $rgbFromHsl = $hsl->toRgb();
   assert($rgb->getHex() === $rgbFromHsl->getHex(), 'Conversion mismatch');
   

3. Log Color Profiles:

   $pdf = new Pdf();
   $lab = $pdf->getLabObjFromCmyk($cmyk);
   \Log::info('LAB Profile', ['L' => $lab->getL(), 'A' => $lab->getA(), 'B' => $lab->getB()]);
   

Extension Points

1. Custom Color Spaces:

   • Extend \Com\Tecnick\Color\Color to support niche models (e.g., HSB):

     class Hsb extends Color {
         public function toHsb(): self { /* ... */ }
     }
     

2. Laravel Facades:

   // app/Facades/Color.php
   namespace App\Facades;
   
   use Illuminate\Support\Facades\Facade;
   use Com\Tecnick\Color\Web;
   
   class Color extends Facade {
       protected static function getFacadeAccessor() {
           return Web::class;
       }
   }
   

   Usage:

   $rgb = Color::getRgbObjFromHex('#336699');
   

3. Color Palette Caching:

   // app/Services/PaletteCache.php
   public function getCachedPalette(string $key): array {
       return Cache::remember("color_palette_{$key}", 3600, function () use ($key) {
           return $this->generatePalette($key);
       });
   }
   

4. Event-Driven Color Changes:

   // app/Listeners/ThemeUpdated.php
   public function handle(ThemeUpdated $event) {
       $hex = $event->theme['primary_color'];
       $rgb = app(Web::class)->getRgbObjFromHex($hex);
       Cache::forever('theme_rgb', $rgb->toArray());
   }