variables.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
 <chapter xml:id="language.variables" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Variables</title>
  
  <sect1 xml: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:
    <code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>
   </para>
   
   <note>
    <simpara>
     For our purposes here, a letter is a-z, A-Z, and the bytes
     from 128 through 255 (<literal>0x80-0xff</literal>).
    </simpara>
   </note>

   <note>
    <simpara>
     <literal>$this</literal> is a special variable that can't be
     assigned.
    </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>
    By default, 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 also 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 (&amp;) to the
    beginning of the variable which is being assigned (the source
    variable). For instance, the following code snippet outputs '<literal>My
    name is Bob</literal>' 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 depending on the context in which they are used
    - booleans default to &false;, integers and floats default to zero, strings (e.g. used in <function>echo</function>) are 
    set as an empty string and arrays become to an empty array.
   </para>
   <para>
    <example>
     <title>Default values of uninitialized variables</title>
     <programlisting role="php">
<![CDATA[
<?php
// Unset AND unreferenced (no use context) variable; outputs NULL
var_dump($unset_var);

// Boolean usage; outputs 'false' (See ternary operators for more on this syntax)
echo($unset_bool ? "true\n" : "false\n");

// String usage; outputs 'string(3) "abc"'
$unset_str .= 'abc';
var_dump($unset_str);

// Integer usage; outputs 'int(25)'
$unset_int += 25; // 0 + 25 => 25
var_dump($unset_int);

// Float/double usage; outputs 'float(1.25)'
$unset_float += 1.25;
var_dump($unset_float);

// Array usage; outputs array(1) {  [3]=>  string(3) "def" }
$unset_arr[3] = "def"; // array() + array(3 => "def") => array(3 => "def")
var_dump($unset_arr);

// Object usage; creates new stdClass object (see http://www.php.net/manual/en/reserved.classes.php)
// Outputs: object(stdClass)#1 (1) {  ["foo"]=>  string(3) "bar" }
$unset_obj->foo = 'bar';
var_dump($unset_obj);
?>
]]>
     </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="errorfunc.constants.errorlevels.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 xml:id="language.variables.predefined">
   <title>Predefined Variables</title>
   
   <para>
    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>.
   </para>

   <para>
    PHP also provides an additional set of predefined arrays
    containing variables from the web server (if applicable), the
    environment, and user input. These 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 can be found
    <link linkend="language.variables.superglobals">here</link>;
    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>.
   </para>

   <note>
    <para>
     Prior to PHP 5.4, the old way of retrieving information
     related to the HTTP request with the <literal>HTTP_*_VARS</literal>
     variables instead of superglobals was still possible.
     This feature could be disabled as of PHP 5.0.0 with the
     <link linkend="ini.register-long-arrays">register_long_arrays</link>
     directive.
    </para>
   </note>
   
   <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>

   <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>
  </sect1>


  <sect1 xml: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 xml:id="language.variables.scope.global">
    <title>The <literal>global</literal> keyword</title>
    <simpara>
     First, an example use of <literal>global</literal>:
    </simpara>
    <para>
     <example>
      <title>Using <literal>global</literal></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 <literal>3</literal>.  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 <varname>$GLOBALS</varname> 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_superglobal()
{
    echo $_POST['name'];
}
?>
]]>
     </programlisting>
    </example>
   </para>
   <note>
    <para>
     Using <literal>global</literal> keyword outside a function is not an
     error. It can be used if the file is included from inside a function.
    </para>
   </note>
  </sect2>
 
  <sect2 xml:id="language.variables.scope.static">
   <title>Using <literal>static</literal> 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
    <literal>0</literal>.  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, <varname>$a</varname> is initialized only in first call of function
    and every time the <literal>test()</literal> 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.
     From PHP 5.6 you can assign values to these variables which are the
     result of expressions, but you can't use any function here, what 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;        // correct (as of PHP 5.6)
    static $int = sqrt(121);  // wrong  (as it is a function)

    $int++;
    echo $int;
}
?>
]]>
      </programlisting>
     </example>
    </para> 
   </note>
   <note>
    <para>
     Static declarations are resolved in compile-time.
    </para>
   </note>
  </sect2>

  <sect2 xml:id="language.variables.scope.references">
   <title>References with <literal>global</literal> and <literal>static</literal> variables</title>
   <simpara>
    PHP 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>

   &example.outputs;

   <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>
   &example.outputs;
   <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>
   </sect2>
  </sect1>

  <sect1 xml: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>

   <simpara>
    Class properties may also be accessed using variable property names. The
    variable property name will be resolved within the scope from which the
    call is made. For instance, if you have an expression such as
    <varname>$foo->$bar</varname>, then the local scope will be examined for
    <varname>$bar</varname> and its value will be used as the name of the
    property of <varname>$foo</varname>. This is also true if
    <varname>$bar</varname> is an array access.
   </simpara>

   <caution>
    <simpara>
     Further dereferencing a variable property that is an array has different
     semantics between PHP 5 and PHP 7. The
     <link linkend="migration70.incompatible.variable-handling.indirect">PHP 7.0 migration guide</link>
     includes further details on the types of expressions that have changed,
     and how to place curly braces to avoid ambiguity.
    </simpara>
   </caution>

   <simpara>
    Curly braces may also be used, to clearly delimit the property
    name. They are most useful when accessing values within a property that
    contains an array, when the property name is made of multiple parts,
    or when the property name contains characters that are not
    otherwise valid (e.g. from <function>json_decode</function>
    or <link linkend="book.simplexml">SimpleXML</link>).
   </simpara>

   <para>
    <example>
     <title>Variable property example</title>
      <programlisting role="php">
