cvs: phpdoc-ar /language control-structures.xml

Index: phpdoc-ar/language/control-structures.xml
+++ phpdoc-ar/language/control-structures.xml
<?xml version="1.0" encoding="ISO-8859-6"?>
<!-- $Revision: 1.1 $ -->
<!-- EN-Revision: 1.83 Maintainer: hafid Status: working -->
 <chapter id="control-structures">
  <title>Control Structures</title>

  <simpara>
   êÊÃäá Ãê ÎÇ×è× PHP åæ åÌåèÙÉ åæ ÇäÈäÇÚÇÊ. ÇäÈäÇÚ 
   êåãæ Ãæ êãèæ ÊÙêêæÇë¬ æÏÇÁ ÏÇäɬ Íäâɬ ÈäÇÚÇ 
   ÔÑ×êñÇ Ãè ÍÊé ÈäÇÚÇ äÇ êâèå ÈÃêñ ÔêÁ (ÈäÇÚ 
   áÇÑÚ). ÚÇÏÉ åÇ ÊæÊçê ÇäÈäÇÚÇÊ ÈáÇÕäÉ åæâè×É. ãÐä㬠
   áÅæñîç êåãæ ÊÌåêÙ ÇäÈäÇÚÇÊ Öåæ åÌåèÙÉ ÈäÇÚêñîÉ åæ ÎäÇä ÊÚäêá 
   åÌåèÙÉ ÈäÇÚÇÊ ÈÍÇÖæÊêæ åÙâèáÊêæ  ("<literal>{}</literal>"). åÌåèÙÉ ÈäÇÚêñîÉ ÊïÙÊÈÑ 
   áê ÍÏ ÐÇÊçÇ ÈäÇÚÇë ÃêÖÇ. Åæñî åÎÊäá ÃæèÇÙ ÇäÈäÇÚÇÊ çê åÍä 
   èÕá áê çÐÇ ÇäáÕä. 
  </simpara>

  <sect1 id="control-structures.if">
   <title><literal>if</literal></title>
   <para>
    ÈæÇÁ <literal>if</literal> çè ÃÍÏ Ãçå 
    åêÒÇÊ ÙÏÉ äÚÇʬ ÈåÇ áê Ðäã PHP. êÓåÍ 
    ÈÇäÊñîæáêÐ ÇäÔñîÑ×êñ äåâÇ×Ù åæ ÇäÔñðêáÑÉ. ÊÊåêÒ PHP 
    ÈÈæêÉ <literal>if</literal> ÔÈêçÉ äÊäã Èà C:
    <informalexample>
     <programlisting>
<![CDATA[
if (expr)
    statement
]]>
     </programlisting>
    </informalexample>
   </para>
   <simpara>
    åËäåÇ Êå èÕáç áê <link linkend="language.expressions">ÇäáÕä ÇäåïÊÙäñðâ 
    ÈÇäÙÈÇÑÇÊ</link>¬ áÅæñî <replaceable>expr</replaceable> Êïâêñîå 
    ÈâêåÊçÇ Çäåæ×âêñîÉ. ÅÐÇ âïêñðåîÊ <replaceable>expr</replaceable> Èà &true;¬ 
   áÅæñî PHP ÊïæáñðÐ <replaceable>ÇäÈäÇÚ</replaceable> èÅÐÇ âïêñðåîÊ 
    Èà &false; - áÅæñîçÇ ÓÊÊÌÇçäçÇ. êåãæ ÅêÌÇÏ ÇäåÒêÏ åæ ÇäåÙäèåÇÊ ÈÎÕèÕ Çäâêå ÇäÊñðê Êïâêñîå 
    Èà &false; áê ÇäáâÑÉ <link
    linkend="language.types.boolean.casting">'ÇäÊñîÍèêä Åäé åæ×âêÉ'</link>
    .
   </simpara>
   <para>
    ÇäåËÇä ÇäËñîÇäêñ ÓêïØçðÑ <computeroutput>à ÃãÈÑ 
    åæ È</computeroutput> ÅÐÇ ãÇæÊ <replaceable>$a</replaceable> ÃãÈÑ 
    åæ <replaceable>$b</replaceable>:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
if ($a > $b)
    print "à ÃãÈÑ åæ È";
?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    ÚÇäÈÇ åÇ ÊÑÚÈ áê Ãæ êãèæ äÏêã ÃãËÑ åæ ÈäÇÚ èÇÍÏ êÊå ÊæáêÐç 
    ÔÑ×êÇë. ÈÇä×ñîÈÙ¬ äêÓÊ çæÇã åæ ÍÇÌÉ ääáñ ãäñ ÈäÇÚ 
    ÈáâÑÉ <literal>if</literal>. ÈÏäÇ åæ Ðä㬠êåãæã ÊÌåêÙ 
    ÙÏÉ ÈäÇÚÇÊ áê åÌåèÙÉ ÈäÇÚêñîÉ èÇÍÏÉ. Ùäé Óêä ÇäåËÇä¬ çÐç ÇäÔñðêáÑÉ 
    ÓÊïØçðÑ <computeroutput>à ÃãÈÑ åæ È</computeroutput>
    ÅÐÇ ãÇæÊ <replaceable>$a</replaceable> ÃãÈÑ åæ 
    <replaceable>$b</replaceable> èÍêæçÇ ÓÊïÙêñðæ âêåÉ 
    <replaceable>$a</replaceable> äÏé <replaceable>$b</replaceable>:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
