define()

O Que a Função define() Faz

A função define() cria uma constante — um valor nomeado que não pode ser alterado após ser definido. Diferente de uma variável, uma constante não possui o prefixo $, é global em todo o script (inclusive dentro de funções) e qualquer tentativa de redefini-la gera um aviso em vez de sobrescrever silenciosamente o valor.

Use define() quando quiser uma fonte única de verdade para um valor que nunca deve mudar em tempo de execução: um sinalizador de configuração, um número de versão, um caminho de arquivo ou um endpoint de API.

Sintaxe

define(string $name, mixed $value, bool $case_insensitive = false): bool

• $name — o nome da constante. Por convenção, usa-se letras maiúsculas com sublinhados (MAX_USERS), mas qualquer identificador válido funciona.
• $value — o valor a ser armazenado. Escalares (int, float, string, bool) e null sempre foram permitidos; arrays tornaram-se valores válidos no PHP 7.0.
• $case_insensitive (opcional) — historicamente, passar true permitia ler a constante com qualquer capitalização. Este parâmetro foi descontinuado no PHP 7.3 e removido no PHP 8.0, portanto, omita-o e trate os nomes de constantes como sensíveis a maiúsculas e minúsculas.

define() retorna true em caso de sucesso e false em caso de falha.

Um Exemplo Básico

Aqui, define() cria uma constante chamada GREETING contendo Hello, world!, e então echo a exibe pelo nome — sem $ e sem aspas.

Armazenando um Array em uma Constante

Desde o PHP 7.0, uma constante pode armazenar um array, o que é útil para tabelas de consulta fixas ou listas de opções:

<?php
define("ROLES", ["admin", "editor", "viewer"]);
echo ROLES[1]; // editor
?>

Verificando Antes de Usar uma Constante

Ler uma constante indefinida é um erro no PHP 8.0+. Proteja com defined() para que seu código se comporte adequadamente:

<?php
if (!defined("APP_ENV")) {
    define("APP_ENV", "production");
}
echo APP_ENV; // production
?>

define() vs. const

PHP oferece duas formas de declarar uma constante, e elas não são intercambiáveis:

Use define() quando o nome ou valor for calculado, ou quando a declaração precisar ser condicional. Use const para constantes simples, sempre declaradas, e para constantes de classe.

Armadilhas Comuns

• Sem $ e sem aspas ao ler. Escreva echo GREETING;, não echo $GREETING; ou echo "GREETING";.
• Redefinir gera aviso, não sobrescreve. Um segundo define("GREETING", ...) emite um aviso e o valor original é mantido.
• Nomes são sensíveis a maiúsculas e minúsculas. GREETING e Greeting são duas constantes diferentes agora que o parâmetro de insensibilidade foi removido.
• Defina uma vez, cedo. Como as constantes são globais e permanentes, defina-as próximo ao início do seu script ou em um arquivo de configuração.

Conclusão

define() é a forma de criar um valor global e imutável em PHP em tempo de execução. Combine com defined() para evitar avisos de redefinição, prefira const para constantes fixas em tempo de compilação e de classe, e consulte PHP Constants para uma visão mais ampla.

Prática