 |
 |
 |
 |
|
|
Date: 08/31/00
- Next message: Luca Perugini: "[PHP-DOC] cvs: phpdoc /it/functions wddx.xml"
- Previous message: Luca Perugini: "[PHP-DOC] cvs: phpdoc /it/language functions.xml"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
perugini Thu Aug 31 15:30:09 2000 EDT
Modified files:
/phpdoc/it/language control-structures.xml
Log:
Sync with en tree.
Index: phpdoc/it/language/control-structures.xml
diff -u phpdoc/it/language/control-structures.xml:1.2 phpdoc/it/language/control-structures.xml:1.3
--- phpdoc/it/language/control-structures.xml:1.2 Wed Mar 1 03:09:01 2000
+++ phpdoc/it/language/control-structures.xml Thu Aug 31 15:30:09 2000
@@ -1,418 +1,424 @@
- <chapter id="control-structures">
- <title>Control Structures</title>
+ <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 <literal>TRUE</literal>, PHP will execute statement, and if it
- evaluates to <literal>FALSE</literal> - 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>
- if ($a > $b)
- print "a is bigger than b";
- </programlisting></informalexample></para>
+ <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>
- <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>
- 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.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 <literal>TRUE</literal>, PHP will execute statement, and if it
+ evaluates to <literal>FALSE</literal> - 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>
+ <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 <literal>FALSE</literal>. 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>
- <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 <literal>FALSE</literal>. 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>
- 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
- <literal>FALSE</literal>, and if there were any <literal>elseif</literal>
- expressions - only if they evaluated to <literal>FALSE</literal>
- as well (see below).</para></sect1>
+ The <literal>else</literal> statement is only executed if the
+ <literal>if</literal> expression evaluated to
+ <literal>FALSE</literal>, and if there were any
+ <literal>elseif</literal> expressions - only if they evaluated to
+ <literal>FALSE</literal> as well (see <link
+ linkend="control-structures.elseif">elseif</link>).
+
+ </para>
+ </sect1>
- <sect1 id="control-structures.elseif">
- <title><literal>elseif</literal></title>
+ <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
+ <literal>FALSE</literal>. However, unlike
+ <literal>else</literal>, it will execute that alternative
+ expression only if the <literal>elseif</literal> conditional
+ expression evaluates to <literal>TRUE</literal>. 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
+ <literal>true</literal> 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
+ <literal>FALSE</literal>, and the current
+ <literal>elseif</literal> expression evaluated to
+ <literal>TRUE</literal>.
+ </simpara>
+ </sect1>
- <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
- <literal>FALSE</literal>. However, unlike <literal>else</literal>,
- it will execute that alternative expression only if the
- <literal>elseif</literal> conditional expression evaluates to
- <literal>TRUE</literal>. 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>
- 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 <literal>true</literal>
- 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 <literal>FALSE</literal>, and the current
- <literal>elseif</literal> expression evaluated to <literal>TRUE</literal>.</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>, 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>, or
- <literal>endswitch;</literal>, respectively.
-
- <informalexample>
- <programlisting>
- <?php if ($a==5): ?>
+ <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>, 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>, 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>
- 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>
+ </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>
- 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.
+ <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
+ <literal>TRUE</literal>. 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
+ <literal>FALSE</literal> 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>
+/* example 1 */
- </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 <literal>TRUE</literal>. 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 <literal>FALSE</literal> from the very beginning, the nested
- statement(s) won't even be run once.</simpara>
+$i = 1;
+while ($i <= 10) {
+ print $i++; /* the printed value would be
+ $i before the increment
+ (post-increment) */
+}
- <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>
+/* example 2 */
- <para>
- The following examples are identical, and both print numbers from
- 1 to 10:
-
- <informalexample>
- <programlisting>
- /* 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 <literal>FALSE</literal> right from the beginning, the loop
- execution would end immediately).</simpara>
-
- <para>
- There is just one syntax for <literal>do..while</literal> loops:
+$i = 1;
+while ($i <= 10):
+ print $i;
+ $i++;
+endwhile;
+ </programlisting>
+ </informalexample>
+ </para>
+ </sect1>
- <informalexample>
- <programlisting>
- $i = 0;
- do {
- print $i;
- } while ($i>0);
- </programlisting>
- </informalexample></para>
+ <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
+ <literal>FALSE</literal> right from the beginning, the loop
+ execution would end immediately).
+ </simpara>
+ <para>
+ There is just one syntax for <literal>do..while</literal> loops:
- <simpara>
+ <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
<literal>FALSE</literal> ($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>
- do {
- if ($i < 5) {
- print "i is not big enough";
- break;
- }
- $i *= $factor;
- if ($i < $minimum_limit) {
- break;
- }
- print "i is ok";
+ 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:
+
+} 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>
- <informalexample>
- <programlisting>
+ <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>
+ </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
+ <literal>TRUE</literal>, the loop continues and the nested
+ statement(s) are executed. If it evaluates to
+ <literal>FALSE</literal>, 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
+ <literal>TRUE</literal>, 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 */
- <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 <literal>TRUE</literal>, the
- loop continues and the nested statement(s) are executed. If it
- evaluates to <literal>FALSE</literal>, 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 <literal>TRUE</literal>, 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>
+for ($i = 1; $i <= 10; $i++) {
+ print $i;
+}
- <para>
- Consider the following examples. All of them display numbers from
- 1 to 10:
+/* example 2 */
+
+for ($i = 1;;$i++) {
+ if ($i > 10) {
+ break;
+ }
+ print $i;
+}
- <informalexample>
- <programlisting>
- /* 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>
+/* example 3 */
- <para>
- PHP also supports the alternate "colon syntax" for
- <literal>for</literal> loops.
+$i = 1;
+for (;;) {
+ if ($i > 10) {
+ break;
+ }
+ print $i;
+ $i++;
+}
- <informalexample>
- <programlisting>
- for (expr1; expr2; expr3): statement; ...; endfor;
- </programlisting>
- </informalexample></para>
+/* 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. PHP3 has no such construct; PHP4 does
@@ -425,10 +431,8 @@
</para>
</sect1>
-
<sect1 id="control-structures.foreach">
<title><literal>foreach</literal></title>
-
<para>
PHP4 (not PHP3) includes a <literal>foreach</literal> construct,
much like perl and some other languages. This simply gives an easy
@@ -441,7 +445,6 @@
</programlisting>
</informalexample>
</para>
-
<simpara>
The first form loops over the array given by
<literal>array_expression</literal>. On each loop, the value of
@@ -449,591 +452,837 @@
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>
-
- <simpara>
- 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.
- </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 like with the each construct.
+ </para>
+ </note>
+ </para>
+ <para>
You may have noticed that the following are functionally
identical:
<informalexample>
- <programlisting>
-reset( $arr );
-while( list( , $value ) = each( $arr ) ) {
- echo "Value: $value<br>\n";
+ <programlisting role="php">
+reset ($arr);
+while (list(, $value) = each ($arr)) {
+ echo "Value: $value<br>\n";
}
-foreach( $arr as $value ) {
- echo "Value: $value<br>\n";
+foreach ($arr as $value) {
+ echo "Value: $value<br>\n";
}
</programlisting>
</informalexample>
The following are also functionally identical:
<informalexample>
- <programlisting>
-reset( $arr );
-while( list( $key, $value ) = each( $arr ) ) {
- echo "Key: $key; Value: $value<br>\n";
+ <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";
+foreach ($arr as $key => $value) {
+ echo "Key: $key; Value: $value<br>\n";
}
</programlisting>
</informalexample>
</para>
-
<para>
Some more examples to demonstrate usages:
<informalexample>
- <programlisting>
+ <programlisting role="php">
/* foreach example 1: value only */
-$a = array(1, 2, 3, 17);
-foreach($a as $v) {
+$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);
+$a = array (1, 2, 3, 17);
+
$i = 0; /* for illustrative purposes only */
foreach($a as $v) {
- print "\$a[$i] => $k.\n";
+ print "\$a[$i] => $k.\n";
}
/* foreach example 3: key and value */
-$a = array(
- "one" => 1,
- "two" => 2,
- "three" => 3,
- "seventeen" => 17
+
+$a = array (
+ "one" => 1,
+ "two" => 2,
+ "three" => 3,
+ "seventeen" => 17
);
foreach($a as $k => $v) {
- print "\$a[$k] => $v.\n";
+ print "\$a[$k] => $v.\n";
}
</programlisting>
</informalexample>
-
</para>
-
</sect1>
-
-
- <sect1 id="control-structures.break">
- <title><literal>break</literal></title>
- <para>
- <literal>break</literal> breaks out of the current looping control-structures.
-
- <informalexample>
- <programlisting>
+ <sect1 id="control-structures.break">
+ <title><literal>break</literal></title>
+ <simpara>
+ <literal>break</literal> ends execution of the current
+ <literal>for</literal>, <literal>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 < 10) {
- if ($arr[$i] == "stop") {
- break;
- }
- $i++;
+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>
-
- <para>
- <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.
-
- <informalexample>
- <programlisting>
- while (list($key,$value) = each($arr)) {
- if (!($key % 2)) { // skip even members
- continue;
- }
- do_something_odd ($value);
- }
- </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>
- 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>
+ </programlisting>
+ </informalexample>
+ </para>
+ </sect1>
- <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>
- 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).
+ <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>
- 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.
+ <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);
+}
- <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>
- 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>
+$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>
- <para>
- A special case is the default case. This case matches anything
- that wasn't matched by the other cases. For example:
+ <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";
+}
- <informalexample>
- <programlisting>
- 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>
+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>
- 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>
+ 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 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>
+ 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. 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>
-
+ 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="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.
+ The <function>require</function> statement replaces itself with
+ the specified file, much like the C preprocessor's
+ <literal>#include</literal> works.
</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>.
+ 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>
- <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.
+ 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>
- 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.
+ <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>
- 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.
+ 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>
-require( 'header.inc' );
- </programlisting>
- </informalexample>
+ 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>
- Please note that both <function>include</function> and
- <function>require</function> actually pull the contents of the
- target file into the calling script file itself; they do not call
- the target via HTTP or anything like that. So any variable set in
- the scope in which the inclusion happens will be available within
- the included file automatically, since it has effectively become a
- part of the calling file.
- <informalexample>
- <programlisting>
-require( "file.inc?varone=1&vartwo=2" ); /* Won't work. */
+ 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.inc" ); /* $varone and $vartwo will be available in file.inc */
- </programlisting>
- </informalexample>
+require ("file.txt"); /* Works. */
+require ("file.php"); /* Works. */
+ </programlisting>
+ </informalexample>
</para>
-
<simpara>
- Don't be misled by the fact that you can require or include files
- via HTTP using the <link linkend="features.remote-files">Remote
- files</link> feature; the above holds true regardless.
+ In PHP3, 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 PHP4, however, this ability
+ has been discontinued. If you need this functionality, see
+ <function>include</function>.
</simpara>
-
<simpara>
- In PHP3, 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 PHP4, however, this ability
- has been discontinued. If you need this functionality, see
- <function>include</function>.
+ 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.
+ The <function>include</function> statement includes and evaluates
+ the specified file.
</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>.
+ 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>
-
- <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>
+ <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++) {
+for ($i = 0; $i < count($files); $i++) {
include $files[$i];
}
- </programlisting>
- </informalexample>
+ </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).
+ <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>
- /* This is WRONG and will not work as desired. */
+ 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>
+if ($condition)
+ include($file);
+else
+ include($other);
+
+/* This is CORRECT. */
+
+if ($condition) {
+ include($file);
+} else {
+ include($other);
+}
+ </programlisting>
+ </informalexample>
</para>
-
<simpara>
- In both PHP3 and PHP4, 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 PHP3, 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 PHP4, however, this restriction does not
- exist. Also, PHP4 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 PHP3.
+ In both PHP3 and PHP4, 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 PHP3, 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 PHP4, however, this restriction does not
+ exist. Also, PHP4 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 PHP3.
</simpara>
-
<example>
- <title><function>include</function> in PHP3 and PHP4</title>
- <para>
- Assume the existence of the following file (named
- <filename>test.inc</filename>) in the same directory as the main
- file:
- <programlisting>
-<?php
+ <title><function>include</function> in PHP3 and PHP4</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;
+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>
-<?php
-$retval = include( 'test.inc' );
+ </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 PHP3, it will
- generate a parse error on line 2; you can't take the value of an
- <function>include</function> in PHP3. In PHP4, however, the
- result will be:
- <screen>
+ </programlisting>
+ </para>
+ <para>
+ When <filename>main.html</filename> is called in PHP3, it will
+ generate a parse error on line 2; you can't take the value of an
+ <function>include</function> in PHP3. In PHP4, 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>
-<?php
-include( 'test.inc' );
+ </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 PHP4, the output will be:
- <screen>
+ </programlisting>
+ </para>
+ <para>
+ In PHP4, the output will be:
+ <screen>
Before the return
Back in main.html
- </screen>
- However, PHP3 will give the following output:
- <screen>
+ </screen>
+ However, PHP3 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>
+ </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 PHP3 does not support
- <literal>return</literal>ing values from files like that.
- </para>
-
+ </screen>
+ </para>
+ <para>
+ The spurious '27' is due to the fact that PHP3 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>
- Please note that both <function>include</function> and
- <function>require</function> actually pull the contents of the
- target file into the calling script file itself; they do not call
- the target via HTTP or anything like that. So any variable set in
- the scope in which the inclusion happens will be available within
- the included file automatically, since it has effectively become a
- part of the calling file.
- <informalexample>
- <programlisting>
-include( "file.inc?varone=1&vartwo=2" ); /* Won't work. */
+ 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.inc" ); /* $varone and $vartwo will be available in file.inc */
-
- </programlisting>
- </informalexample>
-
+include ("file.txt"); /* Works. */
+include ("file.php"); /* Works. */
+ </programlisting>
+ </informalexample>
</para>
-
<simpara>
- Don't be misled by the fact that you can require or include files
- via HTTP using the <link linkend="features.remote-files">Remote
- files</link> feature; the above holds true regardless.
+ 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 {
+ dump_var($var);
+ }
+}
- <simpara>
- See also <function>readfile</function>,
- <function>require</function>, and <function>virtual</function>.
- </simpara>
+// 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>