<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.93 $ -->
<chapter id="language.variables">
<title>Variables</title>
<sect1 id="language.variables.basics">
<title>Basics</title>
<simpara>
Variables in PHP are represented by a dollar sign followed by the
name of the variable. The variable name is case-sensitive.
</simpara>
<para>
Variable names follow the same rules as other labels in PHP. A
valid variable name starts with a letter or underscore, followed
by any number of letters, numbers, or underscores. As a regular
expression, it would be expressed thus:
'[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'
</para>
<note>
<simpara>
For our purposes here, a letter is a-z, A-Z, and the ASCII
characters from 127 through 255 (0x7f-0xff).
</simpara>
</note>
&tip.userlandnaming;
<para>
For information on variable related functions, see the
<link linkend="ref.var">Variable Functions Reference</link>.
</para>
<para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$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 (Extended) ASCII 228.
?>
]]>
</programlisting>
</informalexample>
</para>
<para>
In PHP 3, variables are always assigned by value. That is to say,
when you assign an expression to a variable, the entire value of
the original expression is copied into the destination
variable. This means, for instance, that after assigning one
variable's value to another, changing one of those variables will
have no effect on the other. For more information on this kind of
assignment, see the chapter on <link
linkend="language.expressions">Expressions</link>.
</para>
<para>
As of PHP 4, PHP offers another way to assign values to variables:
<link linkend="language.references">assign by reference</link>.
This means that the new variable simply references (in other words,
"becomes an alias for" or "points to") the original variable.
Changes to the new variable affect the original, and vice versa.
</para>
<para>
To assign by reference, simply prepend an ampersand (&) to the
beginning of the variable which is being assigned (the source
variable). For instance, the following code snippet outputs 'My
name is Bob' twice:
<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 $bar;
echo $foo; // $foo is altered too.
?>
]]>
</programlisting>
</informalexample>
</para>
<para>
One important thing to note is that only named variables may be
assigned by reference.
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$foo = 25;
$bar = &$foo; // This is a valid assignment.
$bar = &(24 * 7); // Invalid; references an unnamed expression.
function test()
{
return 25;
}
$bar = &test(); // Invalid.
?>
]]>
</programlisting>
</informalexample>
</para>
<para>
It is not necessary to initialize variables in PHP however it is a very
good practice. Uninitialized variables have a default value of their type
- &false;, zero, empty string or an empty array.
</para>
<para>
<example>
<title>Default values of uninitialized variables</title>
<programlisting role="php">
<![CDATA[
<?php
echo ($unset_bool ? "true" : "false"); // false
$unset_int += 25; // 0 + 25 => 25
echo $unset_string . "abc"; // "" . "abc" => "abc"
$unset_array[3] = "def"; // array() + array(3 => "def") => array(3 => "def")
?>
]]>
</programlisting>
</example>
</para>
<para>
Relying on the default value of an uninitialized variable is problematic
in the case of including one file into another which uses the same
variable name. It is also a major <link
linkend="security.globals">security risk</link> with <link
linkend="ini.register-globals">register_globals</link> turned on. <link
linkend="e-notice">E_NOTICE</link> level error is issued in case of
working with uninitialized variables, however not in the case of appending
elements to the uninitialized array. <function>isset</function> language
construct can be used to detect if a variable has been already initialized.
</para>
</sect1>
<sect1 id="language.variables.predefined">
<title>Predefined variables</title>
<simpara>
PHP provides a large number of predefined variables to any script
which it runs. Many of these variables, however, cannot be fully
documented as they are dependent upon which server is running, the
version and setup of the server, and other factors. Some of these
variables will not be available when PHP is run on the
<link linkend="features.commandline">command line</link>.
For a listing of these variables, please see the section on
<link linkend="reserved.variables">Reserved Predefined Variables</link>.
</simpara>
<warning>
<simpara>
In PHP 4.2.0 and later, the default value for the PHP directive <link
linkend="ini.register-globals">register_globals</link> is
<emphasis>off</emphasis>. This is a major change in PHP. Having
register_globals <emphasis>off</emphasis> affects the set of predefined
variables available in the global scope. For example, to get
<varname>DOCUMENT_ROOT</varname> you'll use
<varname>$_SERVER['DOCUMENT_ROOT']</varname> instead of
<varname>$DOCUMENT_ROOT</varname>, or <varname>$_GET['id']</varname> from
the URL <literal>http://www.example.com/test.php?id=3</literal> instead
of <varname>$id</varname>, or <varname>$_ENV['HOME']</varname> instead of
<varname>$HOME</varname>.
</simpara>
<simpara>
For related information on this change, read the configuration entry for
<link linkend="ini.register-globals">register_globals</link>, the security
chapter on <link linkend="security.globals">Using Register Globals
</link>, as well as the PHP <ulink url="&url.php.release4.1.0;">4.1.0
</ulink> and <ulink url="&url.php.release4.2.0;">4.2.0</ulink> Release
Announcements.
</simpara>
<simpara>
Using the available PHP Reserved Predefined Variables, like the
<link linkend="language.variables.superglobals">superglobal arrays</link>,
is preferred.
</simpara>
</warning>
<simpara>
From version 4.1.0 onward, PHP provides an additional set of predefined arrays
containing variables from the web server (if applicable), the
environment, and user input. These new arrays are rather special
in that they are automatically global--i.e., automatically
available in every scope. For this reason, they are often known as
"superglobals". (There is no mechanism in PHP for
user-defined superglobals.) The superglobals are listed below;
however, for a listing of their contents and further discussion on
PHP predefined variables and their natures, please see the section
<link linkend="reserved.variables">Reserved Predefined Variables</link>.
Also, you'll notice how the older predefined variables
(<varname>$HTTP_*_VARS</varname>) still exist.
&avail.register-long-arrays;
</simpara>
<note>
<title>Variable variables</title>
<para>
Superglobals cannot be used as
<link linkend="language.variables.variable">variable variables</link>
inside functions or class methods.
</para>
</note>
<note>
<para>
Even though both the superglobal and HTTP_*_VARS can exist at the same
time; they are not identical, so modifying one will not change the other.
</para>
</note>
<para>
If certain variables in <link
linkend="ini.variables-order">variables_order</link> are not set, their
appropriate PHP predefined arrays are also left empty.
</para>
<variablelist id="language.variables.superglobals">
<title>PHP Superglobals</title>
<varlistentry>
<term><link linkend="reserved.variables.globals">$GLOBALS</link></term>
<listitem>
<simpara>
Contains a reference to every variable which is currently
available within the global scope of the script. The keys of
this array are the names of the global variables.
<varname>$GLOBALS</varname> has existed since PHP 3.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="reserved.variables.server">$_SERVER</link></term>
<listitem>
<simpara>
Variables set by the web server or otherwise directly related
to the execution environment of the current script. Analogous
to the old <varname>$HTTP_SERVER_VARS</varname> array (which is
still available, but deprecated).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="reserved.variables.get">$_GET</link></term>
<listitem>
<simpara>
Variables provided to the script via URL query string. Analogous to the
old <varname>$HTTP_GET_VARS</varname> array (which is still
available, but deprecated).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="reserved.variables.post">$_POST</link></term>
<listitem>
<simpara>
Variables provided to the script via HTTP POST. Analogous to the
old <varname>$HTTP_POST_VARS</varname> array (which is still
available, but deprecated).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="reserved.variables.cookies">$_COOKIE</link></term>
<listitem>
<simpara>
Variables provided to the script via HTTP cookies. Analogous to
the old <varname>$HTTP_COOKIE_VARS</varname> array (which is
still available, but deprecated).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="reserved.variables.files">$_FILES</link></term>
<listitem>
<simpara>
Variables provided to the script via HTTP post file
uploads. Analogous to the old
<varname>$HTTP_POST_FILES</varname> array (which is still
available, but deprecated). See <link
linkend="features.file-upload.post-method">POST method
uploads</link> for more information.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="reserved.variables.environment">$_ENV</link></term>
<listitem>
<simpara>
Variables provided to the script via the environment. Analogous
to the old <varname>$HTTP_ENV_VARS</varname> array (which is
still available, but deprecated).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="reserved.variables.request">$_REQUEST</link></term>
<listitem>
<simpara>
Variables provided to the script via the GET, POST, and COOKIE input
mechanisms, and which therefore cannot be trusted. The presence and
order of variable inclusion in this array is defined according to the
PHP <link linkend="ini.variables-order">variables_order</link>
configuration directive. This array has no direct analogue in versions
of PHP prior to 4.1.0. See also
<function>import_request_variables</function>.
</simpara>
<caution>
<simpara>
Since PHP 4.3.0, FILE information from <varname>$_FILES</varname> does
not exist in <varname>$_REQUEST</varname>.
</simpara>
</caution>
<note>
<simpara>
When running on the <link linkend="features.commandline">command line
</link>, this will <emphasis>not</emphasis> include the
<varname>argv</varname> and <varname>argc</varname> entries; these are
present in the <varname>$_SERVER</varname> array.
</simpara>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="reserved.variables.session">$_SESSION</link></term>
<listitem>
<simpara>
Variables which are currently registered to a script's
session. Analogous to the old
<varname>$HTTP_SESSION_VARS</varname> array (which is still
available, but deprecated). See the <link
linkend="ref.session">Session handling functions</link> section
for more information.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</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[
<?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">
<![CDATA[
<?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.
</simpara>
<sect2 id="language.variables.scope.global">
<title>The global keyword</title>
<simpara>
First, an example use of <literal>global</literal>:
</simpara>
<para>
<example>
<title>Using global</title>
<programlisting role="php">
<![CDATA[
<?php
$a = 1;
$b = 2;
function Sum()
{
global $a, $b;
$b = $a + $b;
}
Sum();
echo $b;
?>
]]>
</programlisting>
</example>
</para>
<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>
<para>
<example>
<title>Using <varname>$GLOBALS</varname> instead of global</title>
<programlisting role="php">
<![CDATA[
<?php
$a = 1;
$b = 2;
function Sum()
{
$GLOBALS['b'] = $GLOBALS['a'] + $GLOBALS['b'];
}
Sum();
echo $b;
?>
]]>
</programlisting>
</example>
</para>
<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.
Notice how <varname>$GLOBALS</varname> exists in any scope, this
is because $GLOBALS is a <link
linkend="language.variables.superglobals">superglobal</link>.
Here's an example demonstrating the power of superglobals:
</simpara>
<para>
<example>
<title>Example demonstrating superglobals and scope</title>
<programlisting role="php">
<![CDATA[
<?php
function test_global()
{
// Most predefined variables aren't "super" and require
// 'global' to be available to the functions local scope.
global $HTTP_POST_VARS;
echo $HTTP_POST_VARS['name'];
// Superglobals are available in any scope and do
// not require 'global'. Superglobals are available
// as of PHP 4.1.0, and HTTP_POST_VARS is now
// deemed deprecated.
echo $_POST['name'];
}
?>
]]>
</programlisting>
</example>
</para>
</sect2>
<sect2 id="language.variables.scope.static">
<title>Using static variables</title>
<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>
<para>
<example>
<title>Example demonstrating need for static variables</title>
<programlisting role="php">
<![CDATA[
<?php
function Test()
{
$a = 0;
echo $a;
$a++;
}
?>
]]>
</programlisting>
</example>
</para>
<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>
<para>
<example>
<title>Example use of static variables</title>
<programlisting role="php">
<![CDATA[
<?php
function Test()
{
static $a = 0;
echo $a;
$a++;
}
?>
]]>
</programlisting>
</example>
</para>
<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>
<para>
<example>
<title>Static variables with recursive functions</title>
<programlisting role="php">
<![CDATA[
<?php
function Test()
{
static $count = 0;
$count++;
echo $count;
if ($count < 10) {
Test();
}
$count--;
}
?>
]]>
</programlisting>
</example>
</para>
<note>
<para>
Static variables may be declared as seen in the examples above.
Trying to assign values to these variables which are the
result of expressions will cause a parse error.
</para>
<para>
<example>
<title>Declaring static variables</title>
<programlisting role="php">
<![CDATA[
<?php
function foo(){
static $int = 0; // correct
static $int = 1+2; // wrong (as it is an expression)
static $int = sqrt(121); // wrong (as it is an expression too)
$int++;
echo $int;
}
?>
]]>
</programlisting>
</example>
</para>
</note>
</sect2>
<sect2 id="language.variables.scope.references">
<title>References with global and static variables</title>
<simpara>
The Zend Engine 1, driving PHP 4, implements the
<link linkend="language.variables.scope.static">static</link> and
<link linkend="language.variables.scope.global">global</link> modifier
for variables in terms of <link linkend="language.references">
references</link>. For example, a true global variable
imported inside a function scope with the <literal>global</literal>
statement actually creates a reference to the global variable. This can
lead to unexpected behaviour which the following example addresses:
</simpara>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
function test_global_ref() {
global $obj;
$obj = &new stdclass;
}
function test_global_noref() {
global $obj;
$obj = new stdclass;
}
test_global_ref();
var_dump($obj);
test_global_noref();
var_dump($obj);
?>
]]>
</programlisting>
</informalexample>
<simpara>
Executing this example will result in the following output:
</simpara>
<screen>
NULL
object(stdClass)(0) {
}
</screen>
<simpara>
A similar behaviour applies to the <literal>static</literal> statement.
References are not stored statically:
</simpara>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
function &get_instance_ref() {
static $obj;
echo 'Static object: ';
var_dump($obj);
if (!isset($obj)) {
// Assign a reference to the static variable
$obj = &new stdclass;
}
$obj->property++;
return $obj;
}
function &get_instance_noref() {
static $obj;
echo 'Static object: ';
var_dump($obj);
if (!isset($obj)) {
// Assign the object to the static variable
$obj = new stdclass;
}
$obj->property++;
return $obj;
}
$obj1 = get_instance_ref();
$still_obj1 = get_instance_ref();
echo "\n";
$obj2 = get_instance_noref();
$still_obj2 = get_instance_noref();
?>
]]>
</programlisting>
</informalexample>
<simpara>
Executing this example will result in the following output:
</simpara>
<screen>
Static object: NULL
Static object: NULL
Static object: NULL
Static object: object(stdClass)(1) {
["property"]=>
int(1)
}
</screen>
<simpara>
This example demonstrates that when assigning a reference to a static
variable, it's not <emphasis>remembered</emphasis> when you call the
<literal>&get_instance_ref()</literal> function a second time.
</simpara>
</sect2>
</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[
<?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">
<![CDATA[
<?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">
<![CDATA[
<?php
echo "$a ${$a}";
?>
]]>
</programlisting>
</informalexample>
<simpara>
produces the exact same output as:
</simpara>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
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>
<warning>
<simpara>
Please note that variable variables cannot be used with PHP's
<link linkend="language.variables.superglobals">Superglobal arrays</link>
within functions or class methods.
</simpara>
</warning>
</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, the information from
that form is automatically made available to the script. There
are many ways to access this information, for example:
</simpara>
<para>
<example>
<title>A simple HTML form</title>
<programlisting role="html">
<![CDATA[
<form action="foo.php" method="post">
Name: <input type="text" name="username" /><br />
Email: <input type="text" name="email" /><br />
<input type="submit" name="submit" value="Submit me!" />
</form>
]]>
</programlisting>
</example>
</para>
<para>
Depending on your particular setup and personal preferences, there
are many ways to access data from your HTML forms. Some examples are:
</para>
<para>
<example>
<title>Accessing data from a simple POST HTML form</title>
<programlisting role="html">
<![CDATA[
<?php
// Available since PHP 4.1.0
echo $_POST['username'];
echo $_REQUEST['username'];
import_request_variables('p', 'p_');
echo $p_username;
// Available since PHP 3. As of PHP 5.0.0, these long predefined
// variables can be disabled with the register_long_arrays directive.
echo $HTTP_POST_VARS['username'];
// Available if the PHP directive register_globals = on. As of
// PHP 4.2.0 the default value of register_globals = off.
// Using/relying on this method is not preferred.
echo $username;
?>
]]>
</programlisting>
</example>
</para>
<para>
Using a GET form is similar except you'll use the appropriate
GET predefined variable instead. GET also applies to the
QUERY_STRING (the information after the '?' in a URL). So,
for example, <literal>http://www.example.com/test.php?id=3</literal>
contains GET data which is accessible with <varname>$_GET['id']</varname>.
See also <link linkend="reserved.variables.request">$_REQUEST</link> and
<function>import_request_variables</function>.
</para>
<note>
<para>
<link linkend="language.variables.superglobals">Superglobal arrays</link>,
like <varname>$_POST</varname> and <varname>$_GET</varname>, became
available in PHP 4.1.0
</para>
</note>
<para>
As shown, before PHP 4.2.0 the default value for <link
linkend="ini.register-globals">register_globals</link>
was <emphasis>on</emphasis>. And, in PHP 3 it was always on. The PHP
community is encouraging all to not rely on this directive
as it's preferred to assume it's <emphasis>off</emphasis> and code
accordingly.
</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. See also
<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. For
example, let's post a form to itself and upon submission display
the data:
</simpara>
<para>
<example>
<title>More complex form variables</title>
<programlisting role="php">
<![CDATA[
<?php
if (isset($_POST['action']) && $_POST['action'] == 'submitted') {
echo '<pre>';
print_r($_POST);
echo '<a href="'. $_SERVER['PHP_SELF'] .'">Please try again</a>';
echo '</pre>';
} else {
?>
<form action="<?php echo $_SERVER['PHP_SELF']; ?>" 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>
<option value="guinness">Guinness</option>
<option value="stuttgarter">Stuttgarter Schwabenbr�u</option>
</select><br />
<input type="hidden" name="action" value="submitted" />
<input type="submit" name="submit" value="submit me!" />
</form>
<?php
}
?>
]]>
</programlisting>
</example>
</para>
<para>
In PHP 3, the array form variable usage is limited to
single-dimensional arrays. As of 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="html">
<![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. Cookie data
is then available in the appropriate cookie data arrays, such
as <varname>$_COOKIE</varname>, <varname>$HTTP_COOKIE_VARS</varname>
as well as in <varname>$_REQUEST</varname>. See the
<function>setcookie</function> manual page for more details and
examples.
</simpara>
<simpara>
If you wish to assign multiple values to a single cookie variable, you
may assign it as an array. For example:
</simpara>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
setcookie("MyCookie[foo]", 'Testing 1', time()+3600);
setcookie("MyCookie[bar]", 'Testing 2', time()+3600);
?>
]]>
</programlisting>
</informalexample>
<simpara>
That will create two separate cookies although MyCookie will now
be a single array in your script. If you want to set just one cookie
with multiple values, consider using <function>serialize</function> or
<function>explode</function> on the value first.
</simpara>
<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>A <function>setcookie</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
if (isset($_COOKIE['count'])) {
$count = $_COOKIE['count'] + 1;
} else {
$count = 1;
}
setcookie('count', $count, time()+3600);
setcookie("Cart[$count]", $item, time()+3600);
?>
]]>
</programlisting>
</example>
</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[
<?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, such as:
<function>gettype</function>, <function>is_array</function>,
<function>is_float</function>, <function>is_int</function>,
<function>is_object</function>, and
<function>is_string</function>. See also the chapter on
<link linkend="language.types">Types</link>.
</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
-->