philip Wed Jul 3 18:51:24 2002 EDT
Modified files:
/phpdoc/en/language variables.xml
Log:
In summary, mentioned register_globals and superglobals a lot.
- 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
Index: phpdoc/en/language/variables.xml
diff -u phpdoc/en/language/variables.xml:1.51 phpdoc/en/language/variables.xml:1.52
--- phpdoc/en/language/variables.xml:1.51 Fri Jun 28 20:52:16 2002
+++ phpdoc/en/language/variables.xml Wed Jul 3 18:51:23 2002
@@ -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 @@
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 (&) to the
@@ -118,35 +120,43 @@
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 @@
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 @@
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 @@
<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 @@
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 @@
</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>.
+ <example>
+ <title>A simple HTML form</title>
+ <programlisting role="html">
+<![CDATA[
+<form action="foo.php" method="post">
+ Name: <input type="text" name="username"><br>
+ Email: <input type="text" name="email"><br>
+ <input type="submit" name="submit" value="Submit me!">
+</form>
+]]>
+ </programlisting>
+ </example>
</para>
<para>
+ 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>Simple form variable</title>
- <programlisting role="php">
+ <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;
?>
-<form action="foo.php" method="post">
- Name: <input type="text" name="username"><br>
- <input type="submit">
-</form>
-<?php
]]>
</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>
- When the above form is submitted, the value from the text input
- will be available in
- <varname>$_POST['username']</varname>. If the <link
+ 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 @@
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 @@
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 @@
<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 @@
<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 @@
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 @@
</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 @@
</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 @@
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>
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
