<?xml version="1.0" encoding="big5"?>
 <chapter id="control-structures">
  <title>{y{</title>

  <simpara>
  PHP {OѤ@yyyyҺcC yyiHܼƪȡB եΨơB jB y{Ʀܤ](ťջyy)C @yyyq`H ';' @C QΪA '{ }'iHnhyyզ@աA o˲զyեۤv]O@yyyC `|ЦUU˪yyC 
  </simpara>

  <sect1 id="control-structures.if">
   <title><literal>if</literal></title>
   <para>
if O{y䭫nզA  PHP ]ҥ~C ѤFݭn椣P{q\C PHP ҥΪ if cM C ҥΪS򤣦PG 

    <informalexample>
     <programlisting>
if (expr)
    statement
     </programlisting>
    </informalexample>
   </para>
   <simpara>
if O{y䭫nզA  PHP ]ҥ~C ѤFݭn椣P{q\C PHP ҥΪ if cM C ҥΪS򤣦PG 

   </simpara>
   <para>
HUdҷ|X a is bigger than b pG $a Ȥ $bj: 

    <informalexample>
     <programlisting role="php">
if ($a > $b)
    print "a is bigger than b";
     </programlisting>
    </informalexample>
   </para>
   <para>
q`bMwFAinhL@yOA MACӫOeΤ@ if A Auݭnoǭn檺O '{ }' զyմNFC nHU{q|ܥX a is bigger than b pG $a  $b jA Pɷ| $a ȧۨ $b: 

    <informalexample>
     <programlisting role="php">
if ($a > $b) {
    print "a is bigger than b";
    $b = $a;
}
     </programlisting>
    </informalexample>
   </para>
   <simpara>
If iHbO if X{A o˪p٬_ ifA PHP \Lh_cC pAbs{ܤjۥѫרӱ{y{C 

   </simpara>
  </sect1>
 
  <sect1 id="control-structures.else">
   <title><literal>else</literal></title>
   <para>
ɭԧA|իOA @զb󦨥߮ɰA t@զb󤣦߮ɰC oɥ else NKܦhFC else ɥR if \G pG if yyF߮ɡA if |򪺫OաA ӷ| else ᪺OաC U{|X a is bigger than b pG $a jL $bA ϤhX a is NOT bigger than b : 

    <informalexample>
     <programlisting role="php">
if ($a > $b) {
    print "a is bigger than b";
} else {
    print "a is NOT bigger than b";
}
     </programlisting>
    </informalexample>

else Oեu if Ft⪺GOɭԤ~|QCpG٦O elseif FܡA oǪFG]nO~C(ݤU) 
   </para>
  </sect1>
 
  <sect1 id="control-structures.elseif">
   <title><literal>elseif</literal></title>
   <para>
elseifA @ݴNDOif M elseVXC Like else@ˡA ɥRF if yy\G b if 󤣦߮ɤ~|CM else@˪OA elseif FnD if 󤣦ߡA PɭnDۤv󦨥ߡA_h|۪{qC UCܽd $aB$b jpX a is bigger than b a equal to b  a is smaller than b: 

    <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>
iHnX elseifX{bP@ if yyC Ĥ@Ӧߪ elseif |QC sg PHP {ɧA]iHΨӦr 'else if' A oMr 'elseif' OۦPC M̦bykWPAҦ\MGOSOC (pAx C ܡA oM C pO@ˡC) 

   </simpara>
   <simpara>
A@A elseif Oեue if ML elseif 󤣦ߨåBۤv󦨥߮ɤ~|QC 

   </simpara>
  </sect1>
 
  <sect1 id="control-structures.alternative-syntax">
   <title>ĥyk</title>
   <para>
PHP HUyѤFt~@ؼgkAoǻyy]AGifB whileB forB switchC ĪgkNOOն}Y '{' Aܦ_ ':'G Pɵ '}' Oܦ endif; endwhile; endfor; endswitch;C 

    <informalexample>
     <programlisting role="php">
 &lt;?php if ($a == 5): ?&gt;
 A is equal to 5
 &lt;?php endif; ?&gt;
     </programlisting>
    </informalexample>
   </para>
   <simpara>
bWzܽdA HTML 榡yl "A is equal to 5" Q]b@ if yyC opUu $a O 5 ɸӥyl~QLXӡC 

   </simpara>
   <para>
   Īyk]iΦb elseM elseif WCUNO if [W elseif M else ļgkC 

    <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>
tЬ  <link linkend="control-structures.while">while</link>,
    <link linkend="control-structures.for">for</link>,  <link
    linkend="control-structures.if">if</link> LܽdC 
   </para>
  </sect1>

  <sect1 id="control-structures.while">
   <title><literal>while</literal></title>
   <para>
while jO PHP س²檺jΦC M c  while @ˡA 򥻪yOG     <informalexample>
     <programlisting>
while (expr) statement
     </programlisting>
    </informalexample>
   </para>
   <simpara>
while NܪG unFߡA |s PHP a while OC ]C while O᳣|ˬd@ while O_̵MߡA ҥHNbOɤwgܡA nҦO~|XjC(C槹j餤ҦOsF@`) p while Fb@}lɭԴNߡA while Oڥ|Q (s`)C 

   </simpara>
   <para>
M if @ˡA AiHnhO '{ }' ]_өbwhile j餧C A]iH while ĥykӼg: 

    <informalexample>
     <programlisting>
while (expr): statement ... endwhile;
     </programlisting>
    </informalexample>
   </para>
   <para>
UӥܽdNͬۦPGG  1  10 LX    <informalexample>
     <programlisting>
/* example 1 */

$i = 1;
while ($i &lt;= 10) {
    print $i++;  /* the printed value would be
                    $i before the increment
                    (post-increment) */
}
 
/* example 2 */
 
$i = 1;
while ($i &lt;= 10):
    print $i;
    $i++;
endwhile;
     </programlisting>
    </informalexample>
   </para>
  </sect1>
 
  <sect1 id="control-structures.do.while">
   <title><literal>j</literal></title>
   <simpara>
do.while j M while jthA̫~ˬdO_ߡC o˫OҤF do.while O_X|Q@C ѩ while Ob@}YKˬdA ҥH while ܥi@`]椣FC 

   </simpara>
   <para>
do.while j u@ӥykA SOļgk : 
 
    <informalexample>
     <programlisting role="php">
$i = 0;
do {
   print $i;
} while ($i>0);
     </programlisting>
    </informalexample>
   </para>
   <simpara>
W{u|]@A ]O槹F~ˬd~o{ӱ󤣦ߩOXjC 
   </simpara>
   <para>
 C s{iot@ do.while j ΪkG   <link
    linkend="control-structures.break"><literal>break</literal></link>
OM do.while(0) jӨϵ{b椤~פCUC{qܽdo@ӥΪk: 
    <informalexample>
     <programlisting role="php">
do {
    if ($i &lt; 5) {
        print "i is not big enough";
        break;
    }
    $i *= $factor;
    if ($i &lt; $minimum_limit) {
        break;
    }
    print "i is ok";

     ...process i...

} while(0);
     </programlisting>
    </informalexample>
   </para>
   <simpara>
aϧAݤXW{]SYC N⤣ do.while oӯSʤ]@˥iHgX\ܱj{C 
   </simpara>
  </sect1>
 
  <sect1 id="control-structures.for">
   <title><literal>for j</literal></title>
   <para>
for j iO PHP ̽jC̪ΪkMb C ΪkèSO: 

    <informalexample>
     <programlisting>
for (expr1; expr2; expr3) statement
     </programlisting>
    </informalexample>
   </para>
   <simpara>
Ĥ@ӪF (expr1) Lצp󳣷|t@    </simpara>
   <simpara>
MbCӴ`}le expr2 |QXӡA pGoXGߪܡA j餤OKQA pG expr2 ߪܡA K|XjC 
   </simpara>
   <simpara>
C@Ӵ`q|t@ expr3C    </simpara>
   <simpara>
   TӪF@ӳiHOŪC expr2 ŪܥNj|LҦaUhC (PHP M C @ˡA ۰ʧŪFOߪ) oťWhܵLA ڤWAiQbj餤
<link
    linkend="control-structures.break"><literal>break</literal></link>
    覡ӵC    </simpara>
   <para>
HUC@ӨҤl| 1  10:     <informalexample>
     <programlisting role="php">
/* example 1 */
 
for ($i = 1; $i &lt;= 10; $i++) {
    print $i;
}
 
/* example 2 */
 
for ($i = 1;;$i++) {
    if ($i &gt; 10) {
        break;
    }
    print $i;
}
 
/* example 3 */
 
$i = 1;
for (;;) {
    if ($i &gt; 10) {
        break;
    }
    print $i;
    $i++;
}
 
/* example 4 */
 
for ($i = 1; $i &lt;= 10; print $i, $i++) ;
     </programlisting>
    </informalexample>
   </para>
   <simpara>
MA bWܽdݰ_ӥuĤ@ (]\]H߷Rĥ|ӨҤl) ̥WA LɭԦb for j ΪŪFiHOsg{ܫܤKC 

   </simpara>
   <para>
for j ]t@ؼgkC     <informalexample>
     <programlisting>
for (expr1; expr2; expr3): statement; ...; endfor;
     </programlisting>
     </informalexample>
   </para>
   <para>
{yӥs foreach ROӦs}CMƪC PHP3 So˫O PHP4 C (Ь
<link
    linkend="control-structures.foreach">foreach</link>)C PHP3 ɡAAnPɥ 
<link linkend="control-structures.while">while</link> M<function>list</function> H <function>each</function>
Ƥ~৹ۦPu@C QD򰵪ܽЬݦoǨƪ`C 

   </para>

  </sect1>
  <sect1 id="control-structures.foreach">
   <title><literal>foreach</literal></title>
   <para>
PHP4 (PHP3 èS) [JF foreach \Co\b PERL MLyC ΥiHܤKas}CC XkyӡG ĤGӥuOĤ@ӥyk@F@IʦܦΡCpUG 

    <informalexample>
     <programlisting>
foreach(array_expression as $value) statement
foreach(array_expression as $key =&gt; $value) statement
     </programlisting>
    </informalexample>
   </para>
   <simpara>
Ĥ@ӥyC`|}C array_expression @ӤȦsܼ $value }CҦΧFC 
   </simpara>
   <simpara>
ĤGӥyMĤ@ӮthA Ob󰣤F $value |xsFȡA $key ٷ|xsFثe޸C 
   </simpara>
   <para>
    <note>
     <para>
	   foreach }lɤm}Cз|V}CӤmC oNAbC foreach eե
      <function>reset</function> ơC 
	 </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>
    bUdҡA AiݥX̥\O@˪:     <informalexample>
     <programlisting role="php">
