From e78b6dc0a2fc9d828722db6aa0673a02d44d2e9b Mon Sep 17 00:00:00 2001 From: Philip Olson Date: Wed, 3 Jul 2002 22:51:23 +0000 Subject: [PATCH] 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 git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@87651 c90b9560-bf6c-de11-be94-00142212c4b1 --- language/variables.xml | 318 ++++++++++++++++++++++++++--------------- 1 file changed, 200 insertions(+), 118 deletions(-) diff --git a/language/variables.xml b/language/variables.xml index 88678bd1e7..af78d43d7d 100644 --- a/language/variables.xml +++ b/language/variables.xml @@ -1,5 +1,5 @@ - + Variables @@ -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 Expressions. PHP 4 offers another way to assign values to variables: - assign by reference. 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. + assign by reference. + 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. To assign by reference, simply prepend an ampersand (&) 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 - Predefined variables. + variables will not be available when PHP is run on the + command line. + For a listing of these variables, please see the section on + Reserved Predefined Variables. - 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 by default no - longer placed directly into the global scope; rather, they are - placed into the following superglobal - arrays. + In PHP 4.2.0 and later, the default value for the PHP directive register_globals is + off. This is a major change in PHP. Having + register_globals off affects the set of predefined + variables available in the global scope. For example, to get + DOCUMENT_ROOT you'll use + $_SERVER['DOCUMENT_ROOT'] instead of + $DOCUMENT_ROOT, or $_GET['id'] from + the URL http://www.example.com/test.php?id=3 instead + of $id, or $_ENV['HOME'] instead of + $HOME. - You can still force the old behaviour by setting register_globals to 'On' in - your &php.ini; file. + For related information on this change, read the configuration entry for + register_globals, the security + chapter on Using Register Globals + , as well as the PHP 4.1.0 + and 4.2.0 Release + Announcements. - For more information and background on this change, please see - the PHP 4.1.0 Release - Announcement. + Using the available PHP Reserved Predefined Variables, like the + superglobal arrays, + is preferred. - 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 - Predefined variables. + Reserved Predefined Variables. + Also, you'll notice how the older predefined variables + ($HTTP_*_VARS) still exist. If certain variables in variables_order are not set, their - appropriate superglobal arrays are also left empty. + appropriate PHP predefined arrays are also left empty. @@ -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. + $GLOBALS has existed since PHP 3. @@ -245,16 +258,21 @@ $bar = &test(); // Invalid. 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 not include - the argv and argc - entries; these are present in the $_SERVER - array. The presence and order of variable inclusion in this - array is defined according to the variables_order 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 + import_request_variables. + + + When running on the command line + , this will not include the + argv and argc entries; these are + present in the $_SERVER array. + + @@ -390,8 +408,36 @@ echo $b; 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. + Notice how $GLOBALS exists in any scope, this + is because $GLOBALS is a superglobal. + Here's an example demonstrating the power of superglobals: - + + + + + +]]> + + + + Another important feature of variable scoping is the static variable. A static variable exists @@ -669,61 +715,101 @@ echo "$a $hello"; - Please note that variable variables cannot be used with PHP's new superglobals. + Please note that variable variables cannot be used with PHP's + Superglobal arrays. This means you cannot do things like ${$_GET}. If you are looking for a way to handle availability of superglobals and the old - HTTP_*_VARS, you might want to try referencing them. + HTTP_*_VARS, you might want to try + referencing them. Variables from outside PHP - + HTML Forms (GET and POST) - 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 track_vars - configuration option is turned on, then these variables will be - located in the associative arrays - $_POST, - $_GET, and/or - $_FILES, 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: - - For more information on these variables, please read Predefined - variables. - - - Simple form variable - + A simple HTML form +
- Name:
- + Name:
+ Email:
+
- - When the above form is submitted, the value from the text input - will be available in - $_POST['username']. If the + + + + Accessing data from a simple POST HTML form + + +]]> + + + + + 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, http://www.example.com/test.php?id=3 + contains GET data which is accessible with $_GET['id']. + See also $_REQUEST and + import_request_variables. + + + + + Superglobal arrays, + like $_POST and $_GET, became + available in PHP 4.1.0 + + + + + As shown, before PHP 4.2.0 the default value for register_globals - configuration directive is turned on, then the variable will also - be available as $username in the global scope. + was on. 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 off and code + accordingly. @@ -731,7 +817,7 @@ echo "$a $hello"; The magic_quotes_gpc 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 addslashes, stripslashes and magic_quotes_sybase. @@ -741,7 +827,9 @@ echo "$a $hello"; PHP also understands arrays in the context of form variables (see the related faq). 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: @@ -749,19 +837,31 @@ echo "$a $hello"; More complex form variables '; + + print_r($HTTP_POST_VARS); + print 'Please try again'; + + print ''; +} else { ?> -
- Name:
+ + Name:
Email:
Beer:
- + + + +
+ +
]]> @@ -777,14 +877,13 @@ echo "$a $hello"; When submitting a form, it is possible to use an image instead - of the standard submit button with a tag like: + of the standard submit button with a tag like: + - + - @@ -813,25 +912,36 @@ echo "$a $hello"; the setcookie 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 header function. Any cookies - sent to you from the client will automatically be turned into a - PHP variable just like GET and POST method data. + as for the header function. Cookie data + is then available in the appropriate cookie data arrays, such + as $_COOKIE, $HTTP_COOKIE_VARS + as well as in $_REQUEST. See the + setcookie manual page for more details and + examples. + - If you wish to assign multiple values to a single cookie, just - add [] 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: ]]> + + + 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 serialize or + explode on the value first. + Note that a cookie will replace a previous cookie by the same @@ -841,12 +951,12 @@ setcookie("MyCookie[]", "Testing", time()+3600); - SetCookie Example + A <function>setcookie</function> example ]]> @@ -855,35 +965,6 @@ setcookie("Cart[$count]", $item, time()+3600); - - Environment variables - - - PHP automatically makes environment variables available as normal - PHP variables. - - - - -]]> - - - - - - 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 - getenv function can be used for this. You - can also set an environment variable with the - putenv function. - - - Dots in incoming variable names @@ -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: gettype, is_array, is_float, is_int, is_object, and - is_string. + is_string. See also the chapter on + Types.