constant()

O que constant() faz

A função constant() retorna o valor de uma constante cujo nome é fornecido como uma string. Esta página aborda sua assinatura, por que você usaria essa função em vez de escrever a constante diretamente, como ela funciona com constantes de classe e enum, e os pontos de atenção a observar.

Se você só conhece o nome de uma constante em tempo de execução — por exemplo, porque ele foi construído a partir de outra variável — constant() é a forma de consultá-lo. Para aprender como as constantes são criadas, veja PHP Constants e a função define().

Sintaxe e Valor de Retorno

constant(string $name): mixed

• $name — o nome da constante como uma string. Para uma constante de classe, use a forma completamente qualificada ClassName::CONSTANT.
• Retorna o valor da constante. O tipo de retorno corresponde ao que a constante armazena (int, string, float, bool, array ou um caso de enum).

Se a constante não estiver definida, constant() lança um Error (uma exceção \Error) no PHP 8 e versões posteriores. Verifique antes com defined() quando não tiver certeza.

Exemplo Básico

A constante PI é definida com o valor 3.14159. constant("PI") recupera esse valor, que é então usado para calcular a área de um círculo. A saída é:

The area of a circle with radius 5 is 78.53975.

Quando Devo Usá-la?

Neste exemplo básico, constant("PI") faz exatamente a mesma coisa que escrever PI diretamente — portanto, não há motivo para usá-la aqui. A função só é necessária quando o nome da constante não é conhecido até o tempo de execução. Como não é possível usar uma variável onde pertence um nome de constante, constant() permite resolver um nome armazenado em uma string:

<?php

const LEVEL_LOW  = 1;
const LEVEL_HIGH = 9;

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

echo "Severity level: $value";

Isso imprime Severity level: 9. A constante escolhida depende de $severity, algo que uma referência direta LEVEL_HIGH jamais conseguiria fazer.

Constantes de Classe e Enum

constant() também resolve constantes de classe e casos de enum quando você passa a forma Class::NAME como string:

<?php

class Http
{
    const NOT_FOUND = 404;
}

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

Para um enum, constant() retorna o objeto de caso correspondente, de modo que você pode ler seu value:

<?php

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

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

echo $case->value; // H

Proteção Contra Constantes Indefinidas

Passar o nome de uma constante que não existe lança um Error. Use constant() em conjunto com defined() para verificar primeiro:

<?php

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

Quando TIMEOUT não foi definido, isso imprime not defined em vez de gerar um erro.

Pontos de Atenção

• Ela recebe uma string, não a constante em si. Escrever constant(PI) (sem aspas) tenta usar o valor de PI como nome, o que quase nunca é o desejado.
• Nomes de constantes diferenciam maiúsculas de minúsculas. constant('pi') não encontrará PI.
• Nomes indefinidos lançam erro. Proteja-se com defined() conforme mostrado acima.
• Use-a apenas para nomes dinâmicos. Se você conhece o nome da constante ao escrever o código, referencie-a diretamente — é mais claro e mais rápido.

Prática