mirror of
https://github.com/macintoshplus/doc-en.git
synced 2026-03-29 20:32:07 +02:00
9410c19fda
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@61864 c90b9560-bf6c-de11-be94-00142212c4b1
1450 lines
47 KiB
XML
1450 lines
47 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.42 $ -->
|
|
<chapter id="control-structures">
|
|
<title>Control Structures</title>
|
|
|
|
<simpara>
|
|
Any PHP script is built out of a series of statements. A statement
|
|
can be an assignment, a function call, a loop, a conditional
|
|
statement of even a statement that does nothing (an empty
|
|
statement). Statements usually end with a semicolon. In addition,
|
|
statements can be grouped into a statement-group by encapsulating a
|
|
group of statements with curly braces. A statement-group is a
|
|
statement by itself as well. The various statement types are
|
|
described in this chapter.
|
|
</simpara>
|
|
|
|
<sect1 id="control-structures.if">
|
|
<title><literal>if</literal></title>
|
|
<para>
|
|
The <literal>if</literal> construct is one of the most important
|
|
features of many languages, PHP included. It allows for
|
|
conditional execution of code fragments. PHP features an
|
|
<literal>if</literal> structure that is similar to that of C:
|
|
<informalexample>
|
|
<programlisting>
|
|
if (expr)
|
|
statement
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<simpara>
|
|
As described in the section about expressions, expr is evaluated
|
|
to its truth value. If <replaceable>expr</replaceable> evaluates
|
|
to &true;, PHP will execute statement, and if it
|
|
evaluates to &false; - it'll ignore it.
|
|
</simpara>
|
|
<para>
|
|
The following example would display <computeroutput>a is bigger
|
|
than b</computeroutput> if <replaceable>$a</replaceable> is bigger
|
|
than <replaceable>$b</replaceable>:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
if ($a > $b)
|
|
print "a is bigger than b";
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
Often you'd want to have more than one statement to be executed
|
|
conditionally. Of course, there's no need to wrap each statement
|
|
with an <literal>if</literal> clause. Instead, you can group
|
|
several statements into a statement group. For example, this code
|
|
would display <computeroutput>a is bigger than b</computeroutput>
|
|
if <replaceable>$a</replaceable> is bigger than
|
|
<replaceable>$b</replaceable>, and would then assign the value of
|
|
<replaceable>$a</replaceable> into <replaceable>$b</replaceable>:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
if ($a > $b) {
|
|
print "a is bigger than b";
|
|
$b = $a;
|
|
}
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<simpara>
|
|
If statements can be nested indefinitely within other
|
|
<literal>if</literal> statements, which provides you with complete
|
|
flexibility for conditional execution of the various parts of your
|
|
program.
|
|
</simpara>
|
|
</sect1>
|
|
|
|
<sect1 id="control-structures.else">
|
|
<title><literal>else</literal></title>
|
|
<para>
|
|
Often you'd want to execute a statement if a certain condition is
|
|
met, and a different statement if the condition is not met. This
|
|
is what <literal>else</literal> is for. <literal>else</literal>
|
|
extends an <literal>if</literal> statement to execute a statement
|
|
in case the expression in the <literal>if</literal> statement
|
|
evaluates to &false;. For example, the following
|
|
code would display <computeroutput>a is bigger than
|
|
b</computeroutput> if <replaceable>$a</replaceable> is bigger than
|
|
<replaceable>$b</replaceable>, and <computeroutput>a is NOT bigger
|
|
than b</computeroutput> otherwise:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
if ($a > $b) {
|
|
print "a is bigger than b";
|
|
} else {
|
|
print "a is NOT bigger than b";
|
|
}
|
|
</programlisting>
|
|
</informalexample>
|
|
|
|
The <literal>else</literal> statement is only executed if the
|
|
<literal>if</literal> expression evaluated to
|
|
&false;, and if there were any
|
|
<literal>elseif</literal> expressions - only if they evaluated to
|
|
&false; as well (see <link
|
|
linkend="control-structures.elseif">elseif</link>).
|
|
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="control-structures.elseif">
|
|
<title><literal>elseif</literal></title>
|
|
<para>
|
|
<literal>elseif</literal>, as its name suggests, is a combination
|
|
of <literal>if</literal> and <literal>else</literal>. Like
|
|
<literal>else</literal>, it extends an <literal>if</literal>
|
|
statement to execute a different statement in case the original
|
|
<literal>if</literal> expression evaluates to
|
|
&false;. However, unlike
|
|
<literal>else</literal>, it will execute that alternative
|
|
expression only if the <literal>elseif</literal> conditional
|
|
expression evaluates to &true;. For example, the
|
|
following code would display <computeroutput>a is bigger than
|
|
b</computeroutput>, <computeroutput>a equal to b</computeroutput>
|
|
or <computeroutput>a is smaller than b</computeroutput>:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
if ($a > $b) {
|
|
print "a is bigger than b";
|
|
} elseif ($a == $b) {
|
|
print "a is equal to b";
|
|
} else {
|
|
print "a is smaller than b";
|
|
}
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<simpara>
|
|
There may be several <literal>elseif</literal>s within the same
|
|
<literal>if</literal> statement. The first
|
|
<literal>elseif</literal> expression (if any) that evaluates to
|
|
&true; would be executed. In PHP, you can also
|
|
write 'else if' (in two words) and the behavior would be identical
|
|
to the one of 'elseif' (in a single word). The syntactic meaning
|
|
is slightly different (if you're familiar with C, this is the same
|
|
behavior) but the bottom line is that both would result in exactly
|
|
the same behavior.
|
|
</simpara>
|
|
<simpara>
|
|
The <literal>elseif</literal> statement is only executed if the
|
|
preceding <literal>if</literal> expression and any preceding
|
|
<literal>elseif</literal> expressions evaluated to
|
|
&false;, and the current
|
|
<literal>elseif</literal> expression evaluated to
|
|
&true;.
|
|
</simpara>
|
|
</sect1>
|
|
|
|
<sect1 id="control-structures.alternative-syntax">
|
|
<title>Alternative syntax for control structures</title>
|
|
<para>
|
|
PHP offers an alternative syntax for some of its control
|
|
structures; namely, <literal>if</literal>,
|
|
<literal>while</literal>, <literal>for</literal>,
|
|
<literal>foreach</literal>, and <literal>switch</literal>.
|
|
In each case, the basic form of the alternate syntax is to change
|
|
the opening brace to a colon (:) and the closing brace to
|
|
<literal>endif;</literal>, <literal>endwhile;</literal>,
|
|
<literal>endfor;</literal>, <literal>endforeach;</literal>, or
|
|
<literal>endswitch;</literal>, respectively.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<?php if ($a == 5): ?>
|
|
A is equal to 5
|
|
<?php endif; ?>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<simpara>
|
|
In the above example, the HTML block "A = 5" is nested within an
|
|
<literal>if</literal> statement written in the alternative syntax.
|
|
The HTML block would be displayed only if $a is equal to 5.
|
|
</simpara>
|
|
<para>
|
|
The alternative syntax applies to <literal>else</literal> and
|
|
<literal>elseif</literal> as well. The following is an
|
|
<literal>if</literal> structure with <literal>elseif</literal> and
|
|
<literal>else</literal> in the alternative format:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
if ($a == 5):
|
|
print "a equals 5";
|
|
print "...";
|
|
elseif ($a == 6):
|
|
print "a equals 6";
|
|
print "!!!";
|
|
else:
|
|
print "a is neither 5 nor 6";
|
|
endif;
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
See also <link linkend="control-structures.while">while</link>,
|
|
<link linkend="control-structures.for">for</link>, and <link
|
|
linkend="control-structures.if">if</link> for further examples.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="control-structures.while">
|
|
<title><literal>while</literal></title>
|
|
<para>
|
|
<literal>while</literal> loops are the simplest type of loop in
|
|
PHP. They behave just like their C counterparts. The basic form
|
|
of a <literal>while</literal> statement is:
|
|
<informalexample>
|
|
<programlisting>
|
|
while (expr) statement
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<simpara>
|
|
The meaning of a <literal>while</literal> statement is simple. It
|
|
tells PHP to execute the nested statement(s) repeatedly, as long
|
|
as the <literal>while</literal> expression evaluates to
|
|
&true;. The value of the expression is checked
|
|
each time at the beginning of the loop, so even if this value
|
|
changes during the execution of the nested statement(s), execution
|
|
will not stop until the end of the iteration (each time PHP runs
|
|
the statements in the loop is one iteration). Sometimes, if the
|
|
<literal>while</literal> expression evaluates to
|
|
&false; from the very beginning, the nested
|
|
statement(s) won't even be run once.
|
|
</simpara>
|
|
<para>
|
|
Like with the <literal>if</literal> statement, you can group
|
|
multiple statements within the same <literal>while</literal> loop
|
|
by surrounding a group of statements with curly braces, or by
|
|
using the alternate syntax:
|
|
<informalexample>
|
|
<programlisting>
|
|
while (expr): statement ... endwhile;
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
The following examples are identical, and both print numbers from
|
|
1 to 10:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
/* example 1 */
|
|
|
|
$i = 1;
|
|
while ($i <= 10) {
|
|
print $i++; /* the printed value would be
|
|
$i before the increment
|
|
(post-increment) */
|
|
}
|
|
|
|
/* example 2 */
|
|
|
|
$i = 1;
|
|
while ($i <= 10):
|
|
print $i;
|
|
$i++;
|
|
endwhile;
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="control-structures.do.while">
|
|
<title><literal>do..while</literal></title>
|
|
<simpara>
|
|
<literal>do..while</literal> loops are very similar to
|
|
<literal>while</literal> loops, except the truth expression is
|
|
checked at the end of each iteration instead of in the beginning.
|
|
The main difference from regular <literal>while</literal> loops is
|
|
that the first iteration of a <literal>do..while</literal> loop is
|
|
guarenteed to run (the truth expression is only checked at the end
|
|
of the iteration), whereas it's may not necessarily run with a
|
|
regular <literal>while</literal> loop (the truth expression is
|
|
checked at the beginning of each iteration, if it evaluates to
|
|
&false; right from the beginning, the loop
|
|
execution would end immediately).
|
|
</simpara>
|
|
<para>
|
|
There is just one syntax for <literal>do..while</literal> loops:
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
$i = 0;
|
|
do {
|
|
print $i;
|
|
} while ($i>0);
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<simpara>
|
|
The above loop would run one time exactly, since after the first
|
|
iteration, when truth expression is checked, it evaluates to
|
|
&false; ($i is not bigger than 0) and the loop
|
|
execution ends.
|
|
</simpara>
|
|
<para>
|
|
Advanced C users may be familiar with a different usage of the
|
|
<literal>do..while</literal> loop, to allow stopping execution in
|
|
the middle of code blocks, by encapsulating them with
|
|
<literal>do..while</literal>(0), and using the <link
|
|
linkend="control-structures.break"><literal>break</literal></link>
|
|
statement. The following code fragment demonstrates this:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
do {
|
|
if ($i < 5) {
|
|
print "i is not big enough";
|
|
break;
|
|
}
|
|
$i *= $factor;
|
|
if ($i < $minimum_limit) {
|
|
break;
|
|
}
|
|
print "i is ok";
|
|
|
|
...process i...
|
|
|
|
} while(0);
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<simpara>
|
|
Don't worry if you don't understand this right away or at all.
|
|
You can code scripts and even powerful scripts without using this
|
|
`feature'.
|
|
</simpara>
|
|
</sect1>
|
|
|
|
<sect1 id="control-structures.for">
|
|
<title><literal>for</literal></title>
|
|
<para>
|
|
<literal>for</literal> loops are the most complex loops in PHP.
|
|
They behave like their C counterparts. The syntax of a
|
|
<literal>for</literal> loop is:
|
|
<informalexample>
|
|
<programlisting>
|
|
for (expr1; expr2; expr3) statement
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<simpara>
|
|
The first expression (<replaceable>expr1</replaceable>) is
|
|
evaluated (executed) once unconditionally at the beginning of the
|
|
loop.
|
|
</simpara>
|
|
<simpara>
|
|
In the beginning of each iteration,
|
|
<replaceable>expr2</replaceable> is evaluated. If it evaluates to
|
|
&true;, the loop continues and the nested
|
|
statement(s) are executed. If it evaluates to
|
|
&false;, the execution of the loop ends.
|
|
</simpara>
|
|
<simpara>
|
|
At the end of each iteration, <replaceable>expr3</replaceable> is
|
|
evaluated (executed).
|
|
</simpara>
|
|
<simpara>
|
|
Each of the expressions can be empty.
|
|
<replaceable>expr2</replaceable> being empty means the loop should
|
|
be run indefinitely (PHP implicitly considers it as
|
|
&true;, like C). This may not be as useless as
|
|
you might think, since often you'd want to end the loop using a
|
|
conditional <link
|
|
linkend="control-structures.break"><literal>break</literal></link>
|
|
statement instead of using the <literal>for</literal> truth
|
|
expression.
|
|
</simpara>
|
|
<para>
|
|
Consider the following examples. All of them display numbers from
|
|
1 to 10:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
/* example 1 */
|
|
|
|
for ($i = 1; $i <= 10; $i++) {
|
|
print $i;
|
|
}
|
|
|
|
/* example 2 */
|
|
|
|
for ($i = 1;;$i++) {
|
|
if ($i > 10) {
|
|
break;
|
|
}
|
|
print $i;
|
|
}
|
|
|
|
/* example 3 */
|
|
|
|
$i = 1;
|
|
for (;;) {
|
|
if ($i > 10) {
|
|
break;
|
|
}
|
|
print $i;
|
|
$i++;
|
|
}
|
|
|
|
/* example 4 */
|
|
|
|
for ($i = 1; $i <= 10; print $i, $i++);
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<simpara>
|
|
Of course, the first example appears to be the nicest one (or
|
|
perhaps the fourth), but you may find that being able to use empty
|
|
expressions in <literal>for</literal> loops comes in handy in many
|
|
occasions.
|
|
</simpara>
|
|
<para>
|
|
PHP also supports the alternate "colon syntax" for
|
|
<literal>for</literal> loops.
|
|
<informalexample>
|
|
<programlisting>
|
|
for (expr1; expr2; expr3): statement; ...; endfor;
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
Other languages have a <literal>foreach</literal> statement to
|
|
traverse an array or hash. PHP 3 has no such construct; PHP 4 does
|
|
(see <link
|
|
linkend="control-structures.foreach">foreach</link>). In PHP 3, you
|
|
can combine <link linkend="control-structures.while">while</link>
|
|
with the <function>list</function> and <function>each</function>
|
|
functions to achieve the same effect. See the documentation for
|
|
these functions for an example.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="control-structures.foreach">
|
|
<title><literal>foreach</literal></title>
|
|
<para>
|
|
PHP 4 (not PHP 3) includes a <literal>foreach</literal> construct,
|
|
much like Perl and some other languages. This simply gives an easy
|
|
way to iterate over arrays. There are two syntaxes; the second is
|
|
a minor but useful extension of the first:
|
|
<informalexample>
|
|
<programlisting>
|
|
foreach(array_expression as $value) statement
|
|
foreach(array_expression as $key => $value) statement
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<simpara>
|
|
The first form loops over the array given by
|
|
<literal>array_expression</literal>. On each loop, the value of
|
|
the current element is assigned to <literal>$value</literal> and
|
|
the internal array pointer is advanced by one (so on the next
|
|
loop, you'll be looking at the next element).
|
|
</simpara>
|
|
<simpara>
|
|
The second form does the same thing, except that the current
|
|
element's key will be assigned to the variable
|
|
<literal>$key</literal> on each loop.
|
|
</simpara>
|
|
<para>
|
|
<note>
|
|
<para>
|
|
When <literal>foreach</literal> first starts executing, the
|
|
internal array pointer is automatically reset to the first element
|
|
of the array. This means that you do not need to call
|
|
<function>reset</function> before a <literal>foreach</literal>
|
|
loop.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
<para>
|
|
<note>
|
|
<para>
|
|
Also note that <literal>foreach</literal> operates on a copy of
|
|
the specified array, not the array itself, therefore the array
|
|
pointer is not modified as with the <function>each</function>
|
|
construct and changes to the array element returned are not
|
|
reflected in the original array.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
<literal>foreach</literal> does not support the ability to
|
|
suppress error messages using '@'.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
You may have noticed that the following are functionally
|
|
identical:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
reset ($arr);
|
|
while (list(, $value) = each ($arr)) {
|
|
echo "Value: $value<br>\n";
|
|
}
|
|
|
|
foreach ($arr as $value) {
|
|
echo "Value: $value<br>\n";
|
|
}
|
|
</programlisting>
|
|
</informalexample>
|
|
The following are also functionally identical:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
reset ($arr);
|
|
while (list($key, $value) = each ($arr)) {
|
|
echo "Key: $key; Value: $value<br>\n";
|
|
}
|
|
|
|
foreach ($arr as $key => $value) {
|
|
echo "Key: $key; Value: $value<br>\n";
|
|
}
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
Some more examples to demonstrate usages:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
/* foreach example 1: value only */
|
|
|
|
$a = array (1, 2, 3, 17);
|
|
|
|
foreach ($a as $v) {
|
|
print "Current value of \$a: $v.\n";
|
|
}
|
|
|
|
/* foreach example 2: value (with key printed for illustration) */
|
|
|
|
$a = array (1, 2, 3, 17);
|
|
|
|
$i = 0; /* for illustrative purposes only */
|
|
|
|
foreach($a as $v) {
|
|
print "\$a[$i] => $v.\n";
|
|
}
|
|
|
|
/* foreach example 3: key and value */
|
|
|
|
$a = array (
|
|
"one" => 1,
|
|
"two" => 2,
|
|
"three" => 3,
|
|
"seventeen" => 17
|
|
);
|
|
|
|
foreach($a as $k => $v) {
|
|
print "\$a[$k] => $v.\n";
|
|
}
|
|
|
|
/* foreach example 4: multi-dimensional arrays */
|
|
|
|
$a[0][0] = "a";
|
|
$a[0][1] = "b";
|
|
$a[1][0] = "y";
|
|
$a[1][1] = "z";
|
|
|
|
foreach($a as $v1) {
|
|
foreach ($v1 as $v2) {
|
|
print "$v2\n";
|
|
}
|
|
}
|
|
|
|
/* foreach example 5: dynamic arrays */
|
|
|
|
foreach(array(1, 2, 3, 4, 5) as $v) {
|
|
print "$v\n";
|
|
}
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="control-structures.break">
|
|
<title><literal>break</literal></title>
|
|
<simpara>
|
|
<literal>break</literal> ends execution of the current
|
|
<literal>for</literal>, <literal>foreach</literal>
|
|
<literal>while</literal>, <literal>do..while</literal> or
|
|
<literal>switch</literal> structure.
|
|
</simpara>
|
|
<simpara>
|
|
<literal>break</literal> accepts an optional numeric argument
|
|
which tells it how many nested enclosing structures are to be
|
|
broken out of.
|
|
</simpara>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
$arr = array ('one', 'two', 'three', 'four', 'stop', 'five');
|
|
while (list (, $val) = each ($arr)) {
|
|
if ($val == 'stop') {
|
|
break; /* You could also write 'break 1;' here. */
|
|
}
|
|
echo "$val<br>\n";
|
|
}
|
|
|
|
/* Using the optional argument. */
|
|
|
|
$i = 0;
|
|
while (++$i) {
|
|
switch ($i) {
|
|
case 5:
|
|
echo "At 5<br>\n";
|
|
break 1; /* Exit only the switch. */
|
|
case 10:
|
|
echo "At 10; quitting<br>\n";
|
|
break 2; /* Exit the switch and the while. */
|
|
default:
|
|
break;
|
|
}
|
|
}
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="control-structures.continue">
|
|
<title><literal>continue</literal></title>
|
|
<simpara>
|
|
<literal>continue</literal> is used within looping structures to
|
|
skip the rest of the current loop iteration and continue execution
|
|
at the beginning of the next iteration.
|
|
</simpara>
|
|
<simpara>
|
|
<literal>continue</literal> accepts an optional numeric argument
|
|
which tells it how many levels of enclosing loops it should skip
|
|
to the end of.
|
|
</simpara>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
while (list ($key, $value) = each ($arr)) {
|
|
if (!($key % 2)) { // skip odd members
|
|
continue;
|
|
}
|
|
do_something_odd ($value);
|
|
}
|
|
|
|
$i = 0;
|
|
while ($i++ < 5) {
|
|
echo "Outer<br>\n";
|
|
while (1) {
|
|
echo " Middle<br>\n";
|
|
while (1) {
|
|
echo " Inner<br>\n";
|
|
continue 3;
|
|
}
|
|
echo "This never gets output.<br>\n";
|
|
}
|
|
echo "Neither does this.<br>\n";
|
|
}
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="control-structures.switch">
|
|
<title><literal>switch</literal></title>
|
|
<simpara>
|
|
The <literal>switch</literal> statement is similar to a series of
|
|
IF statements on the same expression. In many occasions, you may
|
|
want to compare the same variable (or expression) with many
|
|
different values, and execute a different piece of code depending
|
|
on which value it equals to. This is exactly what the
|
|
<literal>switch</literal> statement is for.
|
|
</simpara>
|
|
<para>
|
|
The following two examples are two different ways to write the
|
|
same thing, one using a series of <literal>if</literal>
|
|
statements, and the other using the <literal>switch</literal>
|
|
statement:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
if ($i == 0) {
|
|
print "i equals 0";
|
|
}
|
|
if ($i == 1) {
|
|
print "i equals 1";
|
|
}
|
|
if ($i == 2) {
|
|
print "i equals 2";
|
|
}
|
|
|
|
switch ($i) {
|
|
case 0:
|
|
print "i equals 0";
|
|
break;
|
|
case 1:
|
|
print "i equals 1";
|
|
break;
|
|
case 2:
|
|
print "i equals 2";
|
|
break;
|
|
}
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
It is important to understand how the <literal>switch</literal>
|
|
statement is executed in order to avoid mistakes. The
|
|
<literal>switch</literal> statement executes line by line
|
|
(actually, statement by statement). In the beginning, no code is
|
|
executed. Only when a <literal>case</literal> statement is found
|
|
with a value that matches the value of the
|
|
<literal>switch</literal> expression does PHP begin to execute the
|
|
statements. PHP continues to execute the statements until the end
|
|
of the <literal>switch</literal> block, or the first time it sees
|
|
a <literal>break</literal> statement. If you don't write a
|
|
<literal>break</literal> statement at the end of a case's
|
|
statement list, PHP will go on executing the statements of the
|
|
following case. For example:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
switch ($i) {
|
|
case 0:
|
|
print "i equals 0";
|
|
case 1:
|
|
print "i equals 1";
|
|
case 2:
|
|
print "i equals 2";
|
|
}
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<simpara>
|
|
Here, if $i equals to 0, PHP would execute all of the print
|
|
statements! If $i equals to 1, PHP would execute the last two
|
|
print statements, and only if $i equals to 2, you'd get the
|
|
'expected' behavior and only 'i equals 2' would be displayed. So,
|
|
it's important not to forget <literal>break</literal> statements
|
|
(even though you may want to avoid supplying them on purpose under
|
|
certain circumstances).
|
|
</simpara>
|
|
<simpara>
|
|
In a <literal>switch</literal> statement, the condition is
|
|
evaluated only once and the result is compared to each
|
|
<literal>case</literal> statement. In an <literal>elseif</literal>
|
|
statement, the condition is evaluated again. If your condition is
|
|
more complicated than a simple compare and/or is in a tight loop,
|
|
a <literal>switch</literal> may be faster.
|
|
</simpara>
|
|
<para>
|
|
The statement list for a case can also be empty, which simply
|
|
passes control into the statement list for the next case.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
switch ($i) {
|
|
case 0:
|
|
case 1:
|
|
case 2:
|
|
print "i is less than 3 but not negative";
|
|
break;
|
|
case 3:
|
|
print "i is 3";
|
|
}
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
A special case is the default case. This case matches anything
|
|
that wasn't matched by the other cases, and should be the last
|
|
<literal>case</literal> statement. For example:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
switch ($i) {
|
|
case 0:
|
|
print "i equals 0";
|
|
break;
|
|
case 1:
|
|
print "i equals 1";
|
|
break;
|
|
case 2:
|
|
print "i equals 2";
|
|
break;
|
|
default:
|
|
print "i is not equal to 0, 1 or 2";
|
|
}
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
The <literal>case</literal> expression may be any expression that
|
|
evaluates to a simple type, that is, integer or floating-point
|
|
numbers and strings. Arrays or objects cannot be used here unless
|
|
they are dereferenced to a simple type.
|
|
</para>
|
|
<para>
|
|
The alternative syntax for control structures is supported with
|
|
switches. For more information, see <link
|
|
linkend="control-structures.alternative-syntax">Alternative syntax
|
|
for control structures</link> .
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
switch ($i):
|
|
case 0:
|
|
print "i equals 0";
|
|
break;
|
|
case 1:
|
|
print "i equals 1";
|
|
break;
|
|
case 2:
|
|
print "i equals 2";
|
|
break;
|
|
default:
|
|
print "i is not equal to 0, 1 or 2";
|
|
endswitch;
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="control-structures.declare">
|
|
<title><literal>declare</literal></title>
|
|
<para>
|
|
The <literal>declare</literal> construct is used to
|
|
set execution directives for a block of code.
|
|
The syntax of <literal>declare</literal> is similiar to
|
|
the syntax of other flow control constructs:
|
|
<informalexample>
|
|
<programlisting>
|
|
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 one directive is recognized: the
|
|
<literal>ticks</literal> directive. (See below for more
|
|
information on the
|
|
<link linkend="control-structures.declare.ticks">ticks</link>
|
|
directive)
|
|
</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>
|
|
<sect2 id="control-structures.declare.ticks">
|
|
<title>Ticks</title>
|
|
<para>A tick is an event that occurs for every
|
|
<replaceable>N</replaceable> low-level statements executed
|
|
by the parser within the <literal>declare</literal> block.
|
|
The value for <replaceable>N</replaceable> is specified
|
|
using <literal>ticks=<replaceable>N</replaceable></literal>
|
|
within the <literal>declare</literal> blocks's
|
|
<literal>directive</literal> section.
|
|
</para>
|
|
<para>
|
|
The event(s) that occurs on each tick is 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>Profile a section of PHP code</title>
|
|
<programlisting role="php">
|
|
<pre>
|
|
<?php
|
|
// A function that records the time when it is called
|
|
function profile ($dump = FALSE)
|
|
{
|
|
static $profile;
|
|
|
|
// Return the times stored in profile, then erase it
|
|
if ($dump) {
|
|
$temp = $profile;
|
|
unset ($profile);
|
|
return ($temp);
|
|
}
|
|
|
|
$profile[] = microtime ();
|
|
}
|
|
|
|
// Set up a tick handler
|
|
register_tick_function("profile");
|
|
|
|
// Initialize the function before the declare block
|
|
profile ();
|
|
|
|
// Run a block of code, throw a tick every 2nd statement
|
|
declare (ticks=2) {
|
|
for ($x = 1; $x < 50; ++$x) {
|
|
echo similar_text (md5($x), md5($x*$x)), "<br>";
|
|
}
|
|
}
|
|
|
|
// Display the data stored in the profiler
|
|
print_r (profile (TRUE));
|
|
?>
|
|
</pre>
|
|
</programlisting>
|
|
</example>
|
|
The example profiles the PHP code within the 'declare'
|
|
block, recording the time at which every second low-level
|
|
statement in the block was executed. This information can
|
|
then be used to find the slow areas within particular
|
|
segments of code. This process can be performed using other
|
|
methods: using ticks is more convenient and easier to
|
|
implement.
|
|
</para>
|
|
<simpara>
|
|
Ticks are well suited for debugging, implementing simple
|
|
multitasking, backgrounded I/O and many other tasks.
|
|
</simpara>
|
|
<simpara>
|
|
See also <function>register_tick_function</function> and
|
|
<function>unregister_tick_function</function>.
|
|
</simpara>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="function.require">
|
|
<title><function>require</function></title>
|
|
<simpara>
|
|
The <function>require</function> statement replaces itself with
|
|
the specified file, much like the C preprocessor's
|
|
<literal>#include</literal> works.
|
|
</simpara>
|
|
<simpara>
|
|
If "URL fopen wrappers" are enabled in PHP (which they are in the
|
|
default configuration), you can specify the file to be
|
|
<function>require</function>ed using an URL instead of a local
|
|
pathname. See <link linkend="features.remote-files">Remote
|
|
files</link> and <function>fopen</function> for more information.
|
|
</simpara>
|
|
<simpara>
|
|
An important note about how this works is that when a file is
|
|
<function>include</function>ed or <function>require</function>ed,
|
|
parsing drops out of PHP mode and into HTML mode at the beginning
|
|
of the target file, and resumes PHP mode again at the end. For
|
|
this reason, any code inside the target file which should be
|
|
executed as PHP code must be enclosed within <link
|
|
linkend="language.basic-syntax.phpmode">valid PHP start and end
|
|
tags</link>.
|
|
</simpara>
|
|
<simpara>
|
|
<function>require</function> is not actually a function in PHP;
|
|
rather, it is a language construct. It is subject to some
|
|
different rules than functions are. For instance,
|
|
<function>require</function> is not subject to any containing
|
|
control structures. For another, it does not return any value;
|
|
attempting to read a return value from a
|
|
<function>require</function> call results in a parse error.
|
|
</simpara>
|
|
<simpara>
|
|
Unlike <function>include</function>, <function>require</function>
|
|
will <emphasis>always</emphasis> read in the target file,
|
|
<emphasis>even if the line it's on never executes</emphasis>. If
|
|
you want to conditionally include a file, use
|
|
<function>include</function>. The conditional statement won't
|
|
affect the <function>require</function>. However, if the line on
|
|
which the <function>require</function> occurs is not executed,
|
|
neither will any of the code in the target file be executed.
|
|
</simpara>
|
|
<simpara>
|
|
Similarly, looping structures do not affect the behaviour of
|
|
<function>require</function>. Although the code contained in the
|
|
target file is still subject to the loop, the
|
|
<function>require</function> itself happens only once.
|
|
</simpara>
|
|
<para>
|
|
This means that you can't put a <function>require</function>
|
|
statement inside of a loop structure and expect it to include the
|
|
contents of a different file on each iteration. To do that, use an
|
|
<function>include</function> statement.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
require ('header.inc');
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<simpara>
|
|
When a file is <function>require</function>ed, the code it
|
|
contains inherits the variable scope of the line on which the
|
|
<function>require</function> occurs. Any variables available at
|
|
that line in the calling file will be available within the called
|
|
file. If the <function>require</function> occurs inside a
|
|
function within the calling file, then all of the code contained
|
|
in the called file will behave as though it had been defined
|
|
inside that function.
|
|
</simpara>
|
|
<para>
|
|
If the <function>require</function>ed file is called via HTTP
|
|
using the fopen wrappers, and if the target server interprets the
|
|
target file as PHP code, variables may be passed to the
|
|
<function>require</function>ed file using an URL request string as
|
|
used with HTTP GET. This is not strictly speaking the same thing
|
|
as <function>require</function>ing the file and having it inherit
|
|
the parent file's variable scope; the script is actually being run
|
|
on the remote server and the result is then being included into
|
|
the local script.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
/* This example assumes that someserver is configured to parse .php
|
|
* files and not .txt files. Also, 'works' here means that the variables
|
|
* $varone and $vartwo are available within the require()ed file. */
|
|
|
|
/* Won't work; file.txt wasn't handled by someserver. */
|
|
require ("http://someserver/file.txt?varone=1&vartwo=2");
|
|
|
|
/* Won't work; looks for a file named 'file.php?varone=1&vartwo=2'
|
|
* on the local filesystem. */
|
|
require ("file.php?varone=1&vartwo=2");
|
|
|
|
/* Works. */
|
|
require ("http://someserver/file.php?varone=1&vartwo=2");
|
|
|
|
$varone = 1;
|
|
$vartwo = 2;
|
|
require ("file.txt"); /* Works. */
|
|
require ("file.php"); /* Works. */
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<simpara>
|
|
In PHP 3, it is possible to execute a <literal>return</literal>
|
|
statement inside a <function>require</function>ed file, as long as
|
|
that statement occurs in the global scope of the
|
|
<function>require</function>ed file. It may not occur within any
|
|
block (meaning inside braces ({}). In PHP 4, however, this ability
|
|
has been discontinued. If you need this functionality, see
|
|
<function>include</function>.
|
|
</simpara>
|
|
<simpara>
|
|
See also <function>include</function>, <function>require_once</function>,
|
|
<function>include_once</function>, <function>readfile</function>,
|
|
and <function>virtual</function>.
|
|
</simpara>
|
|
</sect1>
|
|
|
|
<sect1 id="function.include">
|
|
<title><function>include</function></title>
|
|
<simpara>
|
|
The <function>include</function> statement includes and evaluates
|
|
the specified file.
|
|
</simpara>
|
|
<simpara>
|
|
If "URL fopen wrappers" are enabled in PHP (which they are in the
|
|
default configuration), you can specify the file to be
|
|
<function>include</function>ed using an URL instead of a local
|
|
pathname. See <link linkend="features.remote-files">Remote
|
|
files</link> and <function>fopen</function> for more information.
|
|
</simpara>
|
|
<simpara>
|
|
An important note about how this works is that when a file is
|
|
<function>include</function>ed or <function>require</function>ed,
|
|
parsing drops out of PHP mode and into HTML mode at the beginning
|
|
of the target file, and resumes again at the end. For this reason,
|
|
any code inside the target file which should be executed as PHP
|
|
code must be enclosed within <link
|
|
linkend="language.basic-syntax.phpmode">valid PHP start and end
|
|
tags</link>.
|
|
</simpara>
|
|
<para>
|
|
This happens each time the <function>include</function> statement
|
|
is encountered, so you can use an <function>include</function>
|
|
statement within a looping structure to include a number of
|
|
different files.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
$files = array ('first.inc', 'second.inc', 'third.inc');
|
|
for ($i = 0; $i < count($files); $i++) {
|
|
include $files[$i];
|
|
}
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
<function>include</function> differs from
|
|
<function>require</function> in that the include statement is
|
|
re-evaluated each time it is encountered (and only when it is
|
|
being executed), whereas the <function>require</function>
|
|
statement is replaced by the required file when it is first
|
|
encountered, whether the contents of the file will be evaluated or
|
|
not (for example, if it is inside an <link
|
|
linkend="control-structures.if">if</link> statement whose
|
|
condition evaluated to &false;).
|
|
</para>
|
|
<para>
|
|
Because <function>include</function> is a special language
|
|
construct, you must enclose it within a statement block if it is
|
|
inside a conditional block.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
/* This is WRONG and will not work as desired. */
|
|
|
|
if ($condition)
|
|
include($file);
|
|
else
|
|
include($other);
|
|
|
|
/* This is CORRECT. */
|
|
|
|
if ($condition) {
|
|
include($file);
|
|
} else {
|
|
include($other);
|
|
}
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<simpara>
|
|
In both PHP 3 and PHP 4, it is possible to execute a
|
|
<literal>return</literal> statement inside an
|
|
<function>include</function>ed file, in order to terminate
|
|
processing in that file and return to the script which called
|
|
it. Some differences in the way this works exist, however. The
|
|
first is that in PHP 3, the <literal>return</literal> may not
|
|
appear inside a block unless it's a function block, in which case
|
|
the <literal>return</literal> applies to that function and not the
|
|
whole file. In PHP 4, however, this restriction does not
|
|
exist. Also, PHP 4 allows you to return values from
|
|
<function>include</function>ed files. You can take the value of
|
|
the <function>include</function> call as you would a normal
|
|
function. This generates a parse error in PHP 3.
|
|
</simpara>
|
|
<example>
|
|
<title><function>include</function> in PHP 3 and PHP 4</title>
|
|
<para>
|
|
Assume the existence of the following file (named
|
|
<filename>test.inc</filename>) in the same directory as the main
|
|
file:
|
|
<programlisting role="php">
|
|
<?php
|
|
echo "Before the return <br>\n";
|
|
if (1) {
|
|
return 27;
|
|
}
|
|
echo "After the return <br>\n";
|
|
?>
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
Assume that the main file (<filename>main.html</filename>)
|
|
contains the following:
|
|
<programlisting role="php">
|
|
<?php
|
|
$retval = include ('test.inc');
|
|
echo "File returned: '$retval'<br>\n";
|
|
?>
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
When <filename>main.html</filename> is called in PHP 3, it will
|
|
generate a parse error on line 2; you can't take the value of an
|
|
<function>include</function> in PHP 3. In PHP 4, however, the
|
|
result will be:
|
|
<screen>
|
|
Before the return
|
|
File returned: '27'
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
Now, assume that <filename>main.html</filename> has been altered
|
|
to contain the following:
|
|
<programlisting role="php">
|
|
<?php
|
|
include ('test.inc');
|
|
echo "Back in main.html<br>\n";
|
|
?>
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
In PHP 4, the output will be:
|
|
<screen>
|
|
Before the return
|
|
Back in main.html
|
|
</screen>
|
|
However, PHP 3 will give the following output:
|
|
<screen>
|
|
Before the return
|
|
27Back in main.html
|
|
|
|
Parse error: parse error in /home/torben/public_html/phptest/main.html on line 5
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
The above parse error is a result of the fact that the
|
|
<literal>return</literal> statement is enclosed in a non-function
|
|
block within <filename>test.inc</filename>. When the return is
|
|
moved outside of the block, the output is:
|
|
<screen>
|
|
Before the return
|
|
27Back in main.html
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
The spurious '27' is due to the fact that PHP 3 does not support
|
|
<literal>return</literal>ing values from files like that.
|
|
</para>
|
|
</example>
|
|
<simpara>
|
|
When a file is <function>include</function>ed, the code it
|
|
contains inherits the variable scope of the line on which the
|
|
<function>include</function> occurs. Any variables available at
|
|
that line in the calling file will be available within the called
|
|
file. If the <function>include</function> occurs inside a
|
|
function within the calling file, then all of the code contained
|
|
in the called file will behave as though it had been defined
|
|
inside that function.
|
|
</simpara>
|
|
<para>
|
|
If the <function>include</function>ed file is called via HTTP
|
|
using the fopen wrappers, and if the target server interprets the
|
|
target file as PHP code, variables may be passed to the
|
|
<function>include</function>ed file using an URL request string as
|
|
used with HTTP GET. This is not strictly speaking the same thing
|
|
as <function>include</function>ing the file and having it inherit
|
|
the parent file's variable scope; the script is actually being run
|
|
on the remote server and the result is then being included into
|
|
the local script.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
/* This example assumes that someserver is configured to parse .php
|
|
* files and not .txt files. Also, 'works' here means that the variables
|
|
* $varone and $vartwo are available within the include()ed file. */
|
|
|
|
/* Won't work; file.txt wasn't handled by someserver. */
|
|
include ("http://someserver/file.txt?varone=1&vartwo=2");
|
|
|
|
/* Won't work; looks for a file named 'file.php?varone=1&vartwo=2'
|
|
* on the local filesystem. */
|
|
include ("file.php?varone=1&vartwo=2");
|
|
|
|
/* Works. */
|
|
include ("http://someserver/file.php?varone=1&vartwo=2");
|
|
|
|
$varone = 1;
|
|
$vartwo = 2;
|
|
include ("file.txt"); /* Works. */
|
|
include ("file.php"); /* Works. */
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<simpara>
|
|
See also <function>require</function>, <function>require_once</function>,
|
|
<function>include_once</function>, <function>readfile</function>,
|
|
and <function>virtual</function>.
|
|
</simpara>
|
|
</sect1>
|
|
|
|
<sect1 id="function.require-once">
|
|
<title><function>require_once</function></title>
|
|
<para>
|
|
The <function>require_once</function> statement replaces
|
|
itself with the specified file, much like the C preprocessor's
|
|
<literal>#include</literal> works, and in that respect is
|
|
similar to the <function>require</function> statement. The main
|
|
difference is that in an inclusion chain, the use of
|
|
<function>require_once</function> will assure that the code is
|
|
added to your script only once, and avoid clashes with variable
|
|
values or function names that can happen.
|
|
</para>
|
|
<para>
|
|
For example, if you create the following 2 include files
|
|
<literal>utils.inc</literal> and <literal>foolib.inc</literal>
|
|
<example>
|
|
<title>utils.inc</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
define("PHPVERSION", floor(phpversion()));
|
|
echo "GLOBALS ARE NICE\n";
|
|
function goodTea()
|
|
{
|
|
return "Oolong tea tastes good!";
|
|
}
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>foolib.inc</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
require ("utils.inc");
|
|
function showVar($var)
|
|
{
|
|
if (PHPVERSION == 4) {
|
|
print_r($var);
|
|
} else {
|
|
var_dump($var);
|
|
}
|
|
}
|
|
|
|
// bunch of other functions ...
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
And then you write a script <literal>cause_error_require.php</literal>
|
|
<example>
|
|
<title>cause_error_require.php</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
require("foolib.inc");
|
|
/* the following will generate an error */
|
|
require("utils.inc");
|
|
$foo = array("1",array("complex","quaternion"));
|
|
echo "this is requiring utils.inc again which is also\n";
|
|
echo "required in foolib.inc\n";
|
|
echo "Running goodTea: ".goodTea()."\n";
|
|
echo "Printing foo: \n";
|
|
showVar($foo);
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
When you try running the latter one, the resulting ouptut will be (using
|
|
PHP 4.01pl2):
|
|
<informalexample>
|
|
<programlisting>
|
|
GLOBALS ARE NICE
|
|
GLOBALS ARE NICE
|
|
|
|
Fatal error: Cannot redeclare goodTea() in utils.inc on line 5
|
|
</programlisting>
|
|
</informalexample>
|
|
By modifying <literal>foolib.inc</literal> and
|
|
<literal>cause_errror_require.php</literal>
|
|
to use <function>require_once</function>
|
|
instead of <function>require</function> and renaming the
|
|
last one to <literal>avoid_error_require_once.php</literal>, we have:
|
|
<example>
|
|
<title>foolib.inc (fixed)</title>
|
|
<programlisting role="php">
|
|
...
|
|
require_once("utils.inc");
|
|
function showVar($var)
|
|
{
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>avoid_error_require_once.php</title>
|
|
<programlisting role="php">
|
|
...
|
|
require_once("foolib.inc");
|
|
require_once("utils.inc");
|
|
$foo = array("1",array("complex","quaternion"));
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
And when running the latter, the output will be (using PHP 4.0.1pl2):
|
|
<informalexample>
|
|
<programlisting>
|
|
GLOBALS ARE NICE
|
|
this is requiring globals.inc again which is also
|
|
required in foolib.inc
|
|
Running goodTea: Oolong tea tastes good!
|
|
Printing foo:
|
|
Array
|
|
(
|
|
[0] => 1
|
|
[1] => Array
|
|
(
|
|
[0] => complex
|
|
[1] => quaternion
|
|
)
|
|
|
|
)
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
Also note that, analogous to the behavior of the
|
|
<literal>#include</literal> of the C preprocessor, this statement
|
|
acts at "compile time", e.g. when the script is parsed and before it
|
|
is executed, and should not be used for parts of the script that need
|
|
to be inserted dynamically during its execution. You should use
|
|
<function>include_once</function> or <function>include</function>
|
|
for that purpose.
|
|
</para>
|
|
<para>
|
|
For more examples on using <function>require_once</function> and
|
|
<function>include_once</function>, look at the PEAR code included in
|
|
the latest PHP source code distributions.
|
|
</para>
|
|
<para>
|
|
See also: <function>require</function>,
|
|
<function>include</function>, <function>include_once</function>,
|
|
<function>get_required_files</function>,
|
|
<function>get_included_files</function>, <function>readfile</function>,
|
|
and <function>virtual</function>.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="function.include-once">
|
|
<title><function>include_once</function></title>
|
|
<para>
|
|
The <function>include_once</function> statement includes and evaluates
|
|
the specified file during the execution of the script.
|
|
This is a behavior similar to the <function>include</function> statement,
|
|
with the important difference that if the code from a file has already
|
|
been included, it will not be included again.
|
|
</para>
|
|
<para>
|
|
As mentioned in the <function>require_once</function> description, the
|
|
<function>include_once</function> should be used in the cases in which
|
|
the same file might be included and evaluated more than once during a
|
|
particular execution of a script, and you want to be sure that it is
|
|
included exactly once to avoid problems with function redefinitions,
|
|
variable value reassignments, etc.
|
|
</para>
|
|
<para>
|
|
For more examples on using <function>require_once</function> and
|
|
<function>include_once</function>, look at the PEAR code included in
|
|
the latest PHP source code distributions.
|
|
</para>
|
|
<para>
|
|
<function>include_once</function> was added in PHP 4.0.1pl2
|
|
</para>
|
|
<para>
|
|
See also: <function>require</function>,
|
|
<function>include</function>, <function>require_once</function>,
|
|
<function>get_required_files</function>,
|
|
<function>get_included_files</function>, <function>readfile</function>,
|
|
and <function>virtual</function>.
|
|
</para>
|
|
</sect1>
|
|
|
|
</chapter>
|
|
|
|
<!-- 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
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../../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
|
|
-->
|