shlomi Tue Feb 5 21:46:20 2002 EDT
Added files:
/phpdoc/he/language variables.xml
Log:
half translated...
Index: phpdoc/he/language/variables.xml
+++ phpdoc/he/language/variables.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- EN-Revision: 1.33 Maintainer: shlomi Status: working -->
<chapter id="language.variables">
<title>Variables</title>
<sect1 id="language.variables.basics">
<title>Basics</title>
<simpara>
������ �-PHP ������� ��-��� �� �� ���� ����� �������.
����� ����� ��� ������ ������� ������� ������ �����
������� (case-sensitive).
</simpara>
<para>
���� �� ������ �-PHP ����� �� ���� ���� ������.
�� ����� ���� ����� �� ��� �� �� ���-������ ������ ����
��� �� ������ ������ �� ��-�����. ���� ���� �� ������
�� ������ ����� ����� ������ ���:
'[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'
</para>
<note>
<simpara>
������ �� ��� ����� a-z,A-Z ���� �-ASCII ��� ���� 127 ��
�� 255 (0x7f-0xff) .
</simpara>
</note>
<para>
<informalexample>
<programlisting role="php">
<![CDATA[
$var = "Bob";
$Var = "Joe";
echo "$var, $Var"; // outputs "Bob, Joe"
$4site = 'not yet'; // invalid; starts with a number
$_4site = 'not yet'; // valid; starts with an underscore
$t�yte = 'mansikka'; // valid; '�' is ASCII 228.
]]>
</programlisting>
</informalexample>
</para>
<para>
�-PHP 3 ���� ������ ����� ������. �����, ���� ���� �����
������, ����� ���� �� �� ������ ���� ������. ���� ���� ��
���� �� ����� ������ ������ ���, ����� ���� �� ��� �������
�� ����� �� ������ ����. ����� ���� ����� �� ����� ����
�<link
linkend="language.expressions">�������</link>.
</para>
<para>
��� ����� 4 �� PHP ���� ������ ���� ����� ����� ������:
<emphasis>���� ����� �����(reference)</emphasis>.
����� ���� ����� ����� ��� ������
(������ ����� "����� �" �� "���� ������ ��" �����)
������ ������. ����� ����� �� ������ ���� ����� �� ��
������ ������ �����. �� ������ ��� ����� ���� �����
������ ����� ����� ���� �� �� ���� ������ ����� �����
��� �� ����� ������� ������ �� ���� �� ������ ����������
������ ������.
</para>
<para>
��� ���� ���� ����� ����� �� ������ ������� (&) ������
�� ������ �������� ���� (����� �����). ������, ������� ���
����� ������ �� �������
'My name is Bob' :
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$foo = 'Bob'; // Assign the value 'Bob' to $foo
$bar = &$foo; // Reference $foo via $bar.
$bar = "My name is $bar"; // Alter $bar...
echo $foo; // $foo is altered too.
echo $bar;
?>
]]>
</programlisting>
</informalexample>
</para>
<para>
���� ����� �� �� ����� ��� �� ���� ���� ���� ����� �����.
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$foo = 25;
$bar = &$foo; // ����� �����
$bar = &(24 * 7); // ����� �� �����, ������ ������ ��� ��
function test()
{
return 25;
}
$bar = &test(); // �� ����
?>
]]>
</programlisting>
</informalexample>
</para>
</sect1>
<sect1 id="language.variables.predefined">
<title>������ ������� ����</title>
<simpara>
PHP ����� ���� ���� �� ������ "������� ����" ��� ������ ����
�����. ��� ������� ��� �� ������� ����� ��� �� �� ������ ����,
������, ��������� �������� ������. ��� ������� ��� �� ���� �����
���� ������ PHP ���� ����� ������.
</simpara>
<simpara>
����� ������ ���, ������ ����� �� ������ ������� ���� �������
������ ����� �� PHP ����� 3 ������ �� ��� <ulink
url="&url.apache;">Apache</ulink> 1.3.6.
</simpara>
<simpara>
����� ����� ���� �� �� �������� ���� ������� ������
(����� ���� ������ ����),
�� ����� ������� �������� <function>phpinfo</function>.
</simpara>
<note>
<simpara>
����� �� ���� ���� ����� ������� ����� ���. �� �����
������ ���� ����-����� ���� ������� �������� ���� �����
����� �� ���� ������ ��� ���� ������.
</simpara>
</note>
<sect2 id="language.variables.predefined.apache">
<title>������ �� ��� Apache</title>
<simpara>
������ ��� ������� ��-��� ��� <ulink
url="&url.apache;">Apache</ulink>. ��� ����� ��� ���� ��
���� ���� ������� ��� �� ������� ����� ������� ������
����� ����� ������ ��. ��� ������� ������� �<ulink url="&url.cgispec;">����
CGI 1.1</ulink> ����� ����� ������ ������.
</simpara>
<simpara>
�� ����� �� �� ������� ���� �� ���� ������� �����
������ PHP ����� ������.
</simpara>
<para>
<variablelist>
<varlistentry>
<term>$GATEWAY_INTERFACE</term>
<listitem>
<simpara>
���� �-CGI ����� ���� ��.
(����-��� 'CGI/1.1' ).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$SERVER_NAME</term>
<listitem>
<simpara>
�� �-host ������ �� ������� ������. �� ������� �� ��� host
��������, ����� �� ���� �� �� �-host ���������.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$SERVER_SOFTWARE</term>
<listitem>
<simpara>
������ ������ �� ���� ������� ������� (headers) ���
���� ������ (requests).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$SERVER_PROTOCOL</term>
<listitem>
<simpara>
�� ����� ��������� ����� ������.
(����-��� 'HTTP/1.0' )
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$REQUEST_METHOD</term>
<listitem>
<simpara>
��� ����� ������� ������ ����� ����. ���� ������ ����:
'GET','HEAD', 'POST', 'PUT'.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$QUERY_STRING</term>
<listitem>
<simpara>
������ ������ (query string) ����� ������ ���� �����.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$DOCUMENT_ROOT</term>
<listitem>
<simpara>
������ ������ ������ �� ������� ������ ���
������ ����.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$HTTP_ACCEPT</term>
<listitem>
<simpara>
����� ���� �-<literal>Accept:</literal> ������ �������,
�� ���� ���� ���.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$HTTP_ACCEPT_CHARSET</term>
<listitem>
<simpara>
����� ���� �-<literal>Accept-Charset:</literal> ������ �������,
�� ���� ���� ���. ������:
'iso-8859-1,*,utf-8'.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$HTTP_ACCEPT_ENCODING</term>
<listitem>
<simpara>
����� ���� �-<literal>Accept-Encoding:</literal> ������ �������,
�� ���� ���� ���. ������:
'gzip'.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$HTTP_ACCEPT_LANGUAGE</term>
<listitem>
<simpara>
����� ���� �-<literal>Accept-Language:</literal> ������ �������,
�� ���� ���� ���. ������:
'en'.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$HTTP_CONNECTION</term>
<listitem>
<simpara>
����� ���� �-<literal>Connection:</literal> ������ �������,
�� ���� ���� ���. ������:
'Keep-Alive'.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$HTTP_HOST</term>
<listitem>
<simpara>
����� ���� �-<literal>Host:</literal> ������ �������,
�� ���� ���� ���.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$HTTP_REFERER</term>
<listitem>
<simpara>
������ �� ����� (�� ����) ����� �� ������ ����� ������.
����� �� ���� ��-��� ����� ������. �� �� �������� ������
������� ��.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$HTTP_USER_AGENT</term>
<listitem>
<simpara>
����� ���� �-<literal>User_Agent:</literal> ������ �������,
�� ���� ���� ���. ���� ������ ������� ��� ������ �����
������ ����� ������. ����:<computeroutput>Mozilla/4.5 [en] (X11; U; Linux
2.2.9 i586)</computeroutput>. ���� ������ ���� �� �����
�������� <function>get_browser</function> ��� ����� �����
�� ����� ��� ������� ������� ����� �� ������.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$REMOTE_ADDR</term>
<listitem>
<simpara>
����� �- IP ����� ������ ���� ����� ������.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$REMOTE_PORT</term>
<listitem>
<simpara>
�-port ����� ����� ����� �� ������ �� ����.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$SCRIPT_FILENAME</term>
<listitem>
<simpara>
�� ����� (pathname) ��������� ��� ���� ������� ������.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$SERVER_ADMIN</term>
<listitem>
<simpara>
���� ������ �������� �-SERVER_ADMIN �� ��� Apache ����� �������
�� ����. �� ������� �� ��� host
��������, ����� �� ����� �-host �������� ��.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$SERVER_PORT</term>
<listitem>
<simpara>
���� �-port ����� ������� �� ����. ����� ����� ��� 80.
���� ������� �-SSL ����, ���� �� ����� ��� �-port ������
�-secure HTTP port .
</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>
���� ����� ��� ����� ������ �� ������� ������
(�� �� document root �� �������)
���� ����� ����� �������� ������.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$SCRIPT_NAME</term>
<listitem>
<simpara>
���� �� ���� ������� ������. ������ ������� �������� �����.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$REQUEST_URI</term>
<listitem>
<simpara>
����� �-URI ������ ����� ����� ������. ������:
/index.html'.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 id="language.variables.predefined.environment">
<title>����� �����</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>
<note>
<para>
The new "Superglobals" were added in PHP version 4.1.0. See the
<ulink url="&url.php.release4.1.0;">4.1.0 Release
Announcement</ulink> for more details. These are the
<varname>$_GET</varname>, <varname>$_POST</varname>,
<varname>$_ENV</varname>, <varname>$_SERVER</varname>,
<varname>$_COOKIE</varname>, <varname>$_REQUEST</varname>
<varname>$_FILES</varname>, and <varname>$_SESSION</varname>
arrays, and they are informally known as
<emphasis>Superglobals</emphasis> since they are always
available without regard to scope. These deprecate the older
respective <varname>$HTTP_*_VARS</varname> arrays.
</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> and <varname>$_*</varname>
arrays. For related information, see the security chapter titled
<link linkend="security.registerglobals">Using Register Globals</link>.
</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>$_COOKIE</term>
<listitem>
<simpara>
An associative array of variables passed to the current
script via HTTP cookies. Automatically global in any
scope. Introduced in PHP 4.1.0.
</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>$_GET</term>
<listitem>
<simpara>
An associative array of variables passed to the current
script via the HTTP GET method. Automatically global in
any scope. Introduced in PHP 4.1.0.
</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>$_POST</term>
<listitem>
<simpara>
An associative array of variables passed to the current
script via the HTTP POST method. Automatically global in
any scope. Introduced in PHP 4.1.0.
</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>. Introduced in 4.0.0.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$_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>$_FILES</varname>. Automatically global in any scope.
Introduced in PHP 4.1.0.
</simpara>
</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>$_ENV</term>
<listitem>
<simpara>
An associative array of variables passed to the current
script via the parent environment. Automagically global
in any scope. Introduced in PHP 4.1.0.
</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>
<varlistentry>
<term>$_SERVER</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. Automatically global
in any scope. Introduced in PHP 4.1.0.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$HTTP_SESSION_VARS</term>
<listitem>
<simpara>
An associative array of session variables passed to the current
script.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$_SESSION</term>
<listitem>
<simpara>
An associative array of session variables passed to the
current script. Automatically global in any scope. Creating
new entries in the $_SESSION array will automatically
register them as session variables, as if you called
<function>session_register</function>. Introduced in PHP 4.1.0.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>$_REQUEST</term>
<listitem>
<simpara>
An associative array merged from the GET, POST, and Cookie variables.
In other words - all the information that is coming from the user,
and that from a security point of view, cannot be trusted.
Automatically global in any scope. Introduced in PHP 4.1.0.
</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">
<![CDATA[
$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">
<![CDATA[
$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">
<![CDATA[
$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">
<![CDATA[
$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">
<![CDATA[
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">
<![CDATA[
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">
<![CDATA[
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">
<![CDATA[
$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">
<![CDATA[
$$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">
<![CDATA[
echo "$a ${$a}";
]]>
</programlisting>
</informalexample>
<simpara>
produces the exact same output as:
</simpara>
<informalexample>
<programlisting role="php">
<![CDATA[
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">
<![CDATA[
<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>
<note>
<para>
The <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link>
configuration directive affects Get, Post and Cookie values. If
turned on, value (It's "PHP!") will automagically become (It\'s \"PHP!\").
Escaping is needed for DB insertion. Also see
<function>addslashes</function>, <function>stripslashes</function> and
<link linkend="ini.magic-quotes-sybase">magic_quotes_sybase</link>.
</para>
</note>
<simpara>
PHP also understands arrays in the context of form variables
(see the <link linkend="faq.html">related faq</link>). 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">
<![CDATA[
<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">
<![CDATA[
<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">
<![CDATA[
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">
<![CDATA[
$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">
<![CDATA[
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">
<![CDATA[
$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
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
-->
