<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.35 $ -->
 <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[
$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
$tyte = '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 <link
    linkend="language.expressions">Expressions</link>.
   </para>
   <para>
    PHP 4 offers another way to assign values to variables:
    <emphasis>assign by reference</emphasis>. 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 arrays or objects.
   </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 $foo;                 // $foo is altered too.
echo $bar;
?>
]]>
     </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>

  </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
    command-line.
   </simpara>

   <simpara>
    Despite these factors, here is a list of predefined variables
    available under a stock installation of PHP 3 running as a module
    under a stock installation of <ulink
    url="&url.apache;">Apache</ulink> 1.3.6.
   </simpara>

   <simpara>
    For a list of all predefined variables (and lots of other useful
    information), please see (and use) <function>phpinfo</function>.
   </simpara>

   <note>
    <simpara>
     This list is neither exhaustive nor intended to be. It is simply
     a guideline as to what sorts of predefined variables you can
     expect to have access to in your script.
    </simpara>
   </note>

   <sect2 id="language.variables.predefined.apache">
    <title>Apache variables</title>

    <simpara>
     These variables are created by the <ulink
     url="&url.apache;">Apache</ulink> webserver. If you are running
     another webserver, there is no guarantee that it will provide the
     same variables; it may omit some, or provide others not listed
     here. That said, a large number of these variables are accounted
     for in the <ulink url="&url.cgispec;">CGI 1.1
     specification</ulink>, so you should be able to expect those.
    </simpara>
    <simpara>
     Note that few, if any, of these will be available (or indeed have
     any meaning) if running PHP on the command line.
    </simpara>

    <para>
     <variablelist>
      <varlistentry>
       <term>$GATEWAY_INTERFACE</term>
       <listitem>
        <simpara>
         What revision of the CGI specification the server is using;
         i.e. 'CGI/1.1'.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$SERVER_NAME</term>
       <listitem>
        <simpara>
         The name of the server host under which the current script is
         executing. If the script is running on a virtual host, this
         will be the value defined for that virtual host.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$SERVER_SOFTWARE</term>
       <listitem>
        <simpara>
         Server identification string, given in the headers when
         responding to requests.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$SERVER_PROTOCOL</term>
       <listitem>
        <simpara>
         Name and revision of the information protocol via which the
         page was requested; i.e. 'HTTP/1.0';
        </simpara>
       </listitem>
      </varlistentry>
      
      <varlistentry>
       <term>$REQUEST_METHOD</term>
       <listitem>
        <simpara>
         Which request method was used to access the page; i.e. 'GET',
         'HEAD', 'POST', 'PUT'.
        </simpara>
       </listitem>
      </varlistentry>
	  
      <varlistentry>
       <term>$QUERY_STRING</term>
       <listitem>
        <simpara>
         The query string, if any, via which the page was accessed.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$DOCUMENT_ROOT</term>
       <listitem>
        <simpara>
         The document root directory under which the current script is
         executing, as defined in the server's configuration file.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$HTTP_ACCEPT</term>
       <listitem>
        <simpara>
         Contents of the <literal>Accept:</literal> header from the
         current request, if there is one.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$HTTP_ACCEPT_CHARSET</term>
       <listitem>
        <simpara>
         Contents of the <literal>Accept-Charset:</literal> header
         from the current request, if there is one. Example:
         'iso-8859-1,*,utf-8'.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$HTTP_ACCEPT_ENCODING</term>
       <listitem>
        <simpara>
         Contents of the <literal>Accept-Encoding:</literal> header
         from the current request, if there is one. Example: 'gzip'.
        </simpara>
       </listitem>
      </varlistentry>
      
      <varlistentry>
       <term>$HTTP_ACCEPT_LANGUAGE</term>
       <listitem>
        <simpara>
         Contents of the <literal>Accept-Language:</literal> header
         from the current request, if there is one. Example: 'en'.
        </simpara>
       </listitem>
      </varlistentry>
      
      <varlistentry>
       <term>$HTTP_CONNECTION</term>
       <listitem>
        <simpara>
         Contents of the <literal>Connection:</literal> header from
         the current request, if there is one. Example: 'Keep-Alive'.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$HTTP_HOST</term>
       <listitem>
        <simpara>
         Contents of the <literal>Host:</literal> header from the
         current request, if there is one.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$HTTP_REFERER</term>
       <listitem>
        <simpara>
         The address of the page (if any) which referred the browser
         to the current page. This is set by the user's browser; not
         all browsers will set this.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$HTTP_USER_AGENT</term>
       <listitem>
        <simpara>
         Contents of the <literal>User_Agent:</literal> header from
         the current request, if there is one. This is a string
         denoting the browser software being used to view the current
         page; i.e. <computeroutput>Mozilla/4.5 [en] (X11; U; Linux
         2.2.9 i586)</computeroutput>. Among other things, you can use
         this value with <function>get_browser</function> to tailor
         your page's functionality to the capabilities of the user's
         browser.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$REMOTE_ADDR</term>
       <listitem>
        <simpara>
         The IP address from which the user is viewing the current
         page.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$REMOTE_PORT</term>
       <listitem>
        <simpara>
         The port being used on the user's machine to communicate with
         the web server.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$SCRIPT_FILENAME</term>
       <listitem>
        <simpara>
         The absolute pathname of the currently executing script.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$SERVER_ADMIN</term>
       <listitem>
        <simpara>
         The value given to the SERVER_ADMIN (for Apache) directive in
         the web server configuration file. If the script is running
         on a virtual host, this will be the value defined for that
         virtual host.
        </simpara>
       </listitem>
      </varlistentry>
      
      <varlistentry>
       <term>$SERVER_PORT</term>
       <listitem>
        <simpara>
         The port on the server machine being used by the web server
         for communication. For default setups, this will be '80';
         using SSL, for instance, will change this to whatever your
         defined secure HTTP port is.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$SERVER_SIGNATURE</term>
       <listitem>
        <simpara>
         String containing the server version and virtual host name
         which are added to server-generated pages, if enabled.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$PATH_TRANSLATED</term>
       <listitem>
        <simpara>
         Filesystem- (not document root-) based path to the current
         script, after the server has done any virtual-to-real
         mapping.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$SCRIPT_NAME</term>
       <listitem>
        <simpara>
         Contains the current script's path. This is useful for pages
         which need to point to themselves.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$REQUEST_URI</term>
       <listitem>
        <simpara>
         The URI which was given in order to access this page; for
         instance, '/index.html'.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </para>

   </sect2>

   <sect2 id="language.variables.predefined.environment">
    <title>Environment variables</title>

    <simpara>
     These variables are imported into PHP's global namespace from the
     environment under which the PHP parser is running. Many are
     provided by the shell under which PHP is running and different
     systems are likely running different kinds of shells, a
     definitive list is impossible. Please see your shell's
     documentation for a list of defined environment variables.
    </simpara>
    <simpara>
     Other environment variables include the CGI variables, placed
     there regardless of whether PHP is running as a server module or
     CGI processor.
    </simpara>
	
   </sect2>

   <sect2 id="language.variables.predefined.php">
    <title>PHP variables</title>
    
    <simpara>
     These variables are created by PHP itself. The
     <varname>$HTTP_*_VARS</varname> variables are available only if
     the <link linkend="ini.track-vars">track_vars</link>
     configuration is turned on. When enabled, the variables are
     always set, even if they are empty arrays. This prevents
     a malicious user from spoofing these variables.
    </simpara>

    <note>
     <para>
      As of PHP 4.0.3, <link
      linkend="ini.track-vars">track_vars</link> is always turned on,
      regardless of the configuration file setting.
     </para>
    </note>

    <note>
     <para>
      The new "Superglobals" were added in PHP version 4.1.0. See the
      <ulink url="&url.php.release4.1.0;">4.1.0 Release
      Announcement</ulink> for more details. These are the
      <varname>$_GET</varname>, <varname>$_POST</varname>,
      <varname>$_ENV</varname>, <varname>$_SERVER</varname>,
      <varname>$_COOKIE</varname>, <varname>$_REQUEST</varname>
      <varname>$_FILES</varname>, and <varname>$_SESSION</varname>
      arrays, and they are informally known as
      <emphasis>Superglobals</emphasis> since they are always
      available without regard to scope. These deprecate the older
      respective <varname>$HTTP_*_VARS</varname> arrays.
     </para>
    </note>

    <para>
     If the <link
     linkend="ini.register-globals">register_globals</link> directive
     is set, then these variables will also be made available in the
     global scope of the script; i.e., separate from the
     <varname>$HTTP_*_VARS</varname> and <varname>$_*</varname> 
     arrays.  For related information, see the security chapter titled 
     <link linkend="security.registerglobals">Using Register Globals</link>.
    </para>
    
    <para>
     <variablelist>
      <varlistentry>
       <term>$argv</term>
       <listitem>
        <simpara>
         Array of arguments passed to the script. When the script is
         run on the command line, this gives C-style access to the
         command line parameters. When called via the GET method, this
         will contain the query string.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$argc</term>
       <listitem>
        <simpara>
         Contains the number of command line parameters passed to the
         script (if run on the command line).
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$PHP_SELF</term>
       <listitem>
        <simpara>
         The filename of the currently executing script, relative to
         the document root. If PHP is running as a command-line
         processor, this variable is not available.  This variable
	 will include path information if present
	 (e.g. $PHP_SELF on this address:
	 "http://example.com/test.php/foo.bar" would be
	 "/test.php/foo.bar")
        </simpara>
       </listitem>
      </varlistentry>
	  
      <varlistentry>
       <term>$HTTP_COOKIE_VARS</term>
       <listitem>
        <simpara>
         An associative array of variables passed to the current
         script via HTTP cookies. 
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$_COOKIE</term>
       <listitem>
        <simpara>
         An associative array of variables passed to the current
         script via HTTP cookies.  Automatically global in any
         scope. Introduced in PHP 4.1.0.
        </simpara>
       </listitem>
      </varlistentry>
      
      <varlistentry>
       <term>$HTTP_GET_VARS</term>
       <listitem>
        <simpara>
         An associative array of variables passed to the current
         script via the HTTP GET method.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$_GET</term>
       <listitem>
        <simpara>
         An associative array of variables passed to the current
         script via the HTTP GET method.  Automatically global in 
         any scope. Introduced in PHP 4.1.0.
        </simpara>
       </listitem>
      </varlistentry>
      
      <varlistentry>
       <term>$HTTP_POST_VARS</term>
       <listitem>
        <simpara>
         An associative array of variables passed to the current
         script via the HTTP POST method.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$_POST</term>
       <listitem>
        <simpara>
         An associative array of variables passed to the current
         script via the HTTP POST method.  Automatically global in 
         any scope. Introduced in PHP 4.1.0.
        </simpara>
       </listitem>
      </varlistentry>
    
      <varlistentry>
       <term>$HTTP_POST_FILES</term>
       <listitem>
        <simpara>
         An associative array of variables containing information
         about files uploaded via the HTTP POST method. See <link
         linkend="features.file-upload.post-method">POST method
         uploads</link> for information on the contents of
         <varname>$HTTP_POST_FILES</varname>.  Introduced in 4.0.0.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$_FILES</term>
       <listitem>
        <simpara>
         An associative array of variables containing information
         about files uploaded via the HTTP POST method. See <link
         linkend="features.file-upload.post-method">POST method
         uploads</link> for information on the contents of
         <varname>$_FILES</varname>. Automatically global in any scope.
         Introduced in PHP 4.1.0.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$HTTP_ENV_VARS</term>
       <listitem>
        <simpara>
         An associative array of variables passed to the current
         script via the parent environment. 
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$_ENV</term>
       <listitem>
        <simpara>
         An associative array of variables passed to the current
         script via the parent environment.  Automagically global 
         in any scope. Introduced in PHP 4.1.0.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$HTTP_SERVER_VARS</term>
       <listitem>
        <simpara>
         An associative array of variables passed to the current
         script from the HTTP server. These variables are analogous to
         the Apache variables described above.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$_SERVER</term>
       <listitem>
        <simpara>
         An associative array of variables passed to the current
         script from the HTTP server. These variables are analogous to
         the Apache variables described above.  Automatically global 
         in any scope. Introduced in PHP 4.1.0.
        </simpara>
       </listitem>
       </varlistentry>

      <varlistentry>
       <term>$HTTP_SESSION_VARS</term>
       <listitem>
        <simpara>
         An associative array of session variables passed to the current
         script.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$_SESSION</term>
       <listitem>
        <simpara>
         An associative array of session variables passed to the
         current script.  Automatically global in any scope.  Creating
         new entries in the $_SESSION array will automatically
         register them as session variables, as if you called
         <function>session_register</function>.  Introduced in PHP 4.1.0.
        </simpara>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term>$_REQUEST</term>
       <listitem>
        <simpara>
         An associative array merged from the GET, POST, and Cookie variables.
         In other words - all the information that is coming from the user, 
         and that from a security point of view, cannot be trusted.
         Automatically global in any scope. Introduced in PHP 4.1.0.
        </simpara>
       </listitem>
      </varlistentry>

     </variablelist>
    </para>
	
   </sect2>

  </sect1>


  <sect1 id="language.variables.scope">
   <title>Variable scope</title>

   <simpara>
    The scope of a variable is the context within which it is defined.
    For the most part all PHP variables only have a single scope.
    This single scope spans included and required files as well.  For
    example:
   </simpara>
   <informalexample>
    <programlisting role="php">