if ($a > $b) {
    print "à ÃãÈÑ åæ È";
    $b = $a;
}
?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <simpara>
    êåãæ ÊÔÈêã ÈäÇÚÇÊ <literal>If</literal> èÈÕèÑÉ ÚêÑ åïæÊçðêñîÉ Öåæ 
    ÈäÇÚÇÊ <literal>if</literal> ÃÎÑé  ååÇ êïÒèñðÏïã ÈåÑèæÉ 
    ÊÇåÉ ÈÚÑÖ ÇäÊñîæáêÐ ÇäÔñîÑ×êñ äåÎÊäá ÃÌÒÇÁ 
    ÈÑæÇåÌã. 
   </simpara>
  </sect1>

  <sect1 id="control-structures.else">
   <title><literal>else</literal></title>
   <para>
    ÚÇäÈÇë åÇ ÊÑÚÈ áê ÊæáêÐ ÈäÇÚ åÇ ÅÐÇ åÇ ÊåÊ åïÕÇÏáÉ ÔÑ× åïÍÏñîÏ 
    èÈäÇÚ åÚÇêÑ Åæ äå ÊÊå åïÕÇÏáÉ ÇäÔñîÑ×. äçÐÇ 
    èïÌðÏîÊ <literal>else</literal>. ÊïèÓñðÙï <literal>else</literal>
    ÈäÇÚî <literal>if</literal> ÈÚÑÖ ÊæáêÐ ÈäÇÚ 
    áê ÍÇäÉ âïêñðåîÊ ÇäÙÈÇÑÉ áê ÈäÇÚ <literal>if</literal> 
    Èà &false;. Ùäé ÓÈêä ÇäåËÇä¬ ÇäÔñðêáÑÉ 
    ÇäÊñîÇäêñîÉ ÊïØòçðÑ <computeroutput>à ÃãÈÑ åæ 
    È</computeroutput> ÅÐÇ ãÇæÊ <replaceable>$a</replaceable> ÃãÈÑ åæ 
    <replaceable>$b</replaceable> è <computeroutput>à äêÓÊ ÃãÈÑ 
    åæ È</computeroutput> áêåÇ ÙÏÇ Ðäã: 
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
if ($a > $b) {
    print "à ÃãÈÑ åæ È";
} else {
    print "à äêÓÊ ÃãÈÑ åæ È";
}
?>
]]>
     </programlisting>
    </informalexample>

    êïæáñîÐï ÈäÇÚï <literal>else</literal> áâ× ÅÐÇ 
    âïêñðåîÊ ÙÈÇÑÉ <literal>if</literal> Èà 
    &false; èÅÐÇ äå Êãïæ çæÇã ÃêñîÉ 
    ÙÈÇÑÇÊ <literal>elseif</literal> - áâ× ÅÐÇ âïêñðåîÊ Èà 
    &false; ãÐäã (ÇÓÊÙÑÖ <link
    linkend="control-structures.elseif">elseif</link>).

   </para>
  </sect1>

  <sect1 id="control-structures.elseif">
   <title><literal>elseif</literal></title>
   <para>
    <literal>elseif</literal>¬ åËäåÇ êèÍê ÅÓåçǬ çê ÊÑãêÈÉ 
    åæ <literal>if</literal> è <literal>else</literal>. åËä 
    <literal>else</literal>¬ çê ÊïèÓñðÙ ÈäÇÚî <literal>if</literal>
    ÈÚÑÖ ÊæáêÐ ÈäÇÚ åÚÇêÑ áê ÍÇäÉ ÅÐÇ åÇ âïêñðåîÊ ÙÈÇÑÉ 
    <literal>if</literal> ÇäÃÕäêñîÉ Èà 
    &false;. åÙ Ðä㬠èÈÙãÓ 
    <literal>else</literal>¬ áÅæñîçÇ ÊïæáñðÐ Êäã ÇäÙÈÇÑÉ 
    ÇäÈÏêäÉ áâ× ÅÐÇ åÇ âïêñðåîÊ ÇäÙÈÇÑÉ ÇäÔñîÑ×êñîÉ <literal>elseif</literal> 
    Èà &true;. Ùäé ÓÈêä ÇäåËÇä¬ 
    ÊïØçðÑï ÇäÔñðêáÑÉ ÇäÊñîÇäêñîÉ <computeroutput>à ÃãÈÑ åæ 
    È</computeroutput>¬ <computeroutput>Ã êÓÇèê È</computeroutput>
    Ãè <computeroutput>Ã ÃÕÚÑ åæ È</computeroutput>:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
if ($a > $b) {
    print "à ÃãÈÑ åæ È";
} elseif ($a == $b) {
    print "Ã êÓÇèê È";
} else {
    print "Ã ÃÕÚÑ åæ È";
}
?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <simpara>
    êåãæ Ãæ ÊÊèÇÌÏ ÙÏÉ <literal>elseif</literal> Öåæ ÈäÇÚ 
    <literal>if</literal> æáÓç. ÙÈÇÑÉ 
    <literal>elseif</literal> ÇäÃèäé (Åæ èïÌðÏîÊ) ÇäÊñðê Êïâêñîå Èà 
    &true; ÓÊïæîáñîÐ. áê PHP¬ êåãæã ÃêÖÇ 
    ãÊÇÈÉ 'else if' (áê ãäåÊêæ) èÇäÓñïäèã Óêãèæ åïåÇËðäÇë 
    äÓïäèã 'elseif' (áê ãäåÉ èÇÍÏÉ). êÎÊäá ÇäåÙæé ÇäæñîÍèêñ 
    ÈÙÖ ÇäÔêÁ (ÅÐÇ ãïæÊ åïÊÙèñðÏÇë Ùäé C¬ áÅæñî ÇäÃåÑ êÊÙäâ ÈæáÓ 
    ÇäÓñïäèã) äãæ ÇäÃÓÇÓ êãåæ áê Ãæñî ãäÇçåÇ êÄÏêÇæ ÊåÇåÇë Åäé 
    æáÓ ÇäÓñïäèã. 
   </simpara>
   <simpara>
    êïæáñîÐï ÈäÇÚ <literal>elseif</literal> áâ× ÅÐÇ âïêñðåîÊ 
    ÙÈÇÑÉ <literal>if</literal> ÇäÓñîÇÈâÉ èÃêñîÉ 
    ÙÈÇÑÇÊ <literal>elseif</literal> ÓÇÈâÉ Èà 
    &false; èâïêñðåîÊ ÙÈÇÑÉ 
    <literal>elseif</literal> ÇäÍÇäêñîÉ Èà 
    &true;.
   </simpara>
  </sect1>

  <sect1 id="control-structures.alternative-syntax">
   <title>ÇäÕñðêÚÉ ÇäæñîÍèêñîÉ ÇäÈÏêäÉ ÇäÎÇÕÉ ÈÈæé ÇäÊñîÍãñïå</title>
   <para>
    ÊèáñðÑï PHP ÕêÚÉ æÍèêñîÉ ÈÏêäÉ äÈÙÖ åæ ÈïæîÇçÇ 
    ÇäÊñîÍãñïåêñîÉ» Ãê <literal>if</literal>¬
    <literal>while</literal>¬ <literal>for</literal>¬
    <literal>foreach</literal> è <literal>switch</literal>.
    áê ãäñ ÇäÍÇäÇʬ áÅæñî ÇäÔñîãä ÇäâÇÙÏêñ ääÕêÚÉ ÇäæñîÍèêñîÉ ÇäÈÏêäÉ êÊåËä áê ÇÓÊÈÏÇä 
    ÍÇÖæÉ ÇäÅáÊÊÇÍ Èæâ×Êêæ (:) èÍÇÖæÉ ÇäÅÚäÇâ Èà 
    <literal>endif;</literal>¬ <literal>endwhile;</literal>¬
    <literal>endfor;</literal>¬ <literal>endforeach;</literal> Ãè 
    <literal>endswitch;</literal>¬ Ùäé ÇäÊñîèÇäê. 
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php if ($a == 5): ?>
à êÓÇèê 5
<?php endif; ?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <simpara>
    áê ÇäåËÇä ÇäÙäèêñ¬ ÔïÈñðãî åâ×Ù HTML "à êÓÇèê 5" ÈÏÇÎä 
    ÈäÇÚ <literal>if</literal> ãïÊðÈî ÈÇäÕñðêÚÉ ÇäæñîÍèêñîÉ ÇäÈÏêäÉ. èêÊå ÅØçÇÑ 
    åâ×Ù HTML áâ× ÅÐÇ ãÇæ $a êïÓÇèê 5.
   </simpara>
   <para>
    Êæ×Èðâï ÇäÕñðêÚÉ ÇäæñîÍèêñîÉ ÇäÈÏêäÉ Ùäé <literal>else</literal> è
    <literal>elseif</literal> ãÐäã. åÇ êäê êïåËñðäï 
    ÈæêÉ <literal>if</literal> åïÑáîâîÉ Èà <literal>elseif</literal> è
    <literal>else</literal> ÈÍÓÈ ÇäÊñîæÓêâ ÇäÈÏêä: 
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
if ($a == 5):
    print "Ã êÓÇèê 5";
    print "...";
