<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 291068 $ -->

<phpdoc:varentry xmlns:phpdoc="http://php.net/ns/phpdoc" xml:id="reserved.variables.server" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" role="noversion">
 <refnamediv>
  <refname>$_SERVER</refname>
  <refname>$HTTP_SERVER_VARS [deprecated]</refname>
  <refpurpose>Server and execution environment information</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <para>
   <varname>$_SERVER</varname> is an array containing information
   such as headers, paths, and script locations. The entries in this
   array are created by the web server. There is no guarantee that
   every web server will provide any of these; servers may omit some,
   or provide others not listed here. That said, a large number of
   these variables are accounted for in the <link
   xlink:href="&url.cgispec;">CGI 1.1 specification</link>, so you should
   be able to expect those.
  </para>

  <simpara>
   <varname>$HTTP_SERVER_VARS</varname> contains the same initial
   information, but is not a <link linkend="language.variables.superglobals">superglobal</link>.
   (Note that <varname>$HTTP_SERVER_VARS</varname> and <varname>$_SERVER</varname>
   are different variables and that PHP handles them as such)
  </simpara>
 </refsect1>

 <refsect1 role="indices">
  &reftitle.indices;

  <simpara>
   You may or may not find any of the following elements in
   <varname>$_SERVER</varname>. Note that few, if any, of these will be
   available (or indeed have any meaning) if running PHP on the
   <link linkend="features.commandline">command line</link>.
  </simpara>

  <para>
   <variablelist>
    <varlistentry>
     <term>'<varname>PHP_SELF</varname>'</term>
     <listitem>
      <simpara>
       The filename of the currently executing script, relative to
       the document root. For instance,
       <varname>$_SERVER['PHP_SELF']</varname> in a script at the
       address <filename>http://example.com/test.php/foo.bar</filename>
       would be <filename>/test.php/foo.bar</filename>.
       The <link linkend="language.constants.predefined">__FILE__</link>
       constant contains the full path and filename of the current (i.e.
       included) file.
      </simpara>
      <simpara>
       If PHP is running as a command-line processor this variable contains
       the script name since PHP 4.3.0. Previously it was not available.
      </simpara>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>'<link linkend="reserved.variables.argv">argv</link>'</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>'<link linkend="reserved.variables.argc">argc</link>'</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>'<varname>GATEWAY_INTERFACE</varname>'</term>
     <listitem>
      <simpara>
       What revision of the CGI specification the server is using;
       i.e. '<literal>CGI/1.1</literal>'.
      </simpara>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>'<varname>SERVER_ADDR</varname>'</term>
     <listitem>
      <simpara>
       The IP address of the server under which the current script is
       executing.
      </simpara>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>'<varname>SERVER_NAME</varname>'</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>'<varname>SERVER_SOFTWARE</varname>'</term>
     <listitem>
      <simpara>
       Server identification string, given in the headers when
       responding to requests.
      </simpara>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>'<varname>SERVER_PROTOCOL</varname>'</term>
     <listitem>
      <simpara>
       Name and revision of the information protocol via which the
       page was requested; i.e. '<literal>HTTP/1.0</literal>';
      </simpara>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>'<varname>REQUEST_METHOD</varname>'</term>
     <listitem>
      <simpara>
       Which request method was used to access the page; i.e. '<literal>GET</literal>',
       '<literal>HEAD</literal>', '<literal>POST</literal>', '<literal>PUT</literal>'.
      </simpara>
      <note>
       <para>
        PHP script is terminated after sending headers (it means after
        producing any output without output buffering) if the request method
        was <literal>HEAD</literal>.
       </para>
      </note>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>'<varname>REQUEST_TIME</varname>'</term>
     <listitem>
      <simpara>
       The timestamp of the start of the request. Available since PHP 5.1.0.
      </simpara>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>'<varname>QUERY_STRING</varname>'</term>
     <listitem>
      <simpara>
       The query string, if any, via which the page was accessed.
      </simpara>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>'<varname>DOCUMENT_ROOT</varname>'</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>'<varname>HTTP_ACCEPT</varname>'</term>
     <listitem>
      <simpara>
       Contents of the <literal>Accept:</literal> header from the
       current request, if there is one.
      </simpara>
     </listitem>
    </varlistentry>

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

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

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

    <varlistentry>
     <term>'<varname>HTTP_REFERER</varname>'</term>
     <listitem>
      <simpara>
       The address of the page (if any) which referred the user
       agent to the current page. This is set by the user agent. Not
       all user agents will set this, and some provide the ability
       to modify <varname>HTTP_REFERER</varname> as a feature. In
       short, it cannot really be trusted.
      </simpara>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>'<varname>HTTP_USER_AGENT</varname>'</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 user agent being which is accessing the page. A
       typical example is: <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 output to the capabilities of the user
       agent.
      </simpara>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>'<varname>HTTPS</varname>'</term>
     <listitem>
      <simpara>
       Set to a non-empty value if the script was queried through the HTTPS
       protocol.
      </simpara>
      <note>
       <simpara>
        Note that when using ISAPI with IIS, the value will be 
        <literal>off</literal> if the request was not made through the HTTPS
        protocol.
       </simpara>
      </note>
     </listitem>
    </varlistentry>

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

    <varlistentry>
     <term>'<varname>REMOTE_HOST</varname>'</term>
     <listitem>
      <simpara>
       The Host name from which the user is viewing the current
       page.  The reverse dns lookup is based off the 
       <varname>REMOTE_ADDR</varname> of the user.
      </simpara>
      <note>
       <simpara>
        Your web server must be configured to create this variable. For
        example in Apache you'll need <literal>HostnameLookups On</literal>
        inside &httpd.conf; for it to exist.  See also
        <function>gethostbyaddr</function>.
       </simpara>
      </note>
     </listitem>
    </varlistentry>

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

    <varlistentry>
     <term>'<varname>SCRIPT_FILENAME</varname>'</term>
     <listitem>
      <para>
       The absolute pathname of the currently executing script.
       <note>
        <para>
         If a script is executed with the CLI, as a relative path,
         such as <filename>file.php</filename> or 
         <filename>../file.php</filename>, 
         <varname>$_SERVER['SCRIPT_FILENAME']</varname> will 
         contain the relative path specified by the user.
        </para>
       </note>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>'<varname>SERVER_ADMIN</varname>'</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>'<varname>SERVER_PORT</varname>'</term>
     <listitem>
      <simpara>
       The port on the server machine being used by the web server
       for communication. For default setups, this will be '<literal>80</literal>';
       using SSL, for instance, will change this to whatever your
       defined secure HTTP port is.
      </simpara>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>'<varname>SERVER_SIGNATURE</varname>'</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>'<varname>PATH_TRANSLATED</varname>'</term>
     <listitem>
      <simpara>
       Filesystem- (not document root-) based path to the current
       script, after the server has done any virtual-to-real
       mapping.
      </simpara>
      <note>
       <simpara>
        As of PHP 4.3.2, <envar>PATH_TRANSLATED</envar> is no longer set 
        implicitly under the Apache 2 <acronym>SAPI</acronym> in contrast 
        to the situation in Apache 1, where it's set to the same value as 
        the <envar>SCRIPT_FILENAME</envar> server variable when it's not 
        populated by Apache.  This change was made to comply with the 
        <acronym>CGI</acronym> specification that 
        <envar>PATH_TRANSLATED</envar> should only exist if 
        <envar>PATH_INFO</envar> is defined.
       </simpara>
       <simpara>
        Apache 2 users may use <literal>AcceptPathInfo = On</literal> inside
        <filename>httpd.conf</filename> to define <envar>PATH_INFO</envar>.
       </simpara>
      </note>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>'<varname>SCRIPT_NAME</varname>'</term>
     <listitem>
      <simpara>
       Contains the current script's path. This is useful for pages
       which need to point to themselves.
       The <link linkend="language.constants.predefined">__FILE__</link>
       constant contains the full path and filename of the current (i.e.
       included) file.
      </simpara>
     </listitem>
    </varlistentry>

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

    <varlistentry>
     <term>'<varname>PHP_AUTH_DIGEST</varname>'</term>
     <listitem>
      <simpara>
       When running under Apache as module doing Digest HTTP authentication
       this variable is set to the 'Authorization' header sent by the
       client (which you should then use to make the appropriate
       validation).
      </simpara>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>'<varname>PHP_AUTH_USER</varname>'</term>
     <listitem>
      <simpara>
       When running under Apache or IIS (ISAPI on PHP 5) as module doing
       HTTP authentication this variable is set to the username provided by
       the user.
      </simpara>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>'<varname>PHP_AUTH_PW</varname>'</term>
     <listitem>
      <simpara>
       When running under Apache or IIS (ISAPI on PHP 5) as module doing
       HTTP authentication this variable is set to the password provided by
       the user.
      </simpara>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>'<varname>AUTH_TYPE</varname>'</term>
     <listitem>
      <simpara>
       When running under Apache as module doing HTTP authenticated this
       variable is set to the authentication type.
      </simpara>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>'<varname>PATH_INFO</varname>'</term>
     <listitem>
      <simpara>
       Contains any client-provided pathname information trailing the
       actual script filename but preceding the query string, if
       available. For instance, if the current script was accessed via
       the
       URL <filename>http://www.example.com/php/path_info.php/some/stuff?foo=bar</filename>,
       then <varname>$_SERVER['PATH_INFO']</varname> would
       contain <literal>/some/stuff</literal>.
      </simpara>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>'<varname>ORIG_PATH_INFO</varname>'</term>
     <listitem>
      <simpara>
       Original version of '<varname>PATH_INFO</varname>' before processed by
       PHP.
      </simpara>
     </listitem>
    </varlistentry>

   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>4.1.0</entry>
       <entry>
        Introduced <varname>$_SERVER</varname> that deprecated
        <varname>$HTTP_SERVER_VARS</varname>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example xml:id="variable.server.basic">
    <title><varname>$_SERVER</varname> example</title>
    <programlisting role="php">
<![CDATA[
<?php
echo $_SERVER['SERVER_NAME'];
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
www.example.com
]]>
    </screen>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  &note.is-superglobal;
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><link linkend="book.filter">The filter extension</link></member>
   </simplelist>
  </para>
 </refsect1>

</phpdoc:varentry>
 
<!-- 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
-->