Documentation pour PHP (Français)

• Utiliser colori.php
• Créer une couleur
• Propriétés d'une couleur
  • Propriétés précalculées
  • name
  • luminance
• Exprimer une couleur dans différents formats
• Modifier une couleur
  • change
  • replace
  • scale
  • greyscale / grayscale
  • sepia
  • complement
  • negative / invert
• Fusionner des couleurs
  • blend
  • unblend
  • whatToBlend
• Comparer deux couleurs
  • contrast
  • contrastedText
  • improveContrast
  • distance
  • same
• Autres fonctions
  • gradient

(Note : colori signifie couleurs en italien. Le singulier est colore.)

Utiliser colori.php

Il suffit de télécharger le fichier colori.php, puis de l'importer dans votre code PHP comme suit :

require_once 'colori.php';

Le fichier colori.php commence par class Couleur. Vous pouvez remplacer Couleur par un autre nom pour nommer la classe différemment. Dans cette documentation, nous utiliserons Colore.

Créer une couleur

Pour avoir accès aux fonctions de colori.php, vous devez créer un objet de classe Colore :

$rosso = new Colore('red');

// Ce qui aura pour résultat :

$rosso == object(Colore)[1]
  public 'r' => float 1,
  public 'g' => float 0,
  public 'b' => float 0,
  public 'a' => float 1,
  public 'h' => float 0,
  public 's' => float 1,
  public 'l' => float 0.5,
  public 'w' => float 0,
  public 'b' => float 0,
  public 'c' => float 0.54291,
  public 'c' => float 80.815,
  public 'c' => float 69.893,
  public 'c' => float 106.85,
  public 'c' => float 0.11349

Le paramètre à fournir en entrée de new Colore(parametre) doit être une chaîne de caractères dans un format valide selon la spécification CSS des formats de couleurs.

Exemples :

Créons les objets $rosso, représentant la couleur rouge, et $rossoTrasparente, représentant la couleur rouge d'opacité 0.6, à partir de leurs expressions dans les différents formats reconnus par CSS.

// Crée la couleur à partir de son nom
$rosso = new Colore('red');

// Crée la couleur à partir de son expression au format hexadécimal
$rosso = new Colore('#FF0000');
$rossoTrasparente = new Colore('#FF000099');
// ou
$rosso = new Colore('#F00');
$rossoTrasparente = new Colore('#F009');

// Crée la couleur à partir de son expression au format RGB
$rosso = new Colore('rgb(255, 0, 0)');
$rossoTrasparente = new Colore('rgb(255, 0, 0, 0.6)');
// ou
$rosso = new Colore('rgb(255 0 0)');
$rossoTrasparente = new Colore('rgb(255 0 0 / 0.6)');

Vous pouvez remplacer rgb par rgba, cela aura le même effet.

// Crée la couleur à partir de son expression au format HSL
$rosso = new Colore('hsl(0, 100%, 50%)');
$rossoTrasparente = new Colore('hsl(0, 100%, 50%, 0.6)');
// ou
$rosso = new Colore('hsl(0 100% 50%)');
$rossoTrasparente = new Colore('hsl(0 100% 50% / 0.6)');

Vous pouvez remplacer hsl par hsla, cela aura le même effet.

// Crée la couleur à partir de son expression au format HWB
$rosso = new Colore('hwb(0 0% 0%)');
$rossoTrasparente = new Colore('hwb(0 0% 0% / 0.6)');

// Crée la couleur à partir de son expression au format LAB
$rosso = new Colore('lab(54% 81 70)');
$rossoTrasparente = new Colore('lab(54% 81 70 / 0.6)');

// Crée la couleur à partie de son expression au format LCH
$rosso = new Colore('lch(54% 107 41)');
$rossoTrasparente = new Colore('lch(54% 107 41 / 0.6)');