elseif ($a == 6):
    print "Ã êÓÇèê 6";
    print "!!!";
else:
    print "à äêÓ äÇ 5 èäÇ 6";
endif;
?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    ÇÓÊÙÑÖ ÃêÖÇ <link linkend="control-structures.while">while</link>¬
    <link linkend="control-structures.for">for</link> è <link
    linkend="control-structures.if">if</link> ääÍÕèä Ùäé ÃåËäÉ ÃãËÑ. 
   </para>
  </sect1>

  <sect1 id="control-structures.while">
   <title><literal>while</literal></title>
   <para>
    ÊïÙòÊîÈîÑï ÍäâÇÊï <literal>while</literal> ÈåËÇÈÉ ÃÈÓ× ÃæèÇÙ ÍäâÇÊ 
    PHP. çê ÊÊÕÑá ÊåÇåÇ åËä æØêÑÇÊçÇ áê C. ÇäÔñîãä ÇäâÇÙÏêñ 
    äÈäÇÚ <literal>while</literal> çè: 
    <informalexample>
     <programlisting>
<![CDATA[
while (expr) ÈäÇÚ
]]>
     </programlisting>
    </informalexample>
   </para>
   <simpara>
    Åæñî åÙæé ÈäÇÚ <literal>while</literal> ÈÓê×. çè 
    êïÎÈðÑï PHP ÈÊæáêÐ ÇäÈäÇÚ (àÇÊ) ÇäåïÔÈñîã (àÉ) ÈÔãä åïÊãÑñðѬ ×ÇäåÇ 
    âïêñðåîÊ ÙÈÇÑÉ <literal>while</literal> Èà 
    &true;. êÊå ÊáâñïÏï âêåÉ ÇäÙÈÇÑÉ 
    áê ãäñð åÑÉ èÐäã ÙæÏ ÈÏÇêÉ ÇäÍäâɬ ÈÍêË Ãæñîç ÍÊé ÅÐÇ ÊÚêñîÑîÊ çÐç ÇäâêåÉ 
    ÃËæÇÁ ÊæáêÐ ÇäÈäÇÚ (àÇÊ) ÇäåïÔÈñîã (àÉ)¬ áÅæñî ÇäÊñîæáêÐ 
    äæ êÊèâá ÅäÇ ÈÈäèÚ æçÇêÉ ÇäÊñðãÑÇÑ (ãäï åÑÉ ÊïÔÚñðäï áêçÇ PHP 
    ÇäÈäÇÚÇÊ áê ÇäÍäâÉ êïåËñðäï Ðäã ÊãÑÇÑÇë èÇÍÏÇë). ÃÍêÇæÇë¬ ÅÐÇ 
    âïêñðåîÊ ÙÈÇÑÉ <literal>while</literal> Èà 
    &false; èÐäã åæÐ åïÓÊçîäð ÇäÈÏÇêɬ áÅæñî ÇäÈäÇÚ (àÇÊ) 
    ÇäåïÔÈñîã (àÉ) äæ êÊå ÊÔÚêäç èäÇ ÍÊé åÑÉ èÇÍÏÉ. 
   </simpara>
   <para>
    åËäåÇ ÇäÍÇä ÈÇäæñðÓÈÉ äÈäÇÚ <literal>if</literal>¬ áÅæñîç êåãæã ÊÌåêÙ 
    ÙÏÉ ÈäÇÚÇÊ Öåæ æáÓ ÍäâÉ <literal>while</literal> 
    èÐäã ÈÅÍÇ×É åÌåèÙÉ ÈäÇÚÇÊ ÈÍÇÖæÊêæ åÙâèáÊêæ Ãè 
    ÈÇÓÊÎÏÇå ÇäÕñðêÚÉ ÇäæñîÍèêñîÉ ÇäÈÏêäÉ: 
    <informalexample>
     <programlisting>
