From aeb2d5524e6cabd4f22ecf853ba0cbf58db17f2d Mon Sep 17 00:00:00 2001 From: cslawi Date: Wed, 20 Oct 1999 22:54:01 +0000 Subject: [PATCH] Normalized according to the DocBook 3.1 DTD. This mostly just adds closing tags and attribute quotes, but lets a stock 3.1 install compile the PHP docs. It still compiles with DocBook 3.0, as well. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@14695 c90b9560-bf6c-de11-be94-00142212c4b1 --- appendices/debugger.sgml | 17 +- appendices/migration.sgml | 54 +++--- appendices/phpdevel.sgml | 236 ++++++++++++------------- chapters/config.sgml | 87 +++++----- chapters/copyright.sgml | 8 +- chapters/install.sgml | 250 +++++++++++---------------- chapters/security.sgml | 109 +++++------- features/connection-handling.sgml | 14 +- features/cookies.sgml | 4 +- features/error-handling.sgml | 14 +- features/file-upload.sgml | 31 ++-- features/http-auth.sgml | 24 +-- features/images.sgml | 2 +- features/persistent-connections.sgml | 20 +-- features/remote-files.sgml | 14 +- language/basic-syntax.sgml | 25 ++- language/constants.sgml | 10 +- language/control-structures.sgml | 108 ++++++------ language/expressions.sgml | 30 ++-- language/functions.sgml | 48 +++-- language/oop.sgml | 18 +- language/operators.sgml | 16 +- language/types.sgml | 105 +++++------ language/variables.sgml | 70 ++++---- 24 files changed, 616 insertions(+), 698 deletions(-) diff --git a/appendices/debugger.sgml b/appendices/debugger.sgml index cbc5d59582..032344fcb7 100644 --- a/appendices/debugger.sgml +++ b/appendices/debugger.sgml @@ -1,4 +1,3 @@ - The PHP Debugger @@ -11,29 +10,27 @@ for every time PHP starts up. All error messages from that request will be sent to this TCP connection. This information is intended for "debugging server" that can run inside an - IDE or programmable editor (such as Emacs). + IDE or programmable editor (such as Emacs). How to set up the debugger: - Set up a TCP port for the debugger in the configuration file (debugger.port) and enable it - (debugger.enabled). + Set up a TCP port for the debugger in the configuration file (debugger.port) and enable it + (debugger.enabled). Set up a TCP listener on that port somewhere - (for example socket -l -s 1400 on UNIX). + (for example socket -l -s 1400 on UNIX). In your code, run "debugger_on(host)", where host is the IP number or name of the - host running the TCP listener. + host running the TCP listener. Now, all warnings, notices etc. will show up on that listener socket, even if you them turned off with - error_reporting. + error_reporting. Debugger Protocol @@ -43,7 +40,7 @@ message. Each message starts with a line of the type start and terminates with a line of the type end. PHP may send lines for different - messages simultaneously. + messages simultaneously. A line has this format: diff --git a/appendices/migration.sgml b/appendices/migration.sgml index 58e3d224eb..36aa6dcfcc 100644 --- a/appendices/migration.sgml +++ b/appendices/migration.sgml @@ -1,4 +1,3 @@ - Migrating from PHP/FI 2.0 to PHP 3.0 @@ -9,26 +8,25 @@ that is much more robust and consistent than 2.0's. 3.0 is also significantly faster, and uses less memory. However, some of these improvements have not been possible without compatibility - changes, both in syntax and functionality. + changes, both in syntax and functionality. In addition, PHP's developers have tried to clean up both PHP's syntax and semantics in version 3.0, and this has also caused some incompatibilities. In the long run, we believe that these changes - are for the better. + are for the better. This chapter will try to guide you through the incompatibilities you might run into when going from PHP/FI 2.0 to PHP 3.0 and help you resolve them. New features are not mentioned here unless - necessary. + necessary. A conversion program that can automatically convert your old - PHP/FI 2.0 scripts exists. It can be found in the convertor subdirectory of the PHP 3.0 + PHP/FI 2.0 scripts exists. It can be found in the convertor subdirectory of the PHP 3.0 distribution. This program only catches the syntax changes though, - so you should read this chapter carefully anyway. + so you should read this chapter carefully anyway. Start/end tags @@ -74,7 +72,7 @@ echo "This is PHP 3.0 code!\n"; </script> - + @@ -109,7 +107,7 @@ endif; Notice that the semicolons have been replaced by colons in all - statements but the one terminating the expression (endif). + statements but the one terminating the expression (endif). while syntax @@ -134,7 +132,7 @@ endwhile; If you use the old while..endwhile syntax in PHP 3.0, you will get a never-ending loop. - + Expression types @@ -142,8 +140,8 @@ endwhile; PHP/FI 2.0 used the left side of expressions to determine what type the result should be. PHP 3.0 takes both sides into account when determining result types, and this may cause 2.0 scripts to behave - unexpectedly in 3.0. - + unexpectedly in 3.0. + Consider this example: @@ -175,7 +173,7 @@ while ("" != $key) { The fix for this is simple. Replace the while statement with: while ((string)$key != "") { - + @@ -185,7 +183,7 @@ while ((string)$key != "") { but you no longer get to see the code fragment causing the error. You will be supplied with a file name and a line number for the error, though. - + @@ -195,11 +193,11 @@ while ((string)$key != "") { in an expression like (1 || test_me()), the function test_me would not be executed since nothing can change the result of the expression after the - 1. + 1. This is a minor compatibility issue, but may cause unexpected - side-effects. + side-effects. @@ -212,7 +210,7 @@ while ((string)$key != "") { fail("darn!");. Because PHP/FI 2.0 had no clear rules for what functions should return when they failed, most such scripts will probably have to be checked manually after using the - 2.0 to 3.0 convertor. + 2.0 to 3.0 convertor. Migration from 2.0: return values, old code @@ -228,7 +226,7 @@ endif; $fp = @fopen($file, "r") or print("Could not open $file for reading<br>\n"); - + @@ -237,38 +235,38 @@ $fp = @fopen($file, "r") or print("Could not open $file for reading<br>\n" The PHP 3.0 Apache module no longer supports Apache versions - prior to 1.2. Apache 1.2 or later is required. + prior to 1.2. Apache 1.2 or later is required. echo no longer supports a format string. Use the - printf function instead. + printf function instead. In PHP/FI 2.0, an implementation side-effect caused $foo[0] to have the same effect as - $foo. This is not true for PHP 3.0. + $foo. This is not true for PHP 3.0. Reading arrays with $array[] is no longer - supported + supported That is, you cannot traverse an array by having a loop that does $data = $array[]. Use current and next - instead. + instead. Also, $array1[] = $array2 does not append the values of $array2 to $array1, but appends $array2 as the last entry of $array1. See also multidimensional array - support. + support. "+" is no longer overloaded as a concatenation operator for strings, instead it converts it's arguments to numbers and performs numeric addition. Use - "." instead. + "." instead. @@ -289,7 +287,7 @@ echo "1"."1"; $a = 1; $b = 1; echo $a + $b; - + This would echo 2 in both PHP 2.0 and 3.0. @@ -299,8 +297,8 @@ $a = 1; $b = 1; echo $a.$b; - This will echo 11 in PHP 3.0. - + This will echo 11 in PHP 3.0. + diff --git a/appendices/phpdevel.sgml b/appendices/phpdevel.sgml index 59e89ae72a..71d4aae801 100644 --- a/appendices/phpdevel.sgml +++ b/appendices/phpdevel.sgml @@ -15,7 +15,7 @@ void php3_foo(INTERNAL_FUNCTION_PARAMETERS) { } Even if your function doesn't take any arguments, this is how it is - called. + called. Function Arguments @@ -23,7 +23,7 @@ void php3_foo(INTERNAL_FUNCTION_PARAMETERS) { Arguments are always of type pval. This type contains a union which has the actual type of the argument. So, if your function takes two arguments, you would do something like the following at - the top of your function: + the top of your function: @@ -40,27 +40,27 @@ if (ARG_COUNT(ht) != 2 || getParameters(ht,2,&arg1,&arg2)==FAILURE) { both cases you will need to pass &(pval *) to getParameters. If you want to check if the n'th parameter was sent to you by reference or not, you can use the function, - ParameterPassedByReference(ht,n). It will return either 1 or 0. + ParameterPassedByReference(ht,n). It will return either 1 or 0. When you change any of the passed parameters, whether they are sent by reference or by value, you can either start over with the parameter by calling pval_destructor on it, or if it's an ARRAY you want to add to, you can use functions similar to the ones in - internal_functions.h which manipulate return_value as an ARRAY. + internal_functions.h which manipulate return_value as an ARRAY. Also if you change a parameter to IS_STRING make sure you first assign the new estrdup()'ed string and the string length, and only later change the type to IS_STRING. If you change the string of a parameter which already IS_STRING or IS_ARRAY you should run - pval_destructor on it first. + pval_destructor on it first. Variable Function Arguments A function can take a variable number of arguments. If your function can - take either 2 or 3 arguments, use the following: + take either 2 or 3 arguments, use the following: @@ -74,7 +74,7 @@ if (arg_count < 2 || arg_count > 3 || WRONG_PARAM_COUNT; } - + Using the Function Arguments @@ -124,7 +124,7 @@ if (arg_count < 2 || arg_count > 3 || - + If you get an argument of one type and would like to use it as @@ -138,18 +138,18 @@ convert_to_double(arg1); convert_to_string(arg1); convert_to_boolean_long(arg1); /* If the string is "" or "0" it becomes 0, 1 otherwise */ convert_string_to_number(arg1); /* Converts string to either LONG or DOUBLE depending on string */ - + - These function all do in-place conversion. They do not return anything. + These function all do in-place conversion. They do not return anything. The actual argument is stored in a union; the members are: - IS_STRING: arg1->value.str.val - IS_LONG: arg1->value.lval - IS_DOUBLE: arg1->value.dval - + IS_STRING: arg1->value.str.val + IS_LONG: arg1->value.lval + IS_DOUBLE: arg1->value.dval + Memory Management in Functions @@ -157,7 +157,7 @@ convert_string_to_number(arg1); /* Converts string to either LONG or DOUBLE dep Any memory needed by a function should be allocated with either emalloc() or estrdup(). These are memory handling abstraction functions that look and smell like the normal malloc() and - strdup() functions. Memory should be freed with efree(). + strdup() functions. Memory should be freed with efree(). There are two kinds of memory in this program: memory which is @@ -167,7 +167,7 @@ convert_string_to_number(arg1); /* Converts string to either LONG or DOUBLE dep make sure you first allocate the memory with either emalloc() or estrdup(). This memory should NEVER be freed by you, unless you later in the same function overwrite your original assignment - (this kind of programming practice is not good though). + (this kind of programming practice is not good though). For any temporary/permanent memory you need in your @@ -179,12 +179,12 @@ convert_string_to_number(arg1); /* Converts string to either LONG or DOUBLE dep leak. The meaning of "the functions behave exactly like their counterparts" is: if you efree() something which was not emalloc()'ed nor estrdup()'ed you might get a segmentation - fault. So please take care and free all of your wasted memory. + fault. So please take care and free all of your wasted memory. If you compile with "-DDEBUG", PHP3 will print out a list of all memory that was allocated using emalloc() and estrdup() but never - freed with efree() when it is done running the specified script. + freed with efree() when it is done running the specified script. Setting Variables in the Symbol Table @@ -193,31 +193,31 @@ convert_string_to_number(arg1); /* Converts string to either LONG or DOUBLE dep variable in the symbol table: - SET_VAR_STRING(name,value) - SET_VAR_DOUBLE(name,value) - SET_VAR_LONG(name,value) - + SET_VAR_STRING(name,value) + SET_VAR_DOUBLE(name,value) + SET_VAR_LONG(name,value) + Be careful here. The value part must be malloc'ed manually because the memory management code will try to free this pointer later. Do - not pass statically allocated memory into a SET_VAR_STRING. - + not pass statically allocated memory into a SET_VAR_STRING. + Symbol tables in PHP 3.0 are implemented as hash tables. At any given time, &symbol_table is a pointer to the 'main' symbol table, and active_symbol_table points to the currently active symbol table (these may be identical like in startup, or - different, if you're inside a function). + different, if you're inside a function). The following examples use 'active_symbol_table'. You should replace it with &symbol_table if you specifically want to work with the 'main' symbol table. Also, the same functions may be - applied to arrays, as explained below. + applied to arrays, as explained below. @@ -238,18 +238,18 @@ check(pvalue.type); Arrays in PHP 3.0 are implemented using the same hashtables as symbol tables. This means the two above functions can also be - used to check variables inside arrays. + used to check variables inside arrays. If you want to define a new array in a symbol table, you should do - the following. + the following. First, you may want to check whether it exists and abort - appropiately, using hash_exists() or hash_find(). + appropiately, using hash_exists() or hash_find(). - Next, initialize the array: + Next, initialize the array: @@ -263,10 +263,10 @@ hash_update(active_symbol_table,"foo",sizeof("foo"),&arr,sizeof(pval),NULL); This code declares a new array, named $foo, in the active symbol - table. This array is empty. + table. This array is empty. - Here's how to add new entries to it: + Here's how to add new entries to it: @@ -295,22 +295,22 @@ hash_next_index_insert(arr.value.ht,&entry,sizeof(pval),NULL); you can supply a pval ** to the hash add function, and it'll be updated with the pval * address of the inserted element inside the hash. If that value is NULL (like in all of the above examples) - - that parameter is ignored. + that parameter is ignored. hash_next_index_insert() uses more or less the same logic as - "$foo[] = bar;" in PHP 2.0. + "$foo[] = bar;" in PHP 2.0. If you are building an array to return from a function, you can - initialize the array just like above by doing: + initialize the array just like above by doing: if (array_init(return_value) == FAILURE) { failed...; } - ...and then adding values with the helper functions: + ...and then adding values with the helper functions: add_next_index_long(return_value,long_value); @@ -327,68 +327,68 @@ pval *arr; if (hash_find(active_symbol_table,"foo",sizeof("foo"),(void **)&arr)==FAILURE) { can't find... } else { use arr->value.ht... } - + Note that hash_find receives a pointer to a pval pointer, and not - a pval pointer. + a pval pointer. Just about any hash function returns SUCCESS or FAILURE (except - for hash_exists(), which returns a boolean truth value). + for hash_exists(), which returns a boolean truth value). Returning simple values A number of macros are available to make returning values from a - function easier. + function easier. The RETURN_* macros all set the return value and return from the function: - RETURN - RETURN_FALSE - RETURN_TRUE - RETURN_LONG(l) - RETURN_STRING(s,dup) If dup is true, duplicates the string - RETURN_STRINGL(s,l,dup) Return string (s) specifying length (l). - RETURN_DOUBLE(d) - + RETURN + RETURN_FALSE + RETURN_TRUE + RETURN_LONG(l) + RETURN_STRING(s,dup) If dup is true, duplicates the string + RETURN_STRINGL(s,l,dup) Return string (s) specifying length (l). + RETURN_DOUBLE(d) + The RETVAL_* macros set the return value, but do not return. - RETVAL_FALSE - RETVAL_TRUE - RETVAL_LONG(l) - RETVAL_STRING(s,dup) If dup is true, duplicates the string - RETVAL_STRINGL(s,l,dup) Return string (s) specifying length (l). - RETVAL_DOUBLE(d) - + RETVAL_FALSE + RETVAL_TRUE + RETVAL_LONG(l) + RETVAL_STRING(s,dup) If dup is true, duplicates the string + RETVAL_STRINGL(s,l,dup) Return string (s) specifying length (l). + RETVAL_DOUBLE(d) + The string macros above will all estrdup() the passed 's' argument, so you can safely free the argument after calling the - macro, or alternatively use statically allocated memory. + macro, or alternatively use statically allocated memory. If your function returns boolean success/error responses, always - use RETURN_TRUE and RETURN_FALSE respectively. + use RETURN_TRUE and RETURN_FALSE respectively. Returning complex values Your function can also return a complex data type such as an - object or an array. + object or an array. Returning an object: - Call object_init(return_value). + Call object_init(return_value). Fill it up with values. The functions available - for this purpose are listed below. + for this purpose are listed below. Possibly, register functions for this object. In order to obtain values from the object, the function would have to fetch "this" from the active_symbol_table. Its type @@ -397,80 +397,80 @@ else { use arr->value.ht... } actual registration of the function can be done using: add_method( return_value, function_name, function_ptr ); - - + + The functions used to populate an object are: add_property_long( return_value, property_name, l ) - Add a property named 'property_name', of - type long, equal to 'l' + type long, equal to 'l' add_property_double( return_value, - property_name, d ) - Same, only adds a double + property_name, d ) - Same, only adds a double add_property_string( return_value, - property_name, str ) - Same, only adds a string + property_name, str ) - Same, only adds a string add_property_stringl( return_value, - property_name, str, l ) - Same, only adds a string of length 'l' - + property_name, str, l ) - Same, only adds a string of length 'l' + Returning an array: - Call array_init(return_value). + Call array_init(return_value). Fill it up with values. The functions available - for this purpose are listed below. - + for this purpose are listed below. + The functions used to populate an array are: add_assoc_long(return_value,key,l) - add - associative entry with key 'key' and long value 'l' - add_assoc_double(return_value,key,d) - add_assoc_string(return_value,key,str,duplicate) + associative entry with key 'key' and long value 'l' + add_assoc_double(return_value,key,d) + add_assoc_string(return_value,key,str,duplicate) add_assoc_stringl(return_value,key,str,length,duplicate) - specify the string length + specify the string length add_index_long(return_value,index,l) - add - entry in index 'index' with long value 'l' - add_index_double(return_value,index,d) - add_index_string(return_value,index,str) + entry in index 'index' with long value 'l' + add_index_double(return_value,index,d) + add_index_string(return_value,index,str) add_index_stringl(return_value,index,str,length) - - specify the string length + - specify the string length add_next_index_long(return_value,l) - add an - array entry in the next free offset with long value 'l' - add_next_index_double(return_value,d) - add_next_index_string(return_value,str) + array entry in the next free offset with long value 'l' + add_next_index_double(return_value,d) + add_next_index_string(return_value,str) add_next_index_stringl(return_value,str,length) - - specify the string length - + - specify the string length + Using the resource list PHP 3.0 has a standard way of dealing with various types of - resources. This replaces all of the local linked lists in PHP 2.0. + resources. This replaces all of the local linked lists in PHP 2.0. Available functions: php3_list_insert(ptr, type) - returns the 'id' - of the newly inserted resource + of the newly inserted resource php3_list_delete(id) - delete the resource - with the specified id + with the specified id php3_list_find(id,*type) - returns the pointer of the resource with the specified id, - updates 'type' to the resource's type + updates 'type' to the resource's type Typically, these functions are used for SQL drivers but they can be used for anything else; for instance, maintaining file - descriptors. + descriptors. - Typical list code would look like this: + Typical list code would look like this: @@ -518,7 +518,7 @@ php3_list_delete(resource_id->value.lval); list_entry_type. In addition, one should add shutdown code for any new resource type defined, in list.c's list_entry_destructor() (even if you don't have anything to do on shutdown, you must add - an empty case). + an empty case). Using the persistent resource table @@ -533,13 +533,13 @@ php3_list_delete(resource_id->value.lval); php3_mysql_do_connect php3_mysql_connect() php3_mysql_pconnect() - + The general idea of persistence modules is this: Code all of your module to work with the - regular resource list mentioned in section (9). + regular resource list mentioned in section (9). Code extra connect functions that check if the resource already exists in the persistent resource list. If it does, register it as in the regular resource list as a pointer to @@ -551,27 +551,27 @@ php3_list_delete(resource_id->value.lval); resource would be found in the persistent resource list and be used without having to recreate it. You should register these resources with a different type (e.g. LE_MYSQL_LINK for - non-persistent link and LE_MYSQL_PLINK for a persistent link). - + non-persistent link and LE_MYSQL_PLINK for a persistent link). + If you read mysql.c, you'll notice that except for the more complex connect function, nothing in the rest of the module has to - be changed. + be changed. The very same interface exists for the regular resource list and the persistent resource list, only 'list' is replaced with - 'plist': + 'plist': php3_plist_insert(ptr, type) - returns the 'id' - of the newly inserted resource + of the newly inserted resource php3_plist_delete(id) - delete the resource - with the specified id + with the specified id php3_plist_find(id,*type) - returns the pointer of the resource with the specified id, - updates 'type' to the resource's type + updates 'type' to the resource's type @@ -584,11 +584,11 @@ php3_list_delete(resource_id->value.lval); that were passed to the function, and hashes the SQL link with this string as a key. The next time someone calls a pconnect() with the same host/user/passwd, the same key would be generated, - and the function would find the SQL link in the persistent list. + and the function would find the SQL link in the persistent list. Until further documented, you should look at mysql.c or msql.c to - see how one should use the plist's hash table abilities. + see how one should use the plist's hash table abilities. One important thing to note: resources going into the persistent @@ -599,7 +599,7 @@ php3_list_delete(resource_id->value.lval); hit), every memory chunk that was allocated using PHP's memory manager is deleted. Since the persistent list isn't supposed to be erased at the end of a request, one mustn't use PHP's memory - manager for allocating resources that go to it. + manager for allocating resources that go to it. When you register a resource that's going to be in the persistent @@ -612,7 +612,7 @@ php3_list_delete(resource_id->value.lval); every resource, even it requires no destructotion and the destructor would be empty. Remember, since emalloc() and friends aren't to be used in conjunction with the persistent list, you - mustn't use efree() here either. + mustn't use efree() here either. @@ -626,36 +626,36 @@ php3_list_delete(resource_id->value.lval); basis. This means that one directory may have a certain safemodeexecdir for example, while another directory may have another. This configuration granularity is especially handy when - a server supports multiple virtual hosts. + a server supports multiple virtual hosts. The steps required to add a new directive: - Add directive to php3_ini_structure struct in mod_php3.h. + Add directive to php3_ini_structure struct in mod_php3.h. In main.c, edit the php3_module_startup function and add the appropriate cfg_get_string() or - cfg_get_long() call. + cfg_get_long() call. Add the directive, restrictions and a comment to the php3_commands structure in mod_php3.c. Note the restrictions part. RSRC_CONF are directives that can only be present in the actual Apache .conf files. Any OR_OPTIONS directives can be present anywhere, include normal .htaccess - files. + files. In either php3take1handler() or - php3flaghandler() add the appropriate entry for your directive. + php3flaghandler() add the appropriate entry for your directive. In the configuration section of the _php3_info() function in functions/info.c you need to add your - new directive. + new directive. And last, you of course have to use your new directive somewhere. It will be addressable as - php3_ini.directive. - + php3_ini.directive. + @@ -689,7 +689,7 @@ php3_list_delete(resource_id->value.lval); HashTable *function_table This is the hash table in which the function is to be looked up. - + pval *object @@ -701,7 +701,7 @@ php3_list_delete(resource_id->value.lval); be modified by the function that is invoked on it (that function will have access to it via $this). If for some reason you don't want that to happen, send a copy of the object instead. - + pval *function_name @@ -711,7 +711,7 @@ php3_list_delete(resource_id->value.lval); set to the appropriate values. The function_name is modified by call_user_function() - it's converted to lowercase. If you need to preserve the case, send a copy of the function name instead. - + pval *retval @@ -720,13 +720,13 @@ php3_list_delete(resource_id->value.lval); the invoked function is saved. The structure must be previously allocated - call_user_function does NOT allocate it by itself. - + int param_count The number of parameters being passed to the function. - + pval *params[] @@ -737,7 +737,7 @@ php3_list_delete(resource_id->value.lval); are sent as-is to the function, which means if the function modifies its arguments, the original values are changed (passing by reference). If you don't want that behavior, pass a copy instead. - + Reporting Errors @@ -805,6 +805,8 @@ php3_list_delete(resource_id->value.lval); + + +--> String Operators @@ -70,7 +70,7 @@ $a = "Hello "; $b = $a . "World!"; // now $b = "Hello World!" - + Assignment Operators @@ -97,7 +97,7 @@ $a += 5; // sets $a to 8, as if we had said: $a = $a + 5; $b = "Hello "; $b .= "There!"; // sets $b to "Hello There!", just like $b = $b . "There!"; - + Bitwise Operators @@ -149,7 +149,7 @@ $b .= "There!"; // sets $b to "Hello There!", just like $b = $b . "There!"; - + Logical Operators @@ -202,7 +202,7 @@ $b .= "There!"; // sets $b to "Hello There!", just like $b = $b . "There!"; The reason for the two different variations of "and" and "or" operators is that they operate at different precedences. (See below.) - + Comparison Operators @@ -262,7 +262,7 @@ $b .= "There!"; // sets $b to "Hello There!", just like $b = $b . "There!"; (expr1) ? (expr2) : (expr3); This expression returns to expr2 if expr1 evalutes to true, and expr3 if - expr1 evaluates to false. + expr1 evaluates to false. Operator Precedence @@ -271,7 +271,7 @@ $b .= "There!"; // sets $b to "Hello There!", just like $b = $b . "There!"; two expressions together. For example, in the expression 1 + 5 * 3, the answer is 16 and not 18 because the multiplication ("*") operator has a higher precedence - than the addition ("+") operator. + than the addition ("+") operator. The following table lists the precedence of operators with the lowest-precedence operators listed first. @@ -368,7 +368,7 @@ $b .= "There!"; // sets $b to "Hello There!", just like $b = $b . "There!"; - + diff --git a/language/types.sgml b/language/types.sgml index 463af598c9..0a070e1ca8 100644 --- a/language/types.sgml +++ b/language/types.sgml @@ -5,29 +5,27 @@ PHP supports the following types: - integer - floating-point numbers - string - array - object - + integer + floating-point numbers + string + array + object + The type of a variable is usually not set by the programmer; rather, it is decided at runtime by PHP depending on the context - in which that variable is used. + in which that variable is used. If you would like to force a variable to be converted to a certain - type, you may either cast the variable or use - the settype function on it. + type, you may either cast the variable or use + the settype function on it. Note that a variable may behave in different manners in certain - situations, depending on what type it is a the time. For more - information, see the section on Type Juggling. + situations, depending on what type it is at the time. For more + information, see the section on Type Juggling. Integers @@ -38,7 +36,7 @@ $a = 1234; # decimal number $a = -123; # a negative number $a = 0123; # octal number (equivalent to 83 decimal) $a = 0x12; # hexadecimal number (equivalent to 18 decimal) - + Floating point numbers @@ -48,12 +46,12 @@ $a = 0x12; # hexadecimal number (equivalent to 18 decimal) $a = 1.234; $a = 1.2e3; - + Strings - Strings can be specified using one of two sets of delimiters. + Strings can be specified using one of two sets of delimiters. If the string is enclosed in double-quotes ("), variables within the string will be expanded (subject to some parsing @@ -109,27 +107,27 @@ $a = 1.2e3; - + You can escape any other character, but a warning will be issued - at the highest warning level. + at the highest warning level. The second way to delimit a string uses the single-quote ("'") character, which does not do any variable expansion or backslash processing (except for "\\" and "\'" so you can insert backslashes - and single-quotes in a singly-quoted string). + and single-quotes in a singly-quoted string). String conversion When a string is evaluated as a numeric value, the resulting - value and type are determined as follows. + value and type are determined as follows. The string will evaluate as a double if it contains any of the characters '.', 'e', or 'E'. Otherwise, it will evaluate as an - integer. + integer. The value is given by the initial portion of the string. If the @@ -138,11 +136,11 @@ $a = 1.2e3; is an optional sign, followed by one or more digits (optionally containing a decimal point), followed by an optional exponent. The exponent is an 'e' or 'E' followed by one or more - digits. + digits. When the first expression is a string, the type of the variable - will depend on the second expression. + will depend on the second expression. @@ -159,14 +157,14 @@ $foo = "10.0 pigs " + 1.0; // $foo is double (11) For more information on this conversion, see the Unix manual - page for strtod(3). + page for strtod(3). Arrays Arrays actually act like both hash tables (associative arrays) - and indexed arrays (vectors). + and indexed arrays (vectors). Single Dimension Arrays @@ -183,7 +181,7 @@ $a[0] = "abc"; $a[1] = "def"; $b["foo"] = 13; - + You can also create an array by simply adding values to @@ -194,7 +192,7 @@ $b["foo"] = 13; $a[] = "hello"; // $a[2] == "hello" $a[] = "world"; // $a[3] == "world" - + Arrays may be sorted using the asort, @@ -202,17 +200,17 @@ $a[] = "world"; // $a[3] == "world" rsort, sort, uasort, usort, and uksort functions depending on the type of - sort you want. + sort you want. You can count the number of items in an array using the - count function. + count function. You can traverse an array using next and prev functions. Another common way to traverse an array is to use the each - function. + function. Multi-Dimensional Arrays @@ -232,7 +230,7 @@ $a[3]["bar"] = $f; # (you can mix numeric and associative indices) $a["foo"][4]["bar"][0] = $f; # four dimensional! - + You can "fill up" multi-dimensional arrays in many ways, @@ -261,7 +259,7 @@ $a = array( 3 => 4 ); - + The array function can be nested for @@ -291,7 +289,7 @@ $a = array( echo $a["apple"]["taste"]; # will output "sweet" ?> - + Objects @@ -312,9 +310,9 @@ class foo { } $bar = new foo; -$bar -> do_foo (); +$bar->do_foo(); - + Type juggling @@ -326,7 +324,7 @@ $bar -> do_foo (); assign a string value to variable var, var becomes a string. If you then assign an integer value to var, it becomes an - integer. + integer. An example of PHP's automatic type conversion is the addition @@ -346,18 +344,16 @@ $foo = $foo + 1.3; // $foo is now a double (3.3) $foo = 5 + "10 Little Piggies"; // $foo is integer (15) $foo = 5 + "10 Small Pigs"; // $foo is integer (15) - + - If the last two examples above seem odd, see String conversion. + If the last two examples above seem odd, see String conversion. If you wish to force a variable to be evaluated as a certain - type, see the section on Type casting. If you + type, see the section on Type casting. If you wish to change the type of a variable, see - settype. + settype. Type casting @@ -372,17 +368,17 @@ $foo = 5 + "10 Small Pigs"; // $foo is integer (15) $foo = 10; // $foo is an integer $bar = (double) $foo; // $bar is a double - + The casts allowed are: - (int), (integer) - cast to integer - (real), (double), (float) - cast to double - (string) - cast to string - (array) - cast to array - (object) - cast to object - + (int), (integer) - cast to integer + (real), (double), (float) - cast to double + (string) - cast to string + (array) - cast to array + (object) - cast to object + Note that tabs and spaces are allowed inside the parentheses, so @@ -393,7 +389,16 @@ $bar = (double) $foo; // $bar is a double $foo = (int) $bar; $foo = ( int ) $bar; - + + + + It may not be obvious exactly what will happen when casting + between certain types. For instance, the following should be + noted: + + + + diff --git a/language/variables.sgml b/language/variables.sgml index f0de2998fb..aa18d6b37b 100644 --- a/language/variables.sgml +++ b/language/variables.sgml @@ -9,7 +9,7 @@ For the most part all PHP variables only have a single scope. However, within user-defined functions a local function scope is introduced. Any variable used inside a function is by default - limited to the local function scope. For example: + limited to the local function scope. For example: @@ -32,7 +32,7 @@ Test (); overridden by a local definition. This can cause some problems in that people may inadvertently change a global variable. In PHP global variables must be declared global inside a function if they - are going to be used in that function. An example: + are going to be used in that function. An example: @@ -54,12 +54,12 @@ echo $b; The above script will output "3". By declaring $a and $b global within the function, all references to either variable will refer to the global version. There is no limit to the number - of global variables that can be manipulated by a function. + of global variables that can be manipulated by a function. A second way to access variables from the global scope is to use the special PHP-defined $GLOBALS array. The previous example can - be rewritten as: + be rewritten as: @@ -78,14 +78,14 @@ 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. + being the value of the array element. Another important feature of variable scoping is the static variable. A static variable exists only in a local function scope, but it does not lose its value when program execution leaves this scope. Consider the following - example: + example: @@ -103,7 +103,7 @@ Function Test () { the variable serves no purpose since as soon as the function exits the $a variable disappears. To make a useful counting function which will not lose track of the current count, the $a variable is - declared static: + declared static: @@ -117,7 +117,7 @@ Function Test () { Now, every time the Test() function is called it will print the - value of $a and increment it. + value of $a and increment it. Static variables are also essential when functions are called @@ -125,7 +125,7 @@ Function Test () { Care 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: + simple function recursively counts to 10: @@ -140,7 +140,7 @@ Function Test () { $count--; } - + Variable variables @@ -148,7 +148,7 @@ 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: @@ -159,7 +159,7 @@ $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. ie. @@ -170,7 +170,7 @@ $$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: @@ -179,7 +179,7 @@ echo "$a ${$a}"; - produces the exact same output as: + produces the exact same output as: @@ -188,7 +188,7 @@ echo "$a $hello"; - ie. they both produce: hello world. + ie. they both produce: hello world. In order to use variable variables with arrays, you have to @@ -196,7 +196,7 @@ echo "$a $hello"; the parser needs to know if you meant to use $a[1] as a variable, or if you wanted $$a as the variable and then the [1] index from that variable. The syntax for resolving this ambiguity is: - ${$a[1]} for the first case and ${$a}[1] for the second. + ${$a[1]} for the first case and ${$a}[1] for the second. Variables from outside PHP @@ -207,7 +207,7 @@ echo "$a $hello"; When a form is submitted to a PHP script, any variables from that form will be automatically made available to the script by - PHP. For instance, consider the following form: + PHP. For instance, consider the following form: @@ -218,19 +218,19 @@ echo "$a $hello"; <input type="submit"> </form> - + When submitted, PHP will create the variable $name, which will will contain whatever what entered into the Name: field - on the form. + on the form. PHP also understands arrays in the context of form variables, but only in one dimension. You may, for example, group related variables together, or use this feature to retrieve values from a - multiple select input: + multiple select input: @@ -247,22 +247,21 @@ echo "$a $hello"; <input type="submit"> </form> - + - If PHP's track_vars feature is turned on, either by the track_vars configuration setting + If PHP's track_vars feature is turned on, either by the track_vars configuration setting or the <?php_track_vars?> directive, then variables submitted via the POST or GET methods will also be found in the global associative arrays - $HTTP_POST_VARS and $HTTP_GET_VARS as appropriate. + $HTTP_POST_VARS and $HTTP_GET_VARS as appropriate. - IMAGE SUBMIT variable names + IMAGE SUBMIT variable names 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: @@ -277,14 +276,13 @@ echo "$a $hello"; the user click within the image. The experienced may note that the actual variable names sent by the browser contains a period rather than an underscore, but PHP converts the period to an - underscore automatically. + underscore automatically. HTTP Cookies - PHP transparently supports HTTP cookies as defined by Netscape's Spec. Cookies are a + PHP transparently supports HTTP cookies as defined by Netscape's Spec. Cookies are a mechanism for storing data in the remote browser and thus tracking or identifying return users. You can set cookies using the SetCookie function. Cookies are part @@ -292,11 +290,11 @@ echo "$a $hello"; 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. + turned into a PHP variable just like GET and POST method data. If you wish to assign multiple values to a single cookie, just - add [] to the cookie name. For example: + add [] to the cookie name. For example: @@ -308,7 +306,7 @@ SetCookie ("MyCookie[]", "Testing", time()+3600); Note that a cookie will replace a previous cookie by the same name in your browser unless the path or domain is different. So, for a shopping cart application you may want to keep a counter - and pass this along. i.e. + and pass this along. i.e. SetCookie Example @@ -317,7 +315,7 @@ $Count++; SetCookie ("Count", $Count, time()+3600); SetCookie ("Cart[$Count]", $item, time()+3600); - + Environment variables @@ -330,7 +328,7 @@ SetCookie ("Cart[$Count]", $item, time()+3600); echo $HOME; /* Shows the HOME environment variable, if set. */ - + Since information coming in via GET, POST and Cookie mechanisms @@ -339,7 +337,7 @@ echo $HOME; /* Shows the HOME environment variable, if set. */ 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. + putenv function. Determining variable types @@ -352,7 +350,7 @@ echo $HOME; /* Shows the HOME environment variable, if set. */ gettype, is_long, is_double, is_string, is_array, and - is_object. + is_object.