L'espace de couleurs CIELAB (utilisé par les formats LAB et LCH) contient des couleurs qui ne sont pas dans l'espace de couleurs sRGB (utilisé par les formats RGB, HSL et HWB). Puisque CSS ne supporte pas encore nativement les couleurs au format LAB ou LCH, passer une telle couleur à new Colore() la convertira en la couleur la plus proche dans l'espace sRGB.

Pour cette raison, vous pourriez remarquer certaines contradictions, par exemple :

$a = new Colore('lab(50% 118 43)');
$a->rgb == 'rgb(232, 0, 78)'
// mais :
$b = new Colore('rgb(232, 0, 78)')
$b->lab == 'lab(50% 76 28)'

$a = new Colore('lch(50% 125 20)');
$a->rgb == 'rgb(232, 0, 78)'
// mais :
$b = new Colore('rgb(232, 0, 78)')
$b->lch == 'lch(50% 81 20)'

Propriétés d'une couleur

Propriétés précalculées

Lorsque un objet de classe Colore est créé en utilisant new Colore(expression), 14 propriétés différentes de la couleur sont calculées. Elles correspondent à tous les paramètres des différents formats de couleurs :

• Les propriétés r, g et b sont les valeurs de rouge, vert et bleu de la couleur lorsqu'elle est exprimée au format rgb(r, g, b). Ces valeurs sont habituellement données entre 0 et 255 ou en pourcentages.

• La propriété h est la valeur de teinte de la couleur lorsqu'elle est exprimée au format hsl(h, s, l) ou hwb(h, w, bk). Cette valeur est un angle, habituellement donné en degrés (de 0 à 360), grades (de 0 à 400), radians (de 0 à 2π) ou tours (de 0 à 1).

• Les propriétés s et l sont respectivement les valeurs de saturation et de luminosité de la couleur lorsqu'elle est exprimée au format hsl(h, s, l). Ces valeurs sont données en pourcentages.

• Les propriétés w et bk sont les valeurs de blancheur et noirceur de la couleur lorsqu'elle est exprimée au format hwb(h w bk). Ces valeurs sont données en pourcentages.

• La propriété ciel est la luminosité de la couleur dans l'espace de couleurs CIELAB, lorsqu'elle est exprimée aux formats lab(ciel ciea cieb) ou lch(ciel ciec cieh). Cette valeur est donnée en pourcentage. La spécification autorise des valeurs supérieures à 100% pour une compatibilité avec le standard HDR.

• Les propriétés ciea et cieb sont respectivement les valeurs de la couleur sur les axes "a" et "b" de l'espace de couleurs CIELAB, lorsqu'elle est exprimée au format lab(ciel ciea cieb). Elles peuvent prendre n'importe quelle valeur numérique, mais sont en général contenues dans l'intervalle [-160, 160].

• La propriété ciec est la valeur de chroma de la couleur losqu'elle est exprimée au format lch(ciel ciec cieh). Elle peut prendre n'importe quelle valeur numérique positive, mais est en général contenue dans l'intervalle [0, 230].

• La propriété cieh est la valeur de teinte de la couleur lorsqu'elle est exprimée au format lch(ciel ciec cieh). Cette valeur est un angle, habituellement donné en degrés (de 0 à 360), grades (de 0 à 400), radians (de 0 à 2π) ou tours (de 0 à 1). Elle est similaire à la propriété h du format HSL, mais sa valeur est définie d'une manière légèrement différente.

• La propriété a est l'opacité de la couleur. C'est le 4ème paramètre optionnel dans chaque format de couleur vu précédemment. Cette valeur est habituellement donnée dans l'intervalle [0, 1] ou en pourcentage.

name

Certaines couleurs ont un nom selon la spécification CSS. Pour ces couleurs-là, le paramètre name renverra leur nom :

(new Colore('red'))->name() == 'red'

Note : si une couleur n'est pas exactement égale à une couleur nommée (par exemple à cause d'un arrondi dans un calcul), la propriété name renverra quand même le nom de la couleur dont elle est proche :