<![CDATA[
while (expr): ÈäÇÚ ... endwhile;
]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    ÇäÃåËäÉ ÇäÊñîÇäêñîÉ åïÊåîÇËðäÉ èãäñ åæçÇ ê×ÈÙ ÃÙÏÇÏÇë åæ 
    1 Åäé 10:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
/* ÇäåËÇä 1 */

$i = 1;
while ($i <= 10) {
    print $i++;  /* ÇäâêåÉ Çäå×ÈèÙÉ ãÇæÊ ÓÊãèæ 
                    $i âÈä ÇäÊñîÒÇêÏ 
                    (ÇäÊñîÒÇêÏ ÇäåïÓÈîâ) */
}

/* ÇäåËÇä 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> ÌÏñï ÔÈêçÉí ÈÍäâÇÊ 
    <literal>while</literal> áêåÇ ÙÏÇ Ãæñî ÙÈÇÑÉ ÇäÍâêâÉ 
    êÊå ÊáâñïÏñïçÇ ÙæÏ æçÇêÉ ãäñ ÊãÑÇÑ ÈÏäÇ åæ ÇäÈÏÇêÉ. 
    êÊåËä Ãçå ÇÎÊäÇá åâÇÑæÉ ÈÍäâÇÊ <literal>while</literal> ÇäÅÙÊêÇÏêñîÉ áê 
    Ãæñî ÇäÊñðãÑÇÑ ÇäÃèä äÍäâÉ <literal>do..while</literal> 
    åÖåèæ ÇäÊñîÔÚêä (êÊå ÊáâñïÏï ÙÈÇÑÉ ÇäÍâêâÉ áâ× ÙæÏ æçÇêÉ 
    ÇäÊñðãÑÇÑ) áê Íêæ êåãæ Ãæ äÇ êïæáñîÐ ÈÇäÖñîÑèÑÉ åÙ 
    ÍäâÉ <literal>while</literal> ÅÙÊêÇÏêñîÉ (êÊå ÊáâñïÏ ÙÈÇÑÉ ÇäÍâêâÉ 
    ÙæÏ ÈÏÇêÉ ãäñð ÊãÑÇѬ ÅÐÇ âïêñðåîÊ Èà 
    &false; åïÈÇÔÑÉ ÙæÏ ÇäÈÏÇêɬ áÅæñî ÊæáêÐ 
    ÇäÍäâÉ êæÊçê ÍÇäÇë).
   </simpara>
   <para>
    çæÇã ÕêÚÉ æÍèêñîÉ èÇÍÏÉ ÊÎñïÕï ÍäâÇÊ <literal>do..while</literal>:

    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
$i = 0;
do {
   print $i;
} while ($i > 0);
?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <simpara>
     ÊÔÊÚä ÇäÍäâÉ ÇäÙïäèêñîÉ ÈÇäÖñîÈ× åÑÉ èÇÍÏÉ áâ׬ ÙæÏ ÇæÊçÇÁ Ãèä 
     ÊãÑÇѬ ÍêË êÊå ÊáâñïÏ ÙÈÇÑÉ ÇäÍâêâɬ Êïâêñîå Èà 
     &false; ($i äêÓÊ ÃãÈÑ åæ 0) èêæÊçê ÊæáêÐ 
     ÇäÍäâÉ.
   </simpara>
   <para>
    êåãæ äåïÓÊÎÏðåê C ÇäåïÊâÏðåðêæ Ãæ êãèæèÇ åÊÂäáêæ åæ ÇÓÊÎÏÇå åÚÇêÑ äÍäâÉ 
    <literal>do..while</literal> ääÓåÇÍ ÈÊèâêá ÇäÊñîæáêÐ 
    áê åïæÊÕá åâÇ×Ù ÇäÔñðêáÑÉ èÐäã ÈÊÚäêáçÇ Èà 
    <literal>do..while</literal>(0) èÈÇÓÊÎÏÇå ÈäÇÚ <link
    linkend="control-structures.break"><literal>break</literal></link>. 
    åâ×Ù ÇäÔñðêáÑÉ ÇäÊñîÇäêñ êèÖðÍï çÐÇ: 
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
do {
    if ($i < 5) {
        print "i äêÓ ãÈêÑÇ ÈåÇ áêç ÇäãáÇêÉ";
        break;
    }
    $i *= $factor;
    if ($i < $minimum_limit) {
        break;
    }
    print "ÍÓæÇë ÈÇäæñðÓÈÉ äà i";

    /* åïÙÇäÌÉ i */

} while(0);
?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <simpara>
    äÇ Êâäâ ÅÐÇ äå ÊÓÊèÙÈ çÐÇ ÇäÂæ Ãè ÈÊÇÊÇ. 
    êåãæã ÊÔáêÑ ÎèÇ×ê× Èä èÍÊé ÎèÇ×ê× âèêñîÉ åæ Ïèæ Ãæ ÊÓÊÎÏå çÐç 
    'ÇäåêÒÉ'.
   </simpara>
  </sect1>

  <sect1 id="control-structures.for">
   <title><literal>for</literal></title>
   <para>
    ÊïÙÊÈÑ ÍäâÇÊ <literal>for</literal> ÃãËÑ ÍäâÇÊ PHP ÊÙâêÏÇë. 
    ÊÊÕÑá åËä æØêÑÇÊçÇ áê C. ÇäÕñðêÚÉ ÇäæñîÍèêñîÉ 
    äÍäâÉ <literal>for</literal> çê:
    <informalexample>
     <programlisting>
<![CDATA[
for (expr1; expr2; expr3) ÈäÇÚ
]]>
     </programlisting>
    </informalexample>
   </para>
   <simpara>
    Êïâêñîå ÇäÙÈÇÑÉ ÇäÃèäé (<replaceable>expr1</replaceable>) 
    (ÊïæáñîÐ) åÑÉ èÇÍÏÉ Ïèæ ÔÑè× èÐäã ÙæÏ ÈÏÇêÉ 
    ÇäÍäâÉ.
   </simpara>
   <simpara>
    ÙæÏ åïÓÊçîä ãäñ ÊãÑÇѬ Êïâêñîå 
    <replaceable>expr2</replaceable>. ÅÐÇ âïêñðåîÊ Èà 
    &true;¬ ÊÓÊåÑ ÇäÍäâÉ èêÊå ÊæáêÐ ÇäÈäÇÚ (àÇÊ) 
    ÇäåïÔÈñîã (àÉ). ÅÐÇ âïêñðåîÊ Èà 
    &false;¬ êæÊçê ÊæáêÐ ÇäÍäâÉ. 
   </simpara>
   <simpara>
    ÙæÏ æçÇêÉ ãäñ ÊãÑÇѬ Êïâêñîå <replaceable>expr3</replaceable> 
    (ÊïæáñîÐ).
   </simpara>
   <simpara>
    êåãæ äãäñ åæ ÇäÙÈÇÑÇÊ Ãæ Êãèæ áÇÑÚÉ. 
    Åæñî ãèæ <replaceable>expr2</replaceable> áÇÑÚÉ êÙæê Ãæñî ÇäÍäâÉ êÌÈ Ãæ 
    ÊÔÊÚä Åäé åÇ äÇ æçÇêÉ (ÖðåæêÇë¬ ÊÙÊÈÑçÇ PHP Ùäé ÃæñîçÇ 
    &true;¬ åËäåÇ áê C). êåãæ äçÐÇ Ãæ äÇ êãèæ ÙÏêå ÇäáÇÆÏÉ åËäåÇ 
    êåãæ Ãæ ÊÙÊâÏ ÈÇÙÊÈÇÑ Ãæñîç ÚÇäÈÇ åÇ ÊÑÚÈ áê ÅæçÇÁ ÇäÍäâÉ ÈÇÓÊÎÏÇå 
    ÈäÇÚ <link
    linkend="control-structures.break"><literal>break</literal></link>
    ÔÑ×êñ ÈÏäÇ åæ ÇÓÊÎÏÇå ÙÈÇÑÉ ÇäÍâêâÉ <literal>for</literal>
    .
   </simpara>
   <para>
    ÎÐ ÈÙêæ ÇäÇÙÊÈÇÑ ÇäÃåËäÉ ÇäÊñîÇäêñîÉ. ÊïØçðÑï ãäñïçÇ ÃÑâÇåÇë åæ 
    1 Åäé 10:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