reset ($arr);
while (list(, $value) = each ($arr)) {
    echo "Value: $value&lt;br&gt;\n";
}

foreach ($arr as $value) {
    echo "Value: $value&lt;br&gt;\n";
}
     </programlisting>
    </informalexample>
    UdҤ]O@˥\઺: 
    <informalexample>
     <programlisting role="php">
reset ($arr);
while (list($key, $value) = each ($arr)) {
    echo "Key: $key; Value: $value&lt;br&gt;\n";
}

foreach ($arr as $key =&gt; $value) {
    echo "Key: $key; Value: $value&lt;br&gt;\n";
}
     </programlisting>
    </informalexample>
   </para>
   <para>
hܽd: 
    <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] =&gt; $v.\n";
}

/* foreach example 3: key and value */

$a = array (
    "one" =&gt; 1,
    "two" =&gt; 2,
    "three" =&gt; 3,
    "seventeen" =&gt; 17
);

foreach($a as $k =&gt; $v) {
    print "\$a[$k] =&gt; $v.\n";
}
     </programlisting>
    </informalexample>
   </para>
  </sect1>
 
  <sect1 id="control-structures.break">
   <title><literal>break</literal></title>
   <simpara>
break OΨӸUCjαy G if B for B whileBswitch C 

   </simpara>
   <simpara>
 break ɥiH[W@ӰѼƧiDqnhּhjC    </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&lt;br&gt;\n";
}

