torben Thu Feb 14 07:15:34 2002 EDT Modified files: /phpdoc/en/appendices predefined.xml Log: Some cleanups and a more thorough treatment of the various globals.
Index: phpdoc/en/appendices/predefined.xml diff -u phpdoc/en/appendices/predefined.xml:1.3 phpdoc/en/appendices/predefined.xml:1.4 --- phpdoc/en/appendices/predefined.xml:1.3 Thu Feb 14 02:02:22 2002 +++ phpdoc/en/appendices/predefined.xml Thu Feb 14 07:15:33 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.3 $ --> +<!-- $Revision: 1.4 $ --> <!-- Note: Please do not link or translate this file yet. This is only an initial update, quite a few more commits will @@ -18,27 +18,60 @@ <sect1 id="predefined.variables"> <title>Predefined Variables</title> - <sect2 id="predefined.variables.apache"> - <title>Apache variables</title> + <sect2 id="predefined.variables.server"> + <title>Server variables: <varname>$_SERVER</varname></title> + + <note> + <simpara> + Introduced in 4.1.0. In earlier versions, use + <varname>$HTTP_SERVER_VARS</varname>. + </simpara> + </note> <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. + <varname>$_SERVER</varname> is an array containing information + such as headers, paths, and script locations. The entries in this + array are created by the webserver. There is no guarantee that + every webserver 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 <ulink + url="&url.cgispec;">CGI 1.1 specification</ulink>, so you should + be able to expect those. + </simpara> + + <simpara> + This is a 'superglobal', or automatic global, variable. This + simply means that it is available in all scopes throughout a + script. You don't need to do a <command>global + $_SERVER;</command> to access it within functions or methods, as + you do with <varname>$HTTP_SERVER_VARS</varname>. + </simpara> + + <simpara> + <varname>$HTTP_SERVER_VARS</varname> contains the same + information, but is not an autoglobal. </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> + <simpara> + 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>$_SERVER</varname> and <varname>$HTTP_SERVER_VARS</varname> + arrays. For related information, see the security chapter titled + <link linkend="security.registerglobals">Using Register + Globals</link>. These individual globals are not autoglobals. + </simpara> + <para> <variablelist> <varlistentry> - <term>$GATEWAY_INTERFACE</term> + <term>'<varname>GATEWAY_INTERFACE</varname>'</term> <listitem> <simpara> What revision of the CGI specification the server is using; @@ -48,7 +81,7 @@ </varlistentry> <varlistentry> - <term>$SERVER_NAME</term> + <term>'<varname>SERVER_NAME</varname>'</term> <listitem> <simpara> The name of the server host under which the current script is @@ -59,7 +92,7 @@ </varlistentry> <varlistentry> - <term>$SERVER_SOFTWARE</term> + <term>'<varname>SERVER_SOFTWARE</varname>'</term> <listitem> <simpara> Server identification string, given in the headers when @@ -69,7 +102,7 @@ </varlistentry> <varlistentry> - <term>$SERVER_PROTOCOL</term> + <term>'<varname>SERVER_PROTOCOL</varname>'</term> <listitem> <simpara> Name and revision of the information protocol via which the @@ -79,7 +112,7 @@ </varlistentry> <varlistentry> - <term>$REQUEST_METHOD</term> + <term>'<varname>REQUEST_METHOD</varname>'</term> <listitem> <simpara> Which request method was used to access the page; i.e. 'GET', @@ -89,7 +122,7 @@ </varlistentry> <varlistentry> - <term>$QUERY_STRING</term> + <term>'<varname>QUERY_STRING</varname>'</term> <listitem> <simpara> The query string, if any, via which the page was accessed. @@ -98,7 +131,7 @@ </varlistentry> <varlistentry> - <term>$DOCUMENT_ROOT</term> + <term>'<varname>DOCUMENT_ROOT</varname>'</term> <listitem> <simpara> The document root directory under which the current script is @@ -108,7 +141,7 @@ </varlistentry> <varlistentry> - <term>$HTTP_ACCEPT</term> + <term>'<varname>HTTP_ACCEPT</varname>'</term> <listitem> <simpara> Contents of the <literal>Accept:</literal> header from the @@ -118,7 +151,7 @@ </varlistentry> <varlistentry> - <term>$HTTP_ACCEPT_CHARSET</term> + <term>'<varname>HTTP_ACCEPT_CHARSET</varname>'</term> <listitem> <simpara> Contents of the <literal>Accept-Charset:</literal> header @@ -129,7 +162,7 @@ </varlistentry> <varlistentry> - <term>$HTTP_ACCEPT_ENCODING</term> + <term>'<varname>HTTP_ACCEPT_ENCODING</varname>'</term> <listitem> <simpara> Contents of the <literal>Accept-Encoding:</literal> header @@ -139,7 +172,7 @@ </varlistentry> <varlistentry> - <term>$HTTP_ACCEPT_LANGUAGE</term> + <term>'<varname>HTTP_ACCEPT_LANGUAGE</varname>'</term> <listitem> <simpara> Contents of the <literal>Accept-Language:</literal> header @@ -149,7 +182,7 @@ </varlistentry> <varlistentry> - <term>$HTTP_CONNECTION</term> + <term>'<varname>HTTP_CONNECTION</varname>'</term> <listitem> <simpara> Contents of the <literal>Connection:</literal> header from @@ -159,7 +192,7 @@ </varlistentry> <varlistentry> - <term>$HTTP_HOST</term> + <term>'<varname>HTTP_HOST</varname>'</term> <listitem> <simpara> Contents of the <literal>Host:</literal> header from the @@ -169,34 +202,36 @@ </varlistentry> <varlistentry> - <term>$HTTP_REFERER</term> + <term>'<varname>HTTP_REFERER</varname>'</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. + 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>$HTTP_USER_AGENT</term> + <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 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. + 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>$REMOTE_ADDR</term> + <term>'<varname>REMOTE_ADDR</varname>'</term> <listitem> <simpara> The IP address from which the user is viewing the current @@ -206,7 +241,7 @@ </varlistentry> <varlistentry> - <term>$REMOTE_PORT</term> + <term>'<varname>REMOTE_PORT</varname>'</term> <listitem> <simpara> The port being used on the user's machine to communicate with @@ -216,7 +251,7 @@ </varlistentry> <varlistentry> - <term>$SCRIPT_FILENAME</term> + <term>'<varname>SCRIPT_FILENAME</varname>'</term> <listitem> <simpara> The absolute pathname of the currently executing script. @@ -225,7 +260,7 @@ </varlistentry> <varlistentry> - <term>$SERVER_ADMIN</term> + <term>'<varname>SERVER_ADMIN</varname>'</term> <listitem> <simpara> The value given to the SERVER_ADMIN (for Apache) directive in @@ -237,7 +272,7 @@ </varlistentry> <varlistentry> - <term>$SERVER_PORT</term> + <term>'<varname>SERVER_PORT</varname>'</term> <listitem> <simpara> The port on the server machine being used by the web server @@ -249,7 +284,7 @@ </varlistentry> <varlistentry> - <term>$SERVER_SIGNATURE</term> + <term>'<varname>SERVER_SIGNATURE</varname>'</term> <listitem> <simpara> String containing the server version and virtual host name @@ -259,7 +294,7 @@ </varlistentry> <varlistentry> - <term>$PATH_TRANSLATED</term> + <term>'<varname>PATH_TRANSLATED</varname>'</term> <listitem> <simpara> Filesystem- (not document root-) based path to the current @@ -270,7 +305,7 @@ </varlistentry> <varlistentry> - <term>$SCRIPT_NAME</term> + <term>'<varname>SCRIPT_NAME</varname>'</term> <listitem> <simpara> Contains the current script's path. This is useful for pages @@ -280,7 +315,7 @@ </varlistentry> <varlistentry> - <term>$REQUEST_URI</term> + <term>'<varname>REQUEST_URI</varname>'</term> <listitem> <simpara> The URI which was given in order to access this page; for @@ -288,14 +323,55 @@ </simpara> </listitem> </varlistentry> + + <varlistentry> + <term>'<varname>argv</varname>'</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>'<varname>argc</varname>'</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>PHP_SELF</varname>'</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. + </simpara> + </listitem> + </varlistentry> + </variablelist> </para> </sect2> <sect2 id="predefined.variables.environment"> - <title>Environment variables</title> + <title>Environment variables: <varname>$_ENV</varname></title> + <note> + <simpara> + Introduced in 4.1.0. In earlier versions, use + <varname>$HTTP_ENV_VARS</varname>. + </simpara> + </note> + <simpara> These variables are imported into PHP's global namespace from the environment under which the PHP parser is running. Many are @@ -304,162 +380,260 @@ 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> + <simpara> + This is a 'superglobal', or automatic global, variable. This + simply means that it is available in all scopes throughout a + script. You don't need to do a <command>global + $_ENV;</command> to access it within functions or methods, as + you do with <varname>$HTTP_ENV_VARS</varname>. + </simpara> + + <simpara> + <varname>$HTTP_ENV_VARS</varname> contains the same + information, but is not an autoglobal. + </simpara> + + <simpara> + 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>$_ENV</varname> and <varname>$HTTP_ENV_VARS</varname> + arrays. For related information, see the security chapter titled + <link linkend="security.registerglobals">Using Register + Globals</link>. These individual globals are not autoglobals. + </simpara> </sect2> - <sect2 id="predefined.variables.php"> - <title>PHP variables</title> + <sect2 id="predefined.variables.cookies"> + <title>HTTP Cookies: <varname>$_COOKIE</varname></title> + + <note> + <simpara> + Introduced in 4.1.0. In earlier versions, use + <varname>$HTTP_COOKIE_VARS</varname>. + </simpara> + </note> <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. + An associative array of variables passed to the current script + via HTTP cookies. Automatically global in any scope. + </simpara> + + <simpara> + This is a 'superglobal', or automatic global, variable. This + simply means that it is available in all scopes throughout a + script. You don't need to do a <command>global + $_COOKIE;</command> to access it within functions or methods, as + you do with <varname>$HTTP_COOKIE_VARS</varname>. + </simpara> + + <simpara> + <varname>$HTTP_COOKIE_VARS</varname> contains the same + information, but is not an autoglobal. + </simpara> + + <simpara> + 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>$_COOKIE</varname> and <varname>$HTTP_COOKIE_VARS</varname> + arrays. For related information, see the security chapter titled + <link linkend="security.registerglobals">Using Register + Globals</link>. These individual globals are not autoglobals. </simpara> + </sect2> + + <sect2 id="predefined.variables.get"> + <title>HTTP GET variables: <varname>$_GET</varname></title> <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> + <simpara> + Introduced in 4.1.0. In earlier versions, use + <varname>$HTTP_GET_VARS</varname>. + </simpara> </note> + + <simpara> + An associative array of variables passed to the current script + via the HTTP GET method. Automatically global in any scope. + </simpara> - <para> + <simpara> + This is a 'superglobal', or automatic global, variable. This + simply means that it is available in all scopes throughout a + script. You don't need to do a <command>global + $_GET;</command> to access it within functions or methods, as + you do with <varname>$HTTP_GET_VARS</varname>. + </simpara> + + <simpara> + <varname>$HTTP_GET_VARS</varname> contains the same + information, but is not an autoglobal. + </simpara> + + <simpara> 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> arrays. This feature should be - used with care, and turned off if possible; while the - <varname>$HTTP_*_VARS</varname> variables are safe, the bare - global equivalents can be overwritten by user input, with - possibly malicious intent. If you cannot turn off <link - linkend="ini.register-globals">register_globals</link>, you must - take whatever steps are necessary to ensure that the data you are - using is safe. - </para> + <varname>$_GET</varname> and <varname>$HTTP_GET_VARS</varname> + arrays. For related information, see the security chapter titled + <link linkend="security.registerglobals">Using Register + Globals</link>. These individual globals are not autoglobals. + </simpara> + </sect2> + + <sect2 id="predefined.variables.post"> + <title>HTTP POST variables: <varname>$_POST</varname></title> + + <note> + <simpara> + Introduced in 4.1.0. In earlier versions, use + <varname>$HTTP_POST_VARS</varname>. + </simpara> + </note> - <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> + <simpara> + An associative array of variables passed to the current script + via the HTTP POST method. Automatically global in any scope. + </simpara> - <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> + <simpara> + This is a 'superglobal', or automatic global, variable. This + simply means that it is available in all scopes throughout a + script. You don't need to do a <command>global + $_POST;</command> to access it within functions or methods, as + you do with <varname>$HTTP_POST_VARS</varname>. + </simpara> - <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. - </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>$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>$HTTP_POST_VARS</term> - <listitem> - <simpara> - An associative array of variables passed to the current - script via the HTTP POST method. - </simpara> - </listitem> - </varlistentry> + <simpara> + <varname>$HTTP_POST_VARS</varname> contains the same + information, but is not an autoglobal. + </simpara> + + <simpara> + 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>$_POST</varname> and <varname>$HTTP_POST_VARS</varname> + arrays. For related information, see the security chapter titled + <link linkend="security.registerglobals">Using Register + Globals</link>. These individual globals are not autoglobals. + </simpara> + </sect2> + + <sect2 id="predefined.variables.files"> + <title>HTTP File upload variables: <varname>$_FILES</varname></title> + + <note> + <simpara> + Introduced in 4.1.0. In earlier versions, use + <varname>$HTTP_POST_FILES</varname>. + </simpara> + </note> - <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>. - </simpara> - <para> - <varname>$HTTP_POST_FILES</varname> is available only in PHP - 4.0.0 and later. - </para> - </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> + <simpara> + An associative array of items uploaded to the current script + via the HTTP POST method. Automatically global in any scope. + </simpara> - <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> - </variablelist> - </para> - + <simpara> + This is a 'superglobal', or automatic global, variable. This + simply means that it is available in all scopes throughout a + script. You don't need to do a <command>global + $_FILES;</command> to access it within functions or methods, as + you do with <varname>$HTTP_POST_FILES</varname>. + </simpara> + + <simpara> + <varname>$HTTP_POST_FILES</varname> contains the same + information, but is not an autoglobal. + </simpara> + + <simpara> + 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>$_FILES</varname> and <varname>$HTTP_POST_FILES</varname> + arrays. For related information, see the security chapter titled + <link linkend="security.registerglobals">Using Register + Globals</link>. These individual globals are not autoglobals. + </simpara> + </sect2> + + <sect2 id="predefined.variables.request"> + <title>HTTP REQUEST variables: <varname>$_REQUEST</varname></title> + + <note> + <simpara> + Introduced in 4.1.0. There is no equivalent array in earlier + versions. + </simpara> + </note> + + <simpara> + An associative array consisting of the contents of + <varname>$_GET</varname>, <varname>$_POST</varname>, + <varname>$_COOKIE</varname>, and <varname>$_FILES</varname>. + </simpara> + + <simpara> + This is a 'superglobal', or automatic global, variable. This + simply means that it is available in all scopes throughout a + script. You don't need to do a <command>global + $_REQUEST;</command> to access it within functions or methods. + </simpara> + + <simpara> + 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>$_REQUEST</varname> array. For related information, see + the security chapter titled <link + linkend="security.registerglobals">Using Register + Globals</link>. These individual globals are not autoglobals. + </simpara> </sect2> </sect1> <sect1 id="predefined.classes"> <title>Predefined Classes</title> + + <sect2 id="predefined.classes.standard"> + <title>Standard Defined Classes</title> + + <simpara> + These classes are defined in the standard set of functions included + in the PHP build. + </simpara> + + <variablelist> + <varlistentry> + <term><classname>Directory</classname></term> + <listitem> + <simpara> + The class from which <function>dir</function> is instantiated. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </sect2> + <sect2 id="predefined.classes.ming"> - <title><link linkend="ref.ming">ming</link> Defined Classes</title> + <title><link linkend="ref.ming">Ming</link> Defined Classes</title> <simpara> These classes are defined in the @@ -562,14 +736,15 @@ </varlistentry> </variablelist> </sect2> + <sect2 id="predefined.classes.oci8"> - <title><link linkend="ref.oci8">oci8</link> Defined Constants</title> + <title><link linkend="ref.oci8">Oracle 8</link> Defined Constants</title> <simpara> - These constants are defined in the - <link linkend="ref.oci8">oci8</link> - extension, and will only be available when that extension has either - been compiled into PHP or dynamically loaded at runtime. + These constants are defined in the <link + linkend="ref.oci8">Oracle 8</link> extension, and will only be + available when that extension has either been compiled into PHP + or dynamically loaded at runtime. </simpara> <variablelist> @@ -617,26 +792,7 @@ </varlistentry> </variablelist> </sect2> - <sect2 id="predefined.classes.standard"> - <title><link linkend="ref.standard">standard</link> Defined Classes</title> - <simpara> - These classes are defined in the - <link linkend="ref.standard">standard</link> - extension, and will only be available when that extension has either - been compiled into PHP or dynamically loaded at runtime. - </simpara> - - <variablelist> - <varlistentry> - <term><classname>Directory</classname></term> - <listitem> - <simpara> - </simpara> - </listitem> - </varlistentry> - </variablelist> - </sect2> </sect1>