/* ÇäåËÇä 1 */

for ($i = 1; $i <= 10; $i++) {
    print $i;
}

/* ÇäåËÇä 2 */

for ($i = 1; ; $i++) {
    if ($i > 10) {
        break;
    }
    print $i;
}

/* ÇäåËÇä 3 */

$i = 1;
for (;;) {
    if ($i > 10) {
        break;
    }
    print $i;
    $i++;
}

/* ÇäåËÇä 4 */

for ($i = 1; $i <= 10; print $i, $i++);
?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <simpara>
    ÈÇä×ñîÈÙ¬ êØçÑ ÇäåËÇä ÇäÃèä Ùäé Ãæñîç ÃáÖäçÇ (Ãè 
    äÑÈåÇ ÇäÑñîÇÈÙ)¬ äãæ êåãæ Ãæ ÊÌðÏ Ãæ âÇÈäêÉ ÇÓÊÎÏÇå ÙÈÇÑÇÊ 
    áÇÑÚÉ áê ÍäâÇÊ <literal>for</literal> åáêÏÇë áê ÙÏÉ 
    áÑîÕ.
   </simpara>
   <para>
    ÊÏÙåï PHP ÃêÖÇ "ÕêÚÉ Çäæñïâ×Êêæ ÇäæñîÍèêñîÉ - colon syntax" ÇäÈÏêäÉ äÃÌä 
    ÍäâÇÊ <literal>for</literal>.
    <informalexample>
     <programlisting>
<![CDATA[
for (expr1; expr2; expr3): ÈäÇÚ; ...; endfor;
]]>
     </programlisting>
     </informalexample>
   </para>
   <para>
    Other languages have a <literal>foreach</literal> statement to
    traverse an array or hash. PHP 3 has no such construct; PHP 4 does
    (see <link
    linkend="control-structures.foreach">foreach</link>). In PHP 3, you
    can combine <link linkend="control-structures.while">while</link>
    with the <function>list</function> and <function>each</function>
    functions to achieve the same effect. See the documentation for
    these functions for an example.
   </para>

  </sect1>

  <sect1 id="control-structures.foreach">
   <title><literal>foreach</literal></title>
   <para>
    PHP 4 (not PHP 3) includes a <literal>foreach</literal> construct, much
    like Perl and some other languages. This simply gives an easy way to
    iterate over arrays. <literal>foreach</literal> works only on arrays, and
    will issue an error when you try to use it on a variable with a different
    data type or an uninitialized variable. There are two syntaxes; the
    second is a minor but useful extension of the first:
    <informalexample>
     <programlisting>
<![CDATA[
foreach (array_expression as $value) statement
foreach (array_expression as $key => $value) statement
]]>
     </programlisting>
    </informalexample>
   </para>
   <simpara>
    The first form loops over the array given by
    <literal>array_expression</literal>. On each loop, the value of
    the current element is assigned to <literal>$value</literal> and
    the internal array pointer is advanced by one (so on the next
    loop, you'll be looking at the next element).
   </simpara>
   <simpara>
    The second form does the same thing, except that the current
    element's key will be assigned to the variable
    <literal>$key</literal> on each loop.
   </simpara>
   <para>
    <note>
     <para>
      When <literal>foreach</literal> first starts executing, the
      internal array pointer is automatically reset to the first element
      of the array. This means that you do not need to call
      <function>reset</function> before a <literal>foreach</literal>
      loop.
     </para>
    </note>
   </para>
   <para>
    <note>
     <para>
      Also note that <literal>foreach</literal> operates on a copy of
      the specified array and not the array itself. Therefore, the
      array pointer is not modified as with the
      <function>each</function> construct, and changes to the array
      element returned are not reflected in the original array.
      However, the internal pointer of the original array
      <emphasis>is</emphasis> advanced with the processing of the
      array.  Assuming the foreach loop runs to completion, the
      array's internal pointer will be at the end of the array.
     </para>
    </note>
   </para>
   <para>
    <note>
     <para>
      <literal>foreach</literal> does not support the ability to
      suppress error messages using '@'.
     </para>
    </note>
   </para>
   <para>
    You may have noticed that the following are functionally
    identical:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
$arr = array("one", "two", "three");
reset ($arr);
while (list(, $value) = each ($arr)) {
    echo "Value: $value<br>\n";
}

foreach ($arr as $value) {
    echo "Value: $value<br>\n";
}
?>
]]>
     </programlisting>
    </informalexample>
    The following are also functionally identical:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
reset ($arr);
while (list($key, $value) = each ($arr)) {
    echo "Key: $key; Value: $value<br>\n";
}

foreach ($arr as $key => $value) {
    echo "Key: $key; Value: $value<br>\n";
}
?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    Some more examples to demonstrate usages:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
/* foreach example 1: value only */

$a = array (1, 2, 3, 17);

foreach ($a as $v) {
   print "Current value of \$a: $v.\n";
}

/* foreach example 2: value (with key printed for illustration) */

$a = array (1, 2, 3, 17);

$i = 0; /* for illustrative purposes only */

foreach ($a as $v) {
    print "\$a[$i] => $v.\n";
    $i++;
}

/* foreach example 3: key and value */

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

foreach ($a as $k => $v) {
    print "\$a[$k] => $v.\n";
}

/* foreach example 4: multi-dimensional arrays */

$a[0][0] = "a";
$a[0][1] = "b";
$a[1][0] = "y";
$a[1][1] = "z";

foreach ($a as $v1) {
    foreach ($v1 as $v2) {
        print "$v2\n";
    }
}

/* foreach example 5: dynamic arrays */