(new Colore('red'))->rgb() == 'rgb(255, 0, 0)'
(new Colore('rgb(255, 0.1, 0.1)'))->name() == 'red'

La propriété exactName récupère le nom uniquement quand la couleur y correspond avec exactitude :

(new Colore('red'))->rgb() == 'rgb(255, 0, 0)'
(new Colore('rgb(255, 0.1, 0.1)'))->exactName() == null

luminance

La propriété luminance renvoie la valeur de luminance de la couleur, telle que définie par le W3C.

rosso.luminance == 0.2126

Exprimer une couleur dans différents formats

Les propriétés hex, rgb, hsl, hwb, lab et lch permettent de récupérer l'expression de la couleur au format correspondant :

$rosso = new Colore('red');
$rosso->hex() == '#ff0000'
$rosso->rgb() == 'rgb(255, 0, 0)'
$rosso->hsl() == 'hsl(0, 100%, 50%)'
$rosso->hwb() == 'hwb(0 0% 0%)'
$rosso->lab() == 'lab(54% 81 70)'
$rosso->lch() == 'lch(54% 107 41)'

Les couleurs transparentes (a < 1) sont aussi supportées :

$rossoTrasparente = new Colore('rgb(255, 0, 0, 0.6)');
$rossoTrasparente->hex() == '#ff000099'
$rossoTrasparente->rgb() == 'rgb(255, 0, 0, 0.6)'
$rossoTrasparente->hsl() == 'hsl(0, 100%, 50%, 0.6)'
$rossoTrasparente->hwb() == 'hwb(0 0% 0% / 0.6)'
$rossoTrasparente->lab() == 'lab(54% 81 70 / 0.6)'
$rossoTrasparente->lch() == 'lch(54% 107 41 / 0.6)'

Ces propriétés masquent l'opacité quand elle est égale à 1. Les propriétés hexa, rgba, hsla, hwba, laba et lcha permettent de l'afficher dans tous les cas :

$rosso = new Colore('red');
$rosso->hexa() == '#ff0000ff'
$rosso->rgba() == 'rgb(255, 0, 0, 1)'
$rosso->hsla() == 'hsl(0, 100%, 50%, 1)'
$rosso->hwba() == 'hwb(0 0% 0% / 1)'
$rosso->laba() == 'lab(54% 81 70 / 1)'
$rosso->lcha() == 'lch(54% 107 41 / 1)'

Modifier une couleur

change

La méthode change permet de modifier n'importe quelle propriété d'une couleur, et renvoie un objet de classe Colore dont toutes les propriétés ont été recalculées suite à la modification.

Comment l'utiliser :

$result = $color->change($prop, $val, $options = (object)['replace' => <Boolean>, 'scale' => <Boolean>]);

Elle s'applique à un objet de classe Colore, ici $color.

Elle prend comme arguments :

• $prop : une chaîne de caractères correspondant au nom de la propriété à modifier, par exemple 'r', 'g', 'b', etc.

• $val : un nombre ou pourcentage correspondant à la valeur qui sera additionnée à la valeur précédente de la propriété.

• $options : un objet contenant les propriétés suivantes :

  • replace (défaut = false) : un booléen. Si true, la valeur de $val remplacera la valeur précédente de la propriété, au lieu de s'y additionner.

  • scale (défaut = false) : un booléen. Si true, la valeur de $val sera multipliée à la valeur précédente de la propriété, au lieu de s'y additionner.

Elle renvoie un objet de classe Colore, ici $result, qui est une copie de $color dont la propriété $prop a été modifiée.

Exemples :

// Réduisons la luminosité du rouge de 10% :
$rosso = new Colore('red');
$nuovoColore = $rosso->change('l', '-10%');
// ce qui donne :
$rosso->hsl() == 'hsl(0, 100%, 50%)'
$nuovoColore->hsl() == 'hsl(0, 100%, 40%)'