<![CDATA[
$a = 1;
include "b.inc";
]]>
    </programlisting>
   </informalexample>
   <simpara>
    Here the <varname>$a</varname> variable will be available within
    the included <filename>b.inc</filename> script.  However, within
    user-defined functions a local function scope is introduced.  Any
    variable used inside a function is by default limited to the local
    function scope.  For example:
   </simpara>
    
   <informalexample>
    <programlisting role="php"> 
<![CDATA[
$a = 1; /* global scope */ 

function Test()
{ 
    echo $a; /* reference to local scope variable */ 
} 

Test();
]]>
    </programlisting>
   </informalexample>

   <simpara>
    This script will not produce any output because the echo statement
    refers to a local version of the <varname>$a</varname> variable,
    and it has not been assigned a value within this scope.  You may
    notice that this is a little bit different from the C language in
    that global variables in C are automatically available to
    functions unless specifically overridden by a local definition.
    This can cause some problems in that people may inadvertently
    change a global variable.  In PHP global variables must be
    declared global inside a function if they are going to be used in
    that function.  An example:
   </simpara>

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

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

    $b = $a + $b;
} 

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

   <simpara>
    The above script will output &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[
$a = 1;
$b = 2;

function Sum()
{
    $GLOBALS["b"] = $GLOBALS["a"] + $GLOBALS["b"];
} 

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

   <simpara>
    The <varname>$GLOBALS</varname> array is an associative array with
    the name of the global variable being the key and the contents of
    that variable being the value of the array element.
   </simpara>

   <simpara>
    Another important feature of variable scoping is the
    <emphasis>static</emphasis> variable.  A static variable exists
    only in a local function scope, but it does not lose its value
    when program execution leaves this scope.  Consider the following
    example:
   </simpara>

   <informalexample>
    <programlisting role="php">
<![CDATA[
function Test ()
{
    $a = 0;
    echo $a;
    $a++;
}
]]>
    </programlisting>
   </informalexample>

   <simpara>
    This function is quite useless since every time it is called it
    sets <varname>$a</varname> to <literal>0</literal> and prints
    &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[
function Test()
{
    static $a = 0;
    echo $a;
    $a++;
}
]]>
    </programlisting>
   </informalexample>

   <simpara>
    Now, every time the Test() function is called it will print the
    value of <varname>$a</varname> and increment it.
   </simpara>

   <simpara>
    Static variables also provide one way to deal with recursive
    functions. A recursive function is one which calls itself.  Care
    must be taken when writing a recursive function because it is
    possible to make it recurse indefinitely.  You must make sure you
    have an adequate way of terminating the recursion.  The following
    simple function recursively counts to 10, using the static
    variable <varname>$count</varname> to know when to stop:
   </simpara>

   <informalexample>
    <programlisting role="php">