foreach (array(1, 2, 3, 4, 5) as $v) {
    print "$v\n";
}
?>
]]>
     </programlisting>
    </informalexample>
   </para>
  </sect1>

  <sect1 id="control-structures.break">
   <title><literal>break</literal></title>
   <simpara>
    <literal>break</literal> ends execution of the current
    <literal>for</literal>, <literal>foreach</literal>
    <literal>while</literal>, <literal>do..while</literal> or
    <literal>switch</literal> structure.
   </simpara>
   <simpara>
    <literal>break</literal> accepts an optional numeric argument
    which tells it how many nested enclosing structures are to be
    broken out of.
   </simpara>
   <para>
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
$arr = array ('one', 'two', 'three', 'four', 'stop', 'five');
while (list (, $val) = each ($arr)) {
    if ($val == 'stop') {
        break;    /* You could also write 'break 1;' here. */
    }
    echo "$val<br>\n";
}

/* Using the optional argument. */

$i = 0;
while (++$i) {
    switch ($i) {
    case 5:
        echo "At 5<br>\n";
        break 1;  /* Exit only the switch. */
    case 10:
        echo "At 10; quitting<br>\n";
        break 2;  /* Exit the switch and the while. */
    default:
        break;
    }
}
?>
]]>
     </programlisting>
    </informalexample>
   </para>
  </sect1>

  <sect1 id="control-structures.continue">
   <title><literal>continue</literal></title>
   <simpara>
    <literal>continue</literal> is used within looping structures to
    skip the rest of the current loop iteration and continue execution
    at the beginning of the next iteration.
   </simpara>
   <note>
    <simpara>
     Note that in PHP the
     <link linkend="control-structures.switch">switch</link> statement is
     considered a looping structure for the purposes of
     <literal>continue</literal>.
    </simpara>
   </note>
   <simpara>
    <literal>continue</literal> accepts an optional numeric argument
    which tells it how many levels of enclosing loops it should skip
    to the end of.
   </simpara>
   <para>
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
while (list ($key, $value) = each ($arr)) {
    if (!($key % 2)) { // skip odd members
        continue;
    }
    do_something_odd ($value);
}

$i = 0;
while ($i++ < 5) {
    echo "Outer<br>\n";
    while (1) {
        echo "&nbsp;&nbsp;Middle<br>\n";
        while (1) {
            echo "&nbsp;&nbsp;Inner<br>\n";
            continue 3;
        }
        echo "This never gets output.<br>\n";
    }
    echo "Neither does this.<br>\n";
}
?>
]]>
     </programlisting>
     </informalexample>
    </para>
    <para>
     Omitting the semicolon after <literal>continue</literal> can lead to
     confusion. Here's an example of what you shouldn't do. 
    </para>
    <para>
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
  for ($i = 0; $i < 5; ++$i) {
      if ($i == 2)
          continue
      print "$i\n";
  }
?>
]]>
      </programlisting>
      <para>
       One can expect the result to be :
      </para>
      <screen>
<![CDATA[
0
1
3
4
]]>
      </screen>
      <para>
       but this script will output :
      </para>
      <screen>
<![CDATA[
2
]]>
      </screen>
      <para>
       because the return value of the <function>print</function>
       call is <literal>int(1)</literal>, and it will look like the
       optional numeric argument mentioned above.
      </para>
     </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>
   <note>
    <simpara>
     Note that unlike some other languages, the
     <link linkend="control-structures.continue">continue</link> statement
     applies to switch and acts similar to <literal>break</literal>.  If you
     have a switch inside a loop and wish to continue to the next iteration of
     the outer loop, use <literal>continue 2</literal>.
    </simpara>
   </note>
   <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">
