cpereira Fri Mar 2 04:10:13 2001 EDT
Modified files:
/phpdoc/pt_BR/language variables.xml
Log:
starting of translation.
putting available for comments of my team
Index: phpdoc/pt_BR/language/variables.xml
diff -u /dev/null phpdoc/pt_BR/language/variables.xml:1.3
--- /dev/null Fri Mar 2 04:10:13 2001
+++ phpdoc/pt_BR/language/variables.xml Fri Mar 2 04:10:12 2001
@@ -0,0 +1,1042 @@
+<?xml encoding="iso-8859-1"?>
+ <chapter id="language.variables">
+ <title>Variables</title>
+
+ <sect1 id="language.variables.basics">
+ <title>Basics</title>
+
+ <simpara>
+ As vari�veis no PHP s�o representadas por um cifr�o($) seguido pelo
+ nome da vari�vel. Os nomes de vari�vel no PHP fazem distin��o entre
+ mai�sculas e min�sculas.
+ Variables in PHP are represented by a dollar sign followed by the
+ name of the variable. The variable name is case-sensitive.
+ </simpara>
+
+ <para>
+ Os nomes de vari�vel seguem as mesmas regras como outros r�tulos no PHP.
+ Um nome de vari�vel v�lido se inicia com uma letra ou sublinhado, seguido
+ de qualquer n�mero de letras, algarismos ou sublinhados. Em uma
+ express�o regular isto poderia ser representado desta forma:
+ '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'
+ </para>
+
+ <note>
+ <simpara>
+ Para nosso prop�sito aqui, letras s�o a-z, A-Z e os caracteres
+ ASCII de 127 a 255 (0x7f-0xff).
+ </simpara>
+ </note>
+
+ <para>
+ <informalexample>
+ <programlisting role="php">
+$var = "Bob";
+$Var = "Joe";
+echo "$var, $Var"; // imprime "Bob, Joe"
+
+$4site = 'not yet'; // inv�lido; come�a com algarismo
+$_4site = 'not yet'; // v�lido; come�a com sublinhado
+$t�yte = 'mansikka'; // v�lido; '�' � ASCII 228.
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ No PHP 3 as vari�veis s�o sempre atribu�das por valor. Isto significa
+ dizer que quando voc� atribui uma express�o a uma vari�vel, o valor
+ da express�o original � copiado integralmente para a vari�vel de destino.
+ Isto significa que, ap�s atribuir o valor de uma vari�vel a
+ outra, a altera��o de uma destas vari�veis n�o afetar� a outra.
+ Para mairoes informa��es sobre este tipo de atribui��o, veja <link
+ linkend="language.expressions">Express�es</link>.
+ </para>
+ <para>
+ PHP 4 oferece um outro meio de atribuir valores a vari�veis:
+ <emphasis>atribui��o por refer�ncia</emphasis>. Isto significa que
+ a nova vari�vel simplesmente referencia (em outras palavras, "torna-se
+ um apelido para" ou "aponta para") a vari�vel original. Altera��es na
+ nova vari�vel afetam a original e vice versa. Isto significa tamb�m que
+ nenhuma c�pia � realizada, de modo que a atribui��o ocorre mais rapidamente.
+ Entretanto, qualquer aumento de velocidade s� ser� realmente notado
+ em *loops* complexos ou em atribui��es de grandes matrizes (*arrays*) ou
+objetos.
+ </para>
+ <para>
+ Para atribuir por refer�ncia, simplesmente adicione um e-comercial (&)
+ na frente do nome da vari�vel que estiver sendo atribu�da (vari�vel de origem)
+ Por exemplo, o trecho de c�digo abaixo imprime 'My name is Bob' duas vezes:
+
+ <informalexample>
+ <programlisting role="php">
+<?php
+$foo = 'Bob'; // Atribui o valor 'Bob' a vari�vel $foo
+$bar = &$foo; // Referecia $foo atrav�s de $bar.
+$bar = "My name is $bar"; // Altera $bar...
+echo $foo; // $foo � alterada tamb�m.
+echo $bar;
+?>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ Uma observa��o importante a se fazer � que somente vari�veis
+ nomeadas podem ser atribu�das por refer�ncia.
+ <informalexample>
+ <programlisting role="php">
+<?php
+$foo = 25;
+$bar = &$foo; // Esta atribui��o � v�lida.
+$bar = &(24 * 7); // Inv�lido; referencia uma express�o sem nome.
+
+function test() {
+ return 25;
+}
+
+$bar = &test(); // Inv�lido.
+?>
+ </programlisting>
+ </informalexample>
+ </para>
+
+ </sect1>
+
+ <sect1 id="language.variables.predefined">
+ <title>Vari�veis Predefinidas</title>
+
+ <simpara>
+ PHP oferece um grande n�mero de vari�veis predefinidas para qualquer
+ script que ele execute. Muitas destas vari�veis, entretanto, n�o podem
+ ser completamente documentadas uma vez dependem de diversos fatores como
+ o servidor no qual scripts s�o executados, a vers�o e configura��o deste
+ servidor, dentre outros fatores. Algumas destas vari�veis n�o estar�o
+ dispon�veis quando o PHP for executado na linha de comando.
+ </simpara>
+
+ <simpara>
+ A despeito destes fatores, temos aqui uma lista de vari�veis predefinidas
+ dispon�veis sob uma instala��o padr�o do PHP 3 executado como um m�dulo
+ em uma instala��o padr�o do <ulink url="&url.apache;">Apache</ulink> 1.3.6.
+ </simpara>
+
+ <simpara>
+ Para obter uma lista de todas as vari�veis predefinidas (e um monte de
+ outras informa��es �teis), veja (e use) <function>phpinfo</function>.
+ </simpara>
+
+ <note>
+ <simpara>
+ This list is neither exhaustive nor intended to be. It is simply
+ a guideline as to what sorts of predefined variables you can
+ expect to have access to in your script.
+ </simpara>
+ </note>
+
+ <sect2 id="language.variables.predefined.apache">
+ <title>Apache variables</title>
+
+ <simpara>
+ These variables are created by the <ulink
+ url="&url.apache;">Apache</ulink> webserver. If you are running
+ another webserver, there is no guarantee that it will provide the
+ same variables; it may omit some, or provide others not listed
+ here. That said, a large number of these variables are accounted
+ for in the <ulink url="&url.cgispec;">CGI 1.1
+ specification</ulink>, so you should be able to expect those.
+ </simpara>
+ <simpara>
+ Note that few, if any, of these will be available (or indeed have
+ any meaning) if running PHP on the command line.
+ </simpara>
+
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>GATEWAY_INTERFACE</term>
+ <listitem>
+ <simpara>
+ What revision of the CGI specification the server is using;
+ i.e. 'CGI/1.1'.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SERVER_NAME</term>
+ <listitem>
+ <simpara>
+ The name of the server host under which the current script is
+ executing. If the script is running on a virtual host, this
+ will be the value defined for that virtual host.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SERVER_SOFTWARE</term>
+ <listitem>
+ <simpara>
+ Server identification string, given in the headers when
+ responding to requests.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SERVER_PROTOCOL</term>
+ <listitem>
+ <simpara>
+ Name and revision of the information protocol via which the
+ page was requested; i.e. 'HTTP/1.0';
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>REQUEST_METHOD</term>
+ <listitem>
+ <simpara>
+ Which request method was used to access the page; i.e. 'GET',
+ 'HEAD', 'POST', 'PUT'.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>QUERY_STRING</term>
+ <listitem>
+ <simpara>
+ The query string, if any, via which the page was accessed.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>DOCUMENT_ROOT</term>
+ <listitem>
+ <simpara>
+ The document root directory under which the current script is
+ executing, as defined in the server's configuration file.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>HTTP_ACCEPT</term>
+ <listitem>
+ <simpara>
+ Contents of the <literal>Accept:</literal> header from the
+ current request, if there is one.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>HTTP_ACCEPT_CHARSET</term>
+ <listitem>
+ <simpara>
+ Contents of the <literal>Accept-Charset:</literal> header
+ from the current request, if there is one. Example:
+ 'iso-8859-1,*,utf-8'.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>HTTP_ENCODING</term>
+ <listitem>
+ <simpara>
+ Contents of the <literal>Accept-Encoding:</literal> header
+ from the current request, if there is one. Example: 'gzip'.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>HTTP_ACCEPT_LANGUAGE</term>
+ <listitem>
+ <simpara>
+ Contents of the <literal>Accept-Language:</literal> header
+ from the current request, if there is one. Example: 'en'.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>HTTP_CONNECTION</term>
+ <listitem>
+ <simpara>
+ Contents of the <literal>Connection:</literal> header from
+ the current request, if there is one. Example: 'Keep-Alive'.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>HTTP_HOST</term>
+ <listitem>
+ <simpara>
+ Contents of the <literal>Host:</literal> header from the
+ current request, if there is one.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>HTTP_REFERER</term>
+ <listitem>
+ <simpara>
+ The address of the page (if any) which referred the browser
+ to the current page. This is set by the user's browser; not
+ all browsers will set this.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>HTTP_USER_AGENT</term>
+ <listitem>
+ <simpara>
+ Contents of the <literal>User_Agent:</literal> header from
+ the current request, if there is one. This is a string
+ denoting the browser software being used to view the current
+ page; i.e. <computeroutput>Mozilla/4.5 [en] (X11; U; Linux
+ 2.2.9 i586)</computeroutput>. Among other things, you can use
+ this value with <function>get_browser</function> to tailor
+ your page's functionality to the capabilities of the user's
+ browser.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>REMOTE_ADDR</term>
+ <listitem>
+ <simpara>
+ The IP address from which the user is viewing the current
+ page.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>REMOTE_PORT</term>
+ <listitem>
+ <simpara>
+ The port being used on the user's machine to communicate with
+ the web server.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SCRIPT_FILENAME</term>
+ <listitem>
+ <simpara>
+ The absolute pathname of the currently executing script.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SERVER_ADMIN</term>
+ <listitem>
+ <simpara>
+ The value given to the SERVER_ADMIN (for Apache) directive in
+ the web server configuration file. If the script is running
+ on a virtual host, this will be the value defined for that
+ virtual host.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SERVER_PORT</term>
+ <listitem>
+ <simpara>
+ The port on the server machine being used by the web server
+ for communication. For default setups, this will be '80';
+ using SSL, for instance, will change this to whatever your
+ defined secure HTTP port is.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SERVER_SIGNATURE</term>
+ <listitem>
+ <simpara>
+ String containing the server version and virtual host name
+ which are added to server-generated pages, if enabled.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PATH_TRANSLATED</term>
+ <listitem>
+ <simpara>
+ Filesystem- (not document root-) based path to the current
+ script, after the server has done any virtual-to-real
+ mapping.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SCRIPT_NAME</term>
+ <listitem>
+ <simpara>
+ Contains the current script's path. This is useful for pages
+ which need to point to themselves.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>REQUEST_URI</term>
+ <listitem>
+ <simpara>
+ The URI which was given in order to access this page; for
+ instance, '/index.html'.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ </sect2>
+
+ <sect2 id="language.variables.predefined.environment">
+ <title>Environment variables</title>
+
+ <simpara>
+ These variables are imported into PHP's global namespace from the
+ environment under which the PHP parser is running. Many are
+ provided by the shell under which PHP is running and different
+ systems are likely running different kinds of shells, a
+ definitive list is impossible. Please see your shell's
+ documentation for a list of defined environment variables.
+ </simpara>
+ <simpara>
+ Other environment variables include the CGI variables, placed
+ there regardless of whether PHP is running as a server module or
+ CGI processor.
+ </simpara>
+
+ </sect2>
+
+ <sect2 id="language.variables.predefined.php">
+ <title>PHP variables</title>
+
+ <simpara>
+ These variables are created by PHP itself. The
+ <varname>$HTTP_*_VARS</varname> variables are available only if
+ the <link linkend="ini.track-vars">track_vars</link>
+ configuration is turned on. When enabled, the variables are
+ always set, even if they are empty arrays. This prevents
+ a malicious user from spoofing these variables.
+ </simpara>
+
+ <note>
+ <para>
+ As of PHP 4.0.3, <link
+ linkend="ini.track-vars">track_vars</link> is always turned on,
+ regardless of the configuration file setting.
+ </para>
+ </note>
+
+ <para>
+ If the <link
+ linkend="ini.register-globals">register_globals</link> directive
+ is set, then these variables will also be made available in the
+ global scope of the script; i.e., separate from the
+ <varname>$HTTP_*_VARS</varname> arrays. This feature should be
+ used with care, and turned off if possible; while the
+ <varname>$HTTP_*_VARS</varname> variables are safe, the bare
+ global equivalents can be overwritten by user input, with
+ possibly malicious intent. If you cannot turn off <link
+ linkend="ini.register-globals">register_globals</link>, you must
+ take whatever steps are necessary to ensure that the data you are
+ using is safe.
+ </para>
+
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>argv</term>
+ <listitem>
+ <simpara>
+ Array of arguments passed to the script. When the script is
+ run on the command line, this gives C-style access to the
+ command line parameters. When called via the GET method, this
+ will contain the query string.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>argc</term>
+ <listitem>
+ <simpara>
+ Contains the number of command line parameters passed to the
+ script (if run on the command line).
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PHP_SELF</term>
+ <listitem>
+ <simpara>
+ The filename of the currently executing script, relative to
+ the document root. If PHP is running as a command-line
+ processor, this variable is not available.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>HTTP_COOKIE_VARS</term>
+ <listitem>
+ <simpara>
+ An associative array of variables passed to the current
+ script via HTTP cookies.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>HTTP_GET_VARS</term>
+ <listitem>
+ <simpara>
+ An associative array of variables passed to the current
+ script via the HTTP GET method.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>HTTP_POST_VARS</term>
+ <listitem>
+ <simpara>
+ An associative array of variables passed to the current
+ script via the HTTP POST method.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>HTTP_POST_FILES</term>
+ <listitem>
+ <simpara>
+ An associative array of variables containing information
+ about files uploaded via the HTTP POST method. See <link
+ linkend="features.file-upload.post-method">POST method
+ uploads</link> for information on the contents of
+ <varname>$HTTP_POST_FILES</varname>.
+ </simpara>
+ <para>
+ <varname>$HTTP_POST_FILES</varname> is available only in PHP
+ 4.0.0 and later.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>HTTP_ENV_VARS</term>
+ <listitem>
+ <simpara>
+ An associative array of variables passed to the current
+ script via the parent environment.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>HTTP_SERVER_VARS</term>
+ <listitem>
+ <simpara>
+ An associative array of variables passed to the current
+ script from the HTTP server. These variables are analogous to
+ the Apache variables described above.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ </sect2>
+
+ </sect1>
+
+
+ <sect1 id="language.variables.scope">
+ <title>Variable scope</title>
+
+ <simpara>
+ The scope of a variable is the context within which it is defined.
+ For the most part all PHP variables only have a single scope.
+ This single scope spans included and required files as well. For
+ example:
+ </simpara>
+ <informalexample>
+ <programlisting role="php">
+$a = 1;
+include "b.inc";
+ </programlisting>
+ </informalexample>
+ <simpara>
+ Here the <varname>$a</varname> variable will be available within
+ the included <filename>b.inc</filename> script. However, within
+ user-defined functions a local function scope is introduced. Any
+ variable used inside a function is by default limited to the local
+ function scope. For example:
+ </simpara>
+
+ <informalexample>
+ <programlisting role="php">
+$a = 1; /* global scope */
+
+Function Test () {
+ echo $a; /* reference to local scope variable */
+}
+
+Test ();
+ </programlisting>
+ </informalexample>
+
+ <simpara>
+ This script will not produce any output because the echo statement
+ refers to a local version of the <varname>$a</varname> variable,
+ and it has not been assigned a value within this scope. You may
+ notice that this is a little bit different from the C language in
+ that global variables in C are automatically available to
+ functions unless specifically overridden by a local definition.
+ This can cause some problems in that people may inadvertently
+ change a global variable. In PHP global variables must be
+ declared global inside a function if they are going to be used in
+ that function. An example:
+ </simpara>
+
+ <informalexample>
+ <programlisting role="php">
+$a = 1;
+$b = 2;
+
+Function Sum () {
+ global $a, $b;
+
+ $b = $a + $b;
+}
+
+Sum ();
+echo $b;
+ </programlisting>
+ </informalexample>
+
+ <simpara>
+ The above script will output "3". By declaring
+ <varname>$a</varname> and <varname>$b</varname> global within the
+ function, all references to either variable will refer to the
+ global version. There is no limit to the number of global
+ variables that can be manipulated by a function.
+ </simpara>
+
+ <simpara>
+ A second way to access variables from the global scope is to use
+ the special PHP-defined <varname>$GLOBALS</varname> array. The
+ previous example can be rewritten as:
+ </simpara>
+
+ <informalexample>
+ <programlisting role="php">
+$a = 1;
+$b = 2;
+
+Function Sum () {
+ $GLOBALS["b"] = $GLOBALS["a"] + $GLOBALS["b"];
+}
+
+Sum ();
+echo $b;
+ </programlisting>
+ </informalexample>
+
+ <simpara>
+ The <varname>$GLOBALS</varname> array is an associative array with
+ the name of the global variable being the key and the contents of
+ that variable being the value of the array element.
+ </simpara>
+
+ <simpara>
+ Another important feature of variable scoping is the
+ <emphasis>static</emphasis> variable. A static variable exists
+ only in a local function scope, but it does not lose its value
+ when program execution leaves this scope. Consider the following
+ example:
+ </simpara>
+
+ <informalexample>
+ <programlisting role="php">
+Function Test () {
+ $a = 0;
+ echo $a;
+ $a++;
+}
+ </programlisting>
+ </informalexample>
+
+ <simpara>
+ This function is quite useless since every time it is called it
+ sets <varname>$a</varname> to <literal>0</literal> and prints
+ "0". The <varname>$a</varname>++ which increments the
+ variable serves no purpose since as soon as the function exits the
+ <varname>$a</varname> variable disappears. To make a useful
+ counting function which will not lose track of the current count,
+ the <varname>$a</varname> variable is declared static:
+ </simpara>
+
+ <informalexample>
+ <programlisting role="php">
+Function Test () {
+ static $a = 0;
+ echo $a;
+ $a++;
+}
+ </programlisting>
+ </informalexample>
+
+ <simpara>
+ Now, every time the Test() function is called it will print the
+ value of <varname>$a</varname> and increment it.
+ </simpara>
+
+ <simpara>
+ Static variables also provide one way to deal with recursive
+ functions. A recursive function is one which calls itself. Care
+ must be taken when writing a recursive function because it is
+ possible to make it recurse indefinitely. You must make sure you
+ have an adequate way of terminating the recursion. The following
+ simple function recursively counts to 10, using the static
+ variable <varname>$count</varname> to know when to stop:
+ </simpara>
+
+ <informalexample>
+ <programlisting role="php">
+Function Test () {
+ static $count = 0;
+
+ $count++;
+ echo $count;
+ if ($count < 10) {
+ Test ();
+ }
+ $count--;
+}
+ </programlisting>
+ </informalexample>
+
+ </sect1>
+
+ <sect1 id="language.variables.variable">
+ <title>Variable variables</title>
+
+ <simpara>
+ Sometimes it is convenient to be able to have variable variable
+ names. That is, a variable name which can be set and used
+ dynamically. A normal variable is set with a statement such as:
+ </simpara>
+
+ <informalexample>
+ <programlisting role="php">
+$a = "hello";
+ </programlisting>
+ </informalexample>
+
+ <simpara>
+ A variable variable takes the value of a variable and treats that
+ as the name of a variable. In the above example,
+ <emphasis>hello</emphasis>, can be used as the name of a variable
+ by using two dollar signs. i.e.
+ </simpara>
+
+ <informalexample>
+ <programlisting role="php">
+$$a = "world";
+ </programlisting>
+ </informalexample>
+
+ <simpara>
+ At this point two variables have been defined and stored in the
+ PHP symbol tree: <varname>$a</varname> with contents "hello" and
+ <varname>$hello</varname> with contents "world". Therefore, this
+ statement:
+ </simpara>
+
+ <informalexample>
+ <programlisting role="php">
+echo "$a ${$a}";
+ </programlisting>
+ </informalexample>
+
+ <simpara>
+ produces the exact same output as:
+ </simpara>
+
+ <informalexample>
+ <programlisting>
+echo "$a $hello";
+ </programlisting>
+ </informalexample>
+
+ <simpara>
+ i.e. they both produce: <computeroutput>hello world</computeroutput>.
+ </simpara>
+
+ <simpara>
+ In order to use variable variables with arrays, you have to
+ resolve an ambiguity problem. That is, if you write
+ <varname>$$a[1]</varname> then the parser needs to know if you
+ meant to use <varname>$a[1]</varname> as a variable, or if you
+ wanted <varname>$$a</varname> as the variable and then the [1]
+ index from that variable. The syntax for resolving this ambiguity
+ is: <varname>${$a[1]}</varname> for the first case and
+ <varname>${$a}[1]</varname> for the second.
+ </simpara>
+
+ </sect1>
+
+ <sect1 id="language.variables.external">
+ <title>Variables from outside PHP</title>
+
+ <sect2 id="language.variables.external.form">
+ <title>HTML Forms (GET and POST)</title>
+
+ <simpara>
+ When a form is submitted to a PHP script, any variables from that
+ form will be automatically made available to the script by
+ PHP. If the <link linkend="ini.track-vars">track_vars</link>
+ configuration option is turned on, then these variables will be
+ located in the associative arrays
+ <varname>$HTTP_POST_VARS</varname>,
+ <varname>$HTTP_GET_VARS</varname>, and/or
+ <varname>$HTTP_POST_FILES</varname>, according to the
+ source of the variable in question.
+ </simpara>
+
+ <para>
+ For more information on these variables, please read <link
+ linkend="language.variables.predefined">Predefined
+ variables</link>.
+ </para>
+
+ <para>
+ <example>
+ <title>Simple form variable</title>
+ <programlisting role="php">
+<form action="foo.php" method="post">
+ Name: <input type="text" name="username"><br>
+ <input type="submit">
+</form>
+ </programlisting>
+ </example>
+ </para>
+
+ <para>
+ When the above form is submitted, the value from the text input
+ will be available in
+ <varname>$HTTP_POST_VARS['username']</varname>. If the <link
+ linkend="ini.register-globals">register_globals</link>
+ configuration directive is turned on, then the variable will also
+ be available as <varname>$username</varname> in the global scope.
+ </para>
+
+ <simpara>
+ PHP also understands arrays in the context of form variables. You
+ may, for example, group related variables together, or use this
+ feature to retrieve values from a multiple select
+ input:
+ </simpara>
+
+ <para>
+ <example>
+ <title>More complex form variables</title>
+ <programlisting role="php">
+<form action="array.php" method="post">
+ Name: <input type="text" name="personal[name]"><br>
+ Email: <input type="text" name="personal[email]"><br>
+ Beer: <br>
+ <select multiple name="beer[]">
+ <option value="warthog">Warthog
+ <option value="guinness">Guinness
+ <option value="stuttgarter">Stuttgarter Schwabenbräu
+ </select>
+ <input type="submit">
+</form>
+ </programlisting>
+ </example>
+ </para>
+
+ <para>
+ In PHP 3, the array form variable usage is limited to
+ single-dimensional arrays. In PHP 4, no such restriction applies.
+ </para>
+
+ <sect3 id="language.variables.external.form.submit">
+ <title>IMAGE SUBMIT variable names</title>
+
+ <simpara>
+ When submitting a form, it is possible to use an image instead
+ of the standard submit button with a tag like:</simpara>
+
+ <informalexample>
+ <programlisting role="php">
+<input type=image src="image.gif" name="sub">
+ </programlisting>
+ </informalexample>
+
+ <simpara>
+ When the user clicks somewhere on the image, the accompanying
+ form will be transmitted to the server with two additional
+ variables, sub_x and sub_y. These contain the coordinates of the
+ user click within the image. The experienced may note that the
+ actual variable names sent by the browser contains a period
+ rather than an underscore, but PHP converts the period to an
+ underscore automatically.
+ </simpara>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="language.variables.external.cookies">
+ <title>HTTP Cookies</title>
+
+ <simpara>
+ PHP transparently supports HTTP cookies as defined by <ulink
+ url="&spec.cookies;">Netscape's Spec</ulink>. Cookies are a
+ mechanism for storing data in the remote browser and thus
+ tracking or identifying return users. You can set cookies using
+ the <function>SetCookie</function> function. Cookies are part of
+ the HTTP header, so the SetCookie function must be called before
+ any output is sent to the browser. This is the same restriction
+ as for the <function>Header</function> function. Any cookies
+ sent to you from the client will automatically be turned into a
+ PHP variable just like GET and POST method data.</simpara>
+
+ <simpara>
+ If you wish to assign multiple values to a single cookie, just
+ add <emphasis>[]</emphasis> to the cookie name. For
+ example:
+ </simpara>
+
+ <informalexample>
+ <programlisting role="php">
+SetCookie ("MyCookie[]", "Testing", time()+3600);
+ </programlisting>
+ </informalexample>
+
+ <simpara>
+ Note that a cookie will replace a previous cookie by the same
+ name in your browser unless the path or domain is different. So,
+ for a shopping cart application you may want to keep a counter
+ and pass this along. i.e.
+ </simpara>
+
+ <example>
+ <title>SetCookie Example</title>
+ <programlisting role="php">
+$Count++;
+SetCookie ("Count", $Count, time()+3600);
+SetCookie ("Cart[$Count]", $item, time()+3600);
+ </programlisting>
+ </example>
+
+ </sect2>
+
+ <sect2 id="language.variables.external.environment">
+ <title>Environment variables</title>
+
+ <para>
+ PHP automatically makes environment variables available as normal
+ PHP variables.
+
+ <informalexample>
+ <programlisting role="php">
+echo $HOME; /* Shows the HOME environment variable, if set. */
+ </programlisting>
+ </informalexample>
+ </para>
+
+ <para>
+ Since information coming in via GET, POST and Cookie mechanisms
+ also automatically create PHP variables, it is sometimes best to
+ explicitly read a variable from the environment in order to make
+ sure that you are getting the right version. The
+ <function>getenv</function> function can be used for this. You
+ can also set an environment variable with the
+ <function>putenv</function> function.
+ </para>
+ </sect2>
+
+ <sect2 id="language.variables.external.dot-in-names">
+ <title>Dots in incoming variable names</title>
+
+ <para>
+ Typically, PHP does not alter the names of variables when they
+ are passed into a script. However, it should be noted that the
+ dot (period, full stop) is not a valid character in a PHP
+ variable name. For the reason, look at it:
+ <programlisting role="php">
+$varname.ext; /* invalid variable name */
+ </programlisting>
+ Now, what the parser sees is a variable named
+ <varname>$varname</varname>, followed by the string concatenation
+ operator, followed by the barestring (i.e. unquoted string which
+ doesn't match any known key or reserved words) 'ext'. Obviously,
+ this doesn't have the intended result.
+ </para>
+
+ <para>
+ For this reason, it is important to note that PHP will
+ automatically replace any dots in incoming variable names with
+ underscores.
+ </para>
+
+ </sect2>
+
+ <sect2 id="language.variables.determining-type-of">
+ <title>Determining variable types</title>
+
+ <para>
+ Because PHP determines the types of variables and converts them
+ (generally) as needed, it is not always obvious what type a given
+ variable is at any one time. PHP includes several functions
+ which find out what type a variable is. They are
+ <function>gettype</function>, <function>is_long</function>,
+ <function>is_double</function>, <function>is_string</function>,
+ <function>is_array</function>, and
+ <function>is_object</function>.
+ </para>
+ </sect2>
+
+ </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:
+ -->
