defined()

O que a Função defined() Faz

defined() é uma função nativa do PHP que verifica se uma constante com um determinado nome já existe. Ela retorna true se a constante estiver definida e false caso contrário. Esta página aborda sua sintaxe, como testar constantes de classe e de namespace, o erro comum de confundi-la com isset(), e quando você realmente precisaria usá-la.

Uma constante é um nome cujo valor não pode mudar durante uma única requisição — criada com define() ou com a palavra-chave const. Como referenciar uma constante indefinida gera um erro (uma exceção Error no PHP 8+, um aviso em versões mais antigas), defined() permite verificar primeiro e evitar isso.

Sintaxe

defined(string $constant_name): bool

• $constant_name — uma string com o nome da constante a ser procurada. Observe que você passa o nome como string ("GREETING"), não a constante em si (GREETING).
• Retorna true se uma constante com esse nome existir, false caso contrário.

Passar a constante sem aspas em vez do seu nome — defined(GREETING) — tenta avaliar GREETING primeiro, o que falha se ela não estiver definida. Sempre coloque o nome entre aspas.

Exemplo Básico

Como GREETING foi criada na linha anterior, defined("GREETING") retorna true e o script imprime Hello, world!.

Verificando Constantes de Classe e de Namespace

defined() também funciona com constantes de classe e de namespace. Use o nome totalmente qualificado como string:

<?php

const PI = 3.14;

class Circle {
    const SHAPE = "round";
}

var_dump(defined("PI"));             // bool(true)
var_dump(defined("Circle::SHAPE"));  // bool(true)  — class constant
var_dump(defined("Circle::MISSING"));// bool(false) — no such constant
var_dump(defined("UNDEFINED"));      // bool(false)

Para constantes de classe, a sintaxe é "ClassName::CONSTANT_NAME". Para uma constante de namespace, forneça seu caminho completo, por exemplo, defined("App\\Config\\VERSION").

defined() vs. isset(): Uma Confusão Comum

defined() verifica constantes; isset() verifica variáveis (e chaves de array / propriedades de objeto). Elas não são intercambiáveis:

<?php

$name = "Alex";          // a variable
define("APP_NAME", "W3"); // a constant

var_dump(isset($name));        // bool(true)  — variable exists
var_dump(defined("name"));     // bool(false) — no constant called "name"
var_dump(defined("APP_NAME")); // bool(true)  — constant exists

Se você se pegar usando defined("$variable"), quase certamente vai querer isset() em vez disso.

Quando Usar

• Protegendo constantes de configuração opcionais. Frameworks frequentemente permitem que você predefina constantes como DEBUG ou APP_ENV; use defined() para aplicar um valor padrão somente quando o usuário não tiver definido um.
• Prevenindo definições duplicadas. define() ao redefinir uma constante existente emite um aviso, então envolva-o em: if (!defined("API_KEY")) { define("API_KEY", "..."); }.
• Detecção de funcionalidades. Bibliotecas expõem constantes marcadoras (por exemplo, PHP_VERSION_ID); defined() confirma se uma funcionalidade baseada em constante está disponível antes de depender dela.

Para ler o valor de uma constante depois de confirmar que ela existe, combine defined() com constant(). Para uma visão mais ampla sobre a criação de constantes, consulte PHP Constants e Class Constants.

Prática