declare

A Palavra-chave declare do PHP

declare é uma estrutura de controle PHP que define uma diretiva de execução para o código que governa. Ao contrário da maioria das instruções, uma diretiva não executa lógica — ela muda como o motor interpreta o código ao redor. O PHP suporta exatamente três diretivas: strict_types (impõe declarações de tipo), encoding (define a codificação de caracteres do script) e ticks (um gancho de evento legado, removido no PHP 8.0).

O motivo mais comum para usar declare hoje é uma única linha no topo de um arquivo: declare(strict_types=1);. Esta página aborda a sintaxe, cada diretiva e as armadilhas que costumam pegar as pessoas de surpresa.

Sintaxe

Existem duas formas. A forma de instrução aplica a diretiva ao restante do arquivo:

declare(directive);

A forma de bloco aplica a diretiva apenas ao código dentro das chaves:

declare(directive) {
    // code block
}

A forma de bloco é válida apenas para ticks. strict_types e encoding devem usar a forma de instrução e precisam ser a primeira instrução no arquivo (apenas <?php pode precedê-las). Usar a forma de bloco com strict_types é um erro fatal.

strict_types: impondo declarações de tipo

Por padrão, o PHP coage argumentos escalares para corresponder às declarações de tipo de uma função. Com declare(strict_types=1); isso não acontece — passar o tipo errado lança um TypeError. Esta é a diretiva que você usará no dia a dia.

Duas regras para lembrar:

• Ela deve ser a primeira instrução no arquivo. Qualquer coisa antes dela — mesmo saída de espaço em branco ou outra instrução — é um erro fatal.
• Ela é por arquivo. O modo estrito se aplica às chamadas feitas a partir deste arquivo, com base em onde a chamada está localizada, não onde a função é definida. Uma função de biblioteca chamada a partir de um arquivo estrito é verificada de forma estrita; a mesma função chamada a partir de um arquivo não estrito não é.

Sem a diretiva, add(2, "3") coagiria silenciosamente "3" para 3 e retornaria 5 — que é exatamente o tipo de bug oculto que strict_types foi projetado para revelar.

encoding: declarando o conjunto de caracteres do script

declare(encoding='ISO-8859-1');

Isso indica ao motor como interpretar os bytes do próprio arquivo de script. Raramente é necessário em sistemas modernos, que usam UTF-8 em todo lugar, mas pode ser importante para arquivos legados ou configurações específicas de servidor. Só tem efeito quando o PHP é compilado com suporte a multibyte.

ticks: um gancho de evento legado

Um tick é um evento disparado a cada N instruções de baixo nível executadas dentro do bloco declare. Era usado para adicionar callbacks simples (tratamento de sinais, criação de perfil) a código de outra forma síncrono. Esta é a única diretiva em que a forma de bloco faz sentido:

declare(ticks=1) {
    function tick_handler() {
        echo "tick" . PHP_EOL;
    }
    register_tick_function('tick_handler');

    $a = 1;
    $a += 2;
}

O número exato de ticks depende de quantas instruções são executadas. A diretiva ticks foi removida no PHP 8.0 — evite-a em código novo; alternativas modernas incluem pcntl_signal para tratamento de sinais.

Quando usar cada diretiva

• strict_types=1 — coloque no topo de cada novo arquivo. É o uso mais valioso de declare e uma convenção quase universal no PHP moderno. Veja Tipos de Dados PHP e Funções PHP para saber como funcionam as declarações de tipo.
• encoding — apenas quando você realmente tem um arquivo-fonte não UTF-8 e suporte a multibyte compilado.
• ticks — não use; foi removido a partir do PHP 8.0.

Conclusão

declare define diretivas de execução para um script. Na prática, isso significa uma linha — declare(strict_types=1); — que transforma a coerção silenciosa de tipos em erros explícitos e torna as assinaturas de suas funções significativas. As diretivas encoding e ticks são de nicho e legadas, respectivamente, mas conhecer todas as três evita que a sintaxe (forma de instrução versus forma de bloco) te surpreenda.

Prática