sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 17:08:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updates to some of the portions affected by track_vars and

Browse source 
register_globals, and some notes about changes between PHP 3 and PHP 4.

Also lots of little cleanups.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@32364 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Torben Wilson 2000-09-10 02:57:19 +00:00
parent 656c4db979
commit c5060b056b
1 changed files with 263 additions and 252 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

515
language/variables.xml
View file

@ -68,7 +68,7 @@ $t
<programlisting role="php">
&lt;?php
$foo = 'Bob'; // Assign the value 'Bob' to $foo
$bar = &amp;$foo; // Reference $foo via $bar.
$bar = &amp;$foo; // Reference $foo via $bar.
$bar = "My name is $bar"; // Alter $bar...
echo $foo; // $foo is altered too.
echo $bar;
@ -110,12 +110,14 @@ $bar = &amp;test(); // Invalid.
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>.
@ -151,252 +153,252 @@ $bar = &amp;test(); // Invalid.
<varlistentry>
<term>GATEWAY_INTERFACE</term>
<listitem>
<simpara>
What revision of the CGI specification the server is using;
i.e. 'CGI/1.1'.
</simpara>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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_ENCODING</term>
<listitem>
<simpara>
Contents of the <literal>Accept-Encoding:</literal> header
from the current request, if there is one. Example: 'gzip'.
</simpara>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<simpara>
The URI which was given in order to access this page; for
instance, '/index.html'.
</simpara>
</listitem>
</varlistentry>
</variablelist>
@ -425,140 +427,132 @@ $bar = &amp;test(); // Invalid.
<sect2 id="language.variables.predefined.php">
<title>PHP variables</title>
<simpara>
These variables are created by PHP itself.
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.
</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>
<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> 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>
<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>
<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>
<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.
</simpara>
<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. Only available if variable tracking
has been turned on via either the <link
linkend="ini.track-vars">track_vars</link> configuration
directive or the
<computeroutput>&lt;?php_track_vars?&gt;</computeroutput>
directive.
</simpara>
<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. Only available if variable
tracking has been turned on via either the <link
linkend="ini.track-vars">track_vars</link> configuration
directive or the
<computeroutput>&lt;?php_track_vars?&gt;</computeroutput>
directive.
</simpara>
<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. Only available if variable
tracking has been turned on via either the <link
linkend="ini.track-vars">track_vars</link> configuration
directive or the
<computeroutput>&lt;?php_track_vars?&gt;</computeroutput>
directive.
</simpara>
<simpara>
An associative array of variables passed to the current
script via the HTTP POST method.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term>HTTP_POST_FILES</term>
<listitem>
<simpara>
An associative array of variables containing information
about files uploaded via the HTTP POST method.
Only available if variable
tracking has been turned on via either the <link
linkend="ini.track-vars">track_vars</link> configuration
directive or the
<computeroutput>&lt;?php_track_vars?&gt;</computeroutput>
directive.
</simpara>
<simpara>
An associative array of variables containing information
about files uploaded via the HTTP POST method.
</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. Only available if variable
tracking has been turned on via either the <link
linkend="ini.track-vars">track_vars</link> configuration
directive or the
<computeroutput>&lt;?php_track_vars?&gt;</computeroutput>
directive.
</simpara>
<simpara>
An associative array of variables passed to the current
script via the parent environment.
</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.
Only available if variable
tracking has been turned on via either the <link
linkend="ini.track-vars">track_vars</link> configuration
directive or the
<computeroutput>&lt;?php_track_vars?&gt;</computeroutput>
directive.
</simpara>
<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>
@ -583,11 +577,11 @@ include "b.inc";
</programlisting>
</informalexample>
<simpara>
Here the $a variable will be available within the included b.inc
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:
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>
@ -604,14 +598,16 @@ Test ();
<simpara>
This script will not produce any output because the echo statement
refers to a local version of the $a 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>
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">
@ -630,17 +626,17 @@ echo $b;
</informalexample>
<simpara>
The above script will output &quot;3&quot;. By declaring $a and
$b 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.
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 $GLOBALS array. The previous example can
be rewritten as:
the special PHP-defined <varname>$GLOBALS</varname> array. The
previous example can be rewritten as:
</simpara>
<informalexample>
@ -658,9 +654,9 @@ echo $b;
</informalexample>
<simpara>
The $GLOBALS 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.
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>
@ -683,11 +679,13 @@ Function Test () {
<simpara>
This function is quite useless since every time it is called it
sets $a to 0 and prints &quot;0&quot;. The $a++ which increments
the variable serves no purpose since as soon as the function exits
the $a variable disappears. To make a useful counting function
which will not lose track of the current count, the $a variable is
declared static:</simpara>
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">
@ -701,7 +699,7 @@ Function Test () {
<simpara>
Now, every time the Test() function is called it will print the
value of $a and increment it.
value of <varname>$a</varname> and increment it.
</simpara>
<simpara>
@ -711,7 +709,7 @@ Function Test () {
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 $count to know when to stop:
variable <varname>$count</varname> to know when to stop:
</simpara>
<informalexample>
@ -761,8 +759,9 @@ $$a = "world";
<simpara>
At this point two variables have been defined and stored in the
PHP symbol tree: $a with contents "hello" and $hello with contents
"world". Therefore, this statement:
PHP symbol tree: <varname>$a</varname> with contents "hello" and
<varname>$hello</varname> with contents "world". Therefore, this
statement:
</simpara>
<informalexample>
@ -782,17 +781,18 @@ echo "$a $hello";
</informalexample>
<simpara>
i.e. they both produce: <emphasis>hello world</emphasis>.
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 $$a[1] then
the parser needs to know if you meant to use $a[1] as a variable,
or if you wanted $$a as the variable and then the [1] index from
that variable. The syntax for resolving this ambiguity is:
${$a[1]} for the first case and ${$a}[1] for the
second.
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>
@ -806,33 +806,48 @@ echo "$a $hello";
<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. For instance, consider the following form:
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">
&lt;form action="foo.php3" method="post">
Name: &lt;input type="text" name="name">&lt;br>
&lt;form action="foo.php" method="post">
Name: &lt;input type="text" name="username">&lt;br>
&lt;input type="submit">
&lt;/form>
</programlisting>
</example>
</para>
<simpara>
When submitted, PHP will create the variable
<computeroutput>$name</computeroutput>, which will will contain
whatever what entered into the <emphasis>Name:</emphasis> field
on the form.
</simpara>
<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>
<simpara>
PHP also understands arrays in the context of form variables, but
only in one dimension. You may, for example, group related
variables together, or use this feature to retrieve values from a
multiple select input:</simpara>
PHP also understands arrays in the context of form variables. You
may, for example, group related variables together, or use this
feature to retrieve values from a multiple select
input:
</simpara>
<para>
<example>
@ -853,14 +868,10 @@ echo "$a $hello";
</example>
</para>
<simpara>
If PHP's track_vars feature is turned on, either by the <link
linkend="ini.track-vars">track_vars</link> configuration setting
or the <computeroutput>&lt;?php_track_vars?&gt;</computeroutput>
directive, then variables submitted via the POST or GET methods
will also be found in the global associative arrays
$HTTP_POST_VARS and $HTTP_GET_VARS as appropriate.
</simpara>
<para>
In PHP 3, the array form variable usage is limited to
single-dimensional arrays. In PHP 4, no such restriction applies.
</para>
<sect3>
<title>IMAGE SUBMIT variable names</title>
@ -969,11 +980,11 @@ echo $HOME; /* Shows the HOME environment variable, if set. */
<programlisting role="php">
$varname.ext; /* invalid variable name */
</programlisting>
Now, what the parser sees is a variable named $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.
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>