Constantes PHP: Um Guia Detalhado

Uma constante em PHP é um valor nomeado que não pode ser alterado após ser definido. Ao contrário das variáveis, as constantes não são prefixadas com $, ficam automaticamente disponíveis em todo o script (sem regras de escopo) e qualquer tentativa de reatribuí-las é ignorada ou gera um erro. São ideais para valores fixos como configurações, chaves de API, números de versão e limites matemáticos.

Este capítulo aborda como definir constantes de duas maneiras diferentes, as diferenças práticas entre elas, constantes mágicas, constantes de classe e as armadilhas mais comuns.

Definindo uma constante

O PHP oferece duas ferramentas: a função define() e a palavra-chave const. Ambas recebem um nome e um valor.

<?php
// Using define()
define("SITE_NAME", "W3docs");

// Using the const keyword
const VERSION = "8.4";

echo SITE_NAME; // W3docs
echo PHP_EOL;
echo VERSION;   // 8.4

Por convenção, os nomes de constantes são escritos em MAIÚSCULAS, mas o PHP não impõe essa regra. Um nome válido começa com uma letra ou sublinhado, seguido de letras, números ou sublinhados — exatamente como um nome de variável, apenas sem o $.

Note que você referencia uma constante pelo seu nome simples (SITE_NAME), sem o $. As constantes diferenciam maiúsculas de minúsculas: SITE_NAME e site_name são duas constantes diferentes.

const vs define()

Ambas produzem o mesmo tipo de constante, mas se comportam de forma diferente no nível da linguagem. Saber qual usar evita erros sutis:

Como define() é executada em tempo de execução, é a escolha certa quando uma constante deve existir apenas sob determinadas condições:

<?php
if (!defined("DEBUG")) {
    define("DEBUG", true);
}

// define() can build the name dynamically — const cannot:
$key = "MAX_USERS";
define($key, 100);
echo MAX_USERS; // 100

const, avaliada em tempo de compilação, é mais rápida e a escolha convencional para constantes de nível superior em código moderno.

Verificando e lendo constantes

Antes de usar uma constante cuja existência é incerta, verifique-a com defined(). Para obter o valor de uma constante quando você tem apenas seu nome como string, use constant():

<?php
define("TIMEOUT", 30);

if (defined("TIMEOUT")) {
    echo constant("TIMEOUT"); // 30
}

Constantes podem armazenar arrays

Desde o PHP 7, as constantes não se limitam a escalares (int, float, string, bool) — elas também podem armazenar arrays. Isso é útil para tabelas de consulta fixas:

<?php
const ALLOWED_ROLES = ["admin", "editor", "viewer"];

echo ALLOWED_ROLES[1]; // editor

Veja Tipos de Dados PHP para saber o que cada tipo de valor pode armazenar.

Constantes mágicas

O PHP possui constantes mágicas — nomes predefinidos cujo valor muda dependendo de onde são usados. São escritas com duplo sublinhado no início e no fim:

<?php
function greet() {
    echo "Called from: " . __FUNCTION__ . PHP_EOL;
    echo "On line: " . __LINE__ . PHP_EOL;
}
greet();

Constantes de classe

Constantes declaradas dentro de uma classe pertencem à própria classe, não a nenhuma instância. Declare-as com const e acesse-as com o operador :: (resolução de escopo):

<?php
class Circle {
    const PI = 3.14159;

    public function area(float $r): float {
        return self::PI * $r * $r;
    }
}

echo Circle::PI;            // 3.14159
echo PHP_EOL;
echo (new Circle)->area(2); // 12.56636

Para uma análise mais aprofundada, leia Constantes de Classe PHP.

Constantes vs variáveis

As duas servem a propósitos diferentes. Uma variável armazena dados que se espera que mudem; uma constante fixa um valor permanentemente. Os principais contrastes:

Use uma constante sempre que um valor deve permanecer fixo durante toda a execução — flags de configuração, limites, strings fixas — para que não possa ser sobrescrito acidentalmente em outro lugar.

Armadilhas comuns

• Redefinir uma constante. Chamar define() duas vezes com o mesmo nome gera um aviso e mantém o primeiro valor; redeclarar com const é um erro fatal. Constantes são de escrita única.
• Esquecer que o $ não existe. Escrever echo $SITE_NAME procura uma variável indefinida, não sua constante.
• Constantes indefinidas. No PHP 8+, usar uma constante de palavra simples indefinida lança um Error. Sempre use define() antes de usar, ou proteja com defined().

Conclusão

As constantes PHP oferecem uma forma segura de armazenar valores que nunca devem mudar: defina-as com const para valores comuns de nível superior ou com define() quando precisar de lógica em tempo de execução ou um nome dinâmico, agrupe dados fixos em constantes de array ou de classe, e use as constantes mágicas integradas para depuração. Bem utilizadas, elas mantêm a configuração em um único lugar e evitam reatribuições acidentais.

Prática