<![CDATA[
<?php
if ($i == 0) {
    print "i equals 0";
} elseif ($i == 1) {
    print "i equals 1";
} elseif ($i == 2) {
    print "i equals 2";
}

switch ($i) {
    case 0:
        print "i equals 0";
        break;
    case 1:
        print "i equals 1";
        break;
    case 2:
        print "i equals 2";
        break;
}
?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    It is important to understand how the <literal>switch</literal>
    statement is executed in order to avoid mistakes.  The
    <literal>switch</literal> statement executes line by line
    (actually, statement by statement).  In the beginning, no code is
    executed.  Only when a <literal>case</literal> statement is found
    with a value that matches the value of the
    <literal>switch</literal> expression does PHP begin to execute the
    statements.  PHP continues to execute the statements until the end
    of the <literal>switch</literal> block, or the first time it sees
    a <literal>break</literal> statement.  If you don't write a
    <literal>break</literal> statement at the end of a case's
    statement list, PHP will go on executing the statements of the
    following case.  For example:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?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 is equal to 0, PHP would execute all of the print
    statements!  If $i is equal to 1, PHP would execute the last two
    print statements. You would get the expected behavior ('i equals 2' 
    would be displayed) only if $i is equal to 2.  Thus,
    it is important not to forget <literal>break</literal> statements
    (even though you may want to avoid supplying them on purpose under
    certain circumstances).
   </simpara>
   <simpara>
    In a <literal>switch</literal> statement, the condition is
    evaluated only once and the result is compared to each
    <literal>case</literal> statement. In an <literal>elseif</literal>
    statement, the condition is evaluated again. If your condition is
    more complicated than a simple compare and/or is in a tight loop,
    a <literal>switch</literal> may be faster.
   </simpara>
   <para>
    The statement list for a case can also be empty, which simply
    passes control into the statement list for the next case.
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?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 <literal>default</literal> case.  This case matches
    anything that wasn't matched by the other cases, and should be the last
    <literal>case</literal> statement.  For example:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?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">
<![CDATA[
<?php
switch ($i):
    case 0:
        print "i equals 0";
        break;
    case 1:
        print "i equals 1";
        break;
    case 2:
        print "i equals 2";
        break;
    default:
        print "i is not equal to 0, 1 or 2";
endswitch;
?>
]]>
     </programlisting>
    </informalexample>
   </para>
  </sect1>

  <sect1 id="control-structures.declare">
   <title><literal>declare</literal></title>
   <para>
    The <literal>declare</literal> construct is used to
    set execution directives for a block of code.
    The syntax of <literal>declare</literal> is similar to
    the syntax of other flow control constructs:
    <informalexample>
     <programlisting>
<![CDATA[
declare (directive) statement
]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    The <literal>directive</literal> section allows the
    behavior of the <literal>declare</literal> block to
    be set.
    Currently only one directive is recognized: the
    <literal>ticks</literal> directive. (See below for more
    information on the
    <link linkend="control-structures.declare.ticks">ticks</link>
    directive)
   </para>
   <para>
    The <literal>statement</literal> part of the
    <literal>declare</literal> block will be executed -- how
    it is executed and what side effects occur during execution
    may depend on the directive set in the
    <literal>directive</literal> block.
   </para>
   <para>
    The <literal>declare</literal> construct can also be used in the global 
    scope, affecting all code following it.
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
// these are the same:

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

// or you can use this:
declare(ticks=1);
// entire script here
?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <sect2 id="control-structures.declare.ticks">
    <title>Ticks</title>
    <para>A tick is an event that occurs for every
    <replaceable>N</replaceable> low-level statements executed
    by the parser within the <literal>declare</literal> block.
    The value for <replaceable>N</replaceable> is specified
    using <literal>ticks=<replaceable>N</replaceable></literal>
    within the <literal>declare</literal> blocks's
    <literal>directive</literal> section.
   </para>
   <para>
    The event(s) that occur on each tick are specified using the
    <function>register_tick_function</function>. See the example 
    below for more details. Note that more than one event can occur
    for each tick.
   </para>
   <para>
    <example>
     <title>Profile a section of PHP code</title>
     <programlisting role="php">
<![CDATA[
<?php
// A function that records the time when it is called
function profile ($dump = FALSE)
{
    static $profile;

    // Return the times stored in profile, then erase it
    if ($dump) {
        $temp = $profile;
        unset ($profile);
        return ($temp);
    }

    $profile[] = microtime ();
}

// Set up a tick handler
register_tick_function("profile");

// Initialize the function before the declare block
profile ();

// Run a block of code, throw a tick every 2nd statement
declare (ticks=2) {
    for ($x = 1; $x < 50; ++$x) {
        echo similar_text (md5($x), md5($x*$x)), "<br />;";
    }
}

// Display the data stored in the profiler
print_r (profile (TRUE));
?>
]]>
     </programlisting>
    </example>
    The example profiles the PHP code within the 'declare'
    block, recording the time at which every second low-level
    statement in the block was executed. This information can
    then be used to find the slow areas within particular
    segments of code. This process can be performed using other
    methods: using ticks is more convenient and easier to
    implement.
   </para>
   <simpara>
    Ticks are well suited for debugging, implementing simple
    multitasking, backgrounded I/O and many other tasks.
   </simpara>
   <simpara>
    See also <function>register_tick_function</function> and
    <function>unregister_tick_function</function>.
   </simpara>
   </sect2>
  </sect1>

  <sect1 id="function.return">
   <title>return</title>
   <simpara>
    If called from within a function, the <function>return</function>
    statement immediately ends execution of the current function, and
    returns its argument as the value of the function
    call. <function>return</function> will also end the execution of
    an <function>eval</function> statement or script file.
   </simpara>
   <simpara>
    If called from the global scope, then execution of the current
    script file is ended. If the current script file was
    <function>include</function>ed or <function>require</function>ed,
    then control is passed back to the calling file. Furthermore, if
    the current script file was <function>include</function>ed, then
    the value given to <function>return</function> will be returned as
    the value of the <function>include</function> call. If
    <function>return</function> is called from within the main script
    file, then script execution ends. If the current script file was
    named by the <link
    linkend="ini.auto-prepend-file">auto_prepend_file</link> or <link
    linkend="ini.auto-append-file">auto_append_file</link>
    configuration options in &php.ini;, 
    then that script file's execution is ended.
   </simpara>
   <simpara>For more information, see <link
   linkend="functions.returning-values">Returning values</link>.
   </simpara>
   <para>
    <note>
     <simpara>
      Note that since <function>return</function> is a language
      construct and not a function, the parentheses surrounding its
      arguments are <emphasis>only</emphasis> required if the argument
      contains an expression. It is common to leave them out while returning a variable.
     </simpara>
    </note>
   </para>
  </sect1>


 <sect1 id="function.require">
   <title><function>require</function></title>

   <simpara>
    The <function>require</function> statement includes and evaluates
    the specific file.
   </simpara>
   <simpara>
     <function>require</function> includes and evaluates a specific file.  
     Detailed information on how this inclusion works is described in the 
     documentation for <function>include</function>.
   </simpara>
   <simpara>
     <function>require</function> and <function>include</function> 
     are identical in every way except how they handle failure.  
     <function>include</function> produces a 
     <link linkend="internal.e-warning">Warning</link> while 
     <function>require</function> results in a <link linkend="internal.e-error">
     Fatal Error</link>.  In other words, don't hesitate to use 
     <function>require</function> if you want a missing file to halt processing 
     of the page.  <function>include</function> does not behave this way, the
     script will continue regardless.  Be sure to have an appropriate
     <link linkend="ini.include-path">include_path</link> setting as well.
   </simpara>
   <para>
    <example>
     <title>Basic <function>require</function> examples</title>
     <programlisting role="php">
<![CDATA[
<?php

require 'prepend.php';

require $somefile;

require ('somefile.txt');

?>
]]>
     </programlisting>
   </example>
   </para>
   <simpara>
    See the <function>include</function> documentation for more examples.
   </simpara>
   <para>
    <note>
     <simpara>
      Prior to PHP 4.0.2, the following applies: <function>require</function>
      will always attempt to read the target file, even if the line it's on
      never executes.  The conditional statement won't affect
      <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.  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>
    </note>
   </para>
   
   &note.language-construct;
   
   &warn.no-win32-fopen-wrapper;
   
   <simpara>
    See also <function>include</function>, <function>require_once</function>,
    <function>include_once</function>, <function>eval</function>, 
    <function>file</function>, <function>readfile</function>, 
    <function>virtual</function> and <link linkend="ini.include-path">include_path</link>.
   </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>
     The documentation below also applies to <function>require</function>.
     The two constructs are identical in every way except how they handle
     failure.  <function>include</function> produces a 
     <link linkend="internal.e-warning">Warning</link> while <function>require</function>
     results in a <link linkend="internal.e-error">Fatal Error</link>.
     In other words, use <function>require</function> if you want 
     a missing file to halt processing of the page.  <function>include</function> does 
     not behave this way, the script will continue regardless.  Be sure to have an 
     appropriate <link linkend="ini.include-path">include_path</link> setting as well.
   </simpara>
   <simpara>
     When a file is included, the code it contains inherits the
     <link linkend="language.variables.scope">variable scope</link> of the
     line on which the include occurs.  Any variables available at that line
     in the calling file will be available within the called file, from that
     point forward.
   </simpara>
   <para>
     <example>
      <title>Basic <function>include</function> example</title>
      <programlisting role="php">
<![CDATA[
vars.php
<?php

$color = 'green';
$fruit = 'apple';

?>

test.php
<?php

echo "A $color $fruit"; // A

include 'vars.php';

echo "A $color $fruit"; // A green apple

?>
]]>
      </programlisting>
     </example>
   </para>
   <simpara>
     If the include 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.  So, it will follow
     the variable scope of that function.
   </simpara>
   <para>
     <example>
     <title>Including within functions</title>
      <programlisting role="php">
<![CDATA[
<?php

function foo()
{
    global $color;

    include 'vars.php';

    echo "A $color $fruit";
}

/* vars.php is in the scope of foo() so     *
 * $fruit is NOT available outside of this  *
 * scope.  $color is because we declared it *
 * as global.                               */

foo();                    // A green apple
echo "A $color $fruit";   // A green

?>
]]>
     </programlisting>
    </example>
   </para>
   <simpara>
     When a file is included, 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>
   <simpara>
     If "<link linkend="ini.allow-url-fopen">URL fopen wrappers</link>"
     are enabled in PHP (which they are in the default configuration),
     you can specify the file to be included using an URL (via HTTP or
     other supported wrapper - see <xref linkend="wrappers"/> for a list
     of protocols) instead of a local pathname.  If the target server interprets
     the target file as PHP code, variables may be passed to the included
     file using an URL request string as used with HTTP GET.  This is
     not strictly speaking the same thing as including 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.
   </simpara>
   &warn.no-win32-fopen-wrapper;
   <para>
    <example>
     <title><function>include</function> through HTTP</title>
     <programlisting role="php">
<![CDATA[
<?php

/* This example assumes that www.example.com is configured to parse .php
 * files and not .txt files. Also, 'Works' here means that the variables
 * $foo and $bar are available within the included file. */

// Won't work; file.txt wasn't handled by www.example.com as PHP
include 'http://www.example.com/file.txt?foo=1&bar=2';

// Won't work; looks for a file named 'file.php?foo=1&bar=2' on the
// local filesystem.
include 'file.php?foo=1&bar=2';

// Works.
include 'http://www.example.com/file.php?foo=1&bar=2';

$foo = 1;
$bar = 2;
include 'file.txt';  // Works.
include 'file.php';  // Works.

?>
]]>
     </programlisting>
    </example>
    See also <link linkend="features.remote-files">Remote files</link>,
    <function>fopen</function> and <function>file</function> for related 
    information.
   </para>
   <para>
     Because <function>include</function> and <function>require</function>
     are special language constructs, you must enclose them within a statement
     block if it's inside a conditional block.
   </para>
   <para>
    <example>
     <title>include() and conditional blocks</title>
     <programlisting role="php">
<![CDATA[
<?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>
    </example>
   </para>
   <simpara>
    Handling Returns: It is possible to execute a <function>return</function> 
    statement inside an included file in order to terminate processing in that 
    file and return to the script which called it.  Also, it's possible to return 
    values from included files.  You can take the value of the include call as 
    you would a normal function.
   </simpara>
   <para>
    <note>
     <simpara>
      In PHP 3, the return may not appear inside a block unless it's
      a function block, in which case the <function>return</function> applies 
      to that function and not the whole file.
     </simpara>
    </note>
   </para>
   <para>
    <example>
     <title><function>include</function> and the <function>return</function> statement</title>
      <programlisting role="php">
<![CDATA[
return.php
<?php

$var = 'PHP';

return $var;

?>

noreturn.php
<?php

$var = 'PHP';

?>

testreturns.php
<?php

$foo = include 'return.php';

echo $foo; // prints 'PHP'

$bar = include 'noreturn.php';

echo $bar; // prints 1

?>
]]>
      </programlisting>
    </example>
   </para>
   <simpara>
    <literal>$bar</literal> is the value <literal>1</literal> because the include 
    was successful.  Notice the difference between the above examples.  The first uses 
    <function>return</function> within the included file while the other does not.  
    A few other ways to "include" files into variables are with 
    <function>fopen</function>, <function>file</function> or by using 
    <function>include</function> along with 
    <link linkend="ref.outcontrol">Output Control Functions</link>.
   </simpara>
   
   &note.language-construct;

   <simpara>
    See also <function>require</function>, <function>require_once</function>,
    <function>include_once</function>, <function>readfile</function>,
    <function>virtual</function>, and
    <link linkend="ini.include-path">include_path</link>.
   </simpara>
 </sect1>

 <sect1 id="function.require-once">
   <title><function>require_once</function></title>
   <para>
    The <function>require_once</function> statement includes and evaluates
    the specified file during the execution of the script.
    This is a behavior similar to the <function>require</function> statement,
    with the only difference being that if the code from a file has already
    been included, it will not be included again.  See the documentation for
    <function>require</function> for more information on how this statement 
    works.
   </para>
   <para>
    <function>require_once</function> should be used in cases where
    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 examples on using <function>require_once</function> and
     <function>include_once</function>, look at the 
     <ulink url="&url.php.pear;">PEAR</ulink> code included in the 
     latest PHP source code distributions.
   </para>
   <para>
    <note>
     <para>
      <function>require_once</function> was added in PHP 4.0.1pl2
     </para>
    </note>
   </para>
   <para>
    <note>
     <para>
      Be aware, that the behaviour of <function>require_once</function>
      and <function>include_once</function> may not be what you expect
      on a non case sensitive operating system (such as Windows).
      <example>
       <title><function>require_once</function> is case insensitive on Windows</title>
       <programlisting role="php">
<![CDATA[
<?php
require_once("a.php"); // this will include a.php
require_once("A.php"); // this will include a.php again on Windows!
?>
]]>
        </programlisting>
      </example>
     </para>
    </note>
   </para>
   &warn.no-win32-fopen-wrapper;
   <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 only difference being that if the code from a file has already
    been included, it will not be included again.  As the name suggests, 
    it will be included just once.
   </para>
   <para>
    <function>include_once</function> should be used in cases where 
    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
    <ulink url="&url.php.pear;">PEAR</ulink> code included in the latest
    PHP source code distributions.
   </para>
   <para>
    <note>
     <para>
      <function>include_once</function> was added in PHP 4.0.1pl2
     </para>
    </note>
   </para>
   <para>
   <note>
     <para>
      Be aware, that the behaviour of <function>include_once</function>
      and <function>require_once</function> may not be what you expect
      on a non case sensitive operating system (such as Windows).
      <example>
       <title><function>include_once</function> is case insensitive on Windows</title>
       <programlisting role="php">
<![CDATA[
<?php
include_once("a.php"); // this will include a.php
include_once("A.php"); // this will include a.php again on Windows!
?>
]]>
        </programlisting>
      </example>
     </para>
    </note>
   </para>
   &warn.no-win32-fopen-wrapper;
   <para>
    See also <function>include</function>,
    <function>require</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:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->