<![CDATA[
function Test()
{
    static $count = 0;

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

  </sect1>

  <sect1 id="language.variables.variable">
   <title>Variable variables</title>

   <simpara>
    Sometimes it is convenient to be able to have variable variable
    names.  That is, a variable name which can be set and used
    dynamically.  A normal variable is set with a statement such as:
   </simpara>

   <informalexample>
    <programlisting role="php">
<![CDATA[
$a = "hello";
]]>
    </programlisting>
   </informalexample>

   <simpara>
    A variable variable takes the value of a variable and treats that
    as the name of a variable.  In the above example,
    <emphasis>hello</emphasis>, can be used as the name of a variable
    by using two dollar signs. i.e.
   </simpara>

   <informalexample>
    <programlisting role="php">
<![CDATA[
$$a = "world";
]]>
    </programlisting>
   </informalexample>

   <simpara>
    At this point two variables have been defined and stored in the
    PHP symbol tree: <varname>$a</varname> with contents "hello" and
    <varname>$hello</varname> with contents "world".  Therefore, this
    statement:
   </simpara>

   <informalexample>
    <programlisting role="php">
<![CDATA[
echo "$a ${$a}";
]]>
    </programlisting>
   </informalexample>

   <simpara>
    produces the exact same output as:
   </simpara>

   <informalexample>
    <programlisting role="php">
<![CDATA[
echo "$a $hello";
]]>
    </programlisting>
   </informalexample>

   <simpara>
    i.e. they both produce: <computeroutput>hello world</computeroutput>.
   </simpara>

   <simpara>
    In order to use variable variables with arrays, you have to
    resolve an ambiguity problem.  That is, if you write
    <varname>$$a[1]</varname> then the parser needs to know if you
    meant to use <varname>$a[1]</varname> as a variable, or if you
    wanted <varname>$$a</varname> as the variable and then the [1]
    index from that variable.  The syntax for resolving this ambiguity
    is: <varname>${$a[1]}</varname> for the first case and
    <varname>${$a}[1]</varname> for the second.
   </simpara>
  
  </sect1>

  <sect1 id="language.variables.external">
   <title>Variables from outside PHP</title>

   <sect2 id="language.variables.external.form">
    <title>HTML Forms (GET and POST)</title>

    <simpara>
     When a form is submitted to a PHP script, any variables from that
     form will be automatically made available to the script by
     PHP. If the <link linkend="ini.track-vars">track_vars</link>
     configuration option is turned on, then these variables will be
     located in the associative arrays
     <varname>$HTTP_POST_VARS</varname>,
     <varname>$HTTP_GET_VARS</varname>, and/or
     <varname>$HTTP_POST_FILES</varname>, according to the
     source of the variable in question.
    </simpara>

    <para>
     For more information on these variables, please read <link
     linkend="language.variables.predefined">Predefined
     variables</link>.
    </para>

    <para>
     <example>
      <title>Simple form variable</title>
      <programlisting role="php">
<![CDATA[
<form action="foo.php" method="post">
    Name: <input type="text" name="username"><br>
    <input type="submit">
</form>
]]>
      </programlisting>
     </example>
    </para>

    <para>
     When the above form is submitted, the value from the text input
     will be available in
     <varname>$HTTP_POST_VARS['username']</varname>. If the <link
     linkend="ini.register-globals">register_globals</link>
     configuration directive is turned on, then the variable will also
     be available as <varname>$username</varname> in the global scope.
    </para>

    <note>
     <para>
      The <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link> 
      configuration directive affects Get, Post and Cookie values.  If 
      turned on, value (It's "PHP!") will automagically become (It\'s \"PHP!\").
      Escaping is needed for DB insertion.  Also see
      <function>addslashes</function>, <function>stripslashes</function> and 
      <link linkend="ini.magic-quotes-sybase">magic_quotes_sybase</link>.
     </para>
    </note>
    
    <simpara>
     PHP also understands arrays in the context of form variables 
     (see the <link linkend="faq.html">related faq</link>).  You may, 
     for example, group related variables together, or use this 
     feature to retrieve values from a multiple select input:
    </simpara>

    <para>
     <example>
      <title>More complex form variables</title>
      <programlisting role="php">
<![CDATA[
<form action="array.php" method="post">
    Name: <input type="text" name="personal[name]"><br>
    Email: <input type="text" name="personal[email]"><br>
    Beer: <br>
    <select multiple name="beer[]">
        <option value="warthog">Warthog
        <option value="guinness">Guinness
        <option value="stuttgarter">Stuttgarter Schwabenbr&auml;u
        </select>
    <input type="submit">
</form>
]]>
      </programlisting>
     </example>
    </para>

    <para>
     In PHP 3, the array form variable usage is limited to
     single-dimensional arrays. In PHP 4, no such restriction applies.
    </para>

    <sect3 id="language.variables.external.form.submit">
     <title>IMAGE SUBMIT variable names</title>

     <simpara>
      When submitting a form, it is possible to use an image instead
      of the standard submit button with a tag like:</simpara>

     <informalexample>
      <programlisting role="php">
<![CDATA[
<input type="image" src="image.gif" name="sub">
]]>
      </programlisting>
     </informalexample>

     <simpara>
      When the user clicks somewhere on the image, the accompanying
      form will be transmitted to the server with two additional
      variables, sub_x and sub_y. These contain the coordinates of the
      user click within the image.  The experienced may note that the
      actual variable names sent by the browser contains a period
      rather than an underscore, but PHP converts the period to an
      underscore automatically.
     </simpara>
    </sect3>

   </sect2>

   <sect2 id="language.variables.external.cookies">
    <title>HTTP Cookies</title>

    <simpara>
     PHP transparently supports HTTP cookies as defined by <ulink
     url="&spec.cookies;">Netscape's Spec</ulink>.  Cookies are a
     mechanism for storing data in the remote browser and thus
     tracking or identifying return users.  You can set cookies using
     the <function>setcookie</function> function.  Cookies are part of
     the HTTP header, so the SetCookie function must be called before
     any output is sent to the browser.  This is the same restriction
     as for the <function>header</function> function.  Any cookies
     sent to you from the client will automatically be turned into a
     PHP variable just like GET and POST method data.</simpara>

    <simpara>
     If you wish to assign multiple values to a single cookie, just
     add <emphasis>[]</emphasis> to the cookie name.  For
     example:
    </simpara>

    <informalexample>
     <programlisting role="php">
<![CDATA[
setcookie("MyCookie[]", "Testing", time()+3600);
]]>
     </programlisting>
    </informalexample>

    <simpara>
     Note that a cookie will replace a previous cookie by the same
     name in your browser unless the path or domain is different.  So,
     for a shopping cart application you may want to keep a counter
     and pass this along.  i.e.
    </simpara>

    <example>
     <title>SetCookie Example</title>
     <programlisting role="php">
<![CDATA[
$Count++;
setcookie("Count", $Count, time()+3600);
setcookie("Cart[$Count]", $item, time()+3600);
]]>
     </programlisting>
    </example>

   </sect2>

   <sect2 id="language.variables.external.environment">
    <title>Environment variables</title>

    <para>
     PHP automatically makes environment variables available as normal
     PHP variables.
     
     <informalexample>
      <programlisting role="php">
<![CDATA[
echo $HOME;  /* Shows the HOME environment variable, if set. */
]]>
      </programlisting>
     </informalexample>
    </para>

    <para>
     Since information coming in via GET, POST and Cookie mechanisms
     also automatically create PHP variables, it is sometimes best to
     explicitly read a variable from the environment in order to make
     sure that you are getting the right version.  The
     <function>getenv</function> function can be used for this.  You
     can also set an environment variable with the
     <function>putenv</function> function.
    </para>
   </sect2>

   <sect2 id="language.variables.external.dot-in-names">
    <title>Dots in incoming variable names</title>

    <para>
     Typically, PHP does not alter the names of variables when they
     are passed into a script. However, it should be noted that the
     dot (period, full stop) is not a valid character in a PHP
     variable name. For the reason, look at it:
     <programlisting role="php">
<![CDATA[
$varname.ext;  /* invalid variable name */
]]>
     </programlisting>
     Now, what the parser sees is a variable named
     <varname>$varname</varname>, followed by the string concatenation
     operator, followed by the barestring (i.e. unquoted string which
     doesn't match any known key or reserved words) 'ext'. Obviously,
     this doesn't have the intended result.
    </para>

    <para>
     For this reason, it is important to note that PHP will
     automatically replace any dots in incoming variable names with
     underscores.
    </para>

   </sect2>

   <sect2 id="language.variables.determining-type-of">
    <title>Determining variable types</title>

    <para>
     Because PHP determines the types of variables and converts them
     (generally) as needed, it is not always obvious what type a given
     variable is at any one time.  PHP includes several functions
     which find out what type a variable is. They are
     <function>gettype</function>, <function>is_long</function>,
     <function>is_double</function>, <function>is_string</function>,
     <function>is_array</function>, and
     <function>is_object</function>.
    </para>
   </sect2>

  </sect1>
     
 </chapter>
 
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->