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

Added a 'Basics' section to sort of flesh out the use of variables.

Browse source 
More importantly, added a bunch of stuff about predefined PHP variables,
since people keep asking about them. I've tried to make it fairly clear
that many of these will not be available in all circumstances.

I hope someone will access to other webservers can provide some
information on unique variables provided (under stock setups) by those
servers. An exhaustive listing may be impossible, but at least we can
explain the bits that are known.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@16690 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
cslawi 1999-12-06 03:23:22 +00:00
parent 2b2b47991e
commit aea6da18e1
1 changed files with 475 additions and 16 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

491
language/variables.sgml
View file

@ -1,17 +1,471 @@
<chapter id="language.variables">
<title>Variables</title>
<chapter id="language.variables">
<title>Variables</title>
<sect1 id="language.variables.basics">
<title>Basics</title>
<para>
Variables in PHP are represented by a dollar sign followed by the
name of the variable. The variable name is case-sensitive.
<informalexample>
<programlisting>
<para>
Variables in PHP are represented by a dollar sign followed by the
name of the variable. The variable name is case-sensitive.
<informalexample>
<programlisting>
$var = "Bob";
$Var = "Joe";
echo "$var, $Var"; // outputs "Bob, Joe"
</programlisting>
</informalexample>
</para>
</programlisting>
</informalexample>
</para>
<para>
In PHP3, 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>
PHP4 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>
&lt;?php
$foo = 'Bob'; // Assign the value 'Bob' to $foo
$bar = &amp;$foo; // Reference $foo via $bar.
$bar = "My name is $bar"; // Alter $bar...
echo $foo; // $foo is altered too.
echo $bar;
?&gt;
</programlisting>
</informalexample>
</para>
<para>
One important thing to note is that only named variables may be
assigned by reference.
<informalexample>
<programlisting>
&lt;?php
$foo = 25;
$bar = &amp;$foo; // This is a valid assignment.
$bar = &amp;(24 * 7); // Invalid; references an unnamed expression.
function test() {
return 25;
}
$bar = &amp;test(); // Invalid.
?&gt;
</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.environment">
<title>Predefined environment variables</title>
<simpara>
These variables are imported into PHP's global namespace from the
environment under which the PHP parser is running. As they 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>
</sect2>
<sect2 id="language.variables.predefined.php">
<title>Predefined PHP variables</title>
<simpara>
These variables are created by PHP itself.
</simpara>
<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
commandline 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 commandline 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>
</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>
</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>
</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>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 id="language.variables.predefined.apache">
<title>Predefined 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.
</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>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>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>HTTP_ACCEPT_CHARSET</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>HTTP_ENCODING</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>HTTP_ACCEPT_LANGUAGE</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>HTTP_CONNECTION</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>HTTP_HOST</term>
<listitem>
<simpara>
The web server hostname on which the script is
executing. This may be a true host name or, if running on a
virtual host, the name of the virtual host.
</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>
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_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_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>SERVER_SOFTWARE</term>
<listitem>
<simpara>
Server identification string, given in the headers when
responding to requests.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>GATEWAY_INTERFACE</term>
<listitem>
<simpara>
What kind of interaction interface is enabled;
i.e. 'CGI/1.1'.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>SERVER_PROTOCOL</term>
<listitem>
<simpara>
The protocol used by the server to communicate with clients;
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';
'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>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>
</sect1>
<sect1 id="language.variables.scope">
<title>Variable scope</title>
@ -137,7 +591,7 @@ Function Test () {
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 statis
simple function recursively counts to 10, using the static
variable $count to know when to stop:
</simpara>
@ -162,7 +616,8 @@ Function Test () {
<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>
dynamically. A normal variable is set with a statement such as:
</simpara>
<informalexample>
<programlisting>
@ -173,7 +628,8 @@ $a = "hello";
<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. ie.</simpara>
be used as the name of a variable by using two dollar signs. i.e.
</simpara>
<informalexample>
<programlisting>
@ -184,7 +640,8 @@ $$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:</simpara>
"world". Therefore, this statement:
</simpara>
<informalexample>
<programlisting>
@ -193,7 +650,8 @@ echo "$a ${$a}";
</informalexample>
<simpara>
produces the exact same output as:</simpara>
produces the exact same output as:
</simpara>
<informalexample>
<programlisting>
@ -202,7 +660,8 @@ echo "$a $hello";
</informalexample>
<simpara>
ie. they both produce: <emphasis>hello world</emphasis>.</simpara>
i.e. they both produce: <emphasis>hello world</emphasis>.
</simpara>
<simpara>
In order to use variable variables with arrays, you have to