<![CDATA[
<?php
class foo {
    var $bar = 'I am bar.';
    var $arr = array('I am A.', 'I am B.', 'I am C.');
    var $r   = 'I am r.';
}

$foo = new foo();
$bar = 'bar';
$baz = array('foo', 'bar', 'baz', 'quux');
echo $foo->$bar . "\n";
echo $foo->{$baz[1]} . "\n";

$start = 'b';
$end   = 'ar';
echo $foo->{$start . $end} . "\n";

$arr = 'arr';
echo $foo->{$arr[1]} . "\n";

?>
]]>
     </programlisting>
     &example.outputs;
     <screen>
I am bar.
I am bar.
I am bar.
I am r.
     </screen>
    </example>
   </para>

   <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. The variable <literal>$this</literal>
     is also a special variable that cannot be referenced dynamically.
    </simpara>
   </warning>
  
  </sect1>

  <sect1 xml:id="language.variables.external">
   <title>Variables From External Sources</title>
   
   <sect2 xml: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 few 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>
     As of PHP 5.4.0, there are only two ways to access data from your HTML forms.
     Currently available methods are listed below:
    </para>

    <para>
     <example>
      <title>Accessing data from a simple POST HTML form</title>
      <programlisting role="php">
<![CDATA[
<?php
echo $_POST['username'];
echo $_REQUEST['username'];
?>
]]>
      </programlisting>
     </example>
    </para>

    <para>
     There were some other ways of accessing user input in old PHP versions. These
     are listed below. See changelog at the bottom of the page for more details.
     <example>
      <title>Old methods of accessing user input</title>
      <programlisting role="php">
<![CDATA[
<?php
// WATCH OUT: these methods ARE NOT supported anymore.
// Valid ones were described above.

// Using import_request_variables() - this function has been removed in PHP 5.4.0
   import_request_variables('p', 'p_');
   echo $p_username;

// These long predefined variables were removed in PHP 5.4.0
   echo $HTTP_POST_VARS['username'];

// Using register_globals. This feature was removed in PHP 5.4.0
   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
     <literal>QUERY_STRING</literal> (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 <varname>$_REQUEST</varname>.
    </para>

    <note>
     <para>
      Dots and spaces in variable names are converted to underscores. For
      example <literal>&lt;input name="a.b" /&gt;</literal> becomes
      <literal>$_REQUEST["a_b"]</literal>.
     </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 ($_POST) {
    echo '<pre>';
    echo htmlspecialchars(print_r($_POST, true));
    echo '</pre>';
}
?>
<form action="" 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="submit" value="submit me!" />
</form>
]]>
      </programlisting>
     </example>
    </para>

    <note>
     <simpara>
      If an external variable name begins with a valid array syntax, trailing characters
      are silently ignored. For example, <literal>&lt;input name="foo[bar]baz"&gt;</literal>
      becomes <literal>$_REQUEST['foo']['bar']</literal>.
     </simpara>
    </note>
 
    <sect3 xml: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, <varname>sub_x</varname> and <varname>sub_y</varname>.
      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 xml:id="language.variables.external.cookies">
    <title>HTTP Cookies</title>

    <simpara>
     PHP transparently supports HTTP cookies as defined by <link
     xlink:href="&url.rfc;6265">RFC 6265</link>.  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> 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 <varname>MyCookie</varname> 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 xml: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 xml: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>
    <para>
     HTTP being a text protocol, most, if not all, content that comes in
     <link linkend="language.variables.superglobals">Superglobal arrays</link>, 
     like <varname>$_POST</varname> and <varname>$_GET</varname> will remain
     as strings. PHP will not try to convert values to a specific type.
     In the example below, <varname>$_GET["var1"]</varname> will contain the
     string "null" and <varname>$_GET["var2"]</varname>, the string "123".
     <programlisting>
<![CDATA[
/index.php?var1=null&var2=123
]]>
      </programlisting>
    </para>
   </sect2>

   <sect2 xml:id="language.variables.external.changelog">
    &reftitle.changelog;

    <para>
     <informaltable>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>&Version;</entry>
         <entry>&Description;</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>5.4.0</entry>
         <entry>
          <link linkend="security.globals">Register Globals</link>, 
          <link linkend="security.magicquotes">Magic Quotes</link> and
          <link linkend="ini.register-long-arrays">register_long_arrays</link>
          has been removed
         </entry>
        </row>
        <row>
         <entry>5.3.0</entry>
         <entry>
          <link linkend="security.globals">Register Globals</link>, 
          <link linkend="security.magicquotes">Magic Quotes</link> and
          <link linkend="ini.register-long-arrays">register_long_arrays</link>
          became deprecated
         </entry>
        </row>
       </tbody>
      </tgroup>
     </informaltable>
    </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:"~/.phpdoc/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
-->