// Remplaçons la luminosité du rouge par 10% :
$rosso = new Colore('red');
$nuovoColore = $rosso->change('l', '10%', (object)['replace' => true ]);
// ce qui donne :
$rosso->hsl() == 'hsl(0, 100%, 50%)'
$nuovoColore->hsl() == 'hsl(0, 100%, 10%)';

// Augmentons la luminosité du rouge de 50% de sa valeur actuelle :
$rosso->hsl() == 'hsl(0, 100%, 50%)'
$nuovoColore = $rosso->change('l', '150%', (object)['scale' => true]);
// ce qui donne :
$rosso->hsl() == 'hsl(0, 100%, 50%)'
$nuovoColore->hsl() == 'hsl(0, 100%, 75%)';

replace

La méthode replace est équivalente à change avec l'option { replace: true }.

Comment l'utiliser :

$result = $color->replace($prop, $val);

Elle s'applique à un objet de classe Colore, ici $color.

Elle prend comme arguments :

• $prop : une chaîne de caractères correspondant au nom de la propriété à modifier, par exemple 'r', 'g', 'b', etc.

• $val : un nombre ou pourcentage correspondant à la valeur qui remplacera la valeur précédente de la propriété.

Elle renvoie un objet de classe Colore, ici $result, qui est une copie de $color dont la propriété $prop a été remplacée.

Exemple :

// Remplaçons la luminosité du rouge par 10% :
$rosso = new Colore('red');
$nuovoColore = $rosso->replace('l', '10%');
// ce qui donne :
$nuovoColore->hsl() == 'hsl(0, 100%, 10%)';

scale

La méthode scale est équivalente à change avec l'option (object)["scale" => true].

Comment l'utiliser :

$result = $color->scale($prop, $val);

Elle s'applique à un objet de classe Colore, ici $color.

Elle prend comme arguments :

• $prop : une chaîne de caractères correspondant au nom de la propriété à modifier, par exemple 'r', 'g', 'b', etc.

• $val : un nombre ou pourcentage correspondant à la valeur qui sera multipliée à la valeur précédente de la propriété.

Elle renvoie un objet de classe Colore, ici $result, qui est une copie de $color dont la propriété $prop a été modifiée.

Exemple :

// Augmentons la luminosité du rouge de 50% de sa valeur actuelle :
$rosso = new Colore('red');
$nuovoColore = $rosso->scale('l', '150%');
// ce qui donne :
$rosso->hsl() == 'hsl(0, 100%, 50%)'
$nuovoColore->hsl() == 'hsl(0, 100%, 75%)'

greyscale / grayscale

La méthode greyscale (ou grayscale) transforme une couleur en un gris ayant la même luminosité qu'elle.

Comment l'utiliser :

$result = $color->greyscale();

Elle s'applique à un objet de class Colore, ici $color.

Elle ne prend aucun argument.

Elle renvoie un objet de classe Colore, ici $result, qui est une copie de $color dont la saturation a été réduite à 0.

Exemple :

// Prenons du bleu
$blu = new Colore('blue');
$blu->hsl() == 'hsl(240, 100%, 50%)'

// Appliquons sepia au bleu
$grigio = $blu->greyscale();
$grigio->hsl() == 'hsl(240, 0%, 50%)'

sepia

La méthode sepia transforme une couleur en un ton sépia.

Comment l'utiliser :

$result = $color->sepia();

Elle s'applique à un objet de class Colore, ici $color.

Elle ne prend aucun argument.

Elle renvoie un objet de classe Colore, ici $result, qui est une modification de $color vers les tons sépia.

Exemple :

// Prenons du bleu
$blu = new Colore('blue');
$blu->rgb() == 'rgb(0, 0, 255)'

// Appliquons greyscale au bleu
$seppia = $blu->sepia();
$seppia->rgb() == 'rgb(48, 43, 33)'

complement

La méthode complement calcule la couleur complémentaire.

Comment l'utiliser :

$result = $color->complement();

Elle s'applique à un objet de classe Colore, ici $color.

Elle ne prend aucun argument.

Elle renvoie un objet de classe Colore, ici $result, qui est la couleur complémentaire de $color.

