php-doc-en/language/control-structures/declare.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<sect1 xml:id="control-structures.declare" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title><literal>declare</literal></title>
 <?phpdoc print-version-for="declare"?>
 <para>
  The <literal>declare</literal> construct is used to
  set execution directives for a block of code.
  The syntax of <literal>declare</literal> is similar to
  the syntax of other flow control constructs:
  <informalexample>
   <programlisting>
<![CDATA[
declare (directive)
    statement
]]>
   </programlisting>
  </informalexample>
 </para>

 <para>
  The <literal>directive</literal> section allows the
  behavior of the <literal>declare</literal> block to
  be set.
  Currently only three directives are recognized: the
  <literal>ticks</literal> directive (See below for more
  information on the
  <link linkend="control-structures.declare.ticks">ticks</link>
  directive), the <literal>encoding</literal> directive (See below for more
  information on the
  <link linkend="control-structures.declare.encoding">encoding</link>
  directive) and the <literal>strict_types</literal> directive (See for more
  information the
  <link linkend="functions.arguments.type-declaration.strict">strict</link>
  section on the Function arguments page)
 </para>
 <para>
  <informaltable>
       <tgroup cols="2">
        <thead>
         <row>
          <entry>&Version;</entry>
          <entry>&Description;</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry>5.3.0</entry>
          <entry>Added <literal>encoding</literal> directive</entry>
         </row>
         <row>
          <entry>7.0.0</entry>
          <entry>Added <literal>strict_types</literal> directive</entry>
         </row>
        </tbody>
       </tgroup>
      </informaltable>
 </para>
 <para>
  As directives are handled as the file is being compiled, only literals may
  be given as directive values. Variables and constants cannot be used. To
  illustrate:
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
// This is valid:
declare(ticks=1);

// This is invalid:
const TICK_VALUE = 1;
declare(ticks=TICK_VALUE);
?>
]]>
   </programlisting>
  </informalexample>
 </para>
 <para>
  The <literal>statement</literal> part of the
  <literal>declare</literal> block will be executed - how
  it is executed and what side effects occur during execution
  may depend on the directive set in the
  <literal>directive</literal> block.
 </para>
 <para>
  The <literal>declare</literal> construct can also be used in the global
  scope, affecting all code following it (however if the file with
  <literal>declare</literal> was included then it does not affect the parent
  file).
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
// these are the same:

// you can use this:
declare(ticks=1) {
    // entire script here
}

// or you can use this:
declare(ticks=1);
// entire script here
?>
]]>
   </programlisting>
  </informalexample>
 </para>

 <sect2 xml:id="control-structures.declare.ticks">
  <title>Ticks</title>
  <para>A tick is an event that occurs for every
  <varname>N</varname> low-level tickable statements executed
  by the parser within the <literal>declare</literal> block.
  The value for <varname>N</varname> is specified
  using <code>ticks=<varname>N</varname></code>
  within the <literal>declare</literal> block's
  <literal>directive</literal> section.
 </para>
 <para>
  Not all statements are tickable. Typically, condition
  expressions and argument expressions are not tickable.
 </para>
 <para>
  The event(s) that occur on each tick are specified using the
  <function>register_tick_function</function>. See the example
  below for more details. Note that more than one event can occur
  for each tick.
 </para>
 <para>
  <example>
   <title>Tick usage example</title>
   <programlisting role="php">
<![CDATA[
<?php

declare(ticks=1);

// A function called on each tick event
function tick_handler()
{
    echo "tick_handler() called\n";
}

register_tick_function('tick_handler');

$a = 1;

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

?>
]]>
   </programlisting>
  </example>
 </para>
 <para>
  <example>
   <title>Ticks usage example</title>
   <programlisting role="php">
<![CDATA[
<?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();

?>
]]>
   </programlisting>
  </example>
 </para>
 <simpara>
  See also <function>register_tick_function</function> and
  <function>unregister_tick_function</function>.
 </simpara>
 </sect2>
 <sect2 xml:id="control-structures.declare.encoding">
  <title>Encoding</title>
  <para>
    A script's encoding can be specified per-script using the encoding directive.
  <example>
   <title>Declaring an encoding for the script.</title>
    <programlisting role="php">
<![CDATA[
<?php
declare(encoding='ISO-8859-1');
// code here
?>
]]>
    </programlisting>
   </example>
  </para>

  <caution>
   <simpara>
    When combined with namespaces, the only legal syntax for declare
    is <literal>declare(encoding='...');</literal> where <literal>...</literal>
    is the encoding value.  <literal>declare(encoding='...') {}</literal>
    will result in a parse error when combined with namespaces.
   </simpara>
  </caution>
  <para>
   The encoding declare value is ignored in PHP 5.3 unless php is compiled with
   <literal>--enable-zend-multibyte</literal>.
  </para>
  <para>
   Note that PHP does not expose whether <literal>--enable-zend-multibyte</literal> was
   used to compile PHP other than by <function>phpinfo</function>.
  </para>
  <para>
   See also <link linkend="ini.zend.script-encoding">zend.script_encoding</link>.
  </para>
 </sect2>
</sect1>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->