php-doc-en/language/variables.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.56 $ -->
 <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>

   <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 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>
    PHP 4 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. 
    This also means that no copying is performed; thus, the assignment 
    happens more quickly. However, any speedup will likely be noticed 
    only in tight loops or when assigning large 
    <link linkend="language.types.array">arrays</link> or 
    <link linkend="language.types.object">objects</link>.
   </para>
   <para>
    To assign by reference, simply prepend an ampersand (&amp;) 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>
    PHP follows Perl's convention when dealing with arithmetic operations
    on character variables and not C's.  For example, in Perl 'Z'+1 turns
    into 'AA', while in C 'Z'+1 turns into '[' { ord('Z') == 90, ord('[') == 91 ).
    <example>
     <title>Arithmetric Operations on Character Variables</title>
     <programlisting role="php">
<![CDATA[
<?php
$i = 'W';
for($n=0; $n<6; $n++)
  echo ++$i . "\n";

/*
  Produces the output similar to the following:

X
Y
Z
AA
AB
AC

*/
?>
]]>
     </programlisting>
    </example>
   </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.registerglobals">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
    'autoglobals' or '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.
   </simpara>
   
   <note>
    <title>Variable variables</title>
    <para>
     Superglobals cannot be used as 
     <link linkend="language.variables.variable">variable variables</link>.
    </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 HTTP GET. 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 any user input mechanism,
       and which therefore cannot be trusted. The presence and order 
       of variable inclusion in this array is defined according to the <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>
      <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.  An example:
   </simpara>

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
$a = 1;
$b = 2;

function Sum()
{
    global $a, $b;

    $b = $a + $b;
} 

Sum();
echo $b;
?>
]]>
    </programlisting>
   </informalexample>

   <simpara>
    The above script will output &quot;3&quot;.  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[
<?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.
    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>
   
   <informalexample>
    <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;
    
    print $HTTP_POST_VARS['name'];
    
    // Superglobals are available in any scope and do 
    // not require 'global'.  Superglobals are available 
    // as of PHP 4.1.0
    print $_POST['name'];
}
?>
]]>
     </programlisting>
    </informalexample>
   </para>
   
   <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[
<?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
    &quot;0&quot;.  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[
<?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">
<![CDATA[
<?php
function Test()
{
    static $count = 0;

    $count++;
    echo $count;
    if ($count < 10) {
        Test ();
    }
    $count--;
}
?>
]]>
    </programlisting>
   </informalexample>

   <simpara>
    The Zend Engine 1, driving <literal>PHP4</literal>, implements the
    <literal>static</literal> and <literal>global</literal> modifier for
    variables in terms of references. 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>&amp;get_instance_ref()</literal> function a second time.
   </simpara>


  </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>.
     This means you cannot do things like <varname>${$_GET}</varname>. If you are 
     looking for a way to handle availability of superglobals and the old
     <varname>HTTP_*_VARS</varname>, you might want to try 
     <link linkend="language.references">referencing</link> them.
    </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

   print $_POST['username'];
   print $_REQUEST['username'];

   import_request_variables('p', 'p_');
   print $p_username;

// Available since PHP 3.

   print $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.

   print $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 an 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 ($HTTP_POST_VARS['action'] == 'submitted') {
    print '<pre>';

    print_r($HTTP_POST_VARS);
    print '<a href="'. $HTTP_SERVER_VARS['PHP_SELF'] .'">Please try again</a>';

    print '</pre>';
} else {
?>
<form action="<?php echo $HTTP_SERVER_VARS['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. 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="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 seperate 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
$count++;
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
-->