declare

(PHP 4, PHP 5, PHP 7, PHP 8)

A instrução declare é usada para definir diretivas de execução para um bloco de código. A sintaxe do declare é similar à sintaxe de outros construtos de controle de fluxo:

declare (directive)
    statement

A seção directive permite que o comportamento do bloco do declare seja definido. Atualmente somente três diretivas são reconhecidas:

As diretivas são manipuladas na compilação do arquivo, somente literais podem ser usadas como valores da diretiva. Variáveis e constantes não podem ser usadas. Para ilustrar:

<?php
// Isto é válido:
declare(ticks=1);

// isto é inválido:
const TICK_VALUE = 1;
declare(ticks=TICK_VALUE);
?>

A parte statement do bloco do declare será executada - como é executada e quais os efeitos colaterais que ocorrem durante a execução depende da diretiva definida no bloco directive.

O construtor do declare também pode ser usado no escopo global, afetando todo o código que o segue (entretanto se o arquivo com o declare for incluído, não afetará o arquivo principal).

<?php
// Os exemplos abaixo tem o mesmo efeito

// Pode ser usado assim:
declare(ticks=1) {
    // script aqui
}

// ou assim:
declare(ticks=1);
// script inteiro aqui
?>

Ticks

Um 'tick' é um evento que ocorre a cada N declarações de baixo nível executadas pelo interpretador dentro do bloco declare. O valor de N é especificado usando ticks=N dentro do bloco declare da seção directive.

Nem todas declarações são passíveis de executar um 'tick'. Normalmente, expressões de condições e argumentos de expressões não são.

Os eventos que serão executados a cada tick são especificados usando a função register_tick_function(). Veja o exemplo abaixo para mais detalhes. Note que mais de um evento pode ser executado para cada tick.

Exemplo #1 Exemplo de uso do Tick

<?php

declare(ticks=1);

// A função a ser chamada em cada evento tick
function tick_handler()
{
    echo "tick_handler() chamada.\n";
}

register_tick_function('tick_handler'); // Causa um evento tick

$a = 1; // Causa um evento tick

if ($a > 0) {
    $a += 2; // Causa um evento tick
    print $a; // Causa um evento tick
}

?>

Consulte também register_tick_function() e unregister_tick_function().

Codificação

A codificação de um script pode ser especificada em cada arquivo com uma diretiva encoding.

Exemplo #2 Declarando a codificação do script

<?php
declare(encoding='ISO-8859-1');
// código aqui
?>

Cuidado

Quando usada com namespaces, a única sintaxe válida para declarar é declare(encoding='...'); onde ... é o valor da codificação. declare(encoding='...') {} irá resultar em um erro de sintaxe quando usada com namespaces.

Veja mais zend.script_encoding.