Core Concepts

Understanding the core concepts of color manipulation and extraction is essential for getting the most out of Color Palette PHP.

Color Spaces • Color Manipulation • Color Extraction • Theme Generation • Best Practices

Color Spaces

Color Palette PHP supports multiple color spaces, each serving different purposes:

RGB (Red, Green, Blue)

The standard color space for digital displays. Each color is represented by its red, green, and blue components.

```php use Farzai\ColorPalette\Color; // Create color from RGB values $color = new Color(37, 99, 235); // Get RGB components $rgb = $color->toRgb(); echo "R: {$rgb['r']}, G: {$rgb['g']}, B: {$rgb['b']}"; ```

HSL (Hue, Saturation, Lightness)

A more intuitive color space for adjustments. Hue represents the color, saturation the intensity, and lightness the brightness.

```php // Convert to HSL $hsl = $color->toHsl(); echo "H: {$hsl['h']}°, S: {$hsl['s']}%, L: {$hsl['l']}%"; // Create from HSL $color = Color::fromHsl(220, 84, 53); ```

CMYK (Cyan, Magenta, Yellow, Key)

Used primarily for print media. Represents colors using cyan, magenta, yellow, and black (key) components.

```php // Convert to CMYK $cmyk = $color->toCmyk(); echo "C: {$cmyk['c']}%, M: {$cmyk['m']}%, Y: {$cmyk['y']}%, K: {$cmyk['k']}%"; ```

LAB (Lightness, A, B)

A perceptually uniform color space. Useful for accurate color matching and calculations.

```php // Convert to LAB $lab = $color->toLab(); echo "L: {$lab['l']}, a: {$lab['a']}, b: {$lab['b']}"; ```

Color Manipulation

Color Palette PHP provides various methods for manipulating colors:

Basic Adjustments

use Farzai\ColorPalette\Color;

$color = new Color(37, 99, 235);

// Lightness adjustments
$lighter = $color->lighten(0.2);    // Increase lightness by 20%
$darker = $color->darken(0.2);      // Decrease lightness by 20%
$withLightness = $color->withLightness(0.5); // Set specific lightness value

// Saturation adjustments
$saturated = $color->saturate(0.1);     // Increase saturation by 10%
$desaturated = $color->desaturate(0.1); // Decrease saturation by 10%

// Hue adjustments
$rotated = $color->rotate(180);     // Rotate hue by 180 degrees

// Color space conversions
$hsv = $color->toHsv();            // Convert to HSV
$newColor = Color::fromHsv(180, 0.5, 0.8); // Create from HSV

// Color analysis
$brightness = $color->getBrightness();
$luminance = $color->getLuminance();
$isLight = $color->isLight();
$isDark = $color->isDark();

// Contrast calculations
$otherColor = new Color(255, 255, 255);
$contrastRatio = $color->getContrastRatio($otherColor);

Color Mixing

use Farzai\ColorPalette\Color;

$color1 = new Color(37, 99, 235);  // Blue
$color2 = new Color(239, 68, 68);  // Red

// Mix colors with different weights
$mixed = $color1->mix($color2, 0.5);  // 50-50 mix
$biased = $color1->mix($color2, 0.7); // 70% of color1, 30% of color2

Color Analysis

use Farzai\ColorPalette\Color;

$color = new Color(37, 99, 235);

// Brightness and contrast
$brightness = $color->getBrightness();
$isLight = $color->isLight();
$isDark = $color->isDark();

// Contrast ratio with another color
$otherColor = new Color(255, 255, 255);
$contrastRatio = $color->getContrastRatio($otherColor);

// Luminance
$luminance = $color->getLuminance();

Color Extraction

Color Palette PHP uses advanced algorithms to extract dominant colors from images:

Extraction Process

Image Loading: Support for various image formats
Color Sampling: Efficient pixel sampling
Color Quantization: Reducing colors to a manageable palette
Color Clustering: Grouping similar colors
Palette Generation: Creating the final color palette

use Farzai\ColorPalette\ImageFactory;
use Farzai\ColorPalette\ColorExtractorFactory;

// Load image
$imageFactory = new ImageFactory();
$image = $imageFactory->createFromPath('image.jpg');

// Configure extractor
$extractorFactory = new ColorExtractorFactory();
$extractor = $extractorFactory->make('gd', [
    'sample_size' => 50,
    'min_saturation' => 0.05,
    'min_brightness' => 0.05
]);

// Extract colors
$palette = $extractor->extract($image, 5);

Theme Generation

Create harmonious color schemes using various color theory principles:

Color Schemes

use Farzai\ColorPalette\Color;
use Farzai\ColorPalette\PaletteGenerator;

$baseColor = new Color(37, 99, 235);
$generator = new PaletteGenerator($baseColor);

// Generate different schemes
$analogous = $generator->analogous();      // Similar colors
$complementary = $generator->complementary(); // Opposite colors
$triadic = $generator->triadic();          // Three evenly spaced colors
$tetradic = $generator->tetradic();        // Four evenly spaced colors

// Generate a complete website theme
$theme = $generator->websiteTheme();

Theme Components

Primary Color: Main brand color
Secondary Color: Supporting color
Accent Color: Highlight color
Background Color: Page background
Surface Colors: UI element backgrounds
Text Colors: Automatically selected for contrast

Best Practices

Performance Optimization

Image Processing
- Use appropriate image sizes
- Choose the right backend (GD vs ImageMagick)
- Implement caching for extracted palettes
Color Manipulation
- Cache computed values
- Batch color transformations
- Use appropriate color spaces for specific operations

Accessibility

Contrast Ratios

// Ensure text is readable
$backgroundColor = $palette->getColors()[0];
$textColor = $palette->getSuggestedTextColor($backgroundColor);
   
// Check contrast ratio
$contrastRatio = $backgroundColor->getContrastRatio($textColor);
$isAccessible = $contrastRatio >= 4.5; // WCAG AA standard

Color Blindness
- Test palettes with color blindness simulators
- Use patterns or shapes alongside colors
- Ensure sufficient contrast between adjacent colors

Error Handling

use Farzai\ColorPalette\Exceptions\ImageException;
use Farzai\ColorPalette\Exceptions\ColorException;

try {
    $image = $imageFactory->createFromPath('image.jpg');
    $palette = $extractor->extract($image);
} catch (ImageException $e) {
    // Handle image-related errors
    log_error('Image processing failed: ' . $e->getMessage());
} catch (ColorException $e) {
    // Handle color-related errors
    log_error('Color processing failed: ' . $e->getMessage());
}

Factory Pattern Implementation

Color Palette PHP uses the Factory pattern to provide a flexible and maintainable way to create objects. This pattern is particularly useful for:

Image Loading

use Farzai\ColorPalette\ImageLoaderFactory;
   
$factory = new ImageLoaderFactory();
$loader = $factory->make([
    'max_size' => 1024,
    'allowed_types' => ['jpg', 'png']
]);
   
$image = $loader->load('path/to/image.jpg');

Color Extraction

use Farzai\ColorPalette\ColorExtractorFactory;
   
$factory = new ColorExtractorFactory();
   
// Choose backend based on needs
$gdExtractor = $factory->make('gd');
$imagickExtractor = $factory->make('imagick');

The factory pattern provides several benefits:

Encapsulation of object creation logic
Easy configuration management
Runtime backend selection
Simplified testing through dependency injection

For more details, see the Factory Classes Documentation.

Color Palette PHP

A powerful PHP library for extracting color palettes from images, generating color themes, and manipulating colors in multiple color spaces (RGB, HSL, CMYK, LAB)