/* Using the optional argument. */

$i = 0;
while (++$i) {
    switch ($i) {
    case 5:
        echo "At 5&lt;br&gt;\n";
        break 1;  /* Exit only the switch. */
    case 10:
        echo "At 10; quitting&lt;br&gt;\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>
continue bj餤@άO߮ɸ{ɰ椤`Ӷ}lU@Ӵ`C 

   </simpara>
   <simpara>
    continue M break @˥iΤ@ӰѼƫܥӱq@hj}lU@`C    </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++ &lt; 5) {
    echo "Outer&lt;br&gt;\n";
    while (1) {
        echo "&nbsp;&nbsp;Middle&lt;br&gt;\n";
        while (1) {
            echo "&nbsp;&nbsp;Inner&lt;br&gt;\n";
            continue 3;
        }
        echo "This never gets output.&lt;br&gt;\n";
    }
    echo "Neither does this.&lt;br&gt;\n";
}
     </programlisting>
     </informalexample>
    </para>
  </sect1>
 
  <sect1 id="control-structures.switch">
   <title><literal>switch</literal></title>
   <simpara>
   switch RO\M@sΦP@F if yyۦC ֪pnD@ܼƩΤ@yFMPƭȧ@A Y@ӼƭȮɫK۹{qC oO switch \ΡC 

   </simpara> 
   <para>
UܽdF˥Τ@sꪺ if MΤ@ switch ӧۦPu@G     <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>
FקK˿A̦nOd switch B@覡C switch O@y@y{C  PHP n@case ȩM switch FҺtXӪȬO@˪C M PHP |b case X{ҦO switch {q̫Ϊ̪ PHP I@y break OC pGASbC case ̫[W break OA PHP |Uh汵bUt@ case OI U{ܽdFo@IG 

    <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>
W{ӨA pG $i O 0 ܡA PHP |Ҧ print OI pG $i O 1A PHP u|᭱yOF u $i  2 ~|o쥻ӷQnGGLX 'i equals 2' C ѦiA UOn|F break ObC case C (Mb@DZpUAiSa[ breakC) 

   </simpara>
   <simpara>
{ switch ɡA Fu|Qˬd@C o@B⵲G|ΨөMC case F b elseif yyӱF|sQt@MC ]bFܽάObt׭nDܰj餤 switch |֤@ǡC 

   </simpara>
   <para>
@ case ҧtOƥؤ]iHO 0 ӡA oˤ@ӵ{|۰ˬdU@ 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>
ӯS case O default caseA pGҦ case Sk߮ɡA default K|QC ݤUܽd: 

    <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>
   Ī case F@wnoX@²檺ƭȡA pơB pƩάOyC pGO}CܴN@wnX}C@ӤøӤ]nO@²檺ȡC 
   </para>
   <para>
    swithes ]̥t@صĪgkA Աi <link
    linkend="control-structures.alternative-syntax">{y{ĥyk </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="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&amp;vartwo=2");

/* Won't work; looks for a file named 'file.php?varone=1&amp;vartwo=2'
 * on the local filesystem. */
require ("file.php?varone=1&amp;vartwo=2");               

/* Works. */
require ("http://someserver/file.php?varone=1&amp;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 &lt; 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">
&lt;?php
echo "Before the return &lt;br&gt;\n";
if (1) {
    return 27;
}
echo "After the return &lt;br&gt;\n";
?&gt;
     </programlisting>
    </para>
    <para>
     Assume that the main file (<filename>main.html</filename>)
     contains the following:
     <programlisting role="php">
&lt;?php
$retval = include ('test.inc');
echo "File returned: '$retval'&lt;br&gt;\n";
?&gt;
     </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">
&lt;?php
include ('test.inc');
echo "Back in main.html&lt;br&gt;\n";
?&gt;
     </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&amp;vartwo=2");

/* Won't work; looks for a file named 'file.php?varone=1&amp;vartwo=2'
 * on the local filesystem. */
include ("file.php?varone=1&amp;vartwo=2");               

/* Works. */
include ("http://someserver/file.php?varone=1&amp;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">
&lt;?php
define(PHPVERSION, floor(phpversion()));
echo "GLOBALS ARE NICE\n";
function goodTea() {
	return "Oolong tea tastes good!";
}
?&gt;
	 </programlisting>
	 </example>
	 <example>
	 <title>foolib.inc</title>
	 <programlisting role="php">
&lt;?php
require ("utils.inc");
function showVar($var) {
	if (PHPVERSION == 4) {
		print_r($var);
	} else {
		var_dump($var);
	}
}

// bunch of other functions ...
?&gt;
	 </programlisting>
	 </example>
	 And then you write a script <literal>cause_error_require.php</literal>
	 <example>
	 <title>cause_error_require.php</title>
	 <programlisting role="php">
&lt;?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);
?&gt;
	 </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] =&gt; 1
    [1] =&gt; Array
        (
            [0] =&gt; complex
            [1] =&gt; 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
indent-tabs-mode:nil
 sgml-parent-document:nil
 sgml-default-dtd-file:"../../manual.ced"
 sgml-exposed-tags:nil
 sgml-local-catalogs:nil
 sgml-local-ecat-files:nil
 End:
 -->
<!-- Keep this comment for vi/vim/gvim
     vi: et:ts=1:sw=1
-->