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

In summary, mentioned register_globals and superglobals a lot.

Browse source 
- Rewrote the register_globals warning for language.variables.predefined
- $GLOBALS has existed since PHP 3
- Added a variable scope example (superglobal vs old php var)
- Updated register_globals related info in various places
- Used mode="html" for html
- Added example showing different ways to access external information
- Explained GET a little
- Updated Array Cookie examples (they still set seperate cookies)
- Removed language.variables.external.environment as this is explained now
- Closed bug #15714


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@87651 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Philip Olson 2002-07-03 22:51:23 +00:00
parent db791d9fb2
commit e78b6dc0a2
1 changed files with 200 additions and 118 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

318
language/variables.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.51 $ -->
<!-- $Revision: 1.52 $ -->
<chapter id="language.variables">
<title>Variables</title>
@ -51,18 +51,20 @@ $t
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
assignment, see the chapter on <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.
<link linkend="language.references">assign by reference</link>.
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
<link linkend="language.types.array">arrays</link> or
<link linkend="language.types.object">objects</link>.
</para>
<para>
To assign by reference, simply prepend an ampersand (&amp;) to the
@ -118,35 +120,43 @@ $bar = &test(); // Invalid.
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. For a listing of these variables, please see the section
<link linkend="reserved.variables">Predefined variables</link>.
variables will not be available when PHP is run on the
<link linkend="features.commandline">command line</link>.
For a listing of these variables, please see the section on
<link linkend="reserved.variables">Reserved Predefined Variables</link>.
</simpara>
<warning>
<simpara>
In PHP 4.2.0 and later, the default set of predefined variables
which are available in the global scope has changed. Individual
input and server variables are <emphasis>by default</emphasis> no
longer placed directly into the global scope; rather, they are
placed into the following <link
linkend="language.variables.superglobals">superglobal
arrays</link>.
In PHP 4.2.0 and later, the default value for the PHP directive <link
linkend="ini.register-globals">register_globals</link> is
<emphasis>off</emphasis>. This is a major change in PHP. Having
register_globals <emphasis>off</emphasis> affects the set of predefined
variables available in the global scope. For example, to get
<varname>DOCUMENT_ROOT</varname> you'll use
<varname>$_SERVER['DOCUMENT_ROOT']</varname> instead of
<varname>$DOCUMENT_ROOT</varname>, or <varname>$_GET['id']</varname> from
the URL <literal>http://www.example.com/test.php?id=3</literal> instead
of <varname>$id</varname>, or <varname>$_ENV['HOME']</varname> instead of
<varname>$HOME</varname>.
</simpara>
<simpara>
You can still force the old behaviour by setting <link
linkend="ini.register-globals">register_globals</link> to 'On' in
your &php.ini; file.
For related information on this change, read the configuration entry for
<link linkend="ini.register-globals">register_globals</link>, the security
chapter on <link linkend="security.registerglobals">Using Register Globals
</link>, as well as the PHP <ulink url="&url.php.release4.1.0;">4.1.0
</ulink> and <ulink url="&url.php.release4.2.0;">4.2.0</ulink> Release
Announcements.
</simpara>
<simpara>
For more information and background on this change, please see
the <ulink url="&url.php.release4.1.0;">PHP 4.1.0 Release
Announcement</ulink>.
Using the available PHP Reserved Predefined Variables, like the
<link linkend="language.variables.superglobals">superglobal arrays</link>,
is preferred.
</simpara>
</warning>
<simpara>
From version 4.1.0 onward, PHP provides a set of predefined arrays
From version 4.1.0 onward, PHP provides an additional set of predefined arrays
containing variables from the web server (if applicable), the
environment, and user input. These new arrays are rather special
in that they are automatically global--i.e., automatically
@ -155,13 +165,15 @@ $bar = &test(); // Invalid.
user-defined superglobals.) The superglobals are listed below;
however, for a listing of their contents and further discussion on
PHP predefined variables and their natures, please see the section
<link linkend="reserved.variables">Predefined variables</link>.
<link linkend="reserved.variables">Reserved Predefined Variables</link>.
Also, you'll notice how the older predefined variables
(<varname>$HTTP_*_VARS</varname>) still exist.
</simpara>
<para>
If certain variables in <link
linkend="ini.variables-order">variables_order</link> are not set, their
appropriate superglobal arrays are also left empty.
appropriate PHP predefined arrays are also left empty.
</para>
<variablelist id="language.variables.superglobals">
@ -173,6 +185,7 @@ $bar = &test(); // Invalid.
Contains a reference to every variable which is currently
available within the global scope of the script. The keys of
this array are the names of the global variables.
<varname>$GLOBALS</varname> has existed since PHP 3.
</simpara>
</listitem>
</varlistentry>
@ -245,16 +258,21 @@ $bar = &test(); // Invalid.
<listitem>
<simpara>
Variables provided to the script via any user input mechanism,
and which therefore cannot be trusted. Note: when running on
the command line, this will <emphasis>not</emphasis> include
the <varname>argv</varname> and <varname>argc</varname>
entries; these are present in the <varname>$_SERVER</varname>
array. The presence and order of variable inclusion in this
array is defined according to the <link
and which therefore cannot be trusted. The presence and order
of variable inclusion in this array is defined according to the <link
linkend="ini.variables-order">variables_order</link>
configuration directive. This array has no direct analogue in
versions of PHP prior to 4.1.0.
versions of PHP prior to 4.1.0. See also
<function>import_request_variables</function>.
</simpara>
<note>
<simpara>
When running on the <link linkend="features.commandline">command line
</link>, this will <emphasis>not</emphasis> include the
<varname>argv</varname> and <varname>argc</varname> entries; these are
present in the <varname>$_SERVER</varname> array.
</simpara>
</note>
</listitem>
</varlistentry>
<varlistentry>
@ -390,8 +408,36 @@ echo $b;
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.
Notice how <varname>$GLOBALS</varname> exists in any scope, this
is because $GLOBALS is a <link
linkend="language.variables.superglobals">superglobal</link>.
Here's an example demonstrating the power of superglobals:
</simpara>
<para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
function test_global()
{
// Most predefined variables aren't "super" and require
// 'global' to be available to the functions local scope.
global $HTTP_POST_VARS;
print $HTTP_POST_VARS['name'];
// Superglobals are available in any scope and do
// not require 'global'. Superglobals are available
// as of PHP 4.1.0
print $_POST['name'];
}
?>
]]>
</programlisting>
</informalexample>
</para>
<simpara>
Another important feature of variable scoping is the
<emphasis>static</emphasis> variable. A static variable exists
@ -669,61 +715,101 @@ echo "$a $hello";
</simpara>
<simpara>
Please note that variable variables cannot be used with PHP's new superglobals.
Please note that variable variables cannot be used with PHP's
<link linkend="language.variables.superglobals">Superglobal arrays</link>.
This means you cannot do things like <varname>${$_GET}</varname>. If you are
looking for a way to handle availability of superglobals and the old
HTTP_*_VARS, you might want to try <link linkend="language.references">referencing</link> them.
<varname>HTTP_*_VARS</varname>, you might want to try
<link linkend="language.references">referencing</link> them.
</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>$_POST</varname>,
<varname>$_GET</varname>, and/or
<varname>$_FILES</varname>, according to the
source of the variable in question.
When a form is submitted to a PHP script, the information from
that form is automatically made available to the script. There
are many ways to access this information, for example:
</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">
<title>A simple HTML form</title>
<programlisting role="html">
<![CDATA[
?>
<form action="foo.php" method="post">
Name: <input type="text" name="username"><br>
<input type="submit">
Name: <input type="text" name="username"><br>
Email: <input type="text" name="email"><br>
<input type="submit" name="submit" value="Submit me!">
</form>
<?php
]]>
</programlisting>
</example>
</para>
<para>
When the above form is submitted, the value from the text input
will be available in
<varname>$_POST['username']</varname>. If the <link
Depending on your particular setup and personal preferences, there
are many ways to access data from your HTML forms. Some examples are:
</para>
<para>
<example>
<title>Accessing data from a simple POST HTML form</title>
<programlisting role="html">
<![CDATA[
<?php
// Available since PHP 4.1.0
print $_POST['username'];
print $_REQUEST['username'];
import_request_variables('p', 'p_');
print $p_username;
// Available since PHP 3.
print $HTTP_POST_VARS['username'];
// Available if the PHP directive register_globals = on. As of
// PHP 4.2.0 the default value of register_globals = off.
// Using/relying on this method is not preferred.
print $username;
?>
]]>
</programlisting>
</example>
</para>
<para>
Using a GET form is similar except you'll use the appropriate
GET predefined variable instead. GET also applies to the
QUERY_STRING (the information after the '?' in an URL). So,
for example, <literal>http://www.example.com/test.php?id=3</literal>
contains GET data which is accessible with <varname>$_GET['id']</varname>.
See also <link linkend="reserved.variables.request">$_REQUEST</link> and
<function>import_request_variables</function>.
</para>
<note>
<para>
<link linkend="language.variables.superglobals">Superglobal arrays</link>,
like <varname>$_POST</varname> and <varname>$_GET</varname>, became
available in PHP 4.1.0
</para>
</note>
<para>
As shown, before PHP 4.2.0 the default value for <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.
was <emphasis>on</emphasis>. And, in PHP 3 it was always on. The PHP
community is encouraging all to not rely on this directive
as it's preferred to assume it's <emphasis>off</emphasis> and code
accordingly.
</para>
<note>
@ -731,7 +817,7 @@ echo "$a $hello";
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
Escaping is needed for DB insertion. See also
<function>addslashes</function>, <function>stripslashes</function> and
<link linkend="ini.magic-quotes-sybase">magic_quotes_sybase</link>.
</para>
@ -741,7 +827,9 @@ echo "$a $hello";
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:
feature to retrieve values from a multiple select input. For
example, let's post a form to itself and upon submission display
the data:
</simpara>
<para>
@ -749,19 +837,31 @@ echo "$a $hello";
<title>More complex form variables</title>
<programlisting role="php">
<![CDATA[
<?php
if ($HTTP_POST_VARS['action'] == 'submitted') {
print '<pre>';
print_r($HTTP_POST_VARS);
print '<a href="'. $HTTP_SERVER_VARS['PHP_SELF'] .'">Please try again</a>';
print '</pre>';
} else {
?>
<form action="array.php" method="post">
Name: <input type="text" name="personal[name]"><br>
<form action="<?php echo $HTTP_SERVER_VARS['PHP_SELF']; ?>" 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äu
</select>
<input type="submit">
<option value="warthog">Warthog</option>
<option value="guinness">Guinness</option>
<option value="stuttgarter">Stuttgarter Schwabenbräu</option>
</select><br>
<input type="hidden" name="action" value="submitted">
<input type="submit" name="submit" value="submit me!">
</form>
<?php
}
?>
]]>
</programlisting>
</example>
@ -777,14 +877,13 @@ echo "$a $hello";
<simpara>
When submitting a form, it is possible to use an image instead
of the standard submit button with a tag like:</simpara>
of the standard submit button with a tag like:
</simpara>
<informalexample>
<programlisting role="php">
<programlisting role="html">
<![CDATA[
?>
<input type="image" src="image.gif" name="sub">
<?php
]]>
</programlisting>
</informalexample>
@ -813,25 +912,36 @@ echo "$a $hello";
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>
as for the <function>header</function> function. Cookie data
is then available in the appropriate cookie data arrays, such
as <varname>$_COOKIE</varname>, <varname>$HTTP_COOKIE_VARS</varname>
as well as in <varname>$_REQUEST</varname>. See the
<function>setcookie</function> manual page for more details and
examples.
</simpara>
<simpara>
If you wish to assign multiple values to a single cookie, just
add <emphasis>[]</emphasis> to the cookie name. For
example:
If you wish to assign multiple values to a single cookie variable, you
may assign it as an array. For example:
</simpara>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
setcookie("MyCookie[]", "Testing", time()+3600);
setcookie("MyCookie[foo]", "Testing 1", time()+3600);
setcookie("MyCookie[bar]", "Testing 2", time()+3600);
?>
]]>
</programlisting>
</informalexample>
<simpara>
That will create two seperate cookies although MyCookie will now
be a single array in your script. If you want to set just one cookie
with multiple values, consider using <function>serialize</function> or
<function>explode</function> on the value first.
</simpara>
<simpara>
Note that a cookie will replace a previous cookie by the same
@ -841,12 +951,12 @@ setcookie("MyCookie[]", "Testing", time()+3600);
</simpara>
<example>
<title>SetCookie Example</title>
<title>A <function>setcookie</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$count++;
setcookie("Count", $count, time()+3600);
setcookie("count", $count, time()+3600);
setcookie("Cart[$count]", $item, time()+3600);
?>
]]>
@ -855,35 +965,6 @@ setcookie("Cart[$count]", $item, time()+3600);
</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[
<?php
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>
@ -921,11 +1002,12 @@ $varname.ext; /* invalid variable name */
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
which find out what type a variable is, such as:
<function>gettype</function>, <function>is_array</function>,
<function>is_float</function>, <function>is_int</function>,
<function>is_object</function>, and
<function>is_string</function>.
<function>is_string</function>. See also the chapter on
<link linkend="features.types">Types</link>.
</para>
</sect2>