PHP: declare - Manual

Last updated: Fri, 13 Nov 2009

declare

declare 命令は、あるコードブロックの中に実効命令をセットするために使用されます。declare の文法は他の制御構造と似ています。

declare (命令)
    文

命令の箇所で、セットされた declareブロックの挙動を指定することが出来ます。現在のところ、使用できる命令は ticks ( ticksに関しては以下を参照してください) と encoding (encoding に関しては以下を参照ください) です。

注意: encoding ディレクティブは PHP 5.3.0 で追加されました。

declareブロックの文の実行のされ方や実行時にどのような作用が起こるかについては命令に何が指定されたかに依存します。

declare構造はグローバルスコープしても使用され、それはそれ以降のコード上の全てにおいて影響します (しかし、declare を含むファイルがインクルードされた場合は、親ファイルにはその影響は及びません)。


<?php
// 以下は同じ意味です

// こうすることもできますし、
declare(ticks=1) {
    // ここにすべてのスクリプトを書きます
}

// こうすることもできます
declare(ticks=1);
// ここにすべてのスクリプトを書きます
?>

Ticks

tickとはdeclareブロックの実行中にパーサが N個の低レベル tick 可能命令を実行するごとに発生するイベントのことです。Nの値は declareブロックの命令の箇所で ticks=Nのように指定します。

すべての文が tick 可能なわけではありません。たとえば条件式や引数式などは tick できません。

tickごとに発生させるイベントはregister_tick_function() を使用して指定します。詳細は以下の例を参照してください。1回のtickで複数のイベントが起こり得ることに注意してください。

例1 Tick の使用例


<?php

declare(ticks=1);

// tick イベントごとにコールされる関数
function tick_handler()
{
     echo "tick_handler() called\n";
}

register_tick_function('tick_handler');

$a = 1;

if ($a > 0) {
      $a += 2;
      print($a);
}

?>

例2 Ticks の使用例


<?php

function tick_handler()
{
  echo "tick_handler() called\n";
}

$a = 1;
tick_handler();

if ($a > 0) {
      $a += 2;
      tick_handler();
      print($a);
      tick_handler();
}
tick_handler();

?>

register_tick_function() および unregister_tick_function() も参照ください。

Encoding

スクリプトのエンコーディングをスクリプトごとに指定するには encoding ディレクティブを使用します。

例3 スクリプトのエンコーディングの宣言


<?php
declare(encoding='ISO-8859-1');
// ここにコードを書きます
?>

警告

名前空間と組み合わせて使用する場合、使用できる形式は declare(encoding='...'); のみです。... にエンコーディングを指定します。declare(encoding='...') {} は、名前空間と組み合わせるとパースエラーとなります。

php を --enable-zend-multibyte つきでコンパイルしていない場合、 PHP 5.3 では encoding 宣言は無視されます。 PHP 6.0 では、encoding 宣言を用いてスキャナにファイル作成時のエンコーディングを伝えます。使用できる値は、たとえば UTF-8 のようなエンコーディング名です。

return

switch

Last updated: Fri, 13 Nov 2009

add a note User Contributed Notes
declare

markandrewslade at dontspamemeat dot gmail
13-Feb-2009 05:06


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.

anotheruser at example dot com
23-Aug-2008 11:50


Code evaluation script which uses debug_backtrace() to get execution time in ns, relative current line number, function, file, and calling function info on each tick, and shove it all in $script_stats array.  See debug_backtrace manual to customize what info is collected.



Warning: this will exhaust allowed memory very easily, so adjust tick counter according to the size of your code.  Also, array_key_exists checking on debug_backtrace arrays is removed here only to keep this example simple, but should be added to avoid a large number of resulting PHP Notice errors.



<?php



$script_stats = array();

$time = microtime(true);



function track_stats(){

    global $script_stats,$time;

    $trace = debug_backtrace();

    $exe_time = (microtime(true) - $time) * 1000;

    $func_args = implode(", ",$trace[1]["args"]);

    $script_stats[] = array(

        "current_time" => microtime(true),

        "memory" => memory_get_usage(true),

        "file" => $trace[1]["file"].': '.$trace[1]["line"],

        "function" => $trace[1]["function"].'('.$func_args.')',

        "called_by" => $trace[2]["function"].' in '.$trace[2]["file"].': '.$trace[2]["line"],

        "ns" => $exe_time

        );

    $time = microtime(true);

    }



declare(ticks = 1);

register_tick_function("track_stats");



// the rest of your project code



// output $script_stats into a html table or something



?>

zabmilenko at charter dot net
08-Jan-2008 09:49


If you misspell the directive, you won't get any error or warning.  The declare block will simply act as a nest for statements:



<?php

declare(tocks="four hundred")

{

    // Has no affect on code and produces

    // no error or warning.

}

?>



Tested in php 5.2.5 on XPsp2

rsemil at gmail dot com
06-Jan-2008 02:30


rosen_ivanov's solution can be replaced by a simple call to memory_get_peak_usage() if you're running at least PHP 5.2.0

rosen_ivanov at abv dot bg
28-Aug-2006 01:06


As Chris already noted, ticks doesn't make your script multi-threaded, but they are still great. I use them mainly for profiling - for example, placing the following at the very beginning of the script allows you to monitor its memory usage:



<?php



function profiler($return=false) {

    static $m=0;

    if ($return) return "$m bytes";

    if (($mem=memory_get_usage())>$m) $m = $mem;

}



register_tick_function('profiler');

declare(ticks=1);



/*

Your code here

*/



echo profiler(true);



?>



This approach is more accurate than calling memory_get_usage only in the end of the script. It has some performance overhead though :)

aeolianmeson at NOSPAM dot blitzeclipse dot com
30-May-2006 07:06


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.

warhog at warhog dot net
18-Dec-2005 08:39


as i read about ticks the first time i thought "wtf, useless crap" - but then i discovered some usefull application...



you can declare a tick-function which checks each n executions of your script whether the connection is still alive or not, very usefull for some kind of scripts to decrease serverload



<?php



function check_connection()

{ if (connection_aborted())

   { // do something here, e.g. close database connections

      // (or  use a shutdown function for this

      exit; }

}



register_tick_function("connection");



declare (ticks=20)

{

  // put your PHP-Script here

  // you may increase/decrease the number of ticks

}



?>

chris-at-free-source.com
28-Feb-2005 08:16


Also note that PHP is run in a single thread and so everything it does will be one line of code at a time.  I'm not aware of any true threading support in PHP, the closest you can get is to fork.



so, declare tick doens't "multi-thread" at all, it is simply is a way to automaticaly call a function every n-lines of code.

fok at nho dot com dot br
08-Jul-2003 01:45


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. =--

daniel@swn
01-Feb-2003 07:56


<?php

ob_end_clean();

ob_implicit_flush(1);



function a() {

 for($i=0;$i<=100000;$i++) { }

 echo "function a() ";

}

function b() {

 for($i=0;$i<=100000;$i++) { }

 echo "function b() ";

}



register_tick_function ("a");

register_tick_function ("b");



declare (ticks=4)

{

    while(true)

    {

        sleep(1);

        echo "\n<br><b>".time()."</b><br>\n";;

    }

}

?>

You will see that a() and b() are slowing down this process. They are in fact not executed every second as expected. So this function is not a real alternative for multithreading using some slow functions..there is no difference to this way: while (true) { a(); b(); sleep(1); }

xxoes
08-Jan-2003 10:23


If i use ticks i must declare all functions before i call the function.



example:



Dosn't work

<?php

function ticks() {

   echo "tick";

}

register_tick_function("ticks");



declare (ticks=1) 1;



echo "";

echo "";



foo(); // Call to undefined function.



function foo() {

   echo "foo";

}

?>



Work

<?php

function ticks() {

   echo "tick";

}

register_tick_function("ticks");



//declare (ticks=1) 1;



echo "";

echo "";



foo();



function foo() {

   echo "foo";

}

?>



win2k : PHP 4.3.0 (cgi-fcgi)

rob_spamsux at rauchmedien dot ihatespam dot com
19-Mar-2002 10:45


Correction to above note:





Apparently, the end brace '}' at the end of the statement causes a tick.





So using





------------


declare (ticks=1) echo "1 tick after this prints";


------------





gives the expected behavior of causing 1 tick.





Note: the tick is issued after the statement executes.





Also, after playing around with this, I found that it is not really the multi-tasking I had expected. It behaves the same as simply calling the functions. I.e. each function must finish before passing the baton to the next function. They do not run in parallel.





It also seems that they always run in the order in which they were registered.





So,





<?php


------------


# register tick functions


register_tick_function ("a");


register_tick_function ("b");





# make the tick functions run


declare (ticks=1);


?>


------------





is equivalent to





------------


a();


b();


------------





It is simply a convenient way to have functions called periodically while some other code is being executed. I.e. you could use it to periodically check the status of something and then exit the script or do something else based on the status.

rob_spamsux at rauchmedien dot ihatespam dot com
19-Mar-2002 09:58


Here is an example of multi-tasking / multi-threading:





<?php


# declare functions


function a() {


  echo "a";


}


function b() {


  echo "b";


}





# register tick functions


register_tick_function ("a");


register_tick_function ("b");





# make the tick functions run


declare (ticks=1);





# that's all there is to it.


?>





Notes:


This will make functions a and b run once each at the same time.





If you try:





declare (ticks=1) {


  1;


}





They will run twice each. That is because it seems to be an undocumented fact that there is always an extra tick.





Therefore:





declare (ticks=2) {


  1;


}





Will cause them to run once.

add a note

return

switch

Last updated: Fri, 13 Nov 2009