diff --git a/language/variables.sgml b/language/variables.sgml index 06aa5159b2..10ca5bfa54 100644 --- a/language/variables.sgml +++ b/language/variables.sgml @@ -1,17 +1,471 @@ - - Variables + + Variables + + + Basics - - Variables in PHP are represented by a dollar sign followed by the - name of the variable. The variable name is case-sensitive. - - + + Variables in PHP are represented by a dollar sign followed by the + name of the variable. The variable name is case-sensitive. + + $var = "Bob"; $Var = "Joe"; echo "$var, $Var"; // outputs "Bob, Joe" - - - + + + + + + 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 Expressions. + + + + PHP4 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. + + + + To assign by reference, simply prepend an ampersand (&) 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: + + + +<?php +$foo = 'Bob'; // Assign the value 'Bob' to $foo +$bar = &$foo; // Reference $foo via $bar. +$bar = "My name is $bar"; // Alter $bar... +echo $foo; // $foo is altered too. +echo $bar; +?> + + + + + + + One important thing to note is that only named variables may be + assigned by reference. + + +<?php +$foo = 25; +$bar = &$foo; // This is a valid assignment. +$bar = &(24 * 7); // Invalid; references an unnamed expression. + +function test() { + return 25; +} + +$bar = &test(); // Invalid. +?> + + + + + + + + Predefined variables + + + 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. + + + + 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 Apache 1.3.6. + + + + For a list of all predefined variables (and lots of other useful + information), please see (and use) phpinfo. + + + + + 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. + + + + + Predefined environment variables + + + 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. + + + + + + Predefined PHP variables + + + These variables are created by PHP itself. + + + + + + argv + + + 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. + + + + + + argc + + + Contains the number of commandline parameters passed to the + script (if run on the command line). + + + + + + PHP_SELF + + + 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. + + + + + + HTTP_COOKIE_VARS + + + 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 track_vars configuration + directive or the + <?php_track_vars?> + directive. + + + + + + HTTP_GET_VARS + + + 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 track_vars configuration + directive or the + <?php_track_vars?> + directive. + + + + + + HTTP_POST_VARS + + + 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 track_vars configuration + directive or the + <?php_track_vars?> + directive. + + + + + + + + + + + Predefined Apache variables + + + These variables are created by the Apache 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. + + + + Note that few, if any, of these will be available (or indeed have + any meaning) if running PHP on the command line. + + + + + + DOCUMENT_ROOT + + + The document root directory under which the current script is + executing, as defined in the server's configuration file. + + + + + + HTTP_ACCEPT + + + + + + + + + HTTP_ACCEPT_CHARSET + + + + + + + + + HTTP_ENCODING + + + + + + + + + HTTP_ACCEPT_LANGUAGE + + + + + + + + + HTTP_CONNECTION + + + + + + + + + HTTP_HOST + + + 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. + + + + + + HTTP_REFERER + + + 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. + + + + + + HTTP_USER_AGENT + + + A string denoting the browser software being used to view the + current page; i.e. Mozilla/4.5 [en] (X11; U; + Linux 2.2.9 i586). Among other things, you + can use this value with get_browser to + tailor your page's functionality to the capabilities of the + user's browser. + + + + + + REMOTE_ADDR + + + The IP address from which the user is viewing the current + page. + + + + + + REMOTE_PORT + + + The port being used on the user's machine to communicate with + the web server. + + + + + + SCRIPT_FILENAME + + + The absolute pathname of the currently executing script. + + + + + + SERVER_ADMIN + + + 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. + + + + + + SERVER_NAME + + + 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. + + + + + + SERVER_PORT + + + 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. + + + + + + SERVER_SIGNATURE + + + String containing the server version and virtual host name + which are added to server-generated pages, if enabled. + + + + + + SERVER_SOFTWARE + + + Server identification string, given in the headers when + responding to requests. + + + + + + GATEWAY_INTERFACE + + + What kind of interaction interface is enabled; + i.e. 'CGI/1.1'. + + + + + + SERVER_PROTOCOL + + + The protocol used by the server to communicate with clients; + i.e. 'HTTP/1.0'; + + + + + + REQUEST_METHOD + + + Which request method was used to access the page; i.e. 'GET'; + 'POST'; 'PUT'. + + + + + + QUERY_STRING + + + The query string, if any, via which the page was accessed. + + + + + + REQUEST_URI + + + The URI which was given in order to access this page; for + instance, '/index.html'. + + + + + + + + + + Variable scope @@ -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: @@ -162,7 +616,8 @@ Function Test () { 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: + dynamically. A normal variable is set with a statement such as: + @@ -173,7 +628,8 @@ $a = "hello"; A variable variable takes the value of a variable and treats that as the name of a variable. In the above example, hello, can - be used as the name of a variable by using two dollar signs. ie. + be used as the name of a variable by using two dollar signs. i.e. + @@ -184,7 +640,8 @@ $$a = "world"; 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: + "world". Therefore, this statement: + @@ -193,7 +650,8 @@ echo "$a ${$a}"; - produces the exact same output as: + produces the exact same output as: + @@ -202,7 +660,8 @@ echo "$a $hello"; - ie. they both produce: hello world. + i.e. they both produce: hello world. + In order to use variable variables with arrays, you have to