eschmid Fri Jan 12 08:49:33 2001 EDT
Modified files:
/phpdoc/pt_BR/language control-structures.xml
Log:
It's now complete.
Index: phpdoc/pt_BR/language/control-structures.xml
diff -u phpdoc/pt_BR/language/control-structures.xml:1.1
phpdoc/pt_BR/language/control-structures.xml:1.2
--- phpdoc/pt_BR/language/control-structures.xml:1.1 Wed Aug 2 10:39:17 2000
+++ phpdoc/pt_BR/language/control-structures.xml Fri Jan 12 08:49:32 2001
@@ -595,4 +595,691 @@
echo "Mais externo<br>\n";
while (1) {
echo " Meio<br>\n";
-
\ No newline at end of file
+ while (1) {
+ echo " Inner<br>\n";
+ continue 3;
+ }
+ echo "This never gets output.<br>\n";
+ }
+ echo "Neither does this.<br>\n";
+}
+ </programlisting>
+ </informalexample>
+ </para>
+ </sect1>
+
+ <sect1 id="control-structures.switch">
+ <title><literal>switch</literal></title>
+ <simpara>
+ The <literal>switch</literal> statement is similar to a series of
+ IF statements on the same expression. In many occasions, you may
+ want to compare the same variable (or expression) with many
+ different values, and execute a different piece of code depending
+ on which value it equals to. This is exactly what the
+ <literal>switch</literal> statement is for.
+ </simpara>
+ <para>
+ The following two examples are two different ways to write the
+ same thing, one using a series of <literal>if</literal>
+ statements, and the other using the <literal>switch</literal>
+ statement:
+ <informalexample>
+ <programlisting role="php">
+if ($i == 0) {
+ print "i equals 0";
+}
+if ($i == 1) {
+ print "i equals 1";
+}
+if ($i == 2) {
+ print "i equals 2";
+}
+
+switch ($i) {
+ case 0:
+ print "i equals 0";
+ break;
+ case 1:
+ print "i equals 1";
+ break;
+ case 2:
+ print "i equals 2";
+ break;
+}
+ </programlisting>
+ </informalexample>
+ </para>
+ <para>
+ It is important to understand how the <literal>switch</literal>
+ statement is executed in order to avoid mistakes. The
+ <literal>switch</literal> statement executes line by line
+ (actually, statement by statement). In the beginning, no code is
+ executed. Only when a <literal>case</literal> statement is found
+ with a value that matches the value of the
+ <literal>switch</literal> expression does PHP begin to execute the
+ statements. PHP continues to execute the statements until the end
+ of the <literal>switch</literal> block, or the first time it sees
+ a <literal>break</literal> statement. If you don't write a
+ <literal>break</literal> statement at the end of a case's
+ statement list, PHP will go on executing the statements of the
+ following case. For example:
+ <informalexample>
+ <programlisting role="php">
+switch ($i) {
+ case 0:
+ print "i equals 0";
+ case 1:
+ print "i equals 1";
+ case 2:
+ print "i equals 2";
+}
+ </programlisting>
+ </informalexample>
+ </para>
+ <simpara>
+ Here, if $i equals to 0, PHP would execute all of the print
+ statements! If $i equals to 1, PHP would execute the last two
+ print statements, and only if $i equals to 2, you'd get the
+ 'expected' behavior and only 'i equals 2' would be displayed. So,
+ it's important not to forget <literal>break</literal> statements
+ (even though you may want to avoid supplying them on purpose under
+ certain circumstances).
+ </simpara>
+ <simpara>
+ In a <literal>switch</literal> statement, the condition is
+ evaluated only once and the result is compared to each
+ <literal>case</literal> statement. In an <literal>elseif</literal>
+ statement, the condition is evaluated again. If your condition is
+ more complicated than a simple compare and/or is in a tight loop,
+ a <literal>switch</literal> may be faster.
+ </simpara>
+ <para>
+ The statement list for a case can also be empty, which simply
+ passes control into the statement list for the next case.
+ <informalexample>
+ <programlisting role="php">
+switch ($i) {
+ case 0:
+ case 1:
+ case 2:
+ print "i is less than 3 but not negative";
+ break;
+ case 3:
+ print "i is 3";
+}
+ </programlisting>
+ </informalexample>
+ </para>
+ <para>
+ A special case is the default case. This case matches anything
+ that wasn't matched by the other cases. For example:
+ <informalexample>
+ <programlisting role="php">
+switch ($i) {
+ case 0:
+ print "i equals 0";
+ break;
+ case 1:
+ print "i equals 1";
+ break;
+ case 2:
+ print "i equals 2";
+ break;
+ default:
+ print "i is not equal to 0, 1 or 2";
+}
+ </programlisting>
+ </informalexample>
+ </para>
+ <para>
+ The <literal>case</literal> expression may be any expression that
+ evaluates to a simple type, that is, integer or floating-point
+ numbers and strings. Arrays or objects cannot be used here unless
+ they are dereferenced to a simple type.
+ </para>
+ <para>
+ The alternative syntax for control structures is supported with
+ switches. For more information, see <link
+ linkend="control-structures.alternative-syntax">Alternative syntax
+ for control structures</link> .
+ <informalexample>
+ <programlisting role="php">
+switch ($i):
+ case 0:
+ print "i equals 0";
+ break;
+ case 1:
+ print "i equals 1";
+ break;
+ case 2:
+ print "i equals 2";
+ break;
+ default:
+ print "i is not equal to 0, 1 or 2";
+endswitch;
+ </programlisting>
+ </informalexample>
+ </para>
+ </sect1>
+
+ <sect1 id="function.require">
+ <title><function>require</function></title>
+ <simpara>
+ The <function>require</function> statement replaces itself with
+ the specified file, much like the C preprocessor's
+ <literal>#include</literal> works.
+ </simpara>
+ <simpara>
+ If "URL fopen wrappers" are enabled in PHP (which they are in the
+ default configuration), you can specify the file to be
+ <function>require</function>ed using an URL instead of a local
+ pathname. See <link linkend="features.remote-files">Remote
+ files</link> and <function>fopen</function> for more information.
+ </simpara>
+ <simpara>
+ An important note about how this works is that when a file is
+ <function>include</function>ed or <function>require</function>ed,
+ parsing drops out of PHP mode and into HTML mode at the beginning
+ of the target file, and resumes PHP mode again at the end. For
+ this reason, any code inside the target file which should be
+ executed as PHP code must be enclosed within <link
+ linkend="language.basic-syntax.phpmode">valid PHP start and end
+ tags</link>.
+ </simpara>
+ <simpara>
+ <function>require</function> is not actually a function in PHP;
+ rather, it is a language construct. It is subject to some
+ different rules than functions are. For instance,
+ <function>require</function> is not subject to any containing
+ control structures. For another, it does not return any value;
+ attempting to read a return value from a
+ <function>require</function> call results in a parse error.
+ </simpara>
+ <simpara>
+ Unlike <function>include</function>, <function>require</function>
+ will <emphasis>always</emphasis> read in the target file,
+ <emphasis>even if the line it's on never executes</emphasis>. If
+ you want to conditionally include a file, use
+ <function>include</function>. The conditional statement won't
+ affect the <function>require</function>. However, if the line on
+ which the <function>require</function> occurs is not executed,
+ neither will any of the code in the target file be executed.
+ </simpara>
+ <simpara>
+ Similarly, looping structures do not affect the behaviour of
+ <function>require</function>. Although the code contained in the
+ target file is still subject to the loop, the
+ <function>require</function> itself happens only once.
+ </simpara>
+ <para>
+ This means that you can't put a <function>require</function>
+ statement inside of a loop structure and expect it to include the
+ contents of a different file on each iteration. To do that, use an
+ <function>include</function> statement.
+ <informalexample>
+ <programlisting role="php">
+require ('header.inc');
+ </programlisting>
+ </informalexample>
+ </para>
+ <simpara>
+ When a file is <function>require</function>ed, the code it
+ contains inherits the variable scope of the line on which the
+ <function>require</function> occurs. Any variables available at
+ that line in the calling file will be available within the called
+ file. If the <function>require</function> occurs inside a
+ function within the calling file, then all of the code contained
+ in the called file will behave as though it had been defined
+ inside that function.
+ </simpara>
+ <para>
+ If the <function>require</function>ed file is called via HTTP
+ using the fopen wrappers, and if the target server interprets the
+ target file as PHP code, variables may be passed to the
+ <function>require</function>ed file using an URL request string as
+ used with HTTP GET. This is not strictly speaking the same thing
+ as <function>require</function>ing the file and having it inherit
+ the parent file's variable scope; the script is actually being run
+ on the remote server and the result is then being included into
+ the local script.
+ <informalexample>
+ <programlisting role="php">
+/* This example assumes that someserver is configured to parse .php
+ * files and not .txt files. Also, 'works' here means that the variables
+ * $varone and $vartwo are available within the require()ed file. */
+
+/* Won't work; file.txt wasn't handled by someserver. */
+require ("http://someserver/file.txt?varone=1&vartwo=2");
+
+/* Won't work; looks for a file named 'file.php?varone=1&vartwo=2'
+ * on the local filesystem. */
+require ("file.php?varone=1&vartwo=2");
+
+/* Works. */
+require ("http://someserver/file.php?varone=1&vartwo=2");
+
+$varone = 1;
+$vartwo = 2;
+require ("file.txt"); /* Works. */
+require ("file.php"); /* Works. */
+ </programlisting>
+ </informalexample>
+ </para>
+ <simpara>
+ In PHP 3, it is possible to execute a <literal>return</literal>
+ statement inside a <function>require</function>ed file, as long as
+ that statement occurs in the global scope of the
+ <function>require</function>ed file. It may not occur within any
+ block (meaning inside braces ({}). In PHP 4, however, this ability
+ has been discontinued. If you need this functionality, see
+ <function>include</function>.
+ </simpara>
+ <simpara>
+ See also <function>include</function>, <function>require_once</function>,
+ <function>include_once</function>, <function>readfile</function>,
+ and <function>virtual</function>.
+ </simpara>
+ </sect1>
+
+ <sect1 id="function.include">
+ <title><function>include</function></title>
+ <simpara>
+ The <function>include</function> statement includes and evaluates
+ the specified file.
+ </simpara>
+ <simpara>
+ If "URL fopen wrappers" are enabled in PHP (which they are in the
+ default configuration), you can specify the file to be
+ <function>include</function>ed using an URL instead of a local
+ pathname. See <link linkend="features.remote-files">Remote
+ files</link> and <function>fopen</function> for more information.
+ </simpara>
+ <simpara>
+ An important note about how this works is that when a file is
+ <function>include</function>ed or <function>require</function>ed,
+ parsing drops out of PHP mode and into HTML mode at the beginning
+ of the target file, and resumes again at the end. For this reason,
+ any code inside the target file which should be executed as PHP
+ code must be enclosed within <link
+ linkend="language.basic-syntax.phpmode">valid PHP start and end
+ tags</link>.
+ </simpara>
+ <para>
+ This happens each time the <function>include</function> statement
+ is encountered, so you can use an <function>include</function>
+ statement within a looping structure to include a number of
+ different files.
+ <informalexample>
+ <programlisting role="php">
+$files = array ('first.inc', 'second.inc', 'third.inc');
+for ($i = 0; $i < count($files); $i++) {
+ include $files[$i];
+}
+ </programlisting>
+ </informalexample>
+ </para>
+ <para>
+ <function>include</function> differs from
+ <function>require</function> in that the include statement is
+ re-evaluated each time it is encountered (and only when it is
+ being executed), whereas the <function>require</function>
+ statement is replaced by the required file when it is first
+ encountered, whether the contents of the file will be evaluated or
+ not (for example, if it is inside an <link
+ linkend="control-structures.if">if</link> statement whose
+ condition evaluated to false).
+ </para>
+ <para>
+ Because <function>include</function> is a special language
+ construct, you must enclose it within a statement block if it is
+ inside a conditional block.
+ <informalexample>
+ <programlisting role="php">
+/* This is WRONG and will not work as desired. */
+
+if ($condition)
+ include($file);
+else
+ include($other);
+
+/* This is CORRECT. */
+
+if ($condition) {
+ include($file);
+} else {
+ include($other);
+}
+ </programlisting>
+ </informalexample>
+ </para>
+ <simpara>
+ In both PHP 3 and PHP 4, it is possible to execute a
+ <literal>return</literal> statement inside an
+ <function>include</function>ed file, in order to terminate
+ processing in that file and return to the script which called
+ it. Some differences in the way this works exist, however. The
+ first is that in PHP 3, the <literal>return</literal> may not
+ appear inside a block unless it's a function block, in which case
+ the <literal>return</literal> applies to that function and not the
+ whole file. In PHP 4, however, this restriction does not
+ exist. Also, PHP 4 allows you to return values from
+ <function>include</function>ed files. You can take the value of
+ the <function>include</function> call as you would a normal
+ function. This generates a parse error in PHP 3.
+ </simpara>
+ <example>
+ <title><function>include</function> in PHP 3 and PHP 4</title>
+ <para>
+ Assume the existence of the following file (named
+ <filename>test.inc</filename>) in the same directory as the main
+ file:
+ <programlisting role="php">
+<?php
+echo "Before the return <br>\n";
+if (1) {
+ return 27;
+}
+echo "After the return <br>\n";
+?>
+ </programlisting>
+ </para>
+ <para>
+ Assume that the main file (<filename>main.html</filename>)
+ contains the following:
+ <programlisting role="php">
+<?php
+$retval = include ('test.inc');
+echo "File returned: '$retval'<br>\n";
+?>
+ </programlisting>
+ </para>
+ <para>
+ When <filename>main.html</filename> is called in PHP 3, it will
+ generate a parse error on line 2; you can't take the value of an
+ <function>include</function> in PHP 3. In PHP 4, however, the
+ result will be:
+ <screen>
+Before the return
+File returned: '27'
+ </screen>
+ </para>
+ <para>
+ Now, assume that <filename>main.html</filename> has been altered
+ to contain the following:
+ <programlisting role="php">
+<?php
+include ('test.inc');
+echo "Back in main.html<br>\n";
+?>
+ </programlisting>
+ </para>
+ <para>
+ In PHP 4, the output will be:
+ <screen>
+Before the return
+Back in main.html
+ </screen>
+ However, PHP 3 will give the following output:
+ <screen>
+Before the return
+27Back in main.html
+
+Parse error: parse error in /home/torben/public_html/phptest/main.html on line 5
+ </screen>
+ </para>
+ <para>
+ The above parse error is a result of the fact that the
+ <literal>return</literal> statement is enclosed in a non-function
+ block within <filename>test.inc</filename>. When the return is
+ moved outside of the block, the output is:
+ <screen>
+Before the return
+27Back in main.html
+ </screen>
+ </para>
+ <para>
+ The spurious '27' is due to the fact that PHP 3 does not support
+ <literal>return</literal>ing values from files like that.
+ </para>
+ </example>
+ <simpara>
+ When a file is <function>include</function>ed, the code it
+ contains inherits the variable scope of the line on which the
+ <function>include</function> occurs. Any variables available at
+ that line in the calling file will be available within the called
+ file. If the <function>include</function> occurs inside a
+ function within the calling file, then all of the code contained
+ in the called file will behave as though it had been defined
+ inside that function.
+ </simpara>
+ <para>
+ If the <function>include</function>ed file is called via HTTP
+ using the fopen wrappers, and if the target server interprets the
+ target file as PHP code, variables may be passed to the
+ <function>include</function>ed file using an URL request string as
+ used with HTTP GET. This is not strictly speaking the same thing
+ as <function>include</function>ing the file and having it inherit
+ the parent file's variable scope; the script is actually being run
+ on the remote server and the result is then being included into
+ the local script.
+ <informalexample>
+ <programlisting role="php">
+/* This example assumes that someserver is configured to parse .php
+ * files and not .txt files. Also, 'works' here means that the variables
+ * $varone and $vartwo are available within the include()ed file. */
+
+/* Won't work; file.txt wasn't handled by someserver. */
+include ("http://someserver/file.txt?varone=1&vartwo=2");
+
+/* Won't work; looks for a file named 'file.php?varone=1&vartwo=2'
+ * on the local filesystem. */
+include ("file.php?varone=1&vartwo=2");
+
+/* Works. */
+include ("http://someserver/file.php?varone=1&vartwo=2");
+
+$varone = 1;
+$vartwo = 2;
+include ("file.txt"); /* Works. */
+include ("file.php"); /* Works. */
+ </programlisting>
+ </informalexample>
+ </para>
+ <simpara>
+ See also <function>require</function>, <function>require_once</function>,
+ <function>include_once</function>, <function>readfile</function>,
+ and <function>virtual</function>.
+ </simpara>
+ </sect1>
+
+ <sect1 id="function.require-once">
+ <title><function>require_once</function></title>
+ <para>
+ The <function>require_once</function> statement replaces
+ itself with the specified file, much like the C preprocessor's
+ <literal>#include</literal> works, and in that respect is
+ similar to the <function>require</function> statement. The main
+ difference is that in an inclusion chain, the use of
+ <function>require_once</function> will assure that the code is
+ added to your script only once, and avoid clashes with variable
+ values or function names that can happen.
+ </para>
+ <para>
+ For example, if you create the following 2 include files
+ <literal>utils.inc</literal> and <literal>foolib.inc</literal>
+ <example>
+ <title>utils.inc</title>
+ <programlisting role="php">
+<?php
+define(PHPVERSION, floor(phpversion()));
+echo "GLOBALS ARE NICE\n";
+function goodTea() {
+ return "Oolong tea tastes good!";
+}
+?>
+ </programlisting>
+ </example>
+ <example>
+ <title>foolib.inc</title>
+ <programlisting role="php">
+<?php
+require ("utils.inc");
+function showVar($var) {
+ if (PHPVERSION == 4) {
+ print_r($var);
+ } else {
+ var_dump($var);
+ }
+}
+
+// bunch of other functions ...
+?>
+ </programlisting>
+ </example>
+ And then you write a script <literal>cause_error_require.php</literal>
+ <example>
+ <title>cause_error_require.php</title>
+ <programlisting role="php">
+<?php
+require("foolib.inc");
+/* the following will generate an error */
+require("utils.inc");
+$foo = array("1",array("complex","quaternion"));
+echo "this is requiring utils.inc again which is also\n";
+echo "required in foolib.inc\n";
+echo "Running goodTea: ".goodTea()."\n";
+echo "Printing foo: \n";
+showVar($foo);
+?>
+ </programlisting>
+ </example>
+ When you try running the latter one, the resulting ouptut will be (using
+ PHP 4.01pl2):
+ <informalexample>
+ <programlisting>
+GLOBALS ARE NICE
+GLOBALS ARE NICE
+
+Fatal error: Cannot redeclare goodTea() in utils.inc on line 5
+ </programlisting>
+ </informalexample>
+ By modifying <literal>foolib.inc</literal> and
+ <literal>cause_errror_require.php</literal>
+ to use <function>require_once</function>
+ instead of <function>require</function> and renaming the
+ last one to <literal>avoid_error_require_once.php</literal>, we have:
+ <example>
+ <title>foolib.inc (fixed)</title>
+ <programlisting role="php">
+...
+require_once("utils.inc");
+function showVar($var) {
+...
+ </programlisting>
+ </example>
+ <example>
+ <title>avoid_error_require_once.php</title>
+ <programlisting role="php">
+...
+require_once("foolib.inc");
+require_once("utils.inc");
+$foo = array("1",array("complex","quaternion"));
+...
+ </programlisting>
+ </example>
+ And when running the latter, the output will be (using PHP 4.0.1pl2):
+ <informalexample>
+ <programlisting>
+GLOBALS ARE NICE
+this is requiring globals.inc again which is also
+required in foolib.inc
+Running goodTea: Oolong tea tastes good!
+Printing foo:
+Array
+(
+ [0] => 1
+ [1] => Array
+ (
+ [0] => complex
+ [1] => quaternion
+ )
+
+)
+ </programlisting>
+ </informalexample>
+ </para>
+ <para>
+ Also note that, analogous to the behavior of the
+ <literal>#include</literal> of the C preprocessor, this statement
+ acts at "compile time", e.g. when the script is parsed and before it
+ is executed, and should not be used for parts of the script that need
+ to be inserted dynamically during its execution. You should use
+ <function>include_once</function> or <function>include</function>
+ for that purpose.
+ </para>
+ <para>
+ For more examples on using <function>require_once</function> and
+ <function>include_once</function>, look at the PEAR code included in
+ the latest PHP source code distributions.
+ </para>
+ <para>
+ See also: <function>require</function>,
+ <function>include</function>, <function>include_once</function>,
+ <function>get_required_files</function>,
+ <function>get_included_files</function>, <function>readfile</function>,
+ and <function>virtual</function>.
+ </para>
+ </sect1>
+
+ <sect1 id="function.include-once">
+ <title><function>include_once</function></title>
+ <para>
+ The <function>include_once</function> statement includes and evaluates
+ the specified file during the execution of the script.
+ This is a behavior similar to the <function>include</function> statement,
+ with the important difference that if the code from a file has already
+ been included, it will not be included again.
+ </para>
+ <para>
+ As mentioned in the <function>require_once</function> description, the
+ <function>include_once</function> should be used in the cases in which
+ the same file might be included and evaluated more than once during a
+ particular execution of a script, and you want to be sure that it is
+ included exactly once to avoid problems with function redefinitions,
+ variable value reassignments, etc.
+ </para>
+ <para>
+ For more examples on using <function>require_once</function> and
+ <function>include_once</function>, look at the PEAR code included in
+ the latest PHP source code distributions.
+ </para>
+ <para>
+ <function>include_once</function> was added in PHP 4.0.1pl2
+ </para>
+ <para>
+ See also: <function>require</function>,
+ <function>include</function>, <function>require_once</function>,
+ <function>get_required_files</function>,
+ <function>get_included_files</function>, <function>readfile</function>,
+ and <function>virtual</function>.
+ </para>
+ </sect1>
+
+ </chapter>
+
+ <!-- Keep this comment at the end of the file
+ Local variables:
+ mode: sgml
+ sgml-omittag:t
+ sgml-shorttag:t
+ sgml-minimize-attributes:nil
+ sgml-always-quote-attributes:t
+ sgml-indent-step:1
+ sgml-indent-data:t
+ sgml-parent-document:nil
+ sgml-default-dtd-file:"../../manual.ced"
+ sgml-exposed-tags:nil
+ sgml-local-catalogs:nil
+ sgml-local-ecat-files:nil
+ End:
+ -->
\ No newline at end of file
