declare

La palabra clave declare en PHP

declare es una estructura de control de PHP que establece una directiva de ejecución para el código que gobierna. A diferencia de la mayoría de las sentencias, una directiva no ejecuta lógica — cambia la forma en que el motor interpreta el código circundante. PHP admite exactamente tres directivas: strict_types (aplica declaraciones de tipo), encoding (establece la codificación de caracteres del script) y ticks (un gancho de eventos heredado, eliminado en PHP 8.0).

El motivo más habitual para usar declare hoy en día es una sola línea al principio de un archivo: declare(strict_types=1);. Esta página cubre la sintaxis, cada directiva y los errores comunes que suelen sorprender a los desarrolladores.

Sintaxis

Existen dos formas. La forma de sentencia aplica la directiva al resto del archivo:

declare(directive);

La forma de bloque aplica la directiva solo al código dentro de las llaves:

declare(directive) {
    // code block
}

La forma de bloque es válida únicamente para ticks. strict_types y encoding deben usar la forma de sentencia y deben ser la primera sentencia del archivo (solo <?php puede precederlas). Usar la forma de bloque con strict_types es un error fatal.

strict_types: aplicar declaraciones de tipo

Por defecto, PHP coerciona los argumentos escalares para que coincidan con las declaraciones de tipo de una función. Con declare(strict_types=1); esto no ocurre — pasar el tipo incorrecto lanza un TypeError. Esta es la directiva que realmente usarás en el día a día.

Dos reglas que debes recordar:

• Debe ser la primera sentencia del archivo. Cualquier cosa antes de ella — incluso espacios en blanco o otra sentencia — es un error fatal.
• Es por archivo. El modo estricto se aplica a las llamadas realizadas desde este archivo, en función de dónde se encuentra la llamada, no de dónde está definida la función. Una función de biblioteca llamada desde un archivo estricto se comprueba estrictamente; la misma función llamada desde un archivo no estricto no lo hace.

Sin la directiva, add(2, "3") coercionaría silenciosamente "3" a 3 y devolvería 5 — exactamente el tipo de error oculto que strict_types está diseñado para detectar.

encoding: declarar el conjunto de caracteres del script

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

Esto le indica al motor cómo interpretar los bytes del propio archivo del script. Rara vez es necesario en sistemas modernos que usan UTF-8 en todas partes, pero puede ser relevante para archivos heredados o configuraciones de servidor específicas. Solo tiene efecto cuando PHP está compilado con soporte multibyte.

ticks: un gancho de eventos heredado

Un tick es un evento que se dispara cada N sentencias de bajo nivel ejecutadas dentro del bloque declare. Se usaba para adjuntar callbacks simples (manejo de señales, perfilado) a código de otro modo síncrono. Esta es la única directiva donde la forma de bloque tiene sentido:

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

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

El número exacto de ticks depende de cuántas sentencias se ejecuten. La directiva ticks fue eliminada en PHP 8.0 — evítala en código nuevo; las alternativas modernas incluyen pcntl_signal para el manejo de señales.

Cuándo usar cada directiva

• strict_types=1 — colócala al principio de cada archivo nuevo. Es el uso más valioso de declare y una convención prácticamente universal en PHP moderno. Consulta PHP Data Types y PHP Functions para ver cómo funcionan las declaraciones de tipo.
• encoding — solo cuando genuinamente tienes un archivo fuente que no es UTF-8 y el soporte multibyte está compilado.
• ticks — no la uses; desapareció a partir de PHP 8.0.

Conclusión

declare establece directivas de ejecución para un script. En la práctica, eso significa una sola línea — declare(strict_types=1); — que convierte la coerción silenciosa de tipos en errores explícitos y hace que las firmas de tus funciones sean significativas. Las directivas encoding y ticks son específicas y heredadas respectivamente, pero conocer las tres evita que la sintaxis (forma de sentencia frente a forma de bloque) te tome por sorpresa.

Práctica