Exemples :

// La couleur complémentaire du rouge est le cyan / aqua
$rosso = new Colore('red');
$rosso->complement()->name() == 'aqua'

// La couleur complémentaire du blanc est le blanc lui-même
$bianco = new Couleur('white');
$bianco->complement()->name() == 'white'

negative / invert

La méthode negative (ou invert) calcule la couleur négative.

Comment l'utiliser :

$result = $color->negative();

Elle s'applique à un objet de classe Colore, ici $color.

Elle ne prend aucun argument.

Elle renvoie un objet de classe Colore, ici $result, qui est la couleur négative de $color.

Exemples :

// La couleur négative du blanc est le noir
$bianco = new Colore('white');
$bianco->negative()->name() == 'black'

// La couleur négative du rouge est le cyan
$rosso = new Colore('red');
$rosso->negative()->name() == 'aqua'

Fusionner des couleurs

blend

La méthode statique blend permet de fusionner plusieurs couleurs. En d'autres termes, elle calcule la couleur que vous verriez à l'écran si vous superposiez plusieurs couleurs.

Comment l'utiliser :

$result = Colore::blend($color1, $color2, $color3, ...);

Elle prend comme arguments :

• un nombre arbitraire d'objets de type Colore ou de chaînes de caractères dans un format compatible avec new Colore(). Chaque couleur sera superposée à la précédente.

Elle renvoie un objet de type Colore qui est la couleur que l'on voit en superposant toutes les couleurs fournies en argument l'une après l'autre.

Attention, si vous superposez une couleur opaque (telle que $color->a == 1) à une autre couleur, alors le résultat sera cette même couleur opaque ; puisqu'elle n'est pas transparente, elle ne laisse pas entrevoir la couleur en-dessous. blend est donc principalement utile pour superposer des couleurs transparentes (telles que $color->a < 1).

Exemples :

// Prenons du rouge et superposons du bleu avec opacité 0.5
$bluTrasparente = (new Colore('blue'))->replace('a', .5);
$result = Colore::blend('red', $bluTrasparente);

// Le résultat est violet, comme on s'y attend
$result->name() == 'purple' 

// Superposons toujours du rouge et du bleu, mais ajoutons-y du vert
// avec opacité 0.4
$verdeTrasparente = (new Colore('green'))->replace('a', .4);
$result = Colore::blend('red', $bluTrasparente, $verdeTrasparente);

// Le résultat est un violet désaturé, presque gris
$result->rgb() == 'rgb(77, 51, 77)' 

unblend

La méthode blend permettait de résoudre l'égalité suivante pour obtenir $result :

$result = Colore::blend($background, $overlay);

La méthode statique unblend, quant à elle, permet résoudre la même équation lorsqu'on veut trouver $background. Autrement dit, elle prend une couleur $result et dé-fusionne $overlay d'avec elle.

$background = Colore::unblend($result, $overlay);

Comment l'utiliser :

$result = Colore::unblend($color1, $color2, $color3, ...);

Elle prend comme arguments :

• un nombre arbitraire d'objets de type Colore ou de chaînes de caractères dans un format compatible avec new Colore(). Chaque couleur sera retirée à la précédente.

Elle renvoie un objet de type Colore qui est la couleur obtenue après avoir dé-fusionné toutes les couleurs fournies en argument une par une.

Exemple :

// Avec blend, nous avons vu que fusionner du rouge et du bleu transparent
// donnait du violet. En toute logique, retirer le bleu transparent du violet
// devrait donc nous donner du rouge à nouveau.
$bluTrasparente = (new Colore('blue'))->replace('a', .5);
$result = Colore::unblend('purple', $bluTrasparente);

// C'est le cas !
$result->name() == 'red'

whatToBlend

La méthode blend permettait de résoudre l'égalité suivante pour obtenir $result :

$result = Colore::blend($background, $overlay)

