Declare Statement

The declare construct is used to set execution directives for a specific block of code or an entire script. It modifies the compilation and execution behavior of the Zend engine for the file or scope in which it is defined. Because declare is evaluated during the compilation phase rather than at runtime, it strictly accepts literal values; variables or constants cannot be evaluated as directive values.

Syntax

The declare statement can be applied globally to an entire file or locally to a specific block of code. Multiple directives can be combined in a single declare statement using a comma-separated list, though specific lexer constraints apply to certain directives.

Global Scope: When declared without a block, the directive applies to all subsequent code within the same compilation unit (file).

declare(directive=value);
declare(directive1=value1, directive2=value2);

Block Scope: When declared with a block, the directive applies exclusively to the enclosed statements. Note: Block scope is only supported by the ticks directive.

Using curly braces:

declare(directive=value) {
    // statements
}

Using alternative syntax:

declare(directive=value):
    // statements
enddeclare;

Supported Directives

PHP supports three specific directives within the declare construct:

1. strict_types

This directive dictates how PHP handles scalar type declarations for function parameters, return types, and typed property assignments.

• Values: 1 (strict mode) or 0 (coercive mode, the default).
• Caller vs. Callee Mechanics: The enforcement of strict_types relies on lexical scoping, creating a strict distinction between the caller and the callee.
  • Parameter Types (Caller): Parameter type strictness is determined exclusively by the file where the function is called. A function defined in a strict file will not enforce strict types on arguments passed to it from a non-strict file; those arguments will be evaluated coercively.
  • Return Types (Callee): Return type strictness is determined exclusively by the file where the function is defined. A function defined in a strict file will enforce strict return types and throw a TypeError on mismatch, even if invoked by a non-strict caller.
• Type Exceptions: In strict mode, PHP requires the exact type to be provided. The single exception is that an int value can be provided where a float is expected.
• Placement: It must precede any opcode-emitting statements in the file. It strictly requires global scope syntax; attempting to use block mode results in a compile-time Fatal error.

2. ticks

A “tick” is an event that occurs for every N low-level, tickable statements executed by the parser within the declare block or file.

• Values: An integer representing the interval of statements (N).
• Mechanics: When the specified number of statements executes, PHP triggers any functions previously registered via register_tick_function(). Not all statements are tickable (e.g., conditional expressions and argument expressions are excluded).
• Placement: This is the only directive that supports both global scope and block scope syntax.

3. encoding

This directive specifies the character encoding of the script file.

• Values: A string literal representing a valid character encoding (e.g., 'UTF-8', 'ISO-8859-1').
• Mechanics: It instructs the Zend scanner on how to decode the script file during compilation. Because this occurs at compile-time, it requires the zend.multibyte INI setting to be enabled in the PHP configuration (php.ini) prior to compilation.
• Placement: It must be the absolute first directive intercepted by the lexer and strictly requires global scope syntax. Using block mode results in a compile-time Fatal error.

Top-Level Placement Constraints

When utilizing both encoding and strict_types in the same file, their placement and order are strictly governed by how PHP’s lexer and parser operate.

Because declare statements do not emit opcodes, multiple declare statements can be placed on separate lines at the top of the file without triggering a Fatal error. The parser only enforces that strict_types precedes any opcode-emitting statements (i.e., CG(active_op_array)->last > 0).

However, the encoding directive is intercepted by the lexer at the very beginning of the file using a strict pattern match. The lexer expects encoding to be the first directive inside the declare construct.

Therefore, the correct approach is to place them on separate lines, ensuring encoding is declared first:

// Correct: Encoding is the first directive seen by the lexer
declare(encoding='UTF-8');
declare(strict_types=1);

Combining them into a single statement where strict_types precedes encoding is flawed. The lexer will fail to detect the encoding directive, and the file will not be lexed with the intended encoding:

// Incorrect: Lexer will not detect the encoding directive
declare(strict_types=1, encoding='UTF-8');

Scope and Resolution Mechanics

The declare construct operates using lexical scoping. Its effects are strictly confined to the file in which it is declared.

If File A contains a declare statement and subsequently includes File B via include or require, the directives from File A do not propagate to File B. File B will execute using PHP’s default behaviors unless it contains its own declare statements. Conversely, a declare statement inside an included file does not leak back into the parent file’s scope.

Master PHP with Deep Grasping Methodology!

Learn More