constant()

Что делает constant()

Функция constant() возвращает значение константы, имя которой передаётся в виде строки. На этой странице описаны её сигнатура, случаи, когда стоит использовать её вместо прямого обращения к константе, работа с константами классов и перечислений, а также подводные камни.

Если имя константы известно лишь во время выполнения программы — например, потому что оно сформировано из другой переменной — constant() позволяет выполнить поиск по этому имени. О том, как создаются константы, читайте в разделах PHP Constants и функция define().

Синтаксис и возвращаемое значение

constant(string $name): mixed

• $name — имя константы в виде строки. Для константы класса используйте полностью квалифицированную форму ClassName::CONSTANT.
• Возвращает значение константы. Тип возвращаемого значения соответствует тому, что хранит константа (int, string, float, bool, array или элемент перечисления).

Если константа не определена, constant() выбрасывает исключение Error (исключение \Error) в PHP 8 и более поздних версиях. Используйте defined(), чтобы проверить существование константы заранее, если вы не уверены.

Базовый пример

Константа PI определена со значением 3.14159. constant("PI") получает это значение, которое затем используется для вычисления площади круга. Вывод:

The area of a circle with radius 5 is 78.53975.

Когда это стоит использовать?

В базовом примере constant("PI") делает ровно то же самое, что и прямое обращение к PI — поэтому здесь нет никакого смысла её использовать. Функция становится полезной только тогда, когда имя константы неизвестно до момента выполнения. Поскольку нельзя подставить переменную туда, где ожидается имя константы, constant() позволяет найти нужную константу по имени, хранящемуся в строке:

<?php

const LEVEL_LOW  = 1;
const LEVEL_HIGH = 9;

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

echo "Severity level: $value";

Это выведет Severity level: 9. Выбор константы зависит от $severity — то, чего нельзя добиться жёстко прописанной ссылкой LEVEL_HIGH.

Константы классов и перечислений

constant() также позволяет обращаться к константам классов и элементам перечислений, если передать строку в форме Class::NAME:

<?php

class Http
{
    const NOT_FOUND = 404;
}

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

Для перечисления (enum) функция constant() возвращает соответствующий объект-элемент, из которого можно прочитать его value:

<?php

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

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

echo $case->value; // H

Защита от неопределённых констант

Передача имени несуществующей константы приведёт к выбросу Error. Используйте constant() совместно с defined(), чтобы проверить существование заранее:

<?php

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

Если TIMEOUT не определена, будет выведено not defined вместо аварийного завершения.

Подводные камни

• Функция принимает строку, а не саму константу. Запись constant(PI) (без кавычек) пытается использовать значение PI в качестве имени, что почти никогда не является желаемым поведением.
• Имена констант чувствительны к регистру. constant('pi') не найдёт PI.
• Неопределённые имена вызывают исключение. Защищайтесь с помощью defined(), как показано выше.
• Используйте функцию только для динамических имён. Если имя константы известно на этапе написания кода, обращайтесь к ней напрямую — это яснее и быстрее.

Практика