La méthode statique whatToBlend, quant à elle, permet re résoudre la même équation lorsqu'on veut trouver $overlay. Autrement dit, elle prend deux couleurs $background et $result et calcule quelle couleur $overlay devrait être fusionnée avec $background pour obtenir la couleur $result.

$overlay = Colore::whatToBlend($background, $result)

Comment l'utiliser :

$overlay = Colore::whatToBlend($background, $result, $alpha, $alphaStep);

Elle prend comme arguments :

• $background et $result : deux objets de type Colore ou chaînes de caractères dans un format compatible avec new Colore().

• $alpha : un nombre, la valeur (optionnelle) d'opacité que vous souhaitez obtenir pour $overlay. En effet, plusieurs couleurs différentes peuvent être solutions de cette équation. Si tel est le cas, fournir cette valeur $alpha permet d'obtenir une solution unique.

• $alphaStep (défaut = 0.1) : un nombre, la valeur (optionnelle) d'écart entre l'opacité des solutions données par whatToBlend, dans le cas où il en existe plusieurs.

Exemples :

// whatToBlend donne la liste des couleurs qui peuvent être
// superposées au rouge pour obtenir du violet :
$result = Colore::whatToBlend('red', 'purple');
array_map($result, fn($c) => $c->rgb()) == [
  'rgb(0, 0, 255, 0.5)',
  'rgb(43, 0, 213, 0.6)',
  'rgb(74, 0, 183, 0.7)',
  'rgb(96, 0, 160, 0.8)',
  'rgb(114, 0, 142, 0.9)',
  'purple'
];

// Si on précise qu'on veut une solution d'opacité 0.5, on obtient
// bien du bleu d'opacité 0.5. C'est bien la valeur de bluTrasparente
// dans les exemples de blend et unblend !
$result = Colore::whatToBlend('red', 'purple', 0.5);
$result->rgb() == 'rgb(0, 0, 255, 0.5)'

Comparer deux couleurs

contrast

La méthode statique contrast calcule le contraste entre deux couleurs.

Comment l'utiliser :

$result = Colore::contrast($color1, $color2);

Elle prend comme arguments :

• $color1 et $color2 : deux objets de type Colore ou chaînes de caractères dans un format compatible avec new Colore().

Elle renvoie un nombre entre 1 et 21.

Exemples :

Colore::contrast('white', 'black') == 21
Colore::contrast('skyblue', 'darkblue') == 8.7835

Pour qu'un texte soit facilement lisible sur une surface colorée, il est nécessaire que le contraste entre la couleur de cette surface et la couleur du texte soit suffisamment élevé. La méthode contrast peut par exemple être pratique pour vérifier si deux couleurs vérifient les recommandations du WCAG.

contrastedText

La méthode contrastedText détermine si du texte noir ou blanc serait le plus visible sur une surface colorée.

Comment l'utiliser :

$result = $color->contrastedText();

Elle s'applique à un objet de type Colore, ici $color.

Elle ne prend aucun argument.

Elle renvoie la chaîne de caractères 'white' ou 'black'.

Exemples :

// Sur une surface bleue ciel, le texte noir
// est plus lisible que le texte blanc
$bluCielo = new Colore('skyblue');
$bluCielo->contrastedText() == 'black'

// Sur une surface bleue foncé, le texte blanc
// est plus lisible que le texte noir
$bluScuro = new Colore('darkblue');
$bluScuro->contrastedText() == 'white'

improveContrast

La méthode improveContrast modifie la couleur à laquelle elle est appliquée, plus particulièrement en augmentant ou diminuant sa luminosité CIE ciel, pour lui donner un meilleur contraste avec une autre couleur.

Comment l'utiliser :

$result = $color->improveContrast($referenceColor, $desiredContrast, $step, $options = (object)["lower" => <Boolean>, "towards" => <Boolean>, "maxIterations" => <Boolean>]);

Elle s'applique à un objet de type Colore ; dans cet exemple, il s'agit de $color.

Elle prend comme arguments :

