Hoppa till huvudinnehåll

Methods Reference

Complete reference for all methods available on Color and MutableColor classes.

Clamping and Value Modes​

Negarity Color supports two modes for handling channel values:

  • Non-Strict Mode (Default): Original values are preserved internally, but clamped values are returned when accessing channels. Out-of-range values are allowed when creating colors.
  • Strict Mode: Values are clamped immediately when assigned. All stored values are always within valid ranges.

The default mode is non-strict, which allows for out-of-gamut colors and preserves precision in calculations. Values are automatically clamped when:

  • Using getChannel() or getter methods (e.g., getR())
  • Converting to string (__toString())
  • Converting to hex (toHex())
  • Serializing to JSON

Use getChannelRaw() or get{Channel}Raw() methods to access original (unclamped) values.

Static Factory Methods​

Color Creation​

rgb(int $r, int $g, int $b): static​

Creates a color in RGB color space.

$color = Color::rgb(255, 100, 50);

rgba(int $r, int $g, int $b, int $a): static​

Creates a color in RGBA color space with alpha channel.

$color = Color::rgba(255, 100, 50, 128);

hsl(int $h, int $s, int $l): static​

Creates a color in HSL color space.

$color = Color::hsl(210, 50, 40);

hsla(int $h, int $s, int $l, int $a): static​

Creates a color in HSLA color space.

$color = Color::hsla(210, 50, 40, 200);

hsv(int $h, int $s, int $v): static​

Creates a color in HSV color space.

$color = Color::hsv(210, 50, 40);

cmyk(int $c, int $m, int $y, int $k): static​

Creates a color in CMYK color space.

$color = Color::cmyk(0, 50, 100, 0);

lab(int $l, int $a, int $b): static​

Creates a color in Lab color space.

$color = Color::lab(50, 20, -30);

lch(int $l, int $c, int $h): static​

Creates a color in LCh color space.

$color = Color::lch(50, 30, 210);

xyz(int $x, int $y, int $z): static​

Creates a color in XYZ color space.

$color = Color::xyz(20, 30, 40);

ycbcr(int $y, int $cb, int $cr): static​

Creates a color in YCbCr color space.

$color = Color::ycbcr(78, 100, -100);

hex(string $value, string $colorSpace = RGB::class): static​

Creates a color from a hexadecimal string.

$color = Color::hex('#FF6432');
$color = Color::hex('FF6432', HSL::class);

Supports formats: #RGB, #RGBA, #RRGGBB, #RRGGBBAA

__callStatic(string $name, array $arguments): static​

Creates a color from a named color (requires registered color registry).

Color::addRegistry(new VGANamedColors());
$red = Color::red();
$blue = Color::blue(HSL::class);

Instance Methods​

Color Space Information​

getColorSpace(): string​

Returns the color space class name.

$space = $color->getColorSpace(); // "Negarity\Color\ColorSpace\RGB"

getColorSpaceName(): string​

Returns the human-readable color space name.

$name = $color->getColorSpaceName(); // "rgb"

getChannels(): array​

Returns all channel names for the current color space.

$channels = $color->getChannels(); // ['r', 'g', 'b']

Channel Access​

getChannel(string $name): float​

Gets a specific channel value by name. Always returns clamped values (within valid range).

$r = $color->getChannel('r');

getChannelRaw(string $name): float​

Gets the raw (original) channel value without clamping. In strict mode, returns the original value before clamping. In non-strict mode, returns the stored value (which may be out of range).

$rRaw = $color->getChannelRaw('r');

getChannelForCalculation(string $name): float​

Gets the channel value appropriate for calculations. In strict mode, returns raw value (because stored values are already clamped). In non-strict mode, returns clamped value (for safety). This method is primarily used by filters and conversion methods.

$r = $color->getChannelForCalculation('r');

getR(), getG(), getB(), getA(), etc.​

Dynamic getter methods for each channel. These return clamped values (same as getChannel()).

$r = $color->getR();
$h = $color->getH(); // For HSL/HSV
$c = $color->getC(); // For CMYK/LCh

getRRaw(), getGRaw(), getBRaw(), getARaw(), etc.​

Dynamic getter methods for raw (original) channel values. These return unclamped values.

$rRaw = $color->getRRaw();
$hRaw = $color->getHRaw(); // For HSL/HSV

Conversion Methods​

toRGB(): static​

Converts the color to RGB color space.

$rgb = $color->toRGB();

toRGBA(int $alpha = 255): static​

Converts the color to RGBA color space.

$rgba = $color->toRGBA();
$rgba = $color->toRGBA(128);

toHSL(): static​

Converts the color to HSL color space.

$hsl = $color->toHSL();

toHSLA(int $alpha = 255): static​

Converts the color to HSLA color space.

$hsla = $color->toHSLA();

toHSV(): static​

Converts the color to HSV color space.

$hsv = $color->toHSV();

toCMYK(): static​

Converts the color to CMYK color space.

$cmyk = $color->toCMYK();

toLab(): static​

Converts the color to Lab color space.

$lab = $color->toLab();

toLCh(): static​

Converts the color to LCh color space.

$lch = $color->toLCh();

toXYZ(): static​

Converts the color to XYZ color space.

$xyz = $color->toXYZ();

toYCbCr(): static​

Converts the color to YCbCr color space.

$ycbcr = $color->toYCbCr();

Modification Methods​

with(array $channels): static​

Creates a new color with specified channel values changed.

$modified = $color->with(['r' => 200, 'g' => 150]);

without(array $channels): static​

Creates a new color with specified channels reset to default values.

$noRed = $color->without(['r']);

Utility Methods​

toArray(): array​

Returns the color as an associative array.

$array = $color->toArray();
// ['color-space' => 'rgb', 'values' => ['r' => 255, 'g' => 100, 'b' => 50]]

toHex(): string​

Converts the color to a hexadecimal string.

$hex = $color->toHex(); // "#FF6432"

__toString(): string​

Returns a string representation of the color.

echo $color; // "rgb(255, 100, 50)"

jsonSerialize(): array​

Implements JsonSerializable for JSON encoding.

$json = json_encode($color);

Filter Methods (Dynamic)​

When filters are registered, they become available as methods:

FilterRegistry::register(new BrightnessFilter());
$brighter = $color->brightness(20);

FilterRegistry::register(new InvertFilter());
$inverted = $color->invert();

MutableColor-Specific Methods​

setChannel(string $name, float|int $value): void​

Directly sets a channel value (only on MutableColor).

$mutable = new MutableColor(RGB::class, ['r' => 255, 'g' => 100, 'b' => 50]);
$mutable->setChannel('r', 200);

Static Registry Methods​

addRegistry(NamedColorRegistryInterface $registry): void​

Adds a named color registry.

Color::addRegistry(new VGANamedColors());

See Also​