constant()

Ce que fait constant()

La fonction constant() renvoie la valeur d'une constante dont le nom est fourni sous forme de string. Cette page couvre sa signature, les raisons pour lesquelles vous pourriez l'utiliser à la place d'une référence directe à la constante, son fonctionnement avec les constantes de classe et d'enum, ainsi que les pièges à éviter.

Si vous ne connaissez le nom d'une constante qu'à l'exécution — par exemple parce qu'il a été construit à partir d'une autre variable — constant() est la bonne façon de la retrouver. Pour apprendre comment créer des constantes, consultez PHP Constants et la fonction define().

Syntaxe et valeur de retour

constant(string $name): mixed

• $name — le nom de la constante sous forme de string. Pour une constante de classe, utilisez la forme qualifiée ClassName::CONSTANT.
• Renvoie la valeur de la constante. Le type de retour correspond à ce que la constante contient (int, string, float, bool, array, ou un cas d'enum).

Si la constante n'est pas définie, constant() lève une Error (une exception \Error) dans PHP 8 et versions ultérieures. Vérifiez d'abord avec defined() si vous n'êtes pas certain.

Exemple de base

La constante PI est définie avec la valeur 3.14159. constant("PI") récupère cette valeur, qui est ensuite utilisée pour calculer l'aire d'un cercle. La sortie est :

The area of a circle with radius 5 is 78.53975.

Quand l'utiliser ?

Dans cet exemple de base, constant("PI") fait exactement la même chose qu'écrire PI directement — il n'y a donc aucune raison de l'utiliser ici. La fonction ne prend tout son intérêt que lorsque le nom de la constante n'est pas connu avant l'exécution. Comme vous ne pouvez pas placer une variable là où un nom de constante est attendu, constant() vous permet de résoudre un nom contenu dans une string :

<?php

const LEVEL_LOW  = 1;
const LEVEL_HIGH = 9;

$severity = 'HIGH';
$value = constant("LEVEL_$severity");

echo "Severity level: $value";

Ceci affiche Severity level: 9. La constante choisie dépend de $severity, ce qu'une référence codée en dur à LEVEL_HIGH ne pourrait jamais faire.

Constantes de classe et d'enum

constant() résout également les constantes de classe et les cas d'enum lorsque vous passez la forme Class::NAME sous forme de string :

<?php

class Http
{
    const NOT_FOUND = 404;
}

echo constant('Http::NOT_FOUND'); // 404

Pour un enum, constant() renvoie l'objet de cas correspondant, vous pouvez donc lire sa value :

<?php

enum Suit: string
{
    case Hearts = 'H';
    case Spades = 'S';
}

$case = constant('Suit::Hearts');

echo $case->value; // H

Se prémunir contre les constantes non définies

Passer le nom d'une constante qui n'existe pas lève une Error. Associez constant() à defined() pour vérifier au préalable :

<?php

if (defined('TIMEOUT')) {
    echo constant('TIMEOUT');
} else {
    echo 'not defined';
}

Lorsque TIMEOUT n'a pas été défini, ceci affiche not defined au lieu de provoquer une erreur.

Pièges à éviter

• Elle attend une string, pas la constante elle-même. Écrire constant(PI) (sans guillemets) tente d'utiliser la valeur de PI comme nom, ce qui n'est presque jamais ce que vous souhaitez.
• Les noms de constantes sont sensibles à la casse. constant('pi') ne trouvera pas PI.
• Les noms non définis lèvent une exception. Protégez-vous avec defined() comme indiqué ci-dessus.
• Utilisez-la uniquement pour les noms dynamiques. Si vous connaissez le nom de la constante au moment où vous écrivez le code, référencez-la directement — c'est plus clair et plus rapide.

Pratique