• $referenceColor : un objet de type Colore ou une chaîne de caractères dans un format compatible avec new Colore(), utilisé comme couleur de référence : la méthode cherche à améliorer la valeur de Colore::contrast($color, $referenceColor).

• $desiredContrast : un nombre utilisé comme la valeur de contraste que la méthode essaiera d'atteindre.

• $step (défaut = 2) : un nombre utilisé comme la quantité qui sera ajoutée ou retirée de la luminosité CIE de $color ; c'est-à-dire qu'à chaque étape, $color->ciel augmente ou diminue de $step%.

• $options : un objet contenant les propriétés suivantes :

  • lower (défaut = false): peut prendre les valeurs suivantes :

    • false : improveContrast ne fera rien si Colore::contrast($color, $referenceColor) > $desiredContrast.
    • true : quand Colore::contrast($color, $referenceColor) > $desiredContrast, $color sera modifiée pour réduire le contraste afin qu'il se rapproche le plus possible de $desiredContrast.

  • towards (défaut = null) : détermine si improveContrast doit augmenter le contraste en éclaircissant ou en assombrissant $color. Peut prendre les valeurs suivantes :

    • 'black' : improveContrast essaiera uniquement d'améliorer le contraste et assombrissant $color.
    • 'white' : improveContrast essaiera uniquement d'améliorer le contraste et éclaircissant $color.
    • null : improveContrast essaiera de déterminer automatiquement s'il vaut mieux assombrir ou éclaircir $color. Si elle n'y parvient pas, la valeur choisie sera 'black'.

  • maxIterations (défaut = 100) : le nombre maximum de fois que improveContrast modifiera la couleur pour améliorer le contraste.

Elle renvoie un objet de classe Colore, ici $result, qui est une copie de $color à laquelle ont été appliquées les modifications de la propriété ciel telles que Colore::contrast($result, $referenceColor) > $desiredContrast.

Exemple :

// Prenons l'exemple d'un fond bleu clair, sur lequel
// on veut placer du texte bleu ciel.
$bluChiaro = new Couleur('lightblue');
$bluCielo = new Couleur('skyblue');
Colore::contrast($bluChiaro, $bluCielo) == 1.1396

// Le contraste entre les couleurs bleu ciel et bleu clair
// est trop faible pour être bien lisible. Le WCAG recommande
// un contraste d'au moins 4.5. Modifions la couleur bleu ciel
// pour atteindre cette valeur.
$nuovoBlue = $bluCielo->improveContrast($bluChiaro, 4.5);

// On peut voir que le nouveau bleu est beaucoup plus
// sombre que le bleu ciel dont on est parti.
$bluCielo->hsl() == 'hsl(197, 71%, 73%)'
$nuovoBlu->hsl() == 'hsl(193, 100%, 24%)'

// Le contraste souhaité est atteint !
Colore::contrast($bluChiaro, $nuovoBlue) == 4.6554

distance

La méthode statique distance mesure à quel point deux couleurs sont différentes.

Comment l'utiliser :

$result = Colore::distance($color1, $color2, $format, $tolerance);

Elle prend comme arguments :

• $color1 et $color2 : deux objets de type Colore ou chaînes de caractères dans un format compatible avec new Colore().

• $format : une chaîne de caractères, détermine quel format des couleurs sera utilisé pour mesurer leur distance. Peut prendre les valeurs suivantes :

  • 'rgb', 'hsl', 'hwb', 'lab' ou 'lch' : la distance entre les deux couleurs sera calculée en additionnant la différence des valeurs de chaque propriété du format choisi.
  • null (défaut) : la distance sera calculée en faisant la moyenne des distances pour tous les formats.

• $tolerance (défaut = 0.02) : un nombre qui représente une certaine tolérance pour ignorer certaines propriétés quand elles n'ont aucun effet. Par exemple, dans le format HSL, si L = 0, alors la couleur est noire indépendament des valeurs de H et S. Pour pouvoir tenir compte de ce fait même quand des arrondis ont rendu la valeur L des couleurs légèrement supérieure à 0, la méthode distance ignore H et S quand $color1->l < $tolerance && $color2->l < $tolerance.

