PHP: declare - PHP中文网

declare

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

declare 结构用来设定一段代码的执行指令。declare 的语法和其它流程控制结构相似：

 
declare (directive)
    statement

directive 部分允许设定 declare 代码段的行为。目前只认识三个指令：ticks（更多信息见下面 ticks 指令）、 encoding（更多信息见下面 encoding 指令）、 strict_types 指令 (更多信息见类型声明页面严格类型章节)。

因为本指令是在文件编译时处理的，所以指令只接受字面量的值。无法使用变量和常量。下面为你演示：

<?php
// 这样是有效的：
declare(ticks=1);

// 这样是无效的：
const TICK_VALUE = 1;
declare(ticks=TICK_VALUE);
?>

declare 代码段中的 statement 部分将被执行——怎样执行以及执行中有什么副作用出现取决于 directive 中设定的指令。

declare 结构也可用于全局范围，影响到其后的所有代码（但如果有 declare 结构的文件被其它文件包含，则对包含它的父文件不起作用）。

<?php
// 两者相等：

// 可以这样用：
declare(ticks=1) {
    // 这里写完整的脚本
}

// 也可以这样用：
declare(ticks=1);
// 这里写完整的脚本
?>

Ticks

Tick（时钟周期）是一个在 declare 代码段中解释器每执行 N 条可计时的低级语句就会发生的事件。N 的值是在 declare 中的 directive 部分用 ticks=N 来指定的。

不是所有语句都可计时。通常条件表达式和参数表达式都不可计时。

在每个 tick 中出现的事件是由 register_tick_function() 来指定的。更多细节见下面的例子。注意每个 tick 中可以出现多个事件。

示例 #1 Tick 的用法示例

<?php

declare(ticks=1);

// 每次 tick 事件都会调用该函数
function tick_handler()
{
    echo "tick_handler() called\n";
}

register_tick_function('tick_handler'); // 引起 tick 事件

$a = 1; // 引起 tick 事件

if ($a > 0) {
    $a += 2; // 引起 tick 事件
    print($a); // 引起 tick 事件
}

?>

参见 register_tick_function() 和 unregister_tick_function()。

Encoding

可以用 encoding 指令来对每段脚本指定其编码方式。

示例 #2 对脚本指定编码方式

<?php
declare(encoding='ISO-8859-1');
// 在这里写代码
?>

警告

当和命名空间结合起来时 declare 的唯一合法语法是 declare(encoding='...');，其中 ... 是编码的值。而 declare(encoding='...') {} 将在与命名空间结合时产生解析错误。

参见 zend.script_encoding。

＋add a note

User Contributed Notes 16 notes

down

Anonymous ¶

13 years ago

