php-doc-en/language/control-structures/declare.xml
2021-08-21 10:15:21 +09:00

194 lines
5.1 KiB
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>declare</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="language.types.declarations.strict">strict typing</link>
section on the type declarations page)
</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'); // causes a tick event
$a = 1; // causes a tick event
if ($a > 0) {
$a += 2; // causes a tick event
print($a); // causes a tick event
}
?>
]]>
</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 <literal>encoding</literal> 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>
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
-->