Elle renvoie un nombre positif.

Exemples :

// Ce sont des couleurs identiques
Colore::distance('red', 'red') == 0

// Ce sont des couleurs bien différentes
Colore::distance('red', 'blue') == 1.3467999999999998

// Malgré des valeurs très différentes de H et S,
// les deux couleurs sont du noir
Colore::distance('hsl(200, 50%, 0%)', 'hsl(50, 35%, 0%)') == 0

same

La méthode statique same détermine si deux couleurs sont identiques.

Comment l'utiliser :

$result = Colore::same($color1, $color2, $tolerance);

Elle prend comme arguments :

• $color1 et $color2 : deux objets de type Colore ou chaînes de caractères dans un format compatible avec new Colore().

• $tolerance (défaut = 0.02) : un nombre qui représente la distance minimale entre deux couleurs pour qu'elles soient considérées différentes.

Elle renvoie true si les couleurs sont considérées identiques, false sinon.

Exemples :

// Ce sont des couleurs identiques
Colore::same('red', 'red') == true

// Ce sont des couleurs différentes
Colore::same('red', 'blue') == false

// Malgré des valeurs très différentes de H et S,
// les deux couleurs sont du noir
Colore::same('hsl(200, 50%, 0%)', 'hsl(50, 35%, 0%)') == true

// Les deux couleurs sont tellement proches
// qu'elles sont considérées identiques
Colore::same('rgb(0, 0, 255)', 'rgb(0, 0, 254)') == true

Autres fonctions

gradient

La méthode statique gradient génère un dégradé entre deux couleurs qui évite de passer par une zone désaturée (voir cet article).

Comment l'utiliser :

$result = Colore::gradient($start, $end, $steps, $format);

Elle prend comme arguments :

• $start et $end : deux objets de type Colore ou chaînes de caractères dans un format compatible avec new Colore().

• $steps (défaut = 5) : le nombre d'étapes - c'est-à-dire le nombre de couleurs qui seront calculées - pour passer de $start à $end. Plus ce nombre est élevé, plus le dégradé sera fluide et évitera la zone désaturée.

• $format (défaut = 'lch') : une chaîne de caractères contenant le nom du format dont les propriétés seront utilisées pour calculer le dégradé. Les valeurs supportées sont 'rgb', 'hsl', 'hwb', 'lab' et 'lch'.

Elle renvoie un Array de longueur $steps + 1 d'objets de type Colore, de la forme [$start, $color2, $color3, ..., $end].

Exemple :

$colori = Colore::gradient('orchid', 'palegreen');

// Pour utiliser le dégradé en CSS, plaçons les couleurs dans la syntaxe de dégradé CSS
$gradiente = 'linear-gradient(to right, ' . implode(', ', array_map(function($c) { return $c->name() ?? $c->rgb() })) . ')';

// En plaçant ceci comme valeur de background-image en CSS, le dégradé serait affiché
$$gradiente == 'linear-gradient(to right, orchid, rgb(255, 122, 167), rgb(255, 153, 134), rgb(253, 182, 89), rgb(210, 220, 98), palegreen)'

// Calculons un dégradé entre les mêmes couleurs, mais en utilisant le format HSL
$colori = Colore::gradient('orchid', 'palegreen', 5, 'hsl');

// Pour utiliser le dégradé en CSS, plaçons les couleurs dans la syntaxe de dégradé CSS
$gradiente = 'linear-gradient(to right, ' . implode(', ', array_map(function($c) { return $c->name() ?? $c->rgb() })) . ')';

// En plaçant ceci comme valeur de background-image en CSS, le dégradé serait affiché
$gradiente == 'linear-gradient(to right, orchid, rgb(227, 118, 158), darksalmon, rgb(241, 221, 133), rgb(204, 246, 142), palegreen)'