It's amazing how many people didn't grasp the concept here. Note the wording in the documentation. It states that the tick handler is called every n native execution cycles. That means native instructions, not including system calls (i'm guessing). This can give you a very good idea if you need to optimize a particular part of your script, since you can measure quite effectively how many native instructions are in your actual code.

A good profiler would take that into account, and force you, the developer, to include calls to the profiler as you're entering and leaving every function. That way you'd be able to keep an eye on how many cycles it took each function to complete. Independent of time.

That is extremely powerful, and not to be underestimated. A good solution would allow aggregate stats, so the total time in a function would be counted, including inside called functions.

down

Kubo2 ¶

8 years ago

Note that in PHP 7 <?php declare(encoding='...'); ?> throws an E_WARNING if Zend Multibyte is turned off.

down

digitalaudiorock at gmail dot com ¶

4 years ago

A few important things to note for anyone using this in conjunction with signal handlers:

If anyone is trying to optionally use either pcntl_async_signals() when available (PHP >= 7.1) or ticks for older versions, this is not possible...at least not in a way that does NOT enable ticks for newer PHP versions. This is because there is simply no way to conditionally declare ticks. For example, the following will "work" but not in the way you might expect:

<?php
if (function_exists('pcntl_async_signals')) {
    pcntl_async_signals(true);
} else {
    declare(ticks=1);
}
?>

While signal handlers will work with this for old and new version, ticks WILL be enabled even in the case where pcntl_async_signals exists, simply because the declare statement exists. So the above is functionally equivalent to:

<?php
if (function_exists('pcntl_async_signals')) pcntl_async_signals(true);
declare(ticks=1);
?>

Another thing to be aware of is that the scoping of this declaration changed a bit from PHP 5.6 to 7.x...actually it was corrected apparently as noted here:

http://php.net/manual/en/function.register-tick-function.php#121204

This can cause some very confusing behavior. One example is with the pear/System_Daemon module. With PHP 5.6 that will work with a SIGTERM handler even if the script using it doesn't itself use declare(ticks=1), but does not work in PHP 7 unless the script itself has the declaration. Not only does the handler not get called, but the signal does nothing at all, and the script doesn't exit.

A side note regarding ticks that's annoyed me for some time: As if there wasn't enough confusion around all this, the Internet is full of false rumors that ticks were deprecated and are being removed, and I believe they all started here:

http://www.hackingwithphp.com/4/21/0/the-declare-function-and-ticks

Despite a very obscure author's note at the very end of the page saying he got that wrong (that even I just noticed), the first very prominent sentence of the article still says this, and that page is near the top of any Google search.

down

sawyerrken at gmail dot com ¶

10 years ago

In the following example:

<?php
function handler(){
    print "hello <br />";
}

register_tick_function("handler");

declare(ticks = 1){
    $b = 2;
} //closing curly bracket tickable
?>

"Hello" will be displayed twice because the closing curly bracket is also tickable. 

One may wonder why the opening curly bracket is not tickable if the closing is tickable. This is because the instruction for PHP to start ticking is given by the opening curly bracket so the ticking starts immediately after it.

down

digitalaudiorock at gmail dot com ¶

4 years ago

Regarding my previous comment as to the change in scope of declare(ticks=1) between 5.6 and 7.x, I intended to mention another example of the affect this can have on signal handlers:

If your script uses declare(ticks=1) and assigns handlers, in 5.6 signals will get caught and call the handler even when the code that is running is in an included file (where the included file doesn't have the declaration). However in 7.x the signal wouldn't get caught until the code returns to the main script.

The best solution to that is to use pcntl_async_signals(true) when it's available, which will allow the signals to get caught regardless of what file the code happens to be in.

down

php dot net at e-z dot name ¶

10 years ago

you can register multiple tick functions:

<?PHP
function a() { echo "a\n"; }
function b() { echo "b\n"; }

register_tick_function('a');
register_tick_function('b');
register_tick_function('b');
register_tick_function('b');

?>

will output on every tick:
a
b
b
b

down

ja2016 at wir dot pl ¶

6 years ago

Don't use uft-8 encoding with BOM. Then fatal error occurs ALWAYS. Substitute it with utf-8 without BOM.

---

*BOM*
<?php 
declare(strict_types=1);
//Fatal error: strict_types declaration must be the very first statement in the script

down

fok at nho dot com dot br ¶

20 years ago

This is a very simple example using ticks to execute a external script to show rx/tx data from the server

<?php

function traf(){
  passthru( './traf.sh' );
  echo "<br />\n";
  flush(); // keeps it flowing to the browser...
  sleep( 1 );
}

register_tick_function( "traf" );

declare( ticks=1 ){
  while( true ){}   // to keep it running...
}

?>

contents of traf.sh:
# Shows TX/RX for eth0 over 1sec
#!/bin/bash

TX1=`cat /proc/net/dev | grep "eth0" | cut -d: -f2 | awk '{print $9}'`
RX1=`cat /proc/net/dev | grep "eth0" | cut -d: -f2 | awk '{print $1}'`
sleep 1
TX2=`cat /proc/net/dev | grep "eth0" | cut -d: -f2 | awk '{print $9}'`
RX2=`cat /proc/net/dev | grep "eth0" | cut -d: -f2 | awk '{print $1}'`

echo -e "TX: $[ $TX2 - $TX1 ] bytes/s \t RX: $[ $RX2 - $RX1 ] bytes/s"
#--= the end. =--

down

ohcc at 163 dot com ¶

3 years ago

It's possible to set directives at one time if every directive is supported.
<?php
    declare(strict_types=1, encoding='UTF-8');
?>

down

markandrewslade at dontspamemeat dot gmail ¶

14 years ago

Note that the two methods for calling declare are not identical.

Method 1:

<?php
// Print "tick" with a timestamp and optional suffix.
function do_tick($str = '') {
    list($sec, $usec) = explode(' ', microtime());
    printf("[%.4f] Tick.%s\n", $sec + $usec, $str);
}
register_tick_function('do_tick');

// Tick once before declaring so we have a point of reference.
do_tick('--start--');

// Method 1
declare(ticks=1);
while(1) sleep(1);

/* Output:
[1234544435.7160] Tick.--start--
[1234544435.7161] Tick.
[1234544435.7162] Tick.
[1234544436.7163] Tick.
[1234544437.7166] Tick.
*/

?>

Method 2:
<?php
// Print "tick" with a timestamp and optional suffix.
function do_tick($str = '') {
    list($sec, $usec) = explode(' ', microtime());
    printf("[%.4f] Tick.%s\n", $sec + $usec, $str);
}
register_tick_function('do_tick');

// Tick once before declaring so we have a point of reference.
do_tick('--start--');

// Method 2
declare(ticks=1) {
    while(1) sleep(1);
}

/* Output: 
[1234544471.6486] Tick.--start--
[1234544472.6489] Tick.
[1234544473.6490] Tick.
[1234544474.6492] Tick.
[1234544475.6493] Tick.
*/
?>

Notice that when using {} after declare, do_tick wasn't auto-called until about 1 second after we entered the declare {} block.  However when not using the {}, do_tick was auto-called not once but twice immediately after calling declare();.

I'm assuming this is due to how PHP handles ticking internally.  That is, declare() without the {} seems to trigger more low-level instructions which in turn fires tick a few times (if ticks=1) in the act of declaring.

down

dewi at dewimorgan dot com ¶

1 year ago

While you cannot conditionally declare ticks in a single source file, as the `declare()` is processed even within the branch of an `if()` that does not run, you can work around this by placing it within a separate file, and conditionally including that file, like so:

<?php
if (function_exists('pcntl_async_signals')) {
    pcntl_async_signals(true);
} else {
    require_once('declareTicks.php');
}
?>

Then in `declareTicks.php` you'd have just:

<?php
    declare(ticks=1);
?>

This allows you to avoid the performance impact of a low tick value in systems which support `pcntl_async_signals()`.

down

-1

wapmorgan at gmail dot com ¶

6 years ago

If you fork'ed (with pcntl_fork) after you've used `declare`, you need to do it again in child thread.

declare(ticks=1);
$pid = pcntl_fork();
if ($pid === 0) {
    declare(ticks=1);
} else {
    // code ..
}

down

-2

aeolianmeson at NOSPAM dot blitzeclipse dot com ¶

17 years ago

The scope of the declare() call if used without a block is a little unpredictable, in my experience. It appears that if placed in a method or function, it may not apply to the calls that ensue, like the following:



<?php

function a()

{

   declare(ticks=2);

   b();

}



function b()

{

   // The declare may not apply here, sometimes.

}

?>



So, if all of a sudden the signals are getting ignored, check this. At the risk of losing the ability to make a mathematical science out of placing a number of activities at varying durations of ticks like many people have chosen to do, I've found it simple to just put this at the top of the code, and just make it global.

down

-4

ohcc at 163 dot com ¶

5 years ago

Using a directive that is not supported by current version of PHP will generate a warning like:

Warning: Unsupported declare 'strict_types' in D:\Server\wuxiancheng.cn\index.php on line 2

You CAN'T prepend an @ sign to the declare construct to supress that error message.

@declare(strict_types=1);

The above code will lead to a Parse error like:

Parse error: syntax error, unexpected 'declare' (T_DECLARE) in D:\Server\wuxiancheng.cn\index.php on line 2

down

-7

php at niekbosch dot nl ¶

9 years ago

Basically 'declare( encoding = .... );' overrides the zend.script_encoding configuration option (as set in php.ini). However, keep in mind that:

* the file encoding must be compatible (at least in the ASCII range of characters) to the zend.script_encoding setting. If you set 'zend.script_encoding' to UTF-8 and save the file in UTF-16, PHP will not be able to interpret the file, let alone the declare statement. As long as you use ASCII compatible encodings (i.e. ISO-8859-1(5), UTF-8 etc) for both the file encoding as the zend.script_encoding, you should be fine. (However, I have not experimented with adding non-ascii characters in comments above the declare statement).

* PHP string literals are converted from your source code encoding (either set with the declare statement or else according to zend.script_encoding) to the mbstring.internal_encoding as set in your php.ini (even if you change the setting using mb_internal_encoding). As an example:

php.ini:
mbstring.internal_encoding = UTF-8

test.php:
<?php
declare(encoding = 'ISO-8859-15');
mb_internal_encoding( 'ISO-8859-15' );
echo 'aäaß' . "\n";
?>

This will still output the string UTF-8 encoded; in a terminal/browser with encoding 'ISO-8859-15' the string will look (something) like this: aÃ€aÃ

down

-12

Ionut ¶

6 years ago

I haven't found this written in the doc: when using declare in the global context, it has to be the first statement in the script, before any other output.

This works:

<?php
declare(strict_types=1);
function sum(int $a, int $b): int {
    return 5.78;
}
# ... but fails when calling the function
?>

This doesn't work:

<html>
<body>
<?php
declare(strict_types=1);
function sum(int $a, int $b): int {
    return 5.78;
}
# PHP Fatal error:  strict_types declaration must be the very first statement in the script [...]
?>

＋add a note