Source of: /manual/en/control-structures.declare.php
<?php
include_once $_SERVER['DOCUMENT_ROOT'] . '/include/shared-manual.inc';
$TOC = array();
$PARENTS = array();
include_once dirname(__FILE__) ."/toc/language.control-structures.inc";
$setup = array (
'home' =>
array (
0 => 'index.php',
1 => 'PHP Manual',
),
'head' =>
array (
0 => 'UTF-8',
1 => 'en',
),
'this' =>
array (
0 => 'control-structures.declare.php',
1 => 'declare',
),
'up' =>
array (
0 => 'language.control-structures.php',
1 => 'Control Structures',
),
'prev' =>
array (
0 => 'control-structures.switch.php',
1 => 'switch',
),
'next' =>
array (
0 => 'function.return.php',
1 => 'return',
),
);
$setup["toc"] = $TOC;
$setup["parents"] = $PARENTS;
manual_setup($setup);
manual_header();
?>
<div id="control-structures.declare" class="sect1">
<h2 class="title"><i>declare</i></h2>
<p class="para">
The <i>declare</i> construct is used to
set execution directives for a block of code.
The syntax of <i>declare</i> is similar to
the syntax of other flow control constructs:
</p><div class="informalexample">
<div class="example-contents programlisting">
<div class="cdata"><pre>
declare (directive)
statement
</pre></div>
</div>
</div><p>
</p>
<p class="para">
The <i>directive</i> section allows the
behavior of the <i>declare</i> block to
be set.
Currently only two directives are recognized: the
<i>ticks</i> directive (See below for more
information on the
<a href="control-structures.declare.php#control-structures.declare.ticks" class="link">ticks</a>
directive) and the <i>encoding</i> directive (See below for more
information on the
<a href="control-structures.declare.php#control-structures.declare.encoding" class="link">encoding</a>
directive).
</p>
<blockquote><p><b class="note">Note</b>:
<span class="simpara">
The encoding directive was added in PHP 5.3.0
</span>
</p></blockquote>
<p class="para">
The <i>statement</i> part of the
<i>declare</i> block will be executed - how
it is executed and what side effects occur during execution
may depend on the directive set in the
<i>directive</i> block.
</p>
<p class="para">
The <i>declare</i> construct can also be used in the global
scope, affecting all code following it (however if the file with
<i>declare</i> was included then it does not affect the parent
file).
</p><div class="informalexample">
<div class="example-contents programlisting">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">// these are the same:<br /><br />// you can use this:<br /></span><span style="color: #007700">declare(</span><span style="color: #0000BB">ticks</span><span style="color: #007700">=</span><span style="color: #0000BB">1</span><span style="color: #007700">) {<br /> </span><span style="color: #FF8000">// entire script here<br /></span><span style="color: #007700">}<br /><br /></span><span style="color: #FF8000">// or you can use this:<br /></span><span style="color: #007700">declare(</span><span style="color: #0000BB">ticks</span><span style="color: #007700">=</span><span style="color: #0000BB">1</span><span style="color: #007700">);<br /></span><span style="color: #FF8000">// entire script here<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div><p>
</p>
<div id="control-structures.declare.ticks" class="sect2">
<h3 class="title">Ticks</h3>
<p class="para">A tick is an event that occurs for every
<var class="varname">N</var> low-level tickable statements executed
by the parser within the <i>declare</i> block.
The value for <var class="varname">N</var> is specified
using <code class="code">ticks=<var class="varname">N</var></code>
within the <i>declare</i> blocks's
<i>directive</i> section.
</p>
<p class="para">
Not all statements are tickable. Typically, condition
expressions and argument expressions are not tickable.
</p>
<p class="para">
The event(s) that occur on each tick are specified using the
<a href="function.register-tick-function.php" class="function">register_tick_function()</a>. See the example
below for more details. Note that more than one event can occur
for each tick.
</p>
<p class="para">
</p><div class="example">
<p><b>Example #1 Tick usage example</b></p>
<div class="example-contents programlisting">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #007700">declare(</span><span style="color: #0000BB">ticks</span><span style="color: #007700">=</span><span style="color: #0000BB">1</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// A function called on each tick event<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">tick_handler</span><span style="color: #007700">()<br />{<br /> echo </span><span style="color: #DD0000">"tick_handler() called\n"</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #0000BB">register_tick_function</span><span style="color: #007700">(</span><span style="color: #DD0000">'tick_handler'</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$a </span><span style="color: #007700">= </span><span style="color: #0000BB">1</span><span style="color: #007700">;<br /><br />if (</span><span style="color: #0000BB">$a </span><span style="color: #007700">> </span><span style="color: #0000BB">0</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$a </span><span style="color: #007700">+= </span><span style="color: #0000BB">2</span><span style="color: #007700">;<br /> print(</span><span style="color: #0000BB">$a</span><span style="color: #007700">);<br />}<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div><p>
</p>
<p class="para">
</p><div class="example">
<p><b>Example #2 Ticks usage example</b></p>
<div class="example-contents programlisting">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #007700">function </span><span style="color: #0000BB">tick_handler</span><span style="color: #007700">()<br />{<br /> echo </span><span style="color: #DD0000">"tick_handler() called\n"</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #0000BB">$a </span><span style="color: #007700">= </span><span style="color: #0000BB">1</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">tick_handler</span><span style="color: #007700">();<br /><br />if (</span><span style="color: #0000BB">$a </span><span style="color: #007700">> </span><span style="color: #0000BB">0</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">$a </span><span style="color: #007700">+= </span><span style="color: #0000BB">2</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">tick_handler</span><span style="color: #007700">();<br /> print(</span><span style="color: #0000BB">$a</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">tick_handler</span><span style="color: #007700">();<br />}<br /></span><span style="color: #0000BB">tick_handler</span><span style="color: #007700">();<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div><p>
</p>
<p class="simpara">
See also <a href="function.register-tick-function.php" class="function">register_tick_function()</a> and
<a href="function.unregister-tick-function.php" class="function">unregister_tick_function()</a>.
</p>
</div>
<div id="control-structures.declare.encoding" class="sect2">
<h3 class="title">Encoding</h3>
<p class="para">
A script's encoding can be specified per-script using the encoding directive.
</p><div class="example">
<p><b>Example #3 Declaring an encoding for the script.</b></p>
<div class="example-contents programlisting">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">declare(</span><span style="color: #0000BB">encoding</span><span style="color: #007700">=</span><span style="color: #DD0000">'ISO-8859-1'</span><span style="color: #007700">);<br /></span><span style="color: #FF8000">// code here<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div><p>
</p>
<div class="caution"><b class="caution">Caution</b>
<p class="simpara">
When combined with namespaces, the only legal syntax for declare
is <i>declare(encoding='...');</i> where <i>...</i>
is the encoding value. <i>declare(encoding='...') {}</i>
will result in a parse error when combined with namespaces.
</p>
</div>
<p class="para">
The encoding declare value is ignored in PHP 5.3 unless php is compiled with
<i>--enable-zend-multibyte</i>. In PHP 6.0, the <i>encoding</i>
directive will be used to inform the scanner what encoding the file is created in. Legal
values are encoding names such as <i>UTF-8</i>.
</p>
</div>
</div><?php manual_footer(); ?>
