cvs: phpdoc /en/appendices migration.xml migration4.xml phpdevel.xml /en/chapters config.xml install.xml security.xml /en/features
error-handling.xml http-auth.xml images.xml safe-mode.xml /en/language basic-syntax.xml constants.xml control-structures.xml expressions.xml
functions.xml oop.xml operators.xml references.xml types.xml variables.xml /en/pear benchmark_timer.xml pear.xml standards.xml
| From: | Hartmut Holzgraefe | Date: | Fri, 23 Nov 2001 21:51:24 +0000 |
| Subject: | cvs: phpdoc /en/appendices migration.xml migration4.xml phpdevel.xml /en/chapters config.xml install.xml security.xml /en/features error-handling.xml http-auth.xml images.xml safe-mode.xml /en/language basic-syntax.xml constants.xml control-structures.xml expressions.xml functions.xml oop.xml operators.xml references.xml types.xml variables.xml /en/pear benchmark_timer.xml pear.xml standards.xml |
||
| Groups: | php.doc | ||
| Request: | Send a blank email to phpdoc+get-969339195@lists.php.net to get a copy of this message | ||
hholzgra Fri Nov 23 16:51:24 2001 EDT
Modified files:
/phpdoc/en/appendices migration.xml migration4.xml phpdevel.xml
/phpdoc/en/chapters config.xml install.xml security.xml
/phpdoc/en/features error-handling.xml http-auth.xml images.xml
safe-mode.xml
/phpdoc/en/language basic-syntax.xml constants.xml
control-structures.xml expressions.xml
functions.xml oop.xml operators.xml
references.xml types.xml variables.xml
/phpdoc/en/pear benchmark_timer.xml pear.xml standards.xml
Log:
added CDATA to programlistings outside the functions dir
Index: phpdoc/en/appendices/migration.xml diff -u phpdoc/en/appendices/migration.xml:1.13 phpdoc/en/appendices/migration.xml:1.14 --- phpdoc/en/appendices/migration.xml:1.13 Sat Nov 10 16:49:25 2001 +++ phpdoc/en/appendices/migration.xml Fri Nov 23 16:51:22 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.13 $ --> +<!-- $Revision: 1.14 $ --> <appendix id="migration"> <title>Migrating from PHP/FI 2.0 to PHP 3.0</title> @@ -46,14 +46,18 @@ <example> <title>Migration: old start/end tags</title> <programlisting role="php"> -<? echo "This is PHP/FI 2.0 code.\n"; > +<![CDATA[ +<? echo "This is PHP/FI 2.0 code.\n"; ?> +]]> </programlisting> </example> As of version 2.0, PHP/FI also supports this variation: <example> <title>Migration: first new start/end tags</title> <programlisting role="php"> -<? echo "This is PHP 3.0 code!\n"; ?> +<![CDATA[ +<? echo "This is PHP 3.0 code!\n"; ?> +]]| </programlisting> </example> @@ -67,7 +71,9 @@ <example> <title>Migration: second new start/end tags</title> <programlisting role="php"> -<?php echo "This is PHP 3.0 code!\n"; ?> +<![CDATA[ +<?php echo "This is PHP 3.0 code!\n"; ?> +]]> </programlisting> </example> @@ -79,11 +85,13 @@ <example> <title>Migration: third new start/end tags</title> <programlisting role="php"> -<script language="php"> +<![CDATA[ +<script language="php"> echo "This is PHP 3.0 code!\n"; -</script> +</script> +]]> </programlisting> </example> </para> @@ -100,6 +108,7 @@ <example> <title>Migration: old if..endif syntax</title> <programlisting role="php"> +<![CDATA[ if ($foo); echo "yep\n"; elseif ($bar); @@ -107,11 +116,13 @@ else; echo "nope\n"; endif; +]]> </programlisting> </example> <example> <title>Migration: new if..endif syntax</title> <programlisting role="php"> +<![CDATA[ if ($foo): echo "yep\n"; elseif ($bar): @@ -119,6 +130,7 @@ else: echo "nope\n"; endif; +]]> </programlisting> </example> @@ -135,17 +147,21 @@ <example> <title>Migration: old while..endwhile syntax</title> <programlisting role="php"> +<![CDATA[ while ($more_to_come); ... endwhile; +]]> </programlisting> </example> <example> <title>Migration: new while..endwhile syntax</title> <programlisting role="php"> +<![CDATA[ while ($more_to_come): ... endwhile; +]]> </programlisting> </example> </para> @@ -169,6 +185,7 @@ Consider this example: <informalexample> <programlisting role="php"> +<![CDATA[ $a[0]=5; $a[1]=7; @@ -177,6 +194,7 @@ echo "$keyn"; next($a); } +]]> </programlisting> </informalexample> @@ -196,7 +214,9 @@ The fix for this is simple. Replace the while statement with: <informalexample> <programlisting role="php"> +<![CDATA[ while ((string)$key != "") { +]]> </programlisting> </informalexample> </para> @@ -244,16 +264,20 @@ <example> <title>Migration from 2.0: return values, old code</title> <programlisting role="php"> +<![CDATA[ $fp = fopen($file, "r"); if ($fp == -1); - echo("Could not open $file for reading<br>\n"); + echo("Could not open $file for reading<br>\n"); endif; +]]| </programlisting> </example> <example> <title>Migration from 2.0: return values, new code</title> <programlisting role="php"> -$fp = @fopen($file, "r") or print("Could not open $file for reading<br>\n"); +<![CDATA[ +$fp = @fopen($file, "r") or print("Could not open $file for reading<br>\n"); +]]> </programlisting> </example> </para> @@ -312,26 +336,34 @@ <example> <title>Migration from 2.0: concatenation for strings</title> <programlisting role="php"> +<![CDATA[ echo "1" + "1"; +]]> </programlisting> <para> In PHP 2.0 this would echo 11, in PHP 3.0 it would echo 2. Instead use: <programlisting role="php"> +<![CDATA[ echo "1"."1"; +]]> </programlisting> <programlisting role="php"> +<![CDATA[ $a = 1; $b = 1; echo $a + $b; +]]> </programlisting> </para> <para> This would echo 2 in both PHP 2.0 and 3.0. <programlisting role="php"> +<![CDATA[ $a = 1; $b = 1; echo $a.$b; +]]> </programlisting> This will echo 11 in PHP 3.0. </para> Index: phpdoc/en/appendices/migration4.xml diff -u phpdoc/en/appendices/migration4.xml:1.14 phpdoc/en/appendices/migration4.xml:1.15 --- phpdoc/en/appendices/migration4.xml:1.14 Sat Nov 10 16:49:26 2001 +++ phpdoc/en/appendices/migration4.xml Fri Nov 23 16:51:22 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.14 $ --> +<!-- $Revision: 1.15 $ --> <appendix id="migration4"> <title>Migrating from PHP 3.0 to PHP 4.0</title> @@ -38,13 +38,17 @@ (--with-apxs) and the necessary link extensions (--enable-versioning). Otherwise, all standard installations instructions apply. For example: - <informalexample><programlisting> + <informalexample> + <programlisting role="configure"> +<![CDATA[ $ ./configure \ --with-apxs=/apache/bin/apxs \ --enable-versioning \ --with-mysql \ --enable-track-vars - </programlisting></informalexample> +]]> + </programlisting> + </informalexample> </para> </section> @@ -58,22 +62,30 @@ For the Apache configuration file, there are slightly more changes. The MIME types recognized by the PHP module have changed. - <informalexample><programlisting> -application/x-httpd-php3 --> application/x-httpd-php -application/x-httpd-php3-source --> application/x-httpd-php-source - </programlisting></informalexample> + <informalexample> + <programlisting role="apache"> +<![CDATA[ +application/x-httpd-php3 --> application/x-httpd-php +application/x-httpd-php3-source --> application/x-httpd-php-source +]]> + </programlisting> + </informalexample> </para> <para> You can make your configuration files work with both versions of PHP (depending on which one is currently compiled into the server), using the following syntax: - <informalexample><programlisting> + <informalexample> + <programlisting> +<![CDATA[ AddType application/x-httpd-php3 .php3 AddType application/x-httpd-php3-source .php3s AddType application/x-httpd-php .php AddType application/x-httpd-php-source .phps - </programlisting></informalexample> +]]> + </programlisting> + </informalexample> </para> <simpara> In addition, the PHP directive names for Apache have changed. @@ -81,12 +93,16 @@ <para> Starting with PHP 4.0, there are only four Apache directives that relate to PHP: - <informalexample><programlisting> + <informalexample> + <programlisting role="apache"> +<![CDATA[ php_value [PHP directive name] [value] php_flag [PHP directive name] [On|Off] php_admin_value [PHP directive name] [value] php_admin_flag [PHP directive name] [On|Off] - </programlisting></informalexample> +]]> + </programlisting> + </informalexample> </para> <simpara> There are two differences between the Admin values and the non admin values: @@ -100,18 +116,26 @@ </simpara> <para> To convert your Apache configuration files, run the apconf-conv.sh script (available in the scripts/apache/ directory). For example: - <informalexample><programlisting> + <informalexample> + <programlisting role="shell"> +<![CDATA[ ~/php4/scripts/apache:# ./apconf-conv.sh /usr/local/apache/conf/httpd.conf - </programlisting></informalexample> +]]> + </programlisting> + </informalexample> </para> <simpara> Your original configuration file will be saved in httpd.conf.orig. </simpara> <para> To convert your .htaccess files, run the aphtaccess-conv.sh script (available in the scripts/apache/ directory as well): - <informalexample><programlisting> + <informalexample> + <programlisting role="shell"> +<![CDATA[ ~/php4/scripts/apache:# find / -name .htaccess -exec ./aphtaccess-conv.sh {} \; - </programlisting></informalexample> +]]> + </programlisting> + </informalexample> </para> <simpara> Likewise, your old .htaccess files will be saved with an .orig prefix. Index: phpdoc/en/appendices/phpdevel.xml diff -u phpdoc/en/appendices/phpdevel.xml:1.13 phpdoc/en/appendices/phpdevel.xml:1.14 --- phpdoc/en/appendices/phpdevel.xml:1.13 Sat Nov 10 16:49:26 2001 +++ phpdoc/en/appendices/phpdevel.xml Fri Nov 23 16:51:22 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.13 $ --> +<!-- $Revision: 1.14 $ --> <appendix id="phpdevel"> <title>PHP development</title> @@ -12,9 +12,11 @@ <para> All functions look like this: <programlisting role="c"> +<![CDATA[ void php3_foo(INTERNAL_FUNCTION_PARAMETERS) { } +]]> </programlisting> Even if your function doesn't take any arguments, this is how it is called.</para></sect2> @@ -31,10 +33,12 @@ <example> <title>Fetching function arguments</title> <programlisting role="c"> +<![CDATA[ pval *arg1, *arg2; -if (ARG_COUNT(ht) != 2 || getParameters(ht,2,&arg1,&arg2)==FAILURE) { +if (ARG_COUNT(ht) != 2 || getParameters(ht,2,&arg1,&arg2)==FAILURE) { WRONG_PARAM_COUNT; } +]]> </programlisting> </example> @@ -68,13 +72,15 @@ <example> <title>Variable function arguments</title> <programlisting role="c"> +<![CDATA[ pval *arg1, *arg2, *arg3; int arg_count = ARG_COUNT(ht); -if (arg_count < 2 || arg_count > 3 || - getParameters(ht,arg_count,&arg1,&arg2,&arg3)==FAILURE) { +if (arg_count < 2 || arg_count > 3 || + getParameters(ht,arg_count,&arg1,&arg2,&arg3)==FAILURE) { WRONG_PARAM_COUNT; } +]]> </programlisting> </example></para></sect2> @@ -135,11 +141,13 @@ functions: <programlisting role="c"> +<![CDATA[ convert_to_long(arg1); 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 */ +]]> </programlisting></para> <simpara> @@ -225,16 +233,20 @@ <example> <title>Checking whether $foo exists in a symbol table</title> <programlisting role="c"> +<![CDATA[ if (hash_exists(active_symbol_table,"foo",sizeof("foo"))) { exists... } else { doesn't exist } +]]> </programlisting> </example> <example> <title>Finding a variable's size in a symbol table</title> <programlisting role="c"> -hash_find(active_symbol_table,"foo",sizeof("foo"),&pvalue); +<![CDATA[ +hash_find(active_symbol_table,"foo",sizeof("foo"),&pvalue); check(pvalue.type); +]]> </programlisting> </example> @@ -257,10 +269,12 @@ <example> <title>Initializing a new array</title> <programlisting role="c"> +<![CDATA[ pval arr; -if (array_init(&arr) == FAILURE) { failed... }; -hash_update(active_symbol_table,"foo",sizeof("foo"),&arr,sizeof(pval),NULL); +if (array_init(&arr) == FAILURE) { failed... }; +hash_update(active_symbol_table,"foo",sizeof("foo"),&arr,sizeof(pval),NULL); +]]> </programlisting> </example> @@ -274,21 +288,23 @@ <example> <title>Adding entries to a new array</title> <programlisting role="c"> +<![CDATA[ pval entry; entry.type = IS_LONG; entry.value.lval = 5; /* defines $foo["bar"] = 5 */ -hash_update(arr.value.ht,"bar",sizeof("bar"),&entry,sizeof(pval),NULL); +hash_update(arr.value.ht,"bar",sizeof("bar"),&entry,sizeof(pval),NULL); /* defines $foo[7] = 5 */ -hash_index_update(arr.value.ht,7,&entry,sizeof(pval),NULL); +hash_index_update(arr.value.ht,7,&entry,sizeof(pval),NULL); /* defines the next free place in $foo[], * $foo[8], to be 5 (works like php2) */ -hash_next_index_insert(arr.value.ht,&entry,sizeof(pval),NULL); +hash_next_index_insert(arr.value.ht,&entry,sizeof(pval),NULL); +]]> </programlisting> </example> @@ -308,16 +324,20 @@ initialize the array just like above by doing:</simpara> <programlisting role="c"> +<![CDATA[ if (array_init(return_value) == FAILURE) { failed...; } +]]> </programlisting> <simpara> ...and then adding values with the helper functions:</simpara> <programlisting role="c"> +<![CDATA[ add_next_index_long(return_value,long_value); add_next_index_double(return_value,double_value); add_next_index_string(return_value,estrdup(string_value)); +]]> </programlisting> <para> @@ -325,10 +345,12 @@ initialization, you'd probably have to look for the array first: <programlisting role="c"> +<![CDATA[ pval *arr; -if (hash_find(active_symbol_table,"foo",sizeof("foo"),(void **)&arr)==FAILURE) { can't find... } -else { use arr->value.ht... } +if (hash_find(active_symbol_table,"foo",sizeof("foo"),(void **)&arr)==FAILURE) { can't find... } +else { use arr->value.ht... } +]]> </programlisting></para> <simpara> @@ -398,8 +420,11 @@ (i.e., you can use regular hash functions on .value.ht). The actual registration of the function can be done using: <programlisting role="c"> +<![CDATA[ add_method( return_value, function_name, function_ptr ); - </programlisting></para></listitem> +]]> + </programlisting> + </para></listitem> </orderedlist></para> <para> @@ -478,41 +503,47 @@ <example> <title>Adding a new resource</title> <programlisting role="c"> +<![CDATA[ RESOURCE *resource; /* ...allocate memory for resource and acquire resource... */ /* add a new resource to the list */ -return_value->value.lval = php3_list_insert((void *) resource, LE_RESOURCE_TYPE); -return_value->type = IS_LONG; +return_value->value.lval = php3_list_insert((void *) resource, LE_RESOURCE_TYPE); +return_value->type = IS_LONG; +]]> </programlisting> </example> <example> <title>Using an existing resource</title> <programlisting role="c"> +<![CDATA[ pval *resource_id; RESOURCE *resource; int type; convert_to_long(resource_id); -resource = php3_list_find(resource_id->value.lval, &type); +resource = php3_list_find(resource_id->value.lval, &type); if (type != LE_RESOURCE_TYPE) { - php3_error(E_WARNING,"resource index %d has the wrong type",resource_id->value.lval); + php3_error(E_WARNING,"resource index %d has the wrong type",resource_id->value.lval); RETURN_FALSE; } /* ...use resource... */ +]]> </programlisting> </example> <example> <title>Deleting an existing resource</title> <programlisting role="c"> +<![CDATA[ pval *resource_id; RESOURCE *resource; int type; convert_to_long(resource_id); -php3_list_delete(resource_id->value.lval); +php3_list_delete(resource_id->value.lval); +]]> </programlisting> </example> Index: phpdoc/en/chapters/config.xml diff -u phpdoc/en/chapters/config.xml:1.30 phpdoc/en/chapters/config.xml:1.31 --- phpdoc/en/chapters/config.xml:1.30 Sun Nov 11 05:20:40 2001 +++ phpdoc/en/chapters/config.xml Fri Nov 23 16:51:22 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.30 $ --> +<!-- $Revision: 1.31 $ --> <chapter id="configuration"> <title>Configuration</title> @@ -16,6 +16,7 @@ <example> <title>php.ini example</title> <programlisting role="ini"> +<![CDATA[ ; any text on a line after an unquoted semicolon (;) is ignored [php] ; section markers (text within square brackets) are also ignored ; Boolean values can be set to either: @@ -29,6 +30,7 @@ ; backslashes are treated the same as any other character include_path = ".;c:\php\lib" +]]> </programlisting> <!-- TODO: add more details about values and expressions --> </example> @@ -102,14 +104,16 @@ <example> <title>Apache configuration example</title> <programlisting role="ini"> -<IfModule mod_php4.c> +<![CDATA[ +<IfModule mod_php4.c> php_value include_path ".:/usr/local/lib/php" php_flag safe_mode on -</IfModule> -<IfModule mod_php3.c> +</IfModule> +<IfModule mod_php3.c> php3_include_path ".:/usr/local/lib/php" php3_safe_mode on -</IfModule> +</IfModule> +]]> </programlisting> </example> </para> @@ -444,14 +448,18 @@ <example> <title>UNIX include_path</title> <programlisting role="php3.ini"> +<![CDATA[ include_path=.:/home/httpd/php-lib -</programlisting> +]]> + </programlisting> </example> <example> <title>Windows include_path</title> <programlisting role="php3.ini"> +<![CDATA[ include_path=".;c:\www\phplib" -</programlisting> +]]> + </programlisting> </example> The default value for this directive is <literal>.</literal> (only the current directory).</para> @@ -1096,9 +1104,12 @@ reference manual): <informalexample> <programlisting role="bs2000"> +<![CDATA[ CNF=B NAM=K -NOTYPE</programlisting> +NOTYPE +]]> + </programlisting> </informalexample> </para> </listitem> Index: phpdoc/en/chapters/install.xml diff -u phpdoc/en/chapters/install.xml:1.94 phpdoc/en/chapters/install.xml:1.95 --- phpdoc/en/chapters/install.xml:1.94 Sun Nov 11 10:06:13 2001 +++ phpdoc/en/chapters/install.xml Fri Nov 23 16:51:22 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.94 $ --> +<!-- $Revision: 1.95 $ --> <chapter id="installation"> <title>Installation</title> @@ -179,7 +179,8 @@ <title> Quick Installation Instructions for PHP 4 (Apache Module Version) </title> - <programlisting> + <programlisting role="shell"> +<![CDATA[ 1. gunzip apache_1.3.x.tar.gz 2. tar xvf apache_1.3.x.tar 3. gunzip php-x.x.x.tar.gz @@ -202,6 +203,7 @@ 18. Use your normal procedure for restarting the Apache server. (You must stop and restart the server, not just cause the server to reload by use a HUP or USR1 signal.) +]]> </programlisting> </example> </sect2> @@ -248,7 +250,8 @@ <title> Installation Instructions for HP-UX 10 </title> - <programlisting> + <screen> +<![CDATA[ From: paul_mckay@clearwater-it.co.uk 04-Jan-2001 09:49 (These tips are for PHP 4.0.4 and Apache v1.3.9) @@ -316,7 +319,8 @@ Hope this helps somebody, Paul Mckay. - </programlisting> +]]> + </screen> </example> </sect1> @@ -417,11 +421,13 @@ <example id="install.openbsd.ports.example"> <title>OpenBSD Ports Install Example</title> <programlisting> +<![CDATA[ $ cd /usr/ports/www/php4 $ make show VARNAME=FLAVORS (choose which flavors you want from the list) $ env FLAVOR="imap gettext ldap mysql gd" make install $ /usr/local/sbin/php4-enable +]]> </programlisting> </example> </sect2> @@ -467,7 +473,8 @@ </simpara> <example id="install.macosx.compile.example"> <title>Mac OS X server install</title> - <programlisting> + <screen> +<![CDATA[ 1. Get the latest distributions of Apache and PHP 2. Untar them, and run the configure program on Apache like so. ./configure --exec-prefix=/usr \ @@ -533,7 +540,8 @@ or (if your don't have a local directory) cp php.ini-dist /usr/bin/php.ini - </programlisting> +]]> + </screen> </example> <simpara> Other examples for @@ -583,9 +591,11 @@ Now type "<literal>sudo open -a TextEdit /etc/httpd/httpd.conf</literal>" TextEdit will open with the web server configuration file. Locate these two lines towards the end of the file: (Use the Find command) - <programlisting> - * #AddType application/x-httpd-php .php - * #AddType application/x-httpd-php-source .phps + <programlisting role="apache"> +<![CDATA[ + #AddType application/x-httpd-php .php + #AddType application/x-httpd-php-source .phps +]]> </programlisting> Remove the two hash marks (<literal>#</literal>), then save the file and quit TextEdit. </para> @@ -3271,7 +3281,7 @@ <listitem> <para> Extract the distribution file to a directory of your choice. - "c:\php\" is a good start. + <filename>c:\php\</filename> is a good start. </para> </listitem> <listitem> @@ -3957,7 +3967,8 @@ <title> Installation Instructions (Apache Module Version) </title> - <programlisting> + <screen> +<![CDATA[ 1. gunzip apache_1.3.x.tar.gz 2. tar xvf apache_1.3.x.tar 3. gunzip php-x.x.x.tar.gz @@ -3997,7 +4008,8 @@ 18. Use your normal procedure for starting the Apache server. (You must stop and restart the server, not just cause the server to reload by use a HUP or USR1 signal.) - </programlisting> +]]> + </screen> </example> <para> @@ -4007,7 +4019,8 @@ installations. You should replace <literal>/path/to/</literal> with the path to these applications on your systems. <informalexample> - <programlisting> + <screen> +<![CDATA[ 1. Several Linux and SysV variants: /etc/rc.d/init.d/httpd restart @@ -4023,7 +4036,8 @@ stop and start: /path/to/apachectl stop /path/to/apachectl startssl - </programlisting> +]]> + </screen> </informalexample> The locations of the apachectl and http(s)dctl binaries often vary. If your system has <literal>locate</literal> or @@ -4034,8 +4048,10 @@ <para> Different examples of compiling PHP for apache are as follows: <informalexample> - <programlisting> + <programlisting role="shell"> +<![CDATA[ ./configure --with-apxs --with-pgsql +]]> </programlisting> </informalexample> </para> @@ -4049,7 +4065,9 @@ <para> <informalexample> <programlisting> +<![CDATA[ ./configure --with-apxs --with-pgsql=shared +]]> </programlisting> </informalexample> </para> @@ -4064,7 +4082,9 @@ <para> <informalexample> <programlisting> +<![CDATA[ ./configure --with-apache=/path/to/apache_source --with-pgsql +]]> </programlisting> </informalexample> </para> @@ -4084,7 +4104,9 @@ <para> <informalexample> <programlisting> +<![CDATA[ ./configure --with-apache=/path/to/apache_source --with-pgsql=shared +]]> </programlisting> </informalexample> </para> @@ -4289,7 +4311,8 @@ </para> <example id="install.caudium.instructions"> <title>Caudium Installation Instructions</title> - <programlisting> + <screen> +<![CDATA[ 1. Make sure you have Caudium installed prior to attempting to install PHP 4. For PHP 4 to work correctly, you will need Pike 7.0.268 or newer. For the sake of this example we assume that @@ -4309,7 +4332,8 @@ <filename>caudium/server/lib/[pike-version]/PHP4.so</filename> is present. 10. Configure the PHP Script Support module if needed. - </programlisting> +]]> + </screen> </example> <para> You can of course compile your Caudium module with support for the @@ -4678,7 +4702,8 @@ <para> <example id="install.netscape-enterprise.solaris"> <title>Installation Example for Netscape Enterprise on Solaris</title> - <programlisting> + <screen> +<![CDATA[ Instructions for Sun Solaris 2.6 with Netscape Enterprise Server 3.6 From: bhager@invacare.com @@ -4710,7 +4735,8 @@ /configure --with-mysql=/usr/local/mysql --with-nsapi=/opt/netscape/suitespot/ --enable-track-vars --enable-libgcc 7. make 8. make install - </programlisting> +]]> + </screen> </example> After performing the base install and reading the appropriate readme file, you may need to performs some additional @@ -4735,7 +4761,8 @@ <title> Configuration Example for Netscape Enterprise </title> - <programlisting> + <screen> +<![CDATA[ Configuration Instructions for Netscape Enterprise Server From: bhager@invacare.com @@ -4750,7 +4777,7 @@ Init fn="load-modules" funcs="php4_init,php4_close,php4_execute,php4_auth_trans" shlib="/php4/nsapiPHP4.dll" Init fn=php4_init errorString="Failed to initialize PHP!" - <object name="default"> + <object name="default"> . . . @@ -4758,13 +4785,13 @@ Service fn="php4_execute" type="magnus-internal/x-httpd-php" . . - </Object> + </Object> - <Object name="x-httpd-php"> + <Object name="x-httpd-php"> ObjectType fn="force-type" type="magnus-internal/x-httpd-php" Service fn=php4_execute - </Object> + </Object> Authentication configuration @@ -4773,20 +4800,21 @@ PASSED TO YOUR PHP SCRIPT. To configure PHP Authentication for the entire server, add the following line: - <Object name="default"> + <Object name="default"> AuthTrans fn=php4_auth_trans . . . . - </Object> + </Object> To use PHP Authentication on a single directory, add the following: - <Object ppath="d:\path\to\authenticated\dir\*"> + <Object ppath="d:\path\to\authenticated\dir\*"> AuthTrans fn=php4_auth_trans - </Object> - </programlisting> + </Object> +]]> + </screen> </example> <para> If you are running Netscape Enterprise 4.x, then you should use the following: @@ -4794,12 +4822,14 @@ <example> <title>Configuration Example for Netscape Enterprise 4.x</title> <programlisting> +<![CDATA[ Place these lines after the mime types init, and everything else is similar to the example configuration above. From: Graeme Hoose (GraemeHoose@BrightStation.com) Init fn="load-modules" shlib="/path/to/server4/bin/libphp4.so" funcs="php4_init,php4_close,php4_execute,php4_auth_trans" Init fn="php4_init" LateInit="yes" +]]> </programlisting> </example> </sect2> @@ -4821,8 +4851,10 @@ Make a file association from the command line. Type the following two lines: <programlisting> +<![CDATA[ assoc .php=PHPScript ftype PHPScript=c:\php\php.exe %1 %* +]]> </programlisting> </para> </listitem> @@ -4868,8 +4900,10 @@ Make a file association from the command line. Type the following two lines: <programlisting> +<![CDATA[ assoc .php=PHPScript ftype PHPScript=c:\php\php.exe %1 %* +]]> </programlisting> </para> </listitem> @@ -4886,8 +4920,10 @@ At the end of the Init section, place these two lines (necessarily after mime type init!): <programlisting> +<![CDATA[ Init fn="load-modules" funcs="php4_init,php4_close,php4_execute,php4_auth_trans" shlib="c:/php/sapi/php4nsapi.dll" Init fn="php4_init" errorString="Failed to initialise PHP!" +]]> </programlisting> </para> </listitem> @@ -4897,7 +4933,9 @@ section, place this line necessarily after all 'ObjectType' and before all 'AddLog' lines: <programlisting> +<![CDATA[ Service fn="php4_execute" type="magnus-internal/x-httpd-php" +]]> </programlisting> </para> </listitem> @@ -4906,10 +4944,12 @@ At the end of the file, create a new object called <literal>x-httpd-php</literal>, by inserting these lines: <programlisting> -<Object name="x-httpd-php"> +<![CDATA[ +<Object name="x-httpd-php"> ObjectType fn="force-type" type="magnus-internal/x-httpd-php" Service fn=php4_execute -</Object> +</Object> +]]> </programlisting> </para> </listitem> Index: phpdoc/en/chapters/security.xml diff -u phpdoc/en/chapters/security.xml:1.35 phpdoc/en/chapters/security.xml:1.36 --- phpdoc/en/chapters/security.xml:1.35 Tue Nov 20 20:48:33 2001 +++ phpdoc/en/chapters/security.xml Fri Nov 23 16:51:22 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.35 $ --> +<!-- $Revision: 1.36 $ --> <chapter id="security"> <title>Security</title> @@ -199,8 +199,10 @@ the following directives: </simpara> <programlisting role="apache-conf"> +<![CDATA[ Action php-script /cgi-bin/php AddHandler php-script .php +]]> </programlisting> <simpara> This option has only been tested with the Apache web server, and @@ -283,7 +285,9 @@ similar to: <informalexample> <programlisting> +<![CDATA[ #!/usr/local/bin/php +]]> </programlisting> </informalexample> as the first line of any file containing PHP tags. You will also @@ -377,14 +381,16 @@ <example> <title>Poor variable checking leads to....</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php // remove a file from the user's home directory $username = $HTTP_POST_VARS['user_submitted_name']; $homedir = "/home/$username"; $file_to_delete = "$userfile"; unlink ($homedir/$userfile); echo "$file_to_delete has been deleted!"; -?> +?> +]]> </programlisting> </example> Since the username is postable from a user form, they can submit @@ -395,7 +401,8 @@ <example> <title>... A filesystem attack</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php // removes a file from anywhere on the hard drive that // the PHP user has access to. If PHP has root access: $username = "../etc/"; @@ -403,7 +410,8 @@ $file_to_delete = "passwd"; unlink ("/home/../etc/passwd"); echo "/home/../etc/passwd has been deleted!"; -?> +?> +]]> </programlisting> </example> There are two important measures you should take to prevent these @@ -424,7 +432,8 @@ <example> <title>More secure file name checking</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php // removes a file from the hard drive that // the PHP user has access to. $username = $HTTP_SERVER_VARS['REMOTE_USER']; // using an authentication mechanisim @@ -440,7 +449,8 @@ fclose($fp); echo "$file_to_delete has been deleted!"; -?> +?> +]]> </programlisting> </example> However, even this is not without it's flaws. If your authentication @@ -450,7 +460,8 @@ <example> <title>More secure file name checking</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php $username = $HTTP_SERVER_VARS['REMOTE_USER']; // using an authentication mechanisim $homedir = "/home/$username"; @@ -460,7 +471,8 @@ if (!ereg('^[^./][^/]*$', $username)) die('bad username'); //die, do not process //etc... -?> +?> +]]> </programlisting> </example> </para> @@ -491,10 +503,12 @@ <example> <title>Attacking Variables with a custom HTML page</title> <programlisting role="php"> -<form method="post" action="attacktarget?username=badfoo&password=badfoo"> -<input type="hidden" name="username" value="badfoo"> -<input type="hidden" name="password" value="badfoo"> -</form> +<![CDATA[ +<form method="post" action="attacktarget?username=badfoo&password=badfoo"> +<input type="hidden" name="username" value="badfoo"> +<input type="hidden" name="password" value="badfoo"> +</form> +]]> </programlisting> </example> </para> @@ -516,11 +530,13 @@ <example> <title>Exploiting common debugging variables</title> <programlisting role="php"> -<form method="post" action="attacktarget?errors=Y&showerrors=1"&debug=1"> -<input type="hidden" name="errors" value="Y"> -<input type="hidden" name="showerrors" value="1"> -<input type="hidden" name="debug" value="1"> -</form> +<![CDATA[ +<form method="post" action="attacktarget?errors=Y&showerrors=1"&debug=1"> +<input type="hidden" name="errors" value="Y"> +<input type="hidden" name="showerrors" value="1"> +<input type="hidden" name="debug" value="1"> +</form> +]]> </programlisting> </example> </para> @@ -573,14 +589,16 @@ <example> <title>Finding dangerous variables with E_ALL</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php if ($username) { // Not initialized or checked before usage $good_login = 1; } if ($good_login == 1) { // If above test fails, not initialized or checked before usage fpassthru ("/highly/sensitive/data/index.html"); } -?> +?> +]]> </programlisting> </example> </para> @@ -605,7 +623,8 @@ <example> <title>Working without register_globals=off</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php if ($username) { // can be forged by a user in get/post/cookies $good_login = 1; } @@ -613,19 +632,22 @@ if ($good_login == 1) { // can be forged by a user in get/post/cookies, fpassthru ("/highly/sensitive/data/index.html"); } -?> +?> +]]> </programlisting> </example> <example> <title>Working with register_globals = off</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php if($HTTP_COOKIE_VARS['username']){ // can only come from a cookie, forged or otherwise $good_login = 1; fpassthru ("/highly/sensitive/data/index.html"); } -?> +?> +]]> </programlisting> </example> By using this wisely, it's even possible to take preventative @@ -638,9 +660,10 @@ <example> <title>Detecting simple variable poisoning</title> <programlisting role="php"> -<?php -if ($HTTP_COOKIE_VARS['username'] && - !$HTTP_POST_VARS['username'] && +<![CDATA[ +<?php +if ($HTTP_COOKIE_VARS['username'] && + !$HTTP_POST_VARS['username'] && !$HTTP_GET_VARS['username'] ) { // Perform other checks to validate the user name... $good_login = 1; @@ -650,7 +673,8 @@ echo "Security violation, admin has been alerted."; exit; } -?> +?> +]]> </programlisting> </example> Of course, simply turning off register_globals does not mean code @@ -671,7 +695,8 @@ <example> <title>Dangerous Variable Usage</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php // remove a file from the user's home directory... or maybe // somebody else's? unlink ($evil_var); @@ -683,7 +708,8 @@ system ($evil_var); exec ($evil_var); -?> +?> +]]> </programlisting> </example> You should always carefully examine your code to make sure that any @@ -749,26 +775,32 @@ then use misleading file extensions: <example> <title>Hiding PHP as another language</title> - <programlisting> + <programlisting role="apache-conf"> +<![CDATA[ # Make PHP code look like other code types AddType application/x-httpd-php .asp .py .pl +]]> </programlisting> </example> Or obscure it completely: <example> <title>Using unknown types for PHP extensions</title> - <programlisting> + <programlisting role="apache-conf"> +<![CDATA[ # Make PHP code look like unknown types AddType application/x-httpd-php .bop .foo .133t +]]> </programlisting> </example> Or hide it as html code, which has a slight performance hit because all html will be parsed through the PHP engine: <example> <title>Using html types for PHP extensions</title> - <programlisting> + <programlisting role="apache-conf"> +<![CDATA[ # Make all PHP code look like html AddType application/x-httpd-php .htm .html +]]> </programlisting> </example> For this to work effectively, you must rename your PHP files with Index: phpdoc/en/features/error-handling.xml diff -u phpdoc/en/features/error-handling.xml:1.21 phpdoc/en/features/error-handling.xml:1.22 --- phpdoc/en/features/error-handling.xml:1.21 Sat Nov 10 16:49:30 2001 +++ phpdoc/en/features/error-handling.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.21 $ --> +<!-- $Revision: 1.22 $ --> <chapter id="features.error-handling"> <title>Error Handling</title> @@ -180,77 +180,78 @@ <example> <title>Using error handling in a script</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php // we will do our own error handling error_reporting(0); // user defined error handling function function userErrorHandler ($errno, $errmsg, $filename, $linenum, $vars) { // timestamp for the error entry - $dt = date("Y-m-d H:i:s (T)"); + $dt = date("Y-m-d H:i:s (T)"); // define an assoc array of error string // in reality the only entries we should // consider are 2,8,256,512 and 1024 $errortype = array ( - 1 => "Error", - 2 => "Warning", - 4 => "Parsing Error", - 8 => "Notice", - 16 => "Core Error", - 32 => "Core Warning", - 64 => "Compile Error", - 128 => "Compile Warning", - 256 => "User Error", - 512 => "User Warning", - 1024=> "User Notice" + 1 => "Error", + 2 => "Warning", + 4 => "Parsing Error", + 8 => "Notice", + 16 => "Core Error", + 32 => "Core Warning", + 64 => "Compile Error", + 128 => "Compile Warning", + 256 => "User Error", + 512 => "User Warning", + 1024=> "User Notice" ); // set of errors for which a var trace will be saved $user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE); - $err = "<errorentry>\n"; - $err .= "\t<datetime>".$dt."</datetime>\n"; - $err .= "\t<errornum>".$errno."</errnumber>\n"; - $err .= "\t<errortype>".$errortype[$errno]."</errortype>\n"; - $err .= "\t<errormsg>".$errmsg."</errormsg>\n"; - $err .= "\t<scriptname>".$filename."</scriptname>\n"; - $err .= "\t<scriptlinenum>".$linenum."</scriptlinenum>\n"; + $err = "<errorentry>\n"; + $err .= "\t<datetime>".$dt."</datetime>\n"; + $err .= "\t<errornum>".$errno."</errnumber>\n"; + $err .= "\t<errortype>".$errortype[$errno]."</errortype>\n"; + $err .= "\t<errormsg>".$errmsg."</errormsg>\n"; + $err .= "\t<scriptname>".$filename."</scriptname>\n"; + $err .= "\t<scriptlinenum>".$linenum."</scriptlinenum>\n"; if (in_array($errno, $user_errors)) - $err .= "\t<vartrace>".wddx_serialize_value($vars,"Variables")."</vartrace>\n"; - $err .= "</errorentry>\n\n"; + $err .= "\t<vartrace>".wddx_serialize_value($vars,"Variables")."</vartrace>\n"; + $err .= "</errorentry>\n\n"; // for testing // echo $err; // save to the error log, and e-mail me if there is a critical user error - error_log($err, 3, "/usr/local/php4/error.log"); + error_log($err, 3, "/usr/local/php4/error.log"); if ($errno == E_USER_ERROR) - mail("phpdev@mydomain.com","Critical User Error",$err); + mail("phpdev@mydomain.com","Critical User Error",$err); } function distance ($vect1, $vect2) { if (!is_array($vect1) || !is_array($vect2)) { - trigger_error("Incorrect parameters, arrays expected", E_USER_ERROR); + trigger_error("Incorrect parameters, arrays expected", E_USER_ERROR); return NULL; } if (count($vect1) != count($vect2)) { - trigger_error("Vectors need to be of the same size", E_USER_ERROR); + trigger_error("Vectors need to be of the same size", E_USER_ERROR); return NULL; } - for ($i=0; $i<count($vect1); $i++) { + for ($i=0; $i<count($vect1); $i++) { $c1 = $vect1[$i]; $c2 = $vect2[$i]; $d = 0.0; if (!is_numeric($c1)) { - trigger_error("Coordinate $i in vector 1 is not a number, using zero", + trigger_error("Coordinate $i in vector 1 is not a number, using zero", E_USER_WARNING); $c1 = 0.0; } if (!is_numeric($c2)) { - trigger_error("Coordinate $i in vector 2 is not a number, using zero", + trigger_error("Coordinate $i in vector 2 is not a number, using zero", E_USER_WARNING); $c2 = 0.0; } @@ -259,26 +260,27 @@ return sqrt($d); } -$old_error_handler = set_error_handler("userErrorHandler"); +$old_error_handler = set_error_handler("userErrorHandler"); // undefined constant, generates a warning $t = I_AM_NOT_DEFINED; -// define some "vectors" -$a = array(2,3,"foo"); +// define some "vectors" +$a = array(2,3,"foo"); $b = array(5.5, 4.3, -1.6); $c = array (1,-3); // generate a user error -$t1 = distance($c,$b)."\n"; +$t1 = distance($c,$b)."\n"; // generate another user error -$t2 = distance($b,"i am not an array")."\n"; +$t2 = distance($b,"i am not an array")."\n"; // generate a warning -$t3 = distance($a,$b)."\n"; +$t3 = distance($a,$b)."\n"; -?> +?> +]]> </programlisting> </example> This is just a simple example showing how to use the Index: phpdoc/en/features/http-auth.xml diff -u phpdoc/en/features/http-auth.xml:1.17 phpdoc/en/features/http-auth.xml:1.18 --- phpdoc/en/features/http-auth.xml:1.17 Sat Nov 10 16:49:30 2001 +++ phpdoc/en/features/http-auth.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.17 $ --> +<!-- $Revision: 1.18 $ --> <chapter id="features.http-auth"> <title>HTTP authentication with PHP</title> @@ -23,17 +23,19 @@ <example> <title>HTTP Authentication example</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php if(!isset($PHP_AUTH_USER)) { - header("WWW-Authenticate: Basic realm=\"My Realm\""); - header("HTTP/1.0 401 Unauthorized"); - echo "Text to send if user hits Cancel button\n"; + header("WWW-Authenticate: Basic realm=\"My Realm\""); + header("HTTP/1.0 401 Unauthorized"); + echo "Text to send if user hits Cancel button\n"; exit; } else { - echo "<p>Hello $PHP_AUTH_USER.</p>"; - echo "<p>You entered $PHP_AUTH_PW as your password.</p>"; + echo "<p>Hello $PHP_AUTH_USER.</p>"; + echo "<p>You entered $PHP_AUTH_PW as your password.</p>"; } ?> +]]> </programlisting> </example></para> @@ -93,27 +95,29 @@ <example> <title>HTTP Authentication example forcing a new name/password</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php function authenticate() { - header( "WWW-Authenticate: Basic realm=\"Test Authentication System\""); - header( "HTTP/1.0 401 Unauthorized"); - echo "You must enter a valid login ID and password to access this resource\n"; + header( "WWW-Authenticate: Basic realm=\"Test Authentication System\""); + header( "HTTP/1.0 401 Unauthorized"); + echo "You must enter a valid login ID and password to access this resource\n"; exit; } - if(!isset($PHP_AUTH_USER) || ($SeenBefore == 1 && !strcmp($OldAuth, $PHP_AUTH_USER)) ) { + if(!isset($PHP_AUTH_USER) || ($SeenBefore == 1 && !strcmp($OldAuth, $PHP_AUTH_USER)) ) { authenticate(); } else { - echo "</p>Welcome: $PHP_AUTH_USER<br>"; - echo "Old: $OldAuth"; - echo "<form action=\"$PHP_SELF\" METHOD=POST>\n"; - echo "<input type=\"hidden\" name=\"SeenBefore\" value=\"1\">\n"; - echo "<input type=\"hidden\" name=\"OldAuth\" value=\"$PHP_AUTH_USER\">\n"; - echo "<input type=\"submit\" value=\"Re Authenticate\">\n"; - echo "</form></p>\n"; + echo "</p>Welcome: $PHP_AUTH_USER<br>"; + echo "Old: $OldAuth"; + echo "<form action='$PHP_SELF' METHOD=POST>\n"; + echo "<input type='hidden' name='SeenBefore' value='1'>\n"; + echo "<input type='hidden' name='OldAuth' value='$PHP_AUTH_USER'>\n"; + echo "<input type='submit' value='Re Authenticate'>\n"; + echo "</form></p>\n"; } ?> +]]> </programlisting> </example> <simpara> Index: phpdoc/en/features/images.xml diff -u phpdoc/en/features/images.xml:1.13 phpdoc/en/features/images.xml:1.14 --- phpdoc/en/features/images.xml:1.13 Sat Nov 10 16:49:30 2001 +++ phpdoc/en/features/images.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.13 $ --> +<!-- $Revision: 1.14 $ --> <chapter id="features.images"> <title>Creating and manipulating images</title> @@ -18,7 +18,8 @@ <example> <title>PNG creation with PHP</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php Header("Content-type: image/png"); $string=implode($argv," "); $im = imageCreateFromPng("images/button1.png"); @@ -28,6 +29,7 @@ ImagePng($im); ImageDestroy($im); ?> +]]> </programlisting> </example> Index: phpdoc/en/features/safe-mode.xml diff -u phpdoc/en/features/safe-mode.xml:1.15 phpdoc/en/features/safe-mode.xml:1.16 --- phpdoc/en/features/safe-mode.xml:1.15 Sat Nov 10 16:49:31 2001 +++ phpdoc/en/features/safe-mode.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.15 $ --> +<!-- $Revision: 1.16 $ --> <chapter id="features.safe-mode"> <title>Safe Mode</title> @@ -12,12 +12,14 @@ <para> The configuration directives that control Safe Mode are: <programlisting role="ini"> +<![CDATA[ safe_mode = Off open_basedir = safe_mode_exec_dir = safe_mode_allowed_env_vars = PHP_ safe_mode_protected_env_vars = LD_LIBRARY_PATH disable_functions = +]]> </programlisting> </para> <para> @@ -25,48 +27,62 @@ if the owner of the current script matches the owner of the file to be operated on by a file function. For example: <programlisting role="ls"> +<![CDATA[ -rw-rw-r-- 1 rasmus rasmus 33 Jul 1 19:20 script.php -rw-r--r-- 1 root root 1116 May 26 18:01 /etc/passwd +]]> </programlisting> Running this script.php <programlisting role="php"> -<?php +<![CDATA[ +<?php readfile('/etc/passwd'); -?> +?> +]]> </programlisting> results in this error when Safe Mode is enabled: - <programlisting> + <screen> +<![CDATA[ Warning: SAFE MODE Restriction in effect. The script whose uid is 500 is not allowed to access /etc/passwd owned by uid 0 in /docroot/script.php on line 2 - </programlisting> +]]> + </screen> </para> <para> If instead of <link linkend="ini.safe-mode">safe_mode</link>, you set an open_basedir directory then all file operations will be limited to files under the specified directory. For example (Apache httpd.conf example): <programlisting role="ini"> -<Directory /docroot> -php_admin_value open_basedir /docroot -</Directory> +<![CDATA[ +<Directory /docroot> + php_admin_value open_basedir /docroot +</Directory> +]]> </programlisting> If you run the same script.php with this open_basedir setting then this is the result: - <programlisting> + <screen> +<![CDATA[ Warning: open_basedir restriction in effect. File is in wrong directory in /docroot/script.php on line 2 - </programlisting> +]]> + </screen> </para> <para> You can also disable individual functions. If we add this to our php.ini file: <programlisting role="ini"> +<![CDATA[ disable_functions readfile,system +]]> </programlisting> Then we get this output: - <programlisting> + <screen> +<![CDATA[ Warning: readfile() has been disabled for security reasons in /docroot/script.php on line 2 - </programlisting> +]]> + </screen> </para> <sect1 id="features.safe-mode.functions"> Index: phpdoc/en/language/basic-syntax.xml diff -u phpdoc/en/language/basic-syntax.xml:1.19 phpdoc/en/language/basic-syntax.xml:1.20 --- phpdoc/en/language/basic-syntax.xml:1.19 Sat Nov 10 16:49:42 2001 +++ phpdoc/en/language/basic-syntax.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.19 $ --> +<!-- $Revision: 1.20 $ --> <chapter id="language.basic-syntax"> <title>Basic syntax</title> @@ -65,18 +65,20 @@ <example> <title>Ways of escaping from HTML</title> <programlisting role="php"> -1. <? echo ("this is the simplest, an SGML processing instruction\n"); ?> - <?= expression ?> This is a shortcut for "<? echo expression ?>" +<![CDATA[ +1. <? echo ("this is the simplest, an SGML processing instruction\n"); ?> + <?= expression ?> This is a shortcut for "<? echo expression ?>" -2. <?php echo("if you want to serve XHTML or XML documents, do like this\n"); ?> +2. <?php echo("if you want to serve XHTML or XML documents, do like this\n"); ?> -3. <script language="php"> +3. <script language="php"> echo ("some editors (like FrontPage) don't like processing instructions"); - </script> + </script> -4. <% echo ("You may optionally use ASP-style tags"); %> - <%= $variable; # This is a shortcut for "<%echo .." %> +4. <% echo ("You may optionally use ASP-style tags"); %> + <%= $variable; # This is a shortcut for "<%echo .." %> +]]> </programlisting> </example> </para> @@ -113,19 +115,22 @@ PHP allows you to use structures like this: <example><title>Advanced escaping</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php if (boolean-expression) { - ?> -<strong>This is true.</strong> - <?php + ?> +<strong>This is true.</strong> + <?php } else { - ?> -<strong>This is false.</strong> - <?php + > +<strong>This is false.</strong> + <?php } - ?> - </programlisting></example> + ?> +]]> + </programlisting> + </example> This works as expected, because PHP handles text within ?> and <?php as an <function>echo</function> statement. @@ -147,11 +152,13 @@ <informalexample> <programlisting role="php"> -<?php +<![CDATA[ +<?php echo "This is a test"; ?> -<?php echo "This is a test" ?> +<?php echo "This is a test" ?> +]]> </programlisting> </informalexample></para></sect1> @@ -161,14 +168,17 @@ <para> PHP supports 'C', 'C++' and Unix shell-style comments. For example: - <informalexample><programlisting role="php"> -<?php + <informalexample> + <programlisting role="php"> +<![CDATA[ +<?php echo "This is a test"; // This is a one-line c++ style comment /* This is a multi line comment yet another line of comment */ echo "This is yet another test"; echo "One Final Test"; # This is shell-style style comment ?> +]]> </programlisting> </informalexample></para> @@ -176,22 +186,30 @@ The "one-line" comment styles actually only comment to the end of the line or the current block of PHP code, whichever comes first.</simpara> - <informalexample><programlisting role="php"> -<h1>This is an <?php # echo "simple";?> example.</h1> -<p>The header above will say 'This is an example'. - </programlisting></informalexample> + <informalexample> + <programlisting role="php"> +<![CDATA[ +<h1>This is an <?php # echo "simple";?> example.>/h1> +<p>The header above will say 'This is an example'. +]]> + </programlisting> + </informalexample> <simpara> You should be careful not to nest 'C' style comments, which can happen when commenting out large blocks.</simpara> - <informalexample><programlisting role="php"> -<?php + <informalexample> + <programlisting role="php"> +<![CDATA[ +<?php /* echo "This is a test"; /* This comment will cause a problem */ */ ?> - </programlisting></informalexample></sect1> +]]> + </programlisting> + </informalexample></sect1> </chapter> <!-- Keep this comment at the end of the file Index: phpdoc/en/language/constants.xml diff -u phpdoc/en/language/constants.xml:1.21 phpdoc/en/language/constants.xml:1.22 --- phpdoc/en/language/constants.xml:1.21 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/language/constants.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.21 $ --> +<!-- $Revision: 1.22 $ --> <chapter id="language.constants"> <title>Constants</title> @@ -98,11 +98,13 @@ <example> <title>Defining Constants</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php define("CONSTANT", "Hello world."); echo CONSTANT; // outputs "Hello world." echo Constant; // outputs "Constant" and issues a notice. -?> +?> +]]> </programlisting> </example> @@ -255,14 +257,16 @@ <example> <title>Using __FILE__ and __LINE__</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php function report_error($file, $line, $message) { echo "An error occured in $file on line $line: $message."; } report_error(__FILE__, __LINE__, "Something went wrong!"); -?> +?> +]]> </programlisting> </example> </para> Index: phpdoc/en/language/control-structures.xml diff -u phpdoc/en/language/control-structures.xml:1.42 phpdoc/en/language/control-structures.xml:1.43 --- phpdoc/en/language/control-structures.xml:1.42 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/language/control-structures.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.42 $ --> +<!-- $Revision: 1.43 $ --> <chapter id="control-structures"> <title>Control Structures</title> @@ -23,8 +23,10 @@ <literal>if</literal> structure that is similar to that of C: <informalexample> <programlisting> +<![CDATA[ if (expr) statement +]]> </programlisting> </informalexample> </para> @@ -40,8 +42,10 @@ than <replaceable>$b</replaceable>: <informalexample> <programlisting role="php"> -if ($a > $b) +<![CDATA[ +if ($a > $b) print "a is bigger than b"; +]]> </programlisting> </informalexample> </para> @@ -56,10 +60,12 @@ <replaceable>$a</replaceable> into <replaceable>$b</replaceable>: <informalexample> <programlisting role="php"> -if ($a > $b) { +<![CDATA[ +if ($a > $b) { print "a is bigger than b"; $b = $a; } +]]> </programlisting> </informalexample> </para> @@ -86,11 +92,13 @@ than b</computeroutput> otherwise: <informalexample> <programlisting role="php"> -if ($a > $b) { +<![CDATA[ +if ($a > $b) { print "a is bigger than b"; } else { print "a is NOT bigger than b"; } +]]> </programlisting> </informalexample> @@ -121,13 +129,15 @@ or <computeroutput>a is smaller than b</computeroutput>: <informalexample> <programlisting role="php"> -if ($a > $b) { +<![CDATA[ +if ($a > $b) { print "a is bigger than b"; } elseif ($a == $b) { print "a is equal to b"; } else { print "a is smaller than b"; } +]]> </programlisting> </informalexample> </para> @@ -166,9 +176,11 @@ <literal>endswitch;</literal>, respectively. <informalexample> <programlisting role="php"> -<?php if ($a == 5): ?> +<![CDATA[ +<?php if ($a == 5): ?> A is equal to 5 -<?php endif; ?> +<?php endif; ?> +]]> </programlisting> </informalexample> </para> @@ -184,6 +196,7 @@ <literal>else</literal> in the alternative format: <informalexample> <programlisting role="php"> +<![CDATA[ if ($a == 5): print "a equals 5"; print "..."; @@ -193,6 +206,7 @@ else: print "a is neither 5 nor 6"; endif; +]]> </programlisting> </informalexample> </para> @@ -211,7 +225,9 @@ of a <literal>while</literal> statement is: <informalexample> <programlisting> +<![CDATA[ while (expr) statement +]]> </programlisting> </informalexample> </para> @@ -235,7 +251,9 @@ using the alternate syntax: <informalexample> <programlisting> +<![CDATA[ while (expr): statement ... endwhile; +]]> </programlisting> </informalexample> </para> @@ -244,10 +262,11 @@ 1 to 10: <informalexample> <programlisting role="php"> +<![CDATA[ /* example 1 */ $i = 1; -while ($i <= 10) { +while ($i <= 10) { print $i++; /* the printed value would be $i before the increment (post-increment) */ @@ -256,10 +275,11 @@ /* example 2 */ $i = 1; -while ($i <= 10): +while ($i <= 10): print $i; $i++; endwhile; +]]> </programlisting> </informalexample> </para> @@ -285,10 +305,12 @@ <informalexample> <programlisting role="php"> +<![CDATA[ $i = 0; do { print $i; } while ($i>0); +]]> </programlisting> </informalexample> </para> @@ -307,13 +329,14 @@ statement. The following code fragment demonstrates this: <informalexample> <programlisting role="php"> +<![CDATA[ do { - if ($i < 5) { + if ($i < 5) { print "i is not big enough"; break; } $i *= $factor; - if ($i < $minimum_limit) { + if ($i < $minimum_limit) { break; } print "i is ok"; @@ -321,6 +344,7 @@ ...process i... } while(0); +]]> </programlisting> </informalexample> </para> @@ -339,7 +363,9 @@ <literal>for</literal> loop is: <informalexample> <programlisting> +<![CDATA[ for (expr1; expr2; expr3) statement +]]> </programlisting> </informalexample> </para> @@ -375,16 +401,17 @@ 1 to 10: <informalexample> <programlisting role="php"> +<![CDATA[ /* example 1 */ -for ($i = 1; $i <= 10; $i++) { +for ($i = 1; $i <= 10; $i++) { print $i; } /* example 2 */ for ($i = 1;;$i++) { - if ($i > 10) { + if ($i > 10) { break; } print $i; @@ -394,7 +421,7 @@ $i = 1; for (;;) { - if ($i > 10) { + if ($i > 10) { break; } print $i; @@ -403,7 +430,8 @@ /* example 4 */ -for ($i = 1; $i <= 10; print $i, $i++); +for ($i = 1; $i <= 10; print $i, $i++); +]]> </programlisting> </informalexample> </para> @@ -418,7 +446,9 @@ <literal>for</literal> loops. <informalexample> <programlisting> +<![CDATA[ for (expr1; expr2; expr3): statement; ...; endfor; +]]> </programlisting> </informalexample> </para> @@ -444,8 +474,10 @@ a minor but useful extension of the first: <informalexample> <programlisting> +<![CDATA[ foreach(array_expression as $value) statement -foreach(array_expression as $key => $value) statement +foreach(array_expression as $key => $value) statement +]]> </programlisting> </informalexample> </para> @@ -494,27 +526,31 @@ identical: <informalexample> <programlisting role="php"> +<![CDATA[ reset ($arr); while (list(, $value) = each ($arr)) { - echo "Value: $value<br>\n"; + echo "Value: $value<br>\n"; } foreach ($arr as $value) { - echo "Value: $value<br>\n"; + echo "Value: $value<br>\n"; } +]]> </programlisting> </informalexample> The following are also functionally identical: <informalexample> <programlisting role="php"> +<![CDATA[ reset ($arr); while (list($key, $value) = each ($arr)) { - echo "Key: $key; Value: $value<br>\n"; + echo "Key: $key; Value: $value<br>\n"; } foreach ($arr as $key => $value) { - echo "Key: $key; Value: $value<br>\n"; + echo "Key: $key; Value: $value<br>\n"; } +]]> </programlisting> </informalexample> </para> @@ -522,6 +558,7 @@ Some more examples to demonstrate usages: <informalexample> <programlisting role="php"> +<![CDATA[ /* foreach example 1: value only */ $a = array (1, 2, 3, 17); @@ -537,20 +574,20 @@ $i = 0; /* for illustrative purposes only */ foreach($a as $v) { - print "\$a[$i] => $v.\n"; + print "\$a[$i] => $v.\n"; } /* foreach example 3: key and value */ $a = array ( - "one" => 1, - "two" => 2, - "three" => 3, - "seventeen" => 17 + "one" => 1, + "two" => 2, + "three" => 3, + "seventeen" => 17 ); -foreach($a as $k => $v) { - print "\$a[$k] => $v.\n"; +foreach($a as $k => $v) { + print "\$a[$k] => $v.\n"; } /* foreach example 4: multi-dimensional arrays */ @@ -571,6 +608,7 @@ foreach(array(1, 2, 3, 4, 5) as $v) { print "$v\n"; } +]]> </programlisting> </informalexample> </para> @@ -592,12 +630,13 @@ <para> <informalexample> <programlisting role="php"> +<![CDATA[ $arr = array ('one', 'two', 'three', 'four', 'stop', 'five'); while (list (, $val) = each ($arr)) { if ($val == 'stop') { break; /* You could also write 'break 1;' here. */ } - echo "$val<br>\n"; + echo "$val<br>\n"; } /* Using the optional argument. */ @@ -606,15 +645,16 @@ while (++$i) { switch ($i) { case 5: - echo "At 5<br>\n"; + echo "At 5<br>\n"; break 1; /* Exit only the switch. */ case 10: - echo "At 10; quitting<br>\n"; + echo "At 10; quitting<br>\n"; break 2; /* Exit the switch and the while. */ default: break; } } +]]> </programlisting> </informalexample> </para> @@ -635,6 +675,7 @@ <para> <informalexample> <programlisting role="php"> +<![CDATA[ while (list ($key, $value) = each ($arr)) { if (!($key % 2)) { // skip odd members continue; @@ -644,17 +685,18 @@ $i = 0; while ($i++ < 5) { - echo "Outer<br>\n"; + echo "Outer<br>\n"; while (1) { - echo " Middle<br>\n"; + echo " Middle<br>\n"; while (1) { - echo " Inner<br>\n"; + echo " Inner<br>\n"; continue 3; } - echo "This never gets output.<br>\n"; + echo "This never gets output.<br>\n"; } - echo "Neither does this.<br>\n"; + echo "Neither does this.<br>\n"; } +]]> </programlisting> </informalexample> </para> @@ -677,6 +719,7 @@ statement: <informalexample> <programlisting role="php"> +<![CDATA[ if ($i == 0) { print "i equals 0"; } @@ -698,6 +741,7 @@ print "i equals 2"; break; } +]]> </programlisting> </informalexample> </para> @@ -717,6 +761,7 @@ following case. For example: <informalexample> <programlisting role="php"> +<![CDATA[ switch ($i) { case 0: print "i equals 0"; @@ -725,6 +770,7 @@ case 2: print "i equals 2"; } +]]> </programlisting> </informalexample> </para> @@ -750,6 +796,7 @@ passes control into the statement list for the next case. <informalexample> <programlisting role="php"> +<![CDATA[ switch ($i) { case 0: case 1: @@ -759,6 +806,7 @@ case 3: print "i is 3"; } +]]> </programlisting> </informalexample> </para> @@ -768,6 +816,7 @@ <literal>case</literal> statement. For example: <informalexample> <programlisting role="php"> +<![CDATA[ switch ($i) { case 0: print "i equals 0"; @@ -781,6 +830,7 @@ default: print "i is not equal to 0, 1 or 2"; } +]]> </programlisting> </informalexample> </para> @@ -797,6 +847,7 @@ for control structures</link> . <informalexample> <programlisting role="php"> +<![CDATA[ switch ($i): case 0: print "i equals 0"; @@ -810,6 +861,7 @@ default: print "i is not equal to 0, 1 or 2"; endswitch; +]]> </programlisting> </informalexample> </para> @@ -824,7 +876,9 @@ the syntax of other flow control constructs: <informalexample> <programlisting> +<![CDATA[ declare (directive) statement +]]> </programlisting> </informalexample> </para> @@ -865,8 +919,9 @@ <example> <title>Profile a section of PHP code</title> <programlisting role="php"> -<pre> -<?php +<![CDATA[ +<pre> +<?php // A function that records the time when it is called function profile ($dump = FALSE) { @@ -890,15 +945,16 @@ // Run a block of code, throw a tick every 2nd statement declare (ticks=2) { - for ($x = 1; $x < 50; ++$x) { + for ($x = 1; $x < 50; ++$x) { echo similar_text (md5($x), md5($x*$x)), "<br>"; } } // Display the data stored in the profiler print_r (profile (TRUE)); -?> -</pre> +?> +</pre> +]]> </programlisting> </example> The example profiles the PHP code within the 'declare' @@ -976,7 +1032,9 @@ <function>include</function> statement. <informalexample> <programlisting role="php"> +<![CDATA[ require ('header.inc'); +]]> </programlisting> </informalexample> </para> @@ -1002,24 +1060,26 @@ the local script. <informalexample> <programlisting role="php"> +<![CDATA[ /* This example assumes that someserver is configured to parse .php * files and not .txt files. Also, 'works' here means that the variables * $varone and $vartwo are available within the require()ed file. */ /* Won't work; file.txt wasn't handled by someserver. */ -require ("http://someserver/file.txt?varone=1&vartwo=2"); +require ("http://someserver/file.txt?varone=1&vartwo=2"); /* Won't work; looks for a file named 'file.php?varone=1&vartwo=2' * on the local filesystem. */ -require ("file.php?varone=1&vartwo=2"); +require ("file.php?varone=1&vartwo=2"); /* Works. */ -require ("http://someserver/file.php?varone=1&vartwo=2"); +require ("http://someserver/file.php?varone=1&vartwo=2"); $varone = 1; $vartwo = 2; require ("file.txt"); /* Works. */ require ("file.php"); /* Works. */ +]]> </programlisting> </informalexample> </para> @@ -1069,10 +1129,12 @@ different files. <informalexample> <programlisting role="php"> +<![CDATA[ $files = array ('first.inc', 'second.inc', 'third.inc'); -for ($i = 0; $i < count($files); $i++) { +for ($i = 0; $i < count($files); $i++) { include $files[$i]; } +]]> </programlisting> </informalexample> </para> @@ -1093,6 +1155,7 @@ inside a conditional block. <informalexample> <programlisting role="php"> +<![CDATA[ /* This is WRONG and will not work as desired. */ if ($condition) @@ -1107,6 +1170,7 @@ } else { include($other); } +]]> </programlisting> </informalexample> </para> @@ -1132,23 +1196,26 @@ <filename>test.inc</filename>) in the same directory as the main file: <programlisting role="php"> -<?php -echo "Before the return <br>\n"; +<![CDATA[ +<?php +echo "Before the return <br>\n"; if (1) { return 27; } -echo "After the return <br>\n"; -?> +echo "After the return <br>\n"; +?> +]]> </programlisting> </para> <para> Assume that the main file (<filename>main.html</filename>) contains the following: <programlisting role="php"> -<?php +<![CDATA[ +<?php $retval = include ('test.inc'); -echo "File returned: '$retval'<br>\n"; -?> +echo "File returned: '$retval'<br>\n"; +?> </programlisting> </para> <para> @@ -1165,10 +1232,12 @@ Now, assume that <filename>main.html</filename> has been altered to contain the following: <programlisting role="php"> -<?php +<![CDATA[ +<?php include ('test.inc'); -echo "Back in main.html<br>\n"; -?> +echo "Back in main.html<br>\n"; +?> +]]> </programlisting> </para> <para> @@ -1222,24 +1291,26 @@ the local script. <informalexample> <programlisting role="php"> +<![CDATA[ /* This example assumes that someserver is configured to parse .php * files and not .txt files. Also, 'works' here means that the variables * $varone and $vartwo are available within the include()ed file. */ /* Won't work; file.txt wasn't handled by someserver. */ -include ("http://someserver/file.txt?varone=1&vartwo=2"); +include ("http://someserver/file.txt?varone=1vartwo=2"); -/* Won't work; looks for a file named 'file.php?varone=1&vartwo=2' +/* Won't work; looks for a file named 'file.php?varone=1&vartwo=2' * on the local filesystem. */ include ("file.php?varone=1&vartwo=2"); /* Works. */ -include ("http://someserver/file.php?varone=1&vartwo=2"); +include ("http://someserver/file.php?varone=1&vartwo=2"); $varone = 1; $vartwo = 2; include ("file.txt"); /* Works. */ include ("file.php"); /* Works. */ +]]> </programlisting> </informalexample> </para> @@ -1268,20 +1339,23 @@ <example> <title>utils.inc</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php define("PHPVERSION", floor(phpversion())); echo "GLOBALS ARE NICE\n"; function goodTea() { return "Oolong tea tastes good!"; } -?> +?> +]]> </programlisting> </example> <example> <title>foolib.inc</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php require ("utils.inc"); function showVar($var) { @@ -1293,14 +1367,16 @@ } // bunch of other functions ... -?> +?> +]]> </programlisting> </example> And then you write a script <literal>cause_error_require.php</literal> <example> <title>cause_error_require.php</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php require("foolib.inc"); /* the following will generate an error */ require("utils.inc"); @@ -1310,18 +1386,21 @@ echo "Running goodTea: ".goodTea()."\n"; echo "Printing foo: \n"; showVar($foo); -?> +?> +]]> </programlisting> </example> When you try running the latter one, the resulting ouptut will be (using PHP 4.01pl2): <informalexample> - <programlisting> + <screen> +<![CDATA[ GLOBALS ARE NICE GLOBALS ARE NICE Fatal error: Cannot redeclare goodTea() in utils.inc on line 5 - </programlisting> +]]> + </screen> </informalexample> By modifying <literal>foolib.inc</literal> and <literal>cause_errror_require.php</literal> @@ -1331,26 +1410,31 @@ <example> <title>foolib.inc (fixed)</title> <programlisting role="php"> +<![CDATA[ ... require_once("utils.inc"); function showVar($var) { ... +]]> </programlisting> </example> <example> <title>avoid_error_require_once.php</title> <programlisting role="php"> +<![CDATA[ ... require_once("foolib.inc"); require_once("utils.inc"); $foo = array("1",array("complex","quaternion")); ... +]]> </programlisting> </example> And when running the latter, the output will be (using PHP 4.0.1pl2): <informalexample> - <programlisting> + <screen> +<![CDATA[ GLOBALS ARE NICE this is requiring globals.inc again which is also required in foolib.inc @@ -1358,15 +1442,16 @@ Printing foo: Array ( - [0] => 1 - [1] => Array + [0] => 1 + [1] => Array ( - [0] => complex - [1] => quaternion + [0] => complex + [1] => quaternion ) ) - </programlisting> +]]> + </screen> </informalexample> </para> <para> Index: phpdoc/en/language/expressions.xml diff -u phpdoc/en/language/expressions.xml:1.17 phpdoc/en/language/expressions.xml:1.18 --- phpdoc/en/language/expressions.xml:1.17 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/language/expressions.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.17 $ --> +<!-- $Revision: 1.18 $ --> <chapter id="language.expressions"> <title>Expressions</title> @@ -28,10 +28,12 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function foo () { return 5; } +]]> </programlisting> </informalexample></para> @@ -127,7 +129,9 @@ it in other languages, the ternary conditional operator: <informalexample><programlisting> +<![CDATA[ $first ? $second : $third +]]> </programlisting></informalexample> If the value of the first subexpression is &true; (non-zero), then @@ -142,6 +146,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function double($i) { return $i*2; @@ -162,6 +167,7 @@ value of 24. the value of the assignment (24) is then assigned into $h, and $h ends with the value of 24 as well. */ +]]> </programlisting> </informalexample> </para> Index: phpdoc/en/language/functions.xml diff -u phpdoc/en/language/functions.xml:1.18 phpdoc/en/language/functions.xml:1.19 --- phpdoc/en/language/functions.xml:1.18 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/language/functions.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.18 $ --> +<!-- $Revision: 1.19 $ --> <chapter id="functions"> <title>Functions</title> @@ -11,11 +11,13 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function foo ($arg_1, $arg_2, ..., $arg_n) { echo "Example function.\n"; return $retval; } +]]> </programlisting> </informalexample> </para> @@ -79,10 +81,12 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function takes_array($input) { echo "$input[0] + $input[1] = ", $input[0]+$input[1]; } +]]> </programlisting> </informalexample> </para> @@ -104,13 +108,15 @@ <informalexample> <programlisting role="php"> -function add_some_extra(&$string) +<![CDATA[ +function add_some_extra(&$string) { $string .= 'and something extra.'; } $str = 'This is a string, '; add_some_extra($str); echo $str; // outputs 'This is a string, and something extra.' +]]> </programlisting> </informalexample> </para> @@ -122,6 +128,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function foo ($bar) { $bar .= ' and something extra.'; @@ -129,8 +136,9 @@ $str = 'This is a string, '; foo ($str); echo $str; // outputs 'This is a string, ' -foo (&$str); +foo (&$str); echo $str; // outputs 'This is a string, and something extra.' +]]> </programlisting> </informalexample> </para> @@ -146,12 +154,14 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function makecoffee ($type = "cappucino") { return "Making a cup of $type.\n"; } echo makecoffee (); echo makecoffee ("espresso"); +]]> </programlisting> </informalexample> </para> @@ -176,12 +186,14 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function makeyogurt ($type = "acidophilus", $flavour) { return "Making a bowl of $type $flavour.\n"; } echo makeyogurt ("raspberry"); // won't work as expected +]]> </programlisting> </informalexample> </para> @@ -201,12 +213,14 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function makeyogurt ($flavour, $type = "acidophilus") { return "Making a bowl of $type $flavour.\n"; } echo makeyogurt ("raspberry"); // works as expected +]]> </programlisting> </informalexample> </para> @@ -251,11 +265,13 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function square ($num) { return $num * $num; } echo square (4); // outputs '16'. +]]> </programlisting> </informalexample> </para> @@ -266,11 +282,13 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function small_numbers() { return array (0, 1, 2); } list ($zero, $one, $two) = small_numbers(); +]]> </programlisting> </informalexample> </para> @@ -280,12 +298,14 @@ when assigning the returned value to a variable: <informalexample> <programlisting role="php"> -function &returns_reference() +<![CDATA[ +function &returns_reference() { return $someref; } -$newref =& returns_reference(); +$newref =& returns_reference(); +]]> </programlisting> </informalexample> </para> @@ -339,15 +359,16 @@ <example> <title>Variable function example</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php function foo() { - echo "In foo()<br>\n"; + echo "In foo()<br>\n"; } function bar($arg = '') { - echo "In bar(); argument was '$arg'.<br>\n"; + echo "In bar(); argument was '$arg'.<br>\n"; } $func = 'foo'; @@ -355,6 +376,7 @@ $func = 'bar'; $func('test'); ?> +]]> </programlisting> </example> </para> Index: phpdoc/en/language/oop.xml diff -u phpdoc/en/language/oop.xml:1.30 phpdoc/en/language/oop.xml:1.31 --- phpdoc/en/language/oop.xml:1.30 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/language/oop.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.30 $ --> +<!-- $Revision: 1.31 $ --> <chapter id="language.oop"> <title>Classes and Objects</title> @@ -11,7 +11,8 @@ <informalexample> <programlisting role="php"> -<?php +<![CDATA[ +<?php class Cart { var $items; // Items in our shopping cart @@ -35,7 +36,8 @@ } } } -?> +?> +]]> </programlisting> </informalexample> </para> @@ -82,6 +84,8 @@ </simpara> <informalexample> <programlisting role="php"> +<![CDATA[ +<?php /* None of these will work in PHP 4. */ class Cart { @@ -106,6 +110,7 @@ /* etc. . . */ } } +]]> </programlisting> </informalexample> </note> @@ -118,11 +123,14 @@ <informalexample> <programlisting role="php"> +<![CDATA[ +<?php $cart = new Cart; $cart->add_item("10", 1); $another_cart = new Cart; $another_cart->add_item("0815", 3); +]]> </programlisting> </informalexample> @@ -154,6 +162,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ // correct, single $ $cart->items = array("10" => 1); @@ -164,6 +173,7 @@ // $cart->$myvar becomes $cart->items $myvar = 'items'; $cart->$myvar = array("10" => 1); +]]> </programlisting> </informalexample> @@ -203,6 +213,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ class Named_Cart extends Cart { var $owner; @@ -212,6 +223,7 @@ $this->owner = $name; } } +]]> </programlisting> </informalexample> @@ -225,10 +237,12 @@ <informalexample> <programlisting role="php"> +<![CDATA[ $ncart = new Named_Cart; // Create a named cart $ncart->set_owner("kris"); // Name that cart print $ncart->owner; // print the cart owners name $ncart->add_item("10", 1); // (inherited functionality from cart) +]]> </programlisting> </informalexample> @@ -256,6 +270,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ // Works in PHP 3 and PHP 4. class Auto_Cart extends Cart { @@ -264,6 +279,7 @@ $this->add_item ("10", 1); } } +]]> </programlisting> </informalexample> @@ -279,6 +295,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ // Works in PHP 3 and PHP 4. class Constructor_Cart extends Cart { @@ -295,6 +312,7 @@ // Shop for real... $different_cart = new Constructor_Cart("20", 17); +]]> </programlisting> </informalexample> @@ -308,11 +326,12 @@ <informalexample> <programlisting role="php"> +<![CDATA[ class A { function A() { - echo "I am the constructor of A.<br>\n"; + echo "I am the constructor of A.<br>\n"; } } @@ -320,12 +339,13 @@ { function C() { - echo "I am a regular function.<br>\n"; + echo "I am a regular function.<br>\n"; } } // no constructor is being called in PHP 3. $b = new B; +]]> </programlisting> </informalexample> @@ -345,17 +365,18 @@ <informalexample> <programlisting role="php"> +<![CDATA[ class A { function A() { - echo "I am the constructor of A.<br>\n"; + echo "I am the constructor of A.<br>\n"; } function B() { - echo "I am a regular function named B in class A.<br>\n"; - echo "I am not a constructor in A.<br>\n"; + echo "I am a regular function named B in class A.<br>\n"; + echo "I am not a constructor in A.<br>\n"; } } @@ -363,12 +384,13 @@ { function C() { - echo "I am a regular function.<br>\n"; + echo "I am a regular function.<br>\n"; } } // This will call B() as a constructor. $b = new B; +]]> </programlisting> </informalexample> @@ -431,11 +453,12 @@ <informalexample> <programlisting role="php"> +<![CDATA[ class A { function example() { - echo "I am the original function A::example().<br>\n"; + echo "I am the original function A::example().<br>\n"; } } @@ -443,23 +466,24 @@ { function example() { - echo "I am the redefined function B::example().<br>\n"; + echo "I am the redefined function B::example().<br>\n"; A::example(); } } // there is no object of class A. // this will print -// I am the original function A::example().<br> +// I am the original function A::example().<br> A::example(); // create an object of class B. $b = new B; // this will print -// I am the redefined function B::example().<br> -// I am the original function A::example().<br> +// I am the redefined function B::example().<br> +// I am the original function A::example().<br> $b->example(); +]]> </programlisting> </informalexample> @@ -522,11 +546,12 @@ <informalexample> <programlisting role="php"> +<![CDATA[ class A { function example() { - echo "I am A::example() and provide basic functionality.<br>\n"; + echo "I am A::example() and provide basic functionality.<br>\n"; } } @@ -534,7 +559,7 @@ { function example() { - echo "I am B::example() and provide additional functionality.<br>\n"; + echo "I am B::example() and provide additional functionality.<br>\n"; parent::example(); } } @@ -543,6 +568,7 @@ // This will call B::example(), which will in turn call A::example(). $b->example(); +]]> </programlisting> </informalexample> </sect1> @@ -591,6 +617,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ classa.inc: class A { @@ -621,6 +648,7 @@ // now use the function show_one() of the $a object. $a->show_one(); +]]> </programlisting> </informalexample> @@ -694,14 +722,14 @@ <informalexample> <programlisting role="php"> - +<![CDATA[ class Foo { function Foo($name) { // create a reference inside the global array $globalref global $globalref; - $globalref[] = &$this; + $globalref[] = &$this; // set name to passed value $this->setName($name); // and put it out @@ -710,7 +738,7 @@ function echoName() { - echo "<br>",$this->name; + echo "<br>",$this->name; } function setName($name) @@ -718,6 +746,7 @@ $this->name = $name; } } +]]> </programlisting> </informalexample> </para> @@ -731,7 +760,7 @@ <informalexample> <programlisting role="php"> - +<![CDATA[ $bar1 = new Foo('set in constructor'); $bar1->echoName(); $globalref[0]->echoName(); @@ -741,7 +770,7 @@ set in constructor set in constructor */ -$bar2 =& new Foo('set in constructor'); +$bar2 =& new Foo('set in constructor'); $bar2->echoName(); $globalref[1]->echoName(); @@ -749,7 +778,7 @@ set in constructor set in constructor set in constructor */ - +]]> </programlisting> </informalexample> </para> @@ -775,6 +804,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ // now we will change the name. what do you expect? // you could expect that both $bar1 and $globalref[0] change their names... $bar1->setName('set from outside'); @@ -798,6 +828,7 @@ /* output: set from outside set from outside */ +]]> </programlisting> </informalexample> </para> @@ -806,6 +837,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ class A { function A($i) @@ -822,27 +854,27 @@ function echoValue() { - echo "<br>","class ",get_class($this),': ',$this->value; + echo "<br>","class ",get_class($this),': ',$this->value; } } class B { - function B(&$a) + function B(&$a) { - $this->a = &$a; + $this->a = &$a; } function echoValue() { - echo "<br>","class ",get_class($this),': ',$this->a->value; + echo "<br>","class ",get_class($this),': ',$this->a->value; } } // try to undestand why using a simple copy here would yield // in an undesired result in the *-marked line -$a =& new A(10); +$a =& new A(10); $a->createRef(); $a->echoValue(); @@ -864,6 +896,7 @@ class B: 11 class B: 11 */ +]]> </programlisting> </informalexample> </para> Index: phpdoc/en/language/operators.xml diff -u phpdoc/en/language/operators.xml:1.28 phpdoc/en/language/operators.xml:1.29 --- phpdoc/en/language/operators.xml:1.28 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/language/operators.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.28 $ --> +<!-- $Revision: 1.29 $ --> <chapter id="language.operators"> <title>Operators</title> <simpara> @@ -75,7 +75,9 @@ things: <informalexample> <programlisting role="php"> +<![CDATA[ $a = ($b = 4) + 5; // $a is equal to 9 now, and $b has been set to 4. +]]> </programlisting> </informalexample> </para> @@ -86,10 +88,12 @@ value to the result of that expression. For example: <informalexample> <programlisting role="php"> +<![CDATA[ $a = 3; $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!"; +]]> </programlisting> </informalexample> </para> @@ -245,7 +249,9 @@ which operates as in C and many other languages. <informalexample> <programlisting> +<![CDATA[ (expr1) ? (expr2) : (expr3); +]]> </programlisting> </informalexample> This expression evaluates to <replaceable>expr2</replaceable> if @@ -272,7 +278,8 @@ <para> <informalexample> <programlisting role="php"> -<?php +<![CDATA[ +<?php /* Intentional file error */ $my_file = @file ('non_existent_file') or die ("Failed opening file: error was '$php_errormsg'"); @@ -281,7 +288,8 @@ $value = @$cache[$key]; // will not issue a notice if the index $key doesn't exist. -?> +?> +]]> </programlisting> </informalexample> </para> @@ -321,8 +329,10 @@ assigned to a variable). <informalexample> <programlisting role="php"> +<![CDATA[ $output = `ls -al`; -echo "<pre>$output</pre>"; +echo "<pre>$output</pre>"; +]]> </programlisting> </informalexample> </para> @@ -384,27 +394,29 @@ Here's a simple example script: <informalexample> <programlisting role="php"> -<?php -echo "<h3>Postincrement</h3>"; +<![CDATA[ +<?php +echo "<h3>Postincrement</h3>"; $a = 5; -echo "Should be 5: " . $a++ . "<br>\n"; -echo "Should be 6: " . $a . "<br>\n"; +echo "Should be 5: " . $a++ . "<br>\n"; +echo "Should be 6: " . $a . "<br>\n"; -echo "<h3>Preincrement</h3>"; +echo "<h3>Preincrement</h3>"; $a = 5; -echo "Should be 6: " . ++$a . "<br>\n"; -echo "Should be 6: " . $a . "<br>\n"; +echo "Should be 6: " . ++$a . "<br>\n"; +echo "Should be 6: " . $a . "<br>\n"; -echo "<h3>Postdecrement</h3>"; +echo "<h3>Postdecrement</h3>"; $a = 5; -echo "Should be 5: " . $a-- . "<br>\n"; -echo "Should be 4: " . $a . "<br>\n"; +echo "Should be 5: " . $a-- . "<br>\n"; +echo "Should be 4: " . $a . "<br>\n"; -echo "<h3>Predecrement</h3>"; +echo "<h3>Predecrement</h3>"; $a = 5; -echo "Should be 4: " . --$a . "<br>\n"; -echo "Should be 4: " . $a . "<br>\n"; -?> +echo "Should be 4: " . --$a . "<br>\n"; +echo "Should be 4: " . $a . "<br>\n"; +?> +]]> </programlisting> </informalexample> </para> @@ -593,11 +605,13 @@ <para> <informalexample> <programlisting role="php"> +<![CDATA[ $a = "Hello "; $b = $a . "World!"; // now $b contains "Hello World!" $a = "Hello "; $a .= "World!"; // now $a contains "Hello World!" +]]> </programlisting> </informalexample> </para> Index: phpdoc/en/language/references.xml diff -u phpdoc/en/language/references.xml:1.17 phpdoc/en/language/references.xml:1.18 --- phpdoc/en/language/references.xml:1.17 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/language/references.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.17 $ --> +<!-- $Revision: 1.18 $ --> <chapter id="language.references"> <title>References Explained</title> @@ -24,7 +24,9 @@ same content. Meaning, when you do: <informalexample> <programlisting role="php"> -$a =& $b +<![CDATA[ +$a =& $b +]]> </programlisting> </informalexample> it means that <varname>$a</varname> and <varname>$b</varname> @@ -44,8 +46,10 @@ and with <literal>new</literal> operator (in PHP 4.0.4 and later): <informalexample> <programlisting role="php"> -$bar =& new fooclass(); -$foo =& find_var ($bar); +<![CDATA[ +$bar =& new fooclass(); +$foo =& find_var ($bar); +]]> </programlisting> </informalexample> </para> @@ -65,13 +69,15 @@ a variable in the calling scope reference to the same content. Example: <informalexample> <programlisting role="php"> -function foo (&$var) +<![CDATA[ +function foo (&$var) { $var++; } $a=5; foo ($a); +]]> </programlisting> </informalexample> will make <varname>$a</varname> to be 6. This happens because in @@ -93,11 +99,13 @@ following construct won't do what you expect: <informalexample> <programlisting role="php"> +<![CDATA[ function foo (&$var) { - $var =& $GLOBALS["baz"]; + $var =& $GLOBALS["baz"]; } foo($bar); +]]> </programlisting> </informalexample> </para> @@ -122,7 +130,8 @@ its arguments. The syntax is as follows: <informalexample> <programlisting role="php"> -function foo (&$var) +<![CDATA[ +function foo (&$var) { $var++; } @@ -130,6 +139,7 @@ $a=5; foo ($a); // $a is 6 here +]]> </programlisting> </informalexample> Note that there's no reference sign on function call - only on @@ -154,12 +164,14 @@ Reference, returned from a function, i.e.: <informalexample> <programlisting role="php"> -function &bar() +<![CDATA[ +function &bar() { $a = 5; return $a; } foo(bar()); +]]> </programlisting> </informalexample> See also explanations about <link @@ -174,7 +186,8 @@ by reference are invalid: <informalexample> <programlisting role="php"> -function bar() // Note the missing & +<![CDATA[ +function bar() // Note the missing & { $a = 5; return $a; @@ -183,9 +196,10 @@ foo($a = 5) // Expression, not variable foo(5) // Constant, not variable +]]> </programlisting> </informalexample> -These requirements are for PHP 4.0.4 and later. + These requirements are for PHP 4.0.4 and later. </para> </sect1> @@ -197,14 +211,16 @@ returning references, use this syntax: <informalexample> <programlisting role="php"> -function &find_var ($param) +<![CDATA[ +function &find_var ($param) { ...code... return $found_var; } -$foo =& find_var ($bar); +$foo =& find_var ($bar); $foo->x = 2; +]]> </programlisting> </informalexample> In this example, the property of the object returned by the @@ -230,9 +246,11 @@ variable content will be destroyed. For example: <informalexample> <programlisting role="php"> +<![CDATA[ $a = 1; $b =& $a; unset ($a); +]]> </programlisting> </informalexample> won't unset <varname>$b</varname>, just <varname>$a</varname>. @@ -261,7 +279,9 @@ this is the same as: <informalexample> <programlisting role="php"> -$var =& $GLOBALS["var"]; +<![CDATA[ +$var =& $GLOBALS["var"]; +]]> </programlisting> </informalexample> </para> Index: phpdoc/en/language/types.xml diff -u phpdoc/en/language/types.xml:1.65 phpdoc/en/language/types.xml:1.66 --- phpdoc/en/language/types.xml:1.65 Fri Nov 23 16:10:34 2001 +++ phpdoc/en/language/types.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.65 $ --> +<!-- $Revision: 1.66 $ --> <chapter id="language.types"> <title>Types</title> @@ -157,7 +157,9 @@ <!-- technically they are just constants --> <informalexample> <programlisting role="php"> +<![CDATA[ $foo = True; // assign the value TRUE to $foo +]]> </programlisting> </informalexample> </para> @@ -169,19 +171,21 @@ structure</link>. <informalexample> <programlisting role="php"> +<![CDATA[ if ($action == "show_version") { // == is an <link linkend="language.operators">operator</link> which returns a <type>boolean</type> echo "The version is 1.23"; } // this is not necessary: if ($show_separators == true) { - echo "<hr>\n"; + echo "<hr>\n"; } // because you can simply type this: if ($show_separators) { - echo "<hr>\n"; + echo "<hr>\n"; } +]]> </programlisting> </informalexample> </para> @@ -282,10 +286,12 @@ <example> <title>Integer literals</title> <programlisting role="php"> +<![CDATA[ $a = 1234; # decimal number $a = -123; # a negative number $a = 0123; # octal number (equivalent to 83 decimal) $a = 0x1A; # hexadecimal number (equivalent to 26 decimal) +]]> </programlisting> </example> <!-- @@ -320,6 +326,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ $large_number = 2147483647; var_dump($large_number); // output: int(2147483647) @@ -336,6 +343,7 @@ $large_number = 50000 * $million; var_dump($large_number); // output: float(50000000000) +]]> </programlisting> </informalexample> <warning> @@ -359,8 +367,10 @@ operators, or with type-jug) --> <informalexample> <programlisting role="php"> +<![CDATA[ var_dump( 25/7 ); // output: float(3.5714285714286) +]]> </programlisting> </informalexample> </para> @@ -412,7 +422,9 @@ sometimes lead to unexpected results. <informalexample> <programlisting role="php"> +<![CDATA[ echo (int) ( (0.1+0.7) * 10 ); // echoes 7! +]]> </programlisting> </informalexample> @@ -578,6 +590,7 @@ </note> <informalexample> <programlisting role="php"> +<![CDATA[ echo 'this is a simple string'; echo 'You can also have embedded newlines in strings, like this way.'; @@ -589,6 +602,7 @@ // output: ... delete C:\*.*? echo 'I am trying to include at this point: \n a newline'; // output: ... this point: \n a newline +]]> </programlisting> </informalexample> </para> @@ -717,8 +731,9 @@ <example> <title>Here doc string quoting example</title> <programlisting role="php"> -<?php -$str = <<<EOD +<![CDATA[ +<?php +$str = <<<EOD Example of string spanning multiple lines using heredoc syntax. @@ -732,20 +747,21 @@ function foo() { - $this->foo = 'Foo'; - $this->bar = array('Bar1', 'Bar2', 'Bar3'); + $this->foo = 'Foo'; + $this->bar = array('Bar1', 'Bar2', 'Bar3'); } } $foo = new foo(); $name = 'MyName'; -echo <<<EOT +echo <<<EOT My name is "$name". I am printing some $foo->foo. -Now, I am printing some {$foo->bar[1]}. +Now, I am printing some {$foo->bar[1]}. This should print a capital 'A': \x41 EOT; ?> +]]> </programlisting> </example> </para> @@ -789,10 +805,12 @@ </simpara> <informalexample> <programlisting role="php"> +<![CDATA[ $beer = 'Heineken'; echo "$beer's taste is great"; // works, "'" is an invalid character for varnames echo "He drunk some $beers"; // won't work, 's' is a valid character for varnames echo "He drunk some ${beer}s"; // works +]]> </programlisting> </informalexample> <simpara> @@ -813,12 +831,13 @@ </simpara> <informalexample> <programlisting role="php"> -$fruits = array( 'strawberry' => 'red' , 'banana' => 'yellow' ); +<![CDATA[ +$fruits = array( 'strawberry' => 'red' , 'banana' => 'yellow' ); echo "A banana is $fruits[banana]."; // note that this works differently outside string-quotes. See <link linkend="language.types.array.foo-bar"><literal>$foo[bar]</literal> outside strings</link> -echo "This square is $square->width meters broad."; -echo "This square is $square->width00 centimeters broad."; // won't work, +echo "This square is $square->width meters broad."; +echo "This square is $square->width00 centimeters broad."; // won't work, // for a solution, see the <link linkend="language.types.string.parsing.complex">complex syntax</link>. <!-- XXX this won't work: @@ -827,7 +846,7 @@ // XXX: like the $obj->{expr} syntax outside a string works, // XXX: analogously to the ${expr} syntax for variable var's. --> - +]]> </programlisting> </informalexample> <simpara> @@ -851,16 +870,17 @@ </simpara> <informalexample> <programlisting role="php"> +<![CDATA[ $great = 'fantastic'; echo "This is { $great}"; // won't work, outputs: This is { fantastic} echo "This is {$great}"; // works, outputs: This is fantastic -echo "This square is {$square->width}00 centimeters broad."; +echo "This square is {$square->width}00 centimeters broad."; echo "This works: {$arr[4][3]}"; echo "This is wrong: {$arr[foo][3]}"; // for the same reason // as <link linkend="language.types.array.foo-bar">$foo[bar]</link > is wrong outside a string. echo "You should do it this way: {$arr['foo'][3]}"; -echo "You can even write {$obj->values[3]->name}"; +echo "You can even write {$obj->values[3]->name}"; echo "This is the value of the var named $name: {${$name}}"; <!-- <xxx> maybe it's better to leave this out?? // this works, but i disencourage its use, since this is NOT @@ -868,6 +888,7 @@ $beer = 'Heineken'; echo "I'd like to have another {${ strrev('reeb') }}, hips"; </xxx> --> +]]> </programlisting> </informalexample> </sect4> @@ -890,10 +911,11 @@ <example> <title>Some string examples</title> <programlisting role="php"> +<![CDATA[ <!-- TODO: either move these examples to a example section, as with arrays, or distribute them under the applicable sections. --> -<?php +<?php /* Assigning a string. */ $str = "This is a string"; @@ -903,13 +925,13 @@ /* Another way to append, includes an escaped newline. */ $str .= " and a newline at the end.\n"; -/* This string will end up being '<p>Number: 9</p>' */ +/* This string will end up being '<p>Number: 9</p>' */ $num = 9; -$str = "<p>Number: $num</p>"; +$str = "<p>Number: $num</p>"; -/* This one will be '<p>Number: $num</p>' */ +/* This one will be '<p>Number: $num</p>' */ $num = 9; -$str = '<p>Number: $num</p>'; +$str = '<p>Number: $num</p>'; /* Get the first character of a string */ $str = 'This is a test.'; @@ -918,7 +940,8 @@ /* Get the last character of a string. */ $str = 'This is still a test.'; $last = $str{strlen($str)-1}; -?> +?> +]]> </programlisting> </example> </para> @@ -982,6 +1005,7 @@ </simpara> <informalexample> <programlisting role="php"> +<![CDATA[ $foo = 1 + "10.5"; // $foo is float (11.5) $foo = 1 + "-1.3e3"; // $foo is float (-1299) $foo = 1 + "bob-1.3e3"; // $foo is integer (1) @@ -990,6 +1014,7 @@ $foo = 1 + "10 Little Piggies"; // $foo is integer (11) $foo = "10.0 pigs " + 1; // $foo is integer (11) $foo = "10.0 pigs " + 1.0; // $foo is float (11) +]]> </programlisting> </informalexample> <simpara> @@ -1002,7 +1027,9 @@ to see for yourself what's going on: <informalexample> <programlisting role="php"> -echo "\$foo==$foo; type is " . gettype ($foo) . "<br>\n"; +<![CDATA[ +echo "\$foo==$foo; type is " . gettype ($foo) . "<br>\n"; +]]> </programlisting> </informalexample> </para> @@ -1156,9 +1183,11 @@ You might have seen the following syntax in old scripts: <informalexample> <programlisting role="php"> +<![CDATA[ $foo[bar] = 'enemy'; echo $foo[bar]; // etc +]]> </programlisting> </informalexample> This is wrong, but it works. Then, why is it wrong? The reason is @@ -1168,7 +1197,9 @@ That means that you can write things like this: <informalexample> <programlisting role="php"> +<![CDATA[ echo $arr[ foo(true) ]; +]]> </programlisting> </informalexample> This is an example of using a function return value @@ -1178,9 +1209,11 @@ <informalexample> <programlisting role="php"> +<![CDATA[ $error_descriptions[E_ERROR] = "A fatal error has occured"; $error_descriptions[E_WARNING] = "PHP issued a warning"; $error_descriptions[E_NOTICE] = "This is just an informal notice"; +]]> </programlisting> </informalexample> Note that <literal>E_ERROR</literal> is also a valid identifier, @@ -1188,9 +1221,11 @@ example is in fact the same as writing: <informalexample> <programlisting role="php"> +<![CDATA[ $error_descriptions[1] = "A fatal error has occured"; $error_descriptions[2] = "PHP issued a warning"; $error_descriptions[8] = "This is just an informal notice"; +]]> </programlisting> </informalexample> because <literal>E_ERROR</literal> equals <literal>1</literal>, etc. @@ -1252,6 +1287,7 @@ <para> <informalexample> <programlisting role="php"> +<![CDATA[ // this $a = array( 'color' => 'red' , 'taste' => 'sweet' @@ -1272,6 +1308,7 @@ $b[] = 'c'; // will result in the array array( 0 => 'a' , 1 => 'b' , 2 => 'c' ), // or simply array('a', 'b', 'c') +]]> </programlisting> </informalexample> </para> @@ -1279,11 +1316,12 @@ <example> <title>Using array()</title> <programlisting role="php"> +<![CDATA[ // Array as (property-)map -$map = array( 'version' => 4 - , 'OS' => 'Linux' - , 'lang' => 'english' - , 'short_tags' => true +$map = array( 'version' => 4 + , 'OS' => 'Linux' + , 'lang' => 'english' + , 'short_tags' => true ); // strictly numerical keys @@ -1293,16 +1331,16 @@ , 156 , -10 ); -// this is the same as array( 0 => 7, 1 => 8, ...) +// this is the same as array( 0 => 7, 1 => 8, ...) $switching = array( 10 // key = 0 - , 5 => 6 - , 3 => 7 - , 'a' => 4 + , 5 => 6 + , 3 => 7 + , 'a' => 4 , 11 // key = 6 (maximum of integer-indices was 5) - , '8' => 2 // key = 8 (integer!) - , '02' => 77 // key = '02' - , 0 => 12 // the value 10 will be overwritten by 12 + , '8' => 2 // key = 8 (integer!) + , '02' => 77 // key = '02' + , 0 => 12 // the value 10 will be overwritten by 12 ); <!-- TODO example of @@ -1314,13 +1352,15 @@ --> // empty array -$empty = array(); +$empty = array(); +]]> </programlisting> </example> <example id="language.types.array.examples.loop"> <title>Collection</title> <programlisting role="php"> +<![CDATA[ $colors = array('red','blue','green','yellow'); foreach ( $colors as $color ) { @@ -1333,6 +1373,7 @@ Do you like green? Do you like yellow? */ +]]> </programlisting> </example> Index: phpdoc/en/language/variables.xml diff -u phpdoc/en/language/variables.xml:1.23 phpdoc/en/language/variables.xml:1.24 --- phpdoc/en/language/variables.xml:1.23 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/language/variables.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.23 $ --> +<!-- $Revision: 1.24 $ --> <chapter id="language.variables"> <title>Variables</title> @@ -29,6 +29,7 @@ <para> <informalexample> <programlisting role="php"> +<![CDATA[ $var = "Bob"; $Var = "Joe"; echo "$var, $Var"; // outputs "Bob, Joe" @@ -36,6 +37,7 @@ $4site = 'not yet'; // invalid; starts with a number $_4site = 'not yet'; // valid; starts with an underscore $täyte = 'mansikka'; // valid; 'ä' is ASCII 228. +]]> </programlisting> </informalexample> </para> @@ -68,13 +70,14 @@ <informalexample> <programlisting role="php"> -<?php +<![CDATA[ +<?php $foo = 'Bob'; // Assign the value 'Bob' to $foo -$bar = &$foo; // Reference $foo via $bar. +$bar = &$foo; // Reference $foo via $bar. $bar = "My name is $bar"; // Alter $bar... echo $foo; // $foo is altered too. echo $bar; -?> +?> </programlisting> </informalexample> </para> @@ -84,10 +87,10 @@ assigned by reference. <informalexample> <programlisting role="php"> -<?php +<?php $foo = 25; -$bar = &$foo; // This is a valid assignment. -$bar = &(24 * 7); // Invalid; references an unnamed expression. +$bar = &$foo; // This is a valid assignment. +$bar = &(24 * 7); // Invalid; references an unnamed expression. function test() { @@ -95,7 +98,8 @@ } $bar = &test(); // Invalid. -?> +?> +]]> </programlisting> </informalexample> </para> @@ -584,8 +588,10 @@ </simpara> <informalexample> <programlisting role="php"> +<![CDATA[ $a = 1; include "b.inc"; +]]> </programlisting> </informalexample> <simpara> @@ -598,6 +604,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ $a = 1; /* global scope */ function Test() @@ -606,6 +613,7 @@ } Test(); +]]> </programlisting> </informalexample> @@ -624,6 +632,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ $a = 1; $b = 2; @@ -636,6 +645,7 @@ Sum(); echo $b; +]]> </programlisting> </informalexample> @@ -655,6 +665,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ $a = 1; $b = 2; @@ -665,6 +676,7 @@ Sum(); echo $b; +]]> </programlisting> </informalexample> @@ -684,12 +696,14 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function Test () { $a = 0; echo $a; $a++; } +]]> </programlisting> </informalexample> @@ -705,12 +719,14 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function Test() { static $a = 0; echo $a; $a++; } +]]> </programlisting> </informalexample> @@ -731,17 +747,19 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function Test() { static $count = 0; $count++; echo $count; - if ($count < 10) { + if ($count < 10) { Test (); } $count--; } +]]> </programlisting> </informalexample> @@ -758,7 +776,9 @@ <informalexample> <programlisting role="php"> +<![CDATA[ $a = "hello"; +]]> </programlisting> </informalexample> @@ -771,7 +791,9 @@ <informalexample> <programlisting role="php"> +<![CDATA[ $$a = "world"; +]]> </programlisting> </informalexample> @@ -784,7 +806,9 @@ <informalexample> <programlisting role="php"> +<![CDATA[ echo "$a ${$a}"; +]]> </programlisting> </informalexample> @@ -794,7 +818,9 @@ <informalexample> <programlisting role="php"> +<![CDATA[ echo "$a $hello"; +]]> </programlisting> </informalexample> @@ -843,10 +869,12 @@ <example> <title>Simple form variable</title> <programlisting role="php"> -<form action="foo.php" method="post"> - Name: <input type="text" name="username"><br> - <input type="submit"> -</form> +<![CDATA[ +<form action="foo.php" method="post"> + Name: <input type="text" name="username"><br> + <input type="submit"> +</form> +]]> </programlisting> </example> </para> @@ -882,17 +910,19 @@ <example> <title>More complex form variables</title> <programlisting role="php"> -<form action="array.php" 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"> -</form> +<![CDATA[ +<form action="array.php" 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"> +</form> +]]> </programlisting> </example> </para> @@ -911,7 +941,9 @@ <informalexample> <programlisting role="php"> -<input type="image" src="image.gif" name="sub"> +<![CDATA[ +<input type="image" src="image.gif" name="sub"> +]]> </programlisting> </informalexample> @@ -951,7 +983,9 @@ <informalexample> <programlisting role="php"> +<![CDATA[ setcookie("MyCookie[]", "Testing", time()+3600); +]]> </programlisting> </informalexample> @@ -965,9 +999,11 @@ <example> <title>SetCookie Example</title> <programlisting role="php"> +<![CDATA[ $Count++; setcookie("Count", $Count, time()+3600); setcookie("Cart[$Count]", $item, time()+3600); +]]> </programlisting> </example> @@ -982,7 +1018,9 @@ <informalexample> <programlisting role="php"> +<![CDATA[ echo $HOME; /* Shows the HOME environment variable, if set. */ +]]> </programlisting> </informalexample> </para> @@ -1007,7 +1045,9 @@ dot (period, full stop) is not a valid character in a PHP variable name. For the reason, look at it: <programlisting role="php"> +<![CDATA[ $varname.ext; /* invalid variable name */ +]]> </programlisting> Now, what the parser sees is a variable named <varname>$varname</varname>, followed by the string concatenation Index: phpdoc/en/pear/benchmark_timer.xml diff -u phpdoc/en/pear/benchmark_timer.xml:1.8 phpdoc/en/pear/benchmark_timer.xml:1.9 --- phpdoc/en/pear/benchmark_timer.xml:1.8 Sun Nov 11 20:48:41 2001 +++ phpdoc/en/pear/benchmark_timer.xml Fri Nov 23 16:51:24 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.8 $ --> +<!-- $Revision: 1.9 $ --> <refentry id="class.benchmark-timer"> <refnamediv> <refname>Benchmark_Timer</refname> @@ -17,15 +17,17 @@ <refsect1> <example id="example.pear.benchmark.timer"> <programlisting role="php"> +<![CDATA[ require_once 'Benchmark/Timer.php'; $timer = new Benchmark_Timer; -$timer->setMarker('start of for() loop'); -for ($i = 0; $i < 1000; $i++) { /* ... */ } -$timer->setMarker('end of for() loop'); +$timer->setMarker('start of for() loop'); +for ($i = 0; $i < 1000; $i++) { /* ... */ } +$timer->setMarker('end of for() loop'); echo 'The for() loop took ' . -$timer->timeElapsed('start of for() loop', 'end of for() loop'); +$timer->timeElapsed('start of for() loop', 'end of for() loop'); +]]> </programlisting> </example> </refsect1> Index: phpdoc/en/pear/pear.xml diff -u phpdoc/en/pear/pear.xml:1.11 phpdoc/en/pear/pear.xml:1.12 --- phpdoc/en/pear/pear.xml:1.11 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/pear/pear.xml Fri Nov 23 16:51:24 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.11 $ --> +<!-- $Revision: 1.12 $ --> <reference id="pear.reference"> <title>PEAR Reference Manual</title> @@ -61,8 +61,10 @@ instantiate your class with the "=& new" operator like this: <programlisting role="php"> -$obj =& new MyClass(); -</programlisting> +<![CDATA[ +$obj =& new MyClass(); +]]> + </programlisting> </para> <simpara> If you only use "= new", the object registered in PEAR's @@ -115,6 +117,7 @@ <example id="example.pear.destructors"> <title>PEAR: emulated destructors</title> <programlisting role="php"> +<![CDATA[ require_once "PEAR.php"; class FileContainer extends PEAR @@ -157,13 +160,13 @@ } } -$fileobj =& new FileContainer("testfile"); +$fileobj =& new FileContainer("testfile"); $fileobj->append("this ends up at the end of the file\n"); // When the request is done and PHP shuts down, $fileobj's // "destructor" is called and updates the file on disk. - -</programlisting> +]]> + </programlisting> </example> <note> <simpara> @@ -188,6 +191,7 @@ <example id="example.pear.error1"> <title>PEAR error example (1)</title> <programlisting role="php"> +<![CDATA[ function mysockopen($host = "localhost", $port = 8090) { $fp = fsockopen($host, $port, $errno, $errstr); @@ -199,9 +203,10 @@ $sock = mysockopen(); if (PEAR::isError($sock)) { - print "mysockopen error: ".$sock->getMessage()."<BR>\n" + print "mysockopen error: ".$sock->getMessage()."<BR>\n" } -</programlisting> +]]> + </programlisting> </example> </para> <simpara> @@ -223,6 +228,7 @@ <example id="example.pear.error2"> <title>PEAR error example (2)</title> <programlisting role="php"> +<![CDATA[ class TCP_Socket extends PEAR { var $sock; @@ -244,8 +250,9 @@ $sock = new TCP_Socket; $sock->setErrorHandling(PEAR_ERROR_DIE); $sock->connect("localhost", 8090); -print "still alive<BR>\n"; -</programlisting> +print "still alive<BR>\n"; +]]> + </programlisting> </example> </para> <simpara> @@ -284,8 +291,10 @@ method like this: <informalexample> <programlisting role="php"> +<![CDATA[ PEAR::setErrorHandling(PEAR_ERROR_DIE); -</programlisting> +]]> + </programlisting> </informalexample> </para> </listitem> @@ -306,8 +315,10 @@ method like this: <informalexample> <programlisting role="php"> +<![CDATA[ PEAR::setErrorHandling(PEAR_ERROR_TRIGGER, E_USER_ERROR); -</programlisting> +]]> + </programlisting> </informalexample> </para> </listitem> @@ -332,8 +343,10 @@ method like this: <informalexample> <programlisting role="php"> +<![CDATA[ PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, "my_error_handler"); -</programlisting> +]]> + </programlisting> </informalexample> </para> <para> @@ -341,13 +354,15 @@ without specifying the callback function again: <informalexample> <programlisting role="php"> +<![CDATA[ PEAR::setErrorMode(PEAR_ERROR_CALLBACK, "my_function_handler"); do_some_stuff(); PEAR::setErrorMode(PEAR_ERROR_DIE); do_some_critical_stuff(); PEAR::setErrorMode(PEAR_ERROR_CALLBACK); // now we're back to using my_function_handler again -</programlisting> +]]> + </programlisting> </informalexample> </para> </listitem> @@ -371,6 +386,7 @@ <example> <title>PEAR Class Constructor Example</title> <programlisting role="php"> +<![CDATA[ class MyClass extends PEAR { var $foo, $bar; @@ -381,7 +397,8 @@ $this->bar = $bar; } } -</programlisting> +]]> + </programlisting> </example> </para> </refsect2> Index: phpdoc/en/pear/standards.xml diff -u phpdoc/en/pear/standards.xml:1.14 phpdoc/en/pear/standards.xml:1.15 --- phpdoc/en/pear/standards.xml:1.14 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/pear/standards.xml Fri Nov 23 16:51:24 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.14 $ --> +<!-- $Revision: 1.15 $ --> <chapter id="pear.standards"> <title>PEAR Coding Standards</title> <note> @@ -17,6 +17,7 @@ hook that will set up Emacs according to these guidelines (you will need to ensure that it is called when you are editing PHP files): <programlisting role="elisp"> +<![CDATA[ (defun php-mode-hook () (setq tab-width 4 c-basic-offset 4 @@ -25,14 +26,17 @@ (not (and (string-match "/\\(PEAR\\|pear\\)/" (buffer-file-name)) (string-match "\.php$" (buffer-file-name)))))) -</programlisting> +]]> + </programlisting> </para> <para>Here are vim rules for the same thing: <programlisting role="vim"> +<![CDATA[ set expandtab set shiftwidth=4 set tabstop=4 -</programlisting> +]]> + </programlisting> </para> </sect1> @@ -42,14 +46,16 @@ These include if, for, while, switch, etc. Here is an example if statement, since it is the most complicated of them: <programlisting role="php"> +<![CDATA[ if ((condition1) || (condition2)) { action1; -} elseif ((condition3) && (condition4)) { +} elseif ((condition3) && (condition4)) { action2; } else { defaultaction; } -</programlisting> +]]> + </programlisting> </para> <simpara> Control statements should have one space between the control keyword @@ -64,6 +70,7 @@ <para> For switch statements: <programlisting role="php"> +<![CDATA[ switch (condition) { case 1: action1; @@ -78,7 +85,8 @@ break; } -</programlisting> +]]> + </programlisting> </para> </sect1> @@ -91,8 +99,10 @@ parameter, the closing parenthesis, and the semicolon. Here's an example: <programlisting role="php"> +<![CDATA[ $var = foo($bar, $baz, $quux); -</programlisting> +]]> + </programlisting> </para> <para> As displayed above, there should be one space on either side of an @@ -100,9 +110,11 @@ variable. In the case of a block of related assignments, more space may be inserted to promote readability: <programlisting role="php"> +<![CDATA[ $short = foo($bar); $long_variable = foo($baz); -</programlisting> +]]> + </programlisting> </para> </sect1> @@ -111,6 +123,7 @@ <para> Function declaractions follow the "one true brace" convention: <programlisting role="php"> +<![CDATA[ function fooFunction($arg1, $arg2 = '') { if (condition) { @@ -118,6 +131,7 @@ } return $val; } +]]> </programlisting> </para> <para> @@ -125,10 +139,11 @@ Always attempt to return a meaningful value from a function if one is appropriate. Here is a slightly longer example: <programlisting role="php"> -function connect(&$dsn, $persistent = false) +<![CDATA[ +function connect(&$dsn, $persistent = false) { if (is_array($dsn)) { - $dsninfo = &$dsn; + $dsninfo = &$dsn; } else { $dsninfo = DB::parseDSN($dsn); } @@ -139,6 +154,7 @@ return true; } +]]> </programlisting> </para> </sect1> @@ -200,6 +216,7 @@ All source code files in the core PEAR distribution should contain the following comment block as the header: <programlisting role="php"> +<![CDATA[ /* vim: set expandtab tabstop=4 shiftwidth=4: */ // +----------------------------------------------------------------------+ // | PHP version 4.0 | @@ -214,12 +231,13 @@ // | obtain it through the world-wide-web, please send a note to | // | license@php.net so we can mail you a copy immediately. | // +----------------------------------------------------------------------+ -// | Authors: Original Author <author@example.com> | -// | Your Name <you@example.com> | +// | Authors: Original Author <author@example.com> | +// | Your Name <you@example.com> | // +----------------------------------------------------------------------+ // -// $Id$ -</programlisting> +// $Id: standards.xml,v 1.15 2001/11/23 21:51:24 hholzgra Exp $ +]]> + </programlisting> </para> <para> There's no hard rule to determine when a new code contributer
Index: phpdoc/en/appendices/migration.xml diff -u phpdoc/en/appendices/migration.xml:1.13 phpdoc/en/appendices/migration.xml:1.14 --- phpdoc/en/appendices/migration.xml:1.13 Sat Nov 10 16:49:25 2001 +++ phpdoc/en/appendices/migration.xml Fri Nov 23 16:51:22 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.13 $ --> +<!-- $Revision: 1.14 $ --> <appendix id="migration"> <title>Migrating from PHP/FI 2.0 to PHP 3.0</title> @@ -46,14 +46,18 @@ <example> <title>Migration: old start/end tags</title> <programlisting role="php"> -<? echo "This is PHP/FI 2.0 code.\n"; > +<![CDATA[ +<? echo "This is PHP/FI 2.0 code.\n"; ?> +]]> </programlisting> </example> As of version 2.0, PHP/FI also supports this variation: <example> <title>Migration: first new start/end tags</title> <programlisting role="php"> -<? echo "This is PHP 3.0 code!\n"; ?> +<![CDATA[ +<? echo "This is PHP 3.0 code!\n"; ?> +]]| </programlisting> </example> @@ -67,7 +71,9 @@ <example> <title>Migration: second new start/end tags</title> <programlisting role="php"> -<?php echo "This is PHP 3.0 code!\n"; ?> +<![CDATA[ +<?php echo "This is PHP 3.0 code!\n"; ?> +]]> </programlisting> </example> @@ -79,11 +85,13 @@ <example> <title>Migration: third new start/end tags</title> <programlisting role="php"> -<script language="php"> +<![CDATA[ +<script language="php"> echo "This is PHP 3.0 code!\n"; -</script> +</script> +]]> </programlisting> </example> </para> @@ -100,6 +108,7 @@ <example> <title>Migration: old if..endif syntax</title> <programlisting role="php"> +<![CDATA[ if ($foo); echo "yep\n"; elseif ($bar); @@ -107,11 +116,13 @@ else; echo "nope\n"; endif; +]]> </programlisting> </example> <example> <title>Migration: new if..endif syntax</title> <programlisting role="php"> +<![CDATA[ if ($foo): echo "yep\n"; elseif ($bar): @@ -119,6 +130,7 @@ else: echo "nope\n"; endif; +]]> </programlisting> </example> @@ -135,17 +147,21 @@ <example> <title>Migration: old while..endwhile syntax</title> <programlisting role="php"> +<![CDATA[ while ($more_to_come); ... endwhile; +]]> </programlisting> </example> <example> <title>Migration: new while..endwhile syntax</title> <programlisting role="php"> +<![CDATA[ while ($more_to_come): ... endwhile; +]]> </programlisting> </example> </para> @@ -169,6 +185,7 @@ Consider this example: <informalexample> <programlisting role="php"> +<![CDATA[ $a[0]=5; $a[1]=7; @@ -177,6 +194,7 @@ echo "$keyn"; next($a); } +]]> </programlisting> </informalexample> @@ -196,7 +214,9 @@ The fix for this is simple. Replace the while statement with: <informalexample> <programlisting role="php"> +<![CDATA[ while ((string)$key != "") { +]]> </programlisting> </informalexample> </para> @@ -244,16 +264,20 @@ <example> <title>Migration from 2.0: return values, old code</title> <programlisting role="php"> +<![CDATA[ $fp = fopen($file, "r"); if ($fp == -1); - echo("Could not open $file for reading<br>\n"); + echo("Could not open $file for reading<br>\n"); endif; +]]| </programlisting> </example> <example> <title>Migration from 2.0: return values, new code</title> <programlisting role="php"> -$fp = @fopen($file, "r") or print("Could not open $file for reading<br>\n"); +<![CDATA[ +$fp = @fopen($file, "r") or print("Could not open $file for reading<br>\n"); +]]> </programlisting> </example> </para> @@ -312,26 +336,34 @@ <example> <title>Migration from 2.0: concatenation for strings</title> <programlisting role="php"> +<![CDATA[ echo "1" + "1"; +]]> </programlisting> <para> In PHP 2.0 this would echo 11, in PHP 3.0 it would echo 2. Instead use: <programlisting role="php"> +<![CDATA[ echo "1"."1"; +]]> </programlisting> <programlisting role="php"> +<![CDATA[ $a = 1; $b = 1; echo $a + $b; +]]> </programlisting> </para> <para> This would echo 2 in both PHP 2.0 and 3.0. <programlisting role="php"> +<![CDATA[ $a = 1; $b = 1; echo $a.$b; +]]> </programlisting> This will echo 11 in PHP 3.0. </para> Index: phpdoc/en/appendices/migration4.xml diff -u phpdoc/en/appendices/migration4.xml:1.14 phpdoc/en/appendices/migration4.xml:1.15 --- phpdoc/en/appendices/migration4.xml:1.14 Sat Nov 10 16:49:26 2001 +++ phpdoc/en/appendices/migration4.xml Fri Nov 23 16:51:22 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.14 $ --> +<!-- $Revision: 1.15 $ --> <appendix id="migration4"> <title>Migrating from PHP 3.0 to PHP 4.0</title> @@ -38,13 +38,17 @@ (--with-apxs) and the necessary link extensions (--enable-versioning). Otherwise, all standard installations instructions apply. For example: - <informalexample><programlisting> + <informalexample> + <programlisting role="configure"> +<![CDATA[ $ ./configure \ --with-apxs=/apache/bin/apxs \ --enable-versioning \ --with-mysql \ --enable-track-vars - </programlisting></informalexample> +]]> + </programlisting> + </informalexample> </para> </section> @@ -58,22 +62,30 @@ For the Apache configuration file, there are slightly more changes. The MIME types recognized by the PHP module have changed. - <informalexample><programlisting> -application/x-httpd-php3 --> application/x-httpd-php -application/x-httpd-php3-source --> application/x-httpd-php-source - </programlisting></informalexample> + <informalexample> + <programlisting role="apache"> +<![CDATA[ +application/x-httpd-php3 --> application/x-httpd-php +application/x-httpd-php3-source --> application/x-httpd-php-source +]]> + </programlisting> + </informalexample> </para> <para> You can make your configuration files work with both versions of PHP (depending on which one is currently compiled into the server), using the following syntax: - <informalexample><programlisting> + <informalexample> + <programlisting> +<![CDATA[ AddType application/x-httpd-php3 .php3 AddType application/x-httpd-php3-source .php3s AddType application/x-httpd-php .php AddType application/x-httpd-php-source .phps - </programlisting></informalexample> +]]> + </programlisting> + </informalexample> </para> <simpara> In addition, the PHP directive names for Apache have changed. @@ -81,12 +93,16 @@ <para> Starting with PHP 4.0, there are only four Apache directives that relate to PHP: - <informalexample><programlisting> + <informalexample> + <programlisting role="apache"> +<![CDATA[ php_value [PHP directive name] [value] php_flag [PHP directive name] [On|Off] php_admin_value [PHP directive name] [value] php_admin_flag [PHP directive name] [On|Off] - </programlisting></informalexample> +]]> + </programlisting> + </informalexample> </para> <simpara> There are two differences between the Admin values and the non admin values: @@ -100,18 +116,26 @@ </simpara> <para> To convert your Apache configuration files, run the apconf-conv.sh script (available in the scripts/apache/ directory). For example: - <informalexample><programlisting> + <informalexample> + <programlisting role="shell"> +<![CDATA[ ~/php4/scripts/apache:# ./apconf-conv.sh /usr/local/apache/conf/httpd.conf - </programlisting></informalexample> +]]> + </programlisting> + </informalexample> </para> <simpara> Your original configuration file will be saved in httpd.conf.orig. </simpara> <para> To convert your .htaccess files, run the aphtaccess-conv.sh script (available in the scripts/apache/ directory as well): - <informalexample><programlisting> + <informalexample> + <programlisting role="shell"> +<![CDATA[ ~/php4/scripts/apache:# find / -name .htaccess -exec ./aphtaccess-conv.sh {} \; - </programlisting></informalexample> +]]> + </programlisting> + </informalexample> </para> <simpara> Likewise, your old .htaccess files will be saved with an .orig prefix. Index: phpdoc/en/appendices/phpdevel.xml diff -u phpdoc/en/appendices/phpdevel.xml:1.13 phpdoc/en/appendices/phpdevel.xml:1.14 --- phpdoc/en/appendices/phpdevel.xml:1.13 Sat Nov 10 16:49:26 2001 +++ phpdoc/en/appendices/phpdevel.xml Fri Nov 23 16:51:22 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.13 $ --> +<!-- $Revision: 1.14 $ --> <appendix id="phpdevel"> <title>PHP development</title> @@ -12,9 +12,11 @@ <para> All functions look like this: <programlisting role="c"> +<![CDATA[ void php3_foo(INTERNAL_FUNCTION_PARAMETERS) { } +]]> </programlisting> Even if your function doesn't take any arguments, this is how it is called.</para></sect2> @@ -31,10 +33,12 @@ <example> <title>Fetching function arguments</title> <programlisting role="c"> +<![CDATA[ pval *arg1, *arg2; -if (ARG_COUNT(ht) != 2 || getParameters(ht,2,&arg1,&arg2)==FAILURE) { +if (ARG_COUNT(ht) != 2 || getParameters(ht,2,&arg1,&arg2)==FAILURE) { WRONG_PARAM_COUNT; } +]]> </programlisting> </example> @@ -68,13 +72,15 @@ <example> <title>Variable function arguments</title> <programlisting role="c"> +<![CDATA[ pval *arg1, *arg2, *arg3; int arg_count = ARG_COUNT(ht); -if (arg_count < 2 || arg_count > 3 || - getParameters(ht,arg_count,&arg1,&arg2,&arg3)==FAILURE) { +if (arg_count < 2 || arg_count > 3 || + getParameters(ht,arg_count,&arg1,&arg2,&arg3)==FAILURE) { WRONG_PARAM_COUNT; } +]]> </programlisting> </example></para></sect2> @@ -135,11 +141,13 @@ functions: <programlisting role="c"> +<![CDATA[ convert_to_long(arg1); 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 */ +]]> </programlisting></para> <simpara> @@ -225,16 +233,20 @@ <example> <title>Checking whether $foo exists in a symbol table</title> <programlisting role="c"> +<![CDATA[ if (hash_exists(active_symbol_table,"foo",sizeof("foo"))) { exists... } else { doesn't exist } +]]> </programlisting> </example> <example> <title>Finding a variable's size in a symbol table</title> <programlisting role="c"> -hash_find(active_symbol_table,"foo",sizeof("foo"),&pvalue); +<![CDATA[ +hash_find(active_symbol_table,"foo",sizeof("foo"),&pvalue); check(pvalue.type); +]]> </programlisting> </example> @@ -257,10 +269,12 @@ <example> <title>Initializing a new array</title> <programlisting role="c"> +<![CDATA[ pval arr; -if (array_init(&arr) == FAILURE) { failed... }; -hash_update(active_symbol_table,"foo",sizeof("foo"),&arr,sizeof(pval),NULL); +if (array_init(&arr) == FAILURE) { failed... }; +hash_update(active_symbol_table,"foo",sizeof("foo"),&arr,sizeof(pval),NULL); +]]> </programlisting> </example> @@ -274,21 +288,23 @@ <example> <title>Adding entries to a new array</title> <programlisting role="c"> +<![CDATA[ pval entry; entry.type = IS_LONG; entry.value.lval = 5; /* defines $foo["bar"] = 5 */ -hash_update(arr.value.ht,"bar",sizeof("bar"),&entry,sizeof(pval),NULL); +hash_update(arr.value.ht,"bar",sizeof("bar"),&entry,sizeof(pval),NULL); /* defines $foo[7] = 5 */ -hash_index_update(arr.value.ht,7,&entry,sizeof(pval),NULL); +hash_index_update(arr.value.ht,7,&entry,sizeof(pval),NULL); /* defines the next free place in $foo[], * $foo[8], to be 5 (works like php2) */ -hash_next_index_insert(arr.value.ht,&entry,sizeof(pval),NULL); +hash_next_index_insert(arr.value.ht,&entry,sizeof(pval),NULL); +]]> </programlisting> </example> @@ -308,16 +324,20 @@ initialize the array just like above by doing:</simpara> <programlisting role="c"> +<![CDATA[ if (array_init(return_value) == FAILURE) { failed...; } +]]> </programlisting> <simpara> ...and then adding values with the helper functions:</simpara> <programlisting role="c"> +<![CDATA[ add_next_index_long(return_value,long_value); add_next_index_double(return_value,double_value); add_next_index_string(return_value,estrdup(string_value)); +]]> </programlisting> <para> @@ -325,10 +345,12 @@ initialization, you'd probably have to look for the array first: <programlisting role="c"> +<![CDATA[ pval *arr; -if (hash_find(active_symbol_table,"foo",sizeof("foo"),(void **)&arr)==FAILURE) { can't find... } -else { use arr->value.ht... } +if (hash_find(active_symbol_table,"foo",sizeof("foo"),(void **)&arr)==FAILURE) { can't find... } +else { use arr->value.ht... } +]]> </programlisting></para> <simpara> @@ -398,8 +420,11 @@ (i.e., you can use regular hash functions on .value.ht). The actual registration of the function can be done using: <programlisting role="c"> +<![CDATA[ add_method( return_value, function_name, function_ptr ); - </programlisting></para></listitem> +]]> + </programlisting> + </para></listitem> </orderedlist></para> <para> @@ -478,41 +503,47 @@ <example> <title>Adding a new resource</title> <programlisting role="c"> +<![CDATA[ RESOURCE *resource; /* ...allocate memory for resource and acquire resource... */ /* add a new resource to the list */ -return_value->value.lval = php3_list_insert((void *) resource, LE_RESOURCE_TYPE); -return_value->type = IS_LONG; +return_value->value.lval = php3_list_insert((void *) resource, LE_RESOURCE_TYPE); +return_value->type = IS_LONG; +]]> </programlisting> </example> <example> <title>Using an existing resource</title> <programlisting role="c"> +<![CDATA[ pval *resource_id; RESOURCE *resource; int type; convert_to_long(resource_id); -resource = php3_list_find(resource_id->value.lval, &type); +resource = php3_list_find(resource_id->value.lval, &type); if (type != LE_RESOURCE_TYPE) { - php3_error(E_WARNING,"resource index %d has the wrong type",resource_id->value.lval); + php3_error(E_WARNING,"resource index %d has the wrong type",resource_id->value.lval); RETURN_FALSE; } /* ...use resource... */ +]]> </programlisting> </example> <example> <title>Deleting an existing resource</title> <programlisting role="c"> +<![CDATA[ pval *resource_id; RESOURCE *resource; int type; convert_to_long(resource_id); -php3_list_delete(resource_id->value.lval); +php3_list_delete(resource_id->value.lval); +]]> </programlisting> </example> Index: phpdoc/en/chapters/config.xml diff -u phpdoc/en/chapters/config.xml:1.30 phpdoc/en/chapters/config.xml:1.31 --- phpdoc/en/chapters/config.xml:1.30 Sun Nov 11 05:20:40 2001 +++ phpdoc/en/chapters/config.xml Fri Nov 23 16:51:22 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.30 $ --> +<!-- $Revision: 1.31 $ --> <chapter id="configuration"> <title>Configuration</title> @@ -16,6 +16,7 @@ <example> <title>php.ini example</title> <programlisting role="ini"> +<![CDATA[ ; any text on a line after an unquoted semicolon (;) is ignored [php] ; section markers (text within square brackets) are also ignored ; Boolean values can be set to either: @@ -29,6 +30,7 @@ ; backslashes are treated the same as any other character include_path = ".;c:\php\lib" +]]> </programlisting> <!-- TODO: add more details about values and expressions --> </example> @@ -102,14 +104,16 @@ <example> <title>Apache configuration example</title> <programlisting role="ini"> -<IfModule mod_php4.c> +<![CDATA[ +<IfModule mod_php4.c> php_value include_path ".:/usr/local/lib/php" php_flag safe_mode on -</IfModule> -<IfModule mod_php3.c> +</IfModule> +<IfModule mod_php3.c> php3_include_path ".:/usr/local/lib/php" php3_safe_mode on -</IfModule> +</IfModule> +]]> </programlisting> </example> </para> @@ -444,14 +448,18 @@ <example> <title>UNIX include_path</title> <programlisting role="php3.ini"> +<![CDATA[ include_path=.:/home/httpd/php-lib -</programlisting> +]]> + </programlisting> </example> <example> <title>Windows include_path</title> <programlisting role="php3.ini"> +<![CDATA[ include_path=".;c:\www\phplib" -</programlisting> +]]> + </programlisting> </example> The default value for this directive is <literal>.</literal> (only the current directory).</para> @@ -1096,9 +1104,12 @@ reference manual): <informalexample> <programlisting role="bs2000"> +<![CDATA[ CNF=B NAM=K -NOTYPE</programlisting> +NOTYPE +]]> + </programlisting> </informalexample> </para> </listitem> Index: phpdoc/en/chapters/install.xml diff -u phpdoc/en/chapters/install.xml:1.94 phpdoc/en/chapters/install.xml:1.95 --- phpdoc/en/chapters/install.xml:1.94 Sun Nov 11 10:06:13 2001 +++ phpdoc/en/chapters/install.xml Fri Nov 23 16:51:22 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.94 $ --> +<!-- $Revision: 1.95 $ --> <chapter id="installation"> <title>Installation</title> @@ -179,7 +179,8 @@ <title> Quick Installation Instructions for PHP 4 (Apache Module Version) </title> - <programlisting> + <programlisting role="shell"> +<![CDATA[ 1. gunzip apache_1.3.x.tar.gz 2. tar xvf apache_1.3.x.tar 3. gunzip php-x.x.x.tar.gz @@ -202,6 +203,7 @@ 18. Use your normal procedure for restarting the Apache server. (You must stop and restart the server, not just cause the server to reload by use a HUP or USR1 signal.) +]]> </programlisting> </example> </sect2> @@ -248,7 +250,8 @@ <title> Installation Instructions for HP-UX 10 </title> - <programlisting> + <screen> +<![CDATA[ From: paul_mckay@clearwater-it.co.uk 04-Jan-2001 09:49 (These tips are for PHP 4.0.4 and Apache v1.3.9) @@ -316,7 +319,8 @@ Hope this helps somebody, Paul Mckay. - </programlisting> +]]> + </screen> </example> </sect1> @@ -417,11 +421,13 @@ <example id="install.openbsd.ports.example"> <title>OpenBSD Ports Install Example</title> <programlisting> +<![CDATA[ $ cd /usr/ports/www/php4 $ make show VARNAME=FLAVORS (choose which flavors you want from the list) $ env FLAVOR="imap gettext ldap mysql gd" make install $ /usr/local/sbin/php4-enable +]]> </programlisting> </example> </sect2> @@ -467,7 +473,8 @@ </simpara> <example id="install.macosx.compile.example"> <title>Mac OS X server install</title> - <programlisting> + <screen> +<![CDATA[ 1. Get the latest distributions of Apache and PHP 2. Untar them, and run the configure program on Apache like so. ./configure --exec-prefix=/usr \ @@ -533,7 +540,8 @@ or (if your don't have a local directory) cp php.ini-dist /usr/bin/php.ini - </programlisting> +]]> + </screen> </example> <simpara> Other examples for @@ -583,9 +591,11 @@ Now type "<literal>sudo open -a TextEdit /etc/httpd/httpd.conf</literal>" TextEdit will open with the web server configuration file. Locate these two lines towards the end of the file: (Use the Find command) - <programlisting> - * #AddType application/x-httpd-php .php - * #AddType application/x-httpd-php-source .phps + <programlisting role="apache"> +<![CDATA[ + #AddType application/x-httpd-php .php + #AddType application/x-httpd-php-source .phps +]]> </programlisting> Remove the two hash marks (<literal>#</literal>), then save the file and quit TextEdit. </para> @@ -3271,7 +3281,7 @@ <listitem> <para> Extract the distribution file to a directory of your choice. - "c:\php\" is a good start. + <filename>c:\php\</filename> is a good start. </para> </listitem> <listitem> @@ -3957,7 +3967,8 @@ <title> Installation Instructions (Apache Module Version) </title> - <programlisting> + <screen> +<![CDATA[ 1. gunzip apache_1.3.x.tar.gz 2. tar xvf apache_1.3.x.tar 3. gunzip php-x.x.x.tar.gz @@ -3997,7 +4008,8 @@ 18. Use your normal procedure for starting the Apache server. (You must stop and restart the server, not just cause the server to reload by use a HUP or USR1 signal.) - </programlisting> +]]> + </screen> </example> <para> @@ -4007,7 +4019,8 @@ installations. You should replace <literal>/path/to/</literal> with the path to these applications on your systems. <informalexample> - <programlisting> + <screen> +<![CDATA[ 1. Several Linux and SysV variants: /etc/rc.d/init.d/httpd restart @@ -4023,7 +4036,8 @@ stop and start: /path/to/apachectl stop /path/to/apachectl startssl - </programlisting> +]]> + </screen> </informalexample> The locations of the apachectl and http(s)dctl binaries often vary. If your system has <literal>locate</literal> or @@ -4034,8 +4048,10 @@ <para> Different examples of compiling PHP for apache are as follows: <informalexample> - <programlisting> + <programlisting role="shell"> +<![CDATA[ ./configure --with-apxs --with-pgsql +]]> </programlisting> </informalexample> </para> @@ -4049,7 +4065,9 @@ <para> <informalexample> <programlisting> +<![CDATA[ ./configure --with-apxs --with-pgsql=shared +]]> </programlisting> </informalexample> </para> @@ -4064,7 +4082,9 @@ <para> <informalexample> <programlisting> +<![CDATA[ ./configure --with-apache=/path/to/apache_source --with-pgsql +]]> </programlisting> </informalexample> </para> @@ -4084,7 +4104,9 @@ <para> <informalexample> <programlisting> +<![CDATA[ ./configure --with-apache=/path/to/apache_source --with-pgsql=shared +]]> </programlisting> </informalexample> </para> @@ -4289,7 +4311,8 @@ </para> <example id="install.caudium.instructions"> <title>Caudium Installation Instructions</title> - <programlisting> + <screen> +<![CDATA[ 1. Make sure you have Caudium installed prior to attempting to install PHP 4. For PHP 4 to work correctly, you will need Pike 7.0.268 or newer. For the sake of this example we assume that @@ -4309,7 +4332,8 @@ <filename>caudium/server/lib/[pike-version]/PHP4.so</filename> is present. 10. Configure the PHP Script Support module if needed. - </programlisting> +]]> + </screen> </example> <para> You can of course compile your Caudium module with support for the @@ -4678,7 +4702,8 @@ <para> <example id="install.netscape-enterprise.solaris"> <title>Installation Example for Netscape Enterprise on Solaris</title> - <programlisting> + <screen> +<![CDATA[ Instructions for Sun Solaris 2.6 with Netscape Enterprise Server 3.6 From: bhager@invacare.com @@ -4710,7 +4735,8 @@ /configure --with-mysql=/usr/local/mysql --with-nsapi=/opt/netscape/suitespot/ --enable-track-vars --enable-libgcc 7. make 8. make install - </programlisting> +]]> + </screen> </example> After performing the base install and reading the appropriate readme file, you may need to performs some additional @@ -4735,7 +4761,8 @@ <title> Configuration Example for Netscape Enterprise </title> - <programlisting> + <screen> +<![CDATA[ Configuration Instructions for Netscape Enterprise Server From: bhager@invacare.com @@ -4750,7 +4777,7 @@ Init fn="load-modules" funcs="php4_init,php4_close,php4_execute,php4_auth_trans" shlib="/php4/nsapiPHP4.dll" Init fn=php4_init errorString="Failed to initialize PHP!" - <object name="default"> + <object name="default"> . . . @@ -4758,13 +4785,13 @@ Service fn="php4_execute" type="magnus-internal/x-httpd-php" . . - </Object> + </Object> - <Object name="x-httpd-php"> + <Object name="x-httpd-php"> ObjectType fn="force-type" type="magnus-internal/x-httpd-php" Service fn=php4_execute - </Object> + </Object> Authentication configuration @@ -4773,20 +4800,21 @@ PASSED TO YOUR PHP SCRIPT. To configure PHP Authentication for the entire server, add the following line: - <Object name="default"> + <Object name="default"> AuthTrans fn=php4_auth_trans . . . . - </Object> + </Object> To use PHP Authentication on a single directory, add the following: - <Object ppath="d:\path\to\authenticated\dir\*"> + <Object ppath="d:\path\to\authenticated\dir\*"> AuthTrans fn=php4_auth_trans - </Object> - </programlisting> + </Object> +]]> + </screen> </example> <para> If you are running Netscape Enterprise 4.x, then you should use the following: @@ -4794,12 +4822,14 @@ <example> <title>Configuration Example for Netscape Enterprise 4.x</title> <programlisting> +<![CDATA[ Place these lines after the mime types init, and everything else is similar to the example configuration above. From: Graeme Hoose (GraemeHoose@BrightStation.com) Init fn="load-modules" shlib="/path/to/server4/bin/libphp4.so" funcs="php4_init,php4_close,php4_execute,php4_auth_trans" Init fn="php4_init" LateInit="yes" +]]> </programlisting> </example> </sect2> @@ -4821,8 +4851,10 @@ Make a file association from the command line. Type the following two lines: <programlisting> +<![CDATA[ assoc .php=PHPScript ftype PHPScript=c:\php\php.exe %1 %* +]]> </programlisting> </para> </listitem> @@ -4868,8 +4900,10 @@ Make a file association from the command line. Type the following two lines: <programlisting> +<![CDATA[ assoc .php=PHPScript ftype PHPScript=c:\php\php.exe %1 %* +]]> </programlisting> </para> </listitem> @@ -4886,8 +4920,10 @@ At the end of the Init section, place these two lines (necessarily after mime type init!): <programlisting> +<![CDATA[ Init fn="load-modules" funcs="php4_init,php4_close,php4_execute,php4_auth_trans" shlib="c:/php/sapi/php4nsapi.dll" Init fn="php4_init" errorString="Failed to initialise PHP!" +]]> </programlisting> </para> </listitem> @@ -4897,7 +4933,9 @@ section, place this line necessarily after all 'ObjectType' and before all 'AddLog' lines: <programlisting> +<![CDATA[ Service fn="php4_execute" type="magnus-internal/x-httpd-php" +]]> </programlisting> </para> </listitem> @@ -4906,10 +4944,12 @@ At the end of the file, create a new object called <literal>x-httpd-php</literal>, by inserting these lines: <programlisting> -<Object name="x-httpd-php"> +<![CDATA[ +<Object name="x-httpd-php"> ObjectType fn="force-type" type="magnus-internal/x-httpd-php" Service fn=php4_execute -</Object> +</Object> +]]> </programlisting> </para> </listitem> Index: phpdoc/en/chapters/security.xml diff -u phpdoc/en/chapters/security.xml:1.35 phpdoc/en/chapters/security.xml:1.36 --- phpdoc/en/chapters/security.xml:1.35 Tue Nov 20 20:48:33 2001 +++ phpdoc/en/chapters/security.xml Fri Nov 23 16:51:22 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.35 $ --> +<!-- $Revision: 1.36 $ --> <chapter id="security"> <title>Security</title> @@ -199,8 +199,10 @@ the following directives: </simpara> <programlisting role="apache-conf"> +<![CDATA[ Action php-script /cgi-bin/php AddHandler php-script .php +]]> </programlisting> <simpara> This option has only been tested with the Apache web server, and @@ -283,7 +285,9 @@ similar to: <informalexample> <programlisting> +<![CDATA[ #!/usr/local/bin/php +]]> </programlisting> </informalexample> as the first line of any file containing PHP tags. You will also @@ -377,14 +381,16 @@ <example> <title>Poor variable checking leads to....</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php // remove a file from the user's home directory $username = $HTTP_POST_VARS['user_submitted_name']; $homedir = "/home/$username"; $file_to_delete = "$userfile"; unlink ($homedir/$userfile); echo "$file_to_delete has been deleted!"; -?> +?> +]]> </programlisting> </example> Since the username is postable from a user form, they can submit @@ -395,7 +401,8 @@ <example> <title>... A filesystem attack</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php // removes a file from anywhere on the hard drive that // the PHP user has access to. If PHP has root access: $username = "../etc/"; @@ -403,7 +410,8 @@ $file_to_delete = "passwd"; unlink ("/home/../etc/passwd"); echo "/home/../etc/passwd has been deleted!"; -?> +?> +]]> </programlisting> </example> There are two important measures you should take to prevent these @@ -424,7 +432,8 @@ <example> <title>More secure file name checking</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php // removes a file from the hard drive that // the PHP user has access to. $username = $HTTP_SERVER_VARS['REMOTE_USER']; // using an authentication mechanisim @@ -440,7 +449,8 @@ fclose($fp); echo "$file_to_delete has been deleted!"; -?> +?> +]]> </programlisting> </example> However, even this is not without it's flaws. If your authentication @@ -450,7 +460,8 @@ <example> <title>More secure file name checking</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php $username = $HTTP_SERVER_VARS['REMOTE_USER']; // using an authentication mechanisim $homedir = "/home/$username"; @@ -460,7 +471,8 @@ if (!ereg('^[^./][^/]*$', $username)) die('bad username'); //die, do not process //etc... -?> +?> +]]> </programlisting> </example> </para> @@ -491,10 +503,12 @@ <example> <title>Attacking Variables with a custom HTML page</title> <programlisting role="php"> -<form method="post" action="attacktarget?username=badfoo&password=badfoo"> -<input type="hidden" name="username" value="badfoo"> -<input type="hidden" name="password" value="badfoo"> -</form> +<![CDATA[ +<form method="post" action="attacktarget?username=badfoo&password=badfoo"> +<input type="hidden" name="username" value="badfoo"> +<input type="hidden" name="password" value="badfoo"> +</form> +]]> </programlisting> </example> </para> @@ -516,11 +530,13 @@ <example> <title>Exploiting common debugging variables</title> <programlisting role="php"> -<form method="post" action="attacktarget?errors=Y&showerrors=1"&debug=1"> -<input type="hidden" name="errors" value="Y"> -<input type="hidden" name="showerrors" value="1"> -<input type="hidden" name="debug" value="1"> -</form> +<![CDATA[ +<form method="post" action="attacktarget?errors=Y&showerrors=1"&debug=1"> +<input type="hidden" name="errors" value="Y"> +<input type="hidden" name="showerrors" value="1"> +<input type="hidden" name="debug" value="1"> +</form> +]]> </programlisting> </example> </para> @@ -573,14 +589,16 @@ <example> <title>Finding dangerous variables with E_ALL</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php if ($username) { // Not initialized or checked before usage $good_login = 1; } if ($good_login == 1) { // If above test fails, not initialized or checked before usage fpassthru ("/highly/sensitive/data/index.html"); } -?> +?> +]]> </programlisting> </example> </para> @@ -605,7 +623,8 @@ <example> <title>Working without register_globals=off</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php if ($username) { // can be forged by a user in get/post/cookies $good_login = 1; } @@ -613,19 +632,22 @@ if ($good_login == 1) { // can be forged by a user in get/post/cookies, fpassthru ("/highly/sensitive/data/index.html"); } -?> +?> +]]> </programlisting> </example> <example> <title>Working with register_globals = off</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php if($HTTP_COOKIE_VARS['username']){ // can only come from a cookie, forged or otherwise $good_login = 1; fpassthru ("/highly/sensitive/data/index.html"); } -?> +?> +]]> </programlisting> </example> By using this wisely, it's even possible to take preventative @@ -638,9 +660,10 @@ <example> <title>Detecting simple variable poisoning</title> <programlisting role="php"> -<?php -if ($HTTP_COOKIE_VARS['username'] && - !$HTTP_POST_VARS['username'] && +<![CDATA[ +<?php +if ($HTTP_COOKIE_VARS['username'] && + !$HTTP_POST_VARS['username'] && !$HTTP_GET_VARS['username'] ) { // Perform other checks to validate the user name... $good_login = 1; @@ -650,7 +673,8 @@ echo "Security violation, admin has been alerted."; exit; } -?> +?> +]]> </programlisting> </example> Of course, simply turning off register_globals does not mean code @@ -671,7 +695,8 @@ <example> <title>Dangerous Variable Usage</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php // remove a file from the user's home directory... or maybe // somebody else's? unlink ($evil_var); @@ -683,7 +708,8 @@ system ($evil_var); exec ($evil_var); -?> +?> +]]> </programlisting> </example> You should always carefully examine your code to make sure that any @@ -749,26 +775,32 @@ then use misleading file extensions: <example> <title>Hiding PHP as another language</title> - <programlisting> + <programlisting role="apache-conf"> +<![CDATA[ # Make PHP code look like other code types AddType application/x-httpd-php .asp .py .pl +]]> </programlisting> </example> Or obscure it completely: <example> <title>Using unknown types for PHP extensions</title> - <programlisting> + <programlisting role="apache-conf"> +<![CDATA[ # Make PHP code look like unknown types AddType application/x-httpd-php .bop .foo .133t +]]> </programlisting> </example> Or hide it as html code, which has a slight performance hit because all html will be parsed through the PHP engine: <example> <title>Using html types for PHP extensions</title> - <programlisting> + <programlisting role="apache-conf"> +<![CDATA[ # Make all PHP code look like html AddType application/x-httpd-php .htm .html +]]> </programlisting> </example> For this to work effectively, you must rename your PHP files with Index: phpdoc/en/features/error-handling.xml diff -u phpdoc/en/features/error-handling.xml:1.21 phpdoc/en/features/error-handling.xml:1.22 --- phpdoc/en/features/error-handling.xml:1.21 Sat Nov 10 16:49:30 2001 +++ phpdoc/en/features/error-handling.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.21 $ --> +<!-- $Revision: 1.22 $ --> <chapter id="features.error-handling"> <title>Error Handling</title> @@ -180,77 +180,78 @@ <example> <title>Using error handling in a script</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php // we will do our own error handling error_reporting(0); // user defined error handling function function userErrorHandler ($errno, $errmsg, $filename, $linenum, $vars) { // timestamp for the error entry - $dt = date("Y-m-d H:i:s (T)"); + $dt = date("Y-m-d H:i:s (T)"); // define an assoc array of error string // in reality the only entries we should // consider are 2,8,256,512 and 1024 $errortype = array ( - 1 => "Error", - 2 => "Warning", - 4 => "Parsing Error", - 8 => "Notice", - 16 => "Core Error", - 32 => "Core Warning", - 64 => "Compile Error", - 128 => "Compile Warning", - 256 => "User Error", - 512 => "User Warning", - 1024=> "User Notice" + 1 => "Error", + 2 => "Warning", + 4 => "Parsing Error", + 8 => "Notice", + 16 => "Core Error", + 32 => "Core Warning", + 64 => "Compile Error", + 128 => "Compile Warning", + 256 => "User Error", + 512 => "User Warning", + 1024=> "User Notice" ); // set of errors for which a var trace will be saved $user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE); - $err = "<errorentry>\n"; - $err .= "\t<datetime>".$dt."</datetime>\n"; - $err .= "\t<errornum>".$errno."</errnumber>\n"; - $err .= "\t<errortype>".$errortype[$errno]."</errortype>\n"; - $err .= "\t<errormsg>".$errmsg."</errormsg>\n"; - $err .= "\t<scriptname>".$filename."</scriptname>\n"; - $err .= "\t<scriptlinenum>".$linenum."</scriptlinenum>\n"; + $err = "<errorentry>\n"; + $err .= "\t<datetime>".$dt."</datetime>\n"; + $err .= "\t<errornum>".$errno."</errnumber>\n"; + $err .= "\t<errortype>".$errortype[$errno]."</errortype>\n"; + $err .= "\t<errormsg>".$errmsg."</errormsg>\n"; + $err .= "\t<scriptname>".$filename."</scriptname>\n"; + $err .= "\t<scriptlinenum>".$linenum."</scriptlinenum>\n"; if (in_array($errno, $user_errors)) - $err .= "\t<vartrace>".wddx_serialize_value($vars,"Variables")."</vartrace>\n"; - $err .= "</errorentry>\n\n"; + $err .= "\t<vartrace>".wddx_serialize_value($vars,"Variables")."</vartrace>\n"; + $err .= "</errorentry>\n\n"; // for testing // echo $err; // save to the error log, and e-mail me if there is a critical user error - error_log($err, 3, "/usr/local/php4/error.log"); + error_log($err, 3, "/usr/local/php4/error.log"); if ($errno == E_USER_ERROR) - mail("phpdev@mydomain.com","Critical User Error",$err); + mail("phpdev@mydomain.com","Critical User Error",$err); } function distance ($vect1, $vect2) { if (!is_array($vect1) || !is_array($vect2)) { - trigger_error("Incorrect parameters, arrays expected", E_USER_ERROR); + trigger_error("Incorrect parameters, arrays expected", E_USER_ERROR); return NULL; } if (count($vect1) != count($vect2)) { - trigger_error("Vectors need to be of the same size", E_USER_ERROR); + trigger_error("Vectors need to be of the same size", E_USER_ERROR); return NULL; } - for ($i=0; $i<count($vect1); $i++) { + for ($i=0; $i<count($vect1); $i++) { $c1 = $vect1[$i]; $c2 = $vect2[$i]; $d = 0.0; if (!is_numeric($c1)) { - trigger_error("Coordinate $i in vector 1 is not a number, using zero", + trigger_error("Coordinate $i in vector 1 is not a number, using zero", E_USER_WARNING); $c1 = 0.0; } if (!is_numeric($c2)) { - trigger_error("Coordinate $i in vector 2 is not a number, using zero", + trigger_error("Coordinate $i in vector 2 is not a number, using zero", E_USER_WARNING); $c2 = 0.0; } @@ -259,26 +260,27 @@ return sqrt($d); } -$old_error_handler = set_error_handler("userErrorHandler"); +$old_error_handler = set_error_handler("userErrorHandler"); // undefined constant, generates a warning $t = I_AM_NOT_DEFINED; -// define some "vectors" -$a = array(2,3,"foo"); +// define some "vectors" +$a = array(2,3,"foo"); $b = array(5.5, 4.3, -1.6); $c = array (1,-3); // generate a user error -$t1 = distance($c,$b)."\n"; +$t1 = distance($c,$b)."\n"; // generate another user error -$t2 = distance($b,"i am not an array")."\n"; +$t2 = distance($b,"i am not an array")."\n"; // generate a warning -$t3 = distance($a,$b)."\n"; +$t3 = distance($a,$b)."\n"; -?> +?> +]]> </programlisting> </example> This is just a simple example showing how to use the Index: phpdoc/en/features/http-auth.xml diff -u phpdoc/en/features/http-auth.xml:1.17 phpdoc/en/features/http-auth.xml:1.18 --- phpdoc/en/features/http-auth.xml:1.17 Sat Nov 10 16:49:30 2001 +++ phpdoc/en/features/http-auth.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.17 $ --> +<!-- $Revision: 1.18 $ --> <chapter id="features.http-auth"> <title>HTTP authentication with PHP</title> @@ -23,17 +23,19 @@ <example> <title>HTTP Authentication example</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php if(!isset($PHP_AUTH_USER)) { - header("WWW-Authenticate: Basic realm=\"My Realm\""); - header("HTTP/1.0 401 Unauthorized"); - echo "Text to send if user hits Cancel button\n"; + header("WWW-Authenticate: Basic realm=\"My Realm\""); + header("HTTP/1.0 401 Unauthorized"); + echo "Text to send if user hits Cancel button\n"; exit; } else { - echo "<p>Hello $PHP_AUTH_USER.</p>"; - echo "<p>You entered $PHP_AUTH_PW as your password.</p>"; + echo "<p>Hello $PHP_AUTH_USER.</p>"; + echo "<p>You entered $PHP_AUTH_PW as your password.</p>"; } ?> +]]> </programlisting> </example></para> @@ -93,27 +95,29 @@ <example> <title>HTTP Authentication example forcing a new name/password</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php function authenticate() { - header( "WWW-Authenticate: Basic realm=\"Test Authentication System\""); - header( "HTTP/1.0 401 Unauthorized"); - echo "You must enter a valid login ID and password to access this resource\n"; + header( "WWW-Authenticate: Basic realm=\"Test Authentication System\""); + header( "HTTP/1.0 401 Unauthorized"); + echo "You must enter a valid login ID and password to access this resource\n"; exit; } - if(!isset($PHP_AUTH_USER) || ($SeenBefore == 1 && !strcmp($OldAuth, $PHP_AUTH_USER)) ) { + if(!isset($PHP_AUTH_USER) || ($SeenBefore == 1 && !strcmp($OldAuth, $PHP_AUTH_USER)) ) { authenticate(); } else { - echo "</p>Welcome: $PHP_AUTH_USER<br>"; - echo "Old: $OldAuth"; - echo "<form action=\"$PHP_SELF\" METHOD=POST>\n"; - echo "<input type=\"hidden\" name=\"SeenBefore\" value=\"1\">\n"; - echo "<input type=\"hidden\" name=\"OldAuth\" value=\"$PHP_AUTH_USER\">\n"; - echo "<input type=\"submit\" value=\"Re Authenticate\">\n"; - echo "</form></p>\n"; + echo "</p>Welcome: $PHP_AUTH_USER<br>"; + echo "Old: $OldAuth"; + echo "<form action='$PHP_SELF' METHOD=POST>\n"; + echo "<input type='hidden' name='SeenBefore' value='1'>\n"; + echo "<input type='hidden' name='OldAuth' value='$PHP_AUTH_USER'>\n"; + echo "<input type='submit' value='Re Authenticate'>\n"; + echo "</form></p>\n"; } ?> +]]> </programlisting> </example> <simpara> Index: phpdoc/en/features/images.xml diff -u phpdoc/en/features/images.xml:1.13 phpdoc/en/features/images.xml:1.14 --- phpdoc/en/features/images.xml:1.13 Sat Nov 10 16:49:30 2001 +++ phpdoc/en/features/images.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.13 $ --> +<!-- $Revision: 1.14 $ --> <chapter id="features.images"> <title>Creating and manipulating images</title> @@ -18,7 +18,8 @@ <example> <title>PNG creation with PHP</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php Header("Content-type: image/png"); $string=implode($argv," "); $im = imageCreateFromPng("images/button1.png"); @@ -28,6 +29,7 @@ ImagePng($im); ImageDestroy($im); ?> +]]> </programlisting> </example> Index: phpdoc/en/features/safe-mode.xml diff -u phpdoc/en/features/safe-mode.xml:1.15 phpdoc/en/features/safe-mode.xml:1.16 --- phpdoc/en/features/safe-mode.xml:1.15 Sat Nov 10 16:49:31 2001 +++ phpdoc/en/features/safe-mode.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.15 $ --> +<!-- $Revision: 1.16 $ --> <chapter id="features.safe-mode"> <title>Safe Mode</title> @@ -12,12 +12,14 @@ <para> The configuration directives that control Safe Mode are: <programlisting role="ini"> +<![CDATA[ safe_mode = Off open_basedir = safe_mode_exec_dir = safe_mode_allowed_env_vars = PHP_ safe_mode_protected_env_vars = LD_LIBRARY_PATH disable_functions = +]]> </programlisting> </para> <para> @@ -25,48 +27,62 @@ if the owner of the current script matches the owner of the file to be operated on by a file function. For example: <programlisting role="ls"> +<![CDATA[ -rw-rw-r-- 1 rasmus rasmus 33 Jul 1 19:20 script.php -rw-r--r-- 1 root root 1116 May 26 18:01 /etc/passwd +]]> </programlisting> Running this script.php <programlisting role="php"> -<?php +<![CDATA[ +<?php readfile('/etc/passwd'); -?> +?> +]]> </programlisting> results in this error when Safe Mode is enabled: - <programlisting> + <screen> +<![CDATA[ Warning: SAFE MODE Restriction in effect. The script whose uid is 500 is not allowed to access /etc/passwd owned by uid 0 in /docroot/script.php on line 2 - </programlisting> +]]> + </screen> </para> <para> If instead of <link linkend="ini.safe-mode">safe_mode</link>, you set an open_basedir directory then all file operations will be limited to files under the specified directory. For example (Apache httpd.conf example): <programlisting role="ini"> -<Directory /docroot> -php_admin_value open_basedir /docroot -</Directory> +<![CDATA[ +<Directory /docroot> + php_admin_value open_basedir /docroot +</Directory> +]]> </programlisting> If you run the same script.php with this open_basedir setting then this is the result: - <programlisting> + <screen> +<![CDATA[ Warning: open_basedir restriction in effect. File is in wrong directory in /docroot/script.php on line 2 - </programlisting> +]]> + </screen> </para> <para> You can also disable individual functions. If we add this to our php.ini file: <programlisting role="ini"> +<![CDATA[ disable_functions readfile,system +]]> </programlisting> Then we get this output: - <programlisting> + <screen> +<![CDATA[ Warning: readfile() has been disabled for security reasons in /docroot/script.php on line 2 - </programlisting> +]]> + </screen> </para> <sect1 id="features.safe-mode.functions"> Index: phpdoc/en/language/basic-syntax.xml diff -u phpdoc/en/language/basic-syntax.xml:1.19 phpdoc/en/language/basic-syntax.xml:1.20 --- phpdoc/en/language/basic-syntax.xml:1.19 Sat Nov 10 16:49:42 2001 +++ phpdoc/en/language/basic-syntax.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.19 $ --> +<!-- $Revision: 1.20 $ --> <chapter id="language.basic-syntax"> <title>Basic syntax</title> @@ -65,18 +65,20 @@ <example> <title>Ways of escaping from HTML</title> <programlisting role="php"> -1. <? echo ("this is the simplest, an SGML processing instruction\n"); ?> - <?= expression ?> This is a shortcut for "<? echo expression ?>" +<![CDATA[ +1. <? echo ("this is the simplest, an SGML processing instruction\n"); ?> + <?= expression ?> This is a shortcut for "<? echo expression ?>" -2. <?php echo("if you want to serve XHTML or XML documents, do like this\n"); ?> +2. <?php echo("if you want to serve XHTML or XML documents, do like this\n"); ?> -3. <script language="php"> +3. <script language="php"> echo ("some editors (like FrontPage) don't like processing instructions"); - </script> + </script> -4. <% echo ("You may optionally use ASP-style tags"); %> - <%= $variable; # This is a shortcut for "<%echo .." %> +4. <% echo ("You may optionally use ASP-style tags"); %> + <%= $variable; # This is a shortcut for "<%echo .." %> +]]> </programlisting> </example> </para> @@ -113,19 +115,22 @@ PHP allows you to use structures like this: <example><title>Advanced escaping</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php if (boolean-expression) { - ?> -<strong>This is true.</strong> - <?php + ?> +<strong>This is true.</strong> + <?php } else { - ?> -<strong>This is false.</strong> - <?php + > +<strong>This is false.</strong> + <?php } - ?> - </programlisting></example> + ?> +]]> + </programlisting> + </example> This works as expected, because PHP handles text within ?> and <?php as an <function>echo</function> statement. @@ -147,11 +152,13 @@ <informalexample> <programlisting role="php"> -<?php +<![CDATA[ +<?php echo "This is a test"; ?> -<?php echo "This is a test" ?> +<?php echo "This is a test" ?> +]]> </programlisting> </informalexample></para></sect1> @@ -161,14 +168,17 @@ <para> PHP supports 'C', 'C++' and Unix shell-style comments. For example: - <informalexample><programlisting role="php"> -<?php + <informalexample> + <programlisting role="php"> +<![CDATA[ +<?php echo "This is a test"; // This is a one-line c++ style comment /* This is a multi line comment yet another line of comment */ echo "This is yet another test"; echo "One Final Test"; # This is shell-style style comment ?> +]]> </programlisting> </informalexample></para> @@ -176,22 +186,30 @@ The "one-line" comment styles actually only comment to the end of the line or the current block of PHP code, whichever comes first.</simpara> - <informalexample><programlisting role="php"> -<h1>This is an <?php # echo "simple";?> example.</h1> -<p>The header above will say 'This is an example'. - </programlisting></informalexample> + <informalexample> + <programlisting role="php"> +<![CDATA[ +<h1>This is an <?php # echo "simple";?> example.>/h1> +<p>The header above will say 'This is an example'. +]]> + </programlisting> + </informalexample> <simpara> You should be careful not to nest 'C' style comments, which can happen when commenting out large blocks.</simpara> - <informalexample><programlisting role="php"> -<?php + <informalexample> + <programlisting role="php"> +<![CDATA[ +<?php /* echo "This is a test"; /* This comment will cause a problem */ */ ?> - </programlisting></informalexample></sect1> +]]> + </programlisting> + </informalexample></sect1> </chapter> <!-- Keep this comment at the end of the file Index: phpdoc/en/language/constants.xml diff -u phpdoc/en/language/constants.xml:1.21 phpdoc/en/language/constants.xml:1.22 --- phpdoc/en/language/constants.xml:1.21 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/language/constants.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.21 $ --> +<!-- $Revision: 1.22 $ --> <chapter id="language.constants"> <title>Constants</title> @@ -98,11 +98,13 @@ <example> <title>Defining Constants</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php define("CONSTANT", "Hello world."); echo CONSTANT; // outputs "Hello world." echo Constant; // outputs "Constant" and issues a notice. -?> +?> +]]> </programlisting> </example> @@ -255,14 +257,16 @@ <example> <title>Using __FILE__ and __LINE__</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php function report_error($file, $line, $message) { echo "An error occured in $file on line $line: $message."; } report_error(__FILE__, __LINE__, "Something went wrong!"); -?> +?> +]]> </programlisting> </example> </para> Index: phpdoc/en/language/control-structures.xml diff -u phpdoc/en/language/control-structures.xml:1.42 phpdoc/en/language/control-structures.xml:1.43 --- phpdoc/en/language/control-structures.xml:1.42 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/language/control-structures.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.42 $ --> +<!-- $Revision: 1.43 $ --> <chapter id="control-structures"> <title>Control Structures</title> @@ -23,8 +23,10 @@ <literal>if</literal> structure that is similar to that of C: <informalexample> <programlisting> +<![CDATA[ if (expr) statement +]]> </programlisting> </informalexample> </para> @@ -40,8 +42,10 @@ than <replaceable>$b</replaceable>: <informalexample> <programlisting role="php"> -if ($a > $b) +<![CDATA[ +if ($a > $b) print "a is bigger than b"; +]]> </programlisting> </informalexample> </para> @@ -56,10 +60,12 @@ <replaceable>$a</replaceable> into <replaceable>$b</replaceable>: <informalexample> <programlisting role="php"> -if ($a > $b) { +<![CDATA[ +if ($a > $b) { print "a is bigger than b"; $b = $a; } +]]> </programlisting> </informalexample> </para> @@ -86,11 +92,13 @@ than b</computeroutput> otherwise: <informalexample> <programlisting role="php"> -if ($a > $b) { +<![CDATA[ +if ($a > $b) { print "a is bigger than b"; } else { print "a is NOT bigger than b"; } +]]> </programlisting> </informalexample> @@ -121,13 +129,15 @@ or <computeroutput>a is smaller than b</computeroutput>: <informalexample> <programlisting role="php"> -if ($a > $b) { +<![CDATA[ +if ($a > $b) { print "a is bigger than b"; } elseif ($a == $b) { print "a is equal to b"; } else { print "a is smaller than b"; } +]]> </programlisting> </informalexample> </para> @@ -166,9 +176,11 @@ <literal>endswitch;</literal>, respectively. <informalexample> <programlisting role="php"> -<?php if ($a == 5): ?> +<![CDATA[ +<?php if ($a == 5): ?> A is equal to 5 -<?php endif; ?> +<?php endif; ?> +]]> </programlisting> </informalexample> </para> @@ -184,6 +196,7 @@ <literal>else</literal> in the alternative format: <informalexample> <programlisting role="php"> +<![CDATA[ if ($a == 5): print "a equals 5"; print "..."; @@ -193,6 +206,7 @@ else: print "a is neither 5 nor 6"; endif; +]]> </programlisting> </informalexample> </para> @@ -211,7 +225,9 @@ of a <literal>while</literal> statement is: <informalexample> <programlisting> +<![CDATA[ while (expr) statement +]]> </programlisting> </informalexample> </para> @@ -235,7 +251,9 @@ using the alternate syntax: <informalexample> <programlisting> +<![CDATA[ while (expr): statement ... endwhile; +]]> </programlisting> </informalexample> </para> @@ -244,10 +262,11 @@ 1 to 10: <informalexample> <programlisting role="php"> +<![CDATA[ /* example 1 */ $i = 1; -while ($i <= 10) { +while ($i <= 10) { print $i++; /* the printed value would be $i before the increment (post-increment) */ @@ -256,10 +275,11 @@ /* example 2 */ $i = 1; -while ($i <= 10): +while ($i <= 10): print $i; $i++; endwhile; +]]> </programlisting> </informalexample> </para> @@ -285,10 +305,12 @@ <informalexample> <programlisting role="php"> +<![CDATA[ $i = 0; do { print $i; } while ($i>0); +]]> </programlisting> </informalexample> </para> @@ -307,13 +329,14 @@ statement. The following code fragment demonstrates this: <informalexample> <programlisting role="php"> +<![CDATA[ do { - if ($i < 5) { + if ($i < 5) { print "i is not big enough"; break; } $i *= $factor; - if ($i < $minimum_limit) { + if ($i < $minimum_limit) { break; } print "i is ok"; @@ -321,6 +344,7 @@ ...process i... } while(0); +]]> </programlisting> </informalexample> </para> @@ -339,7 +363,9 @@ <literal>for</literal> loop is: <informalexample> <programlisting> +<![CDATA[ for (expr1; expr2; expr3) statement +]]> </programlisting> </informalexample> </para> @@ -375,16 +401,17 @@ 1 to 10: <informalexample> <programlisting role="php"> +<![CDATA[ /* example 1 */ -for ($i = 1; $i <= 10; $i++) { +for ($i = 1; $i <= 10; $i++) { print $i; } /* example 2 */ for ($i = 1;;$i++) { - if ($i > 10) { + if ($i > 10) { break; } print $i; @@ -394,7 +421,7 @@ $i = 1; for (;;) { - if ($i > 10) { + if ($i > 10) { break; } print $i; @@ -403,7 +430,8 @@ /* example 4 */ -for ($i = 1; $i <= 10; print $i, $i++); +for ($i = 1; $i <= 10; print $i, $i++); +]]> </programlisting> </informalexample> </para> @@ -418,7 +446,9 @@ <literal>for</literal> loops. <informalexample> <programlisting> +<![CDATA[ for (expr1; expr2; expr3): statement; ...; endfor; +]]> </programlisting> </informalexample> </para> @@ -444,8 +474,10 @@ a minor but useful extension of the first: <informalexample> <programlisting> +<![CDATA[ foreach(array_expression as $value) statement -foreach(array_expression as $key => $value) statement +foreach(array_expression as $key => $value) statement +]]> </programlisting> </informalexample> </para> @@ -494,27 +526,31 @@ identical: <informalexample> <programlisting role="php"> +<![CDATA[ reset ($arr); while (list(, $value) = each ($arr)) { - echo "Value: $value<br>\n"; + echo "Value: $value<br>\n"; } foreach ($arr as $value) { - echo "Value: $value<br>\n"; + echo "Value: $value<br>\n"; } +]]> </programlisting> </informalexample> The following are also functionally identical: <informalexample> <programlisting role="php"> +<![CDATA[ reset ($arr); while (list($key, $value) = each ($arr)) { - echo "Key: $key; Value: $value<br>\n"; + echo "Key: $key; Value: $value<br>\n"; } foreach ($arr as $key => $value) { - echo "Key: $key; Value: $value<br>\n"; + echo "Key: $key; Value: $value<br>\n"; } +]]> </programlisting> </informalexample> </para> @@ -522,6 +558,7 @@ Some more examples to demonstrate usages: <informalexample> <programlisting role="php"> +<![CDATA[ /* foreach example 1: value only */ $a = array (1, 2, 3, 17); @@ -537,20 +574,20 @@ $i = 0; /* for illustrative purposes only */ foreach($a as $v) { - print "\$a[$i] => $v.\n"; + print "\$a[$i] => $v.\n"; } /* foreach example 3: key and value */ $a = array ( - "one" => 1, - "two" => 2, - "three" => 3, - "seventeen" => 17 + "one" => 1, + "two" => 2, + "three" => 3, + "seventeen" => 17 ); -foreach($a as $k => $v) { - print "\$a[$k] => $v.\n"; +foreach($a as $k => $v) { + print "\$a[$k] => $v.\n"; } /* foreach example 4: multi-dimensional arrays */ @@ -571,6 +608,7 @@ foreach(array(1, 2, 3, 4, 5) as $v) { print "$v\n"; } +]]> </programlisting> </informalexample> </para> @@ -592,12 +630,13 @@ <para> <informalexample> <programlisting role="php"> +<![CDATA[ $arr = array ('one', 'two', 'three', 'four', 'stop', 'five'); while (list (, $val) = each ($arr)) { if ($val == 'stop') { break; /* You could also write 'break 1;' here. */ } - echo "$val<br>\n"; + echo "$val<br>\n"; } /* Using the optional argument. */ @@ -606,15 +645,16 @@ while (++$i) { switch ($i) { case 5: - echo "At 5<br>\n"; + echo "At 5<br>\n"; break 1; /* Exit only the switch. */ case 10: - echo "At 10; quitting<br>\n"; + echo "At 10; quitting<br>\n"; break 2; /* Exit the switch and the while. */ default: break; } } +]]> </programlisting> </informalexample> </para> @@ -635,6 +675,7 @@ <para> <informalexample> <programlisting role="php"> +<![CDATA[ while (list ($key, $value) = each ($arr)) { if (!($key % 2)) { // skip odd members continue; @@ -644,17 +685,18 @@ $i = 0; while ($i++ < 5) { - echo "Outer<br>\n"; + echo "Outer<br>\n"; while (1) { - echo " Middle<br>\n"; + echo " Middle<br>\n"; while (1) { - echo " Inner<br>\n"; + echo " Inner<br>\n"; continue 3; } - echo "This never gets output.<br>\n"; + echo "This never gets output.<br>\n"; } - echo "Neither does this.<br>\n"; + echo "Neither does this.<br>\n"; } +]]> </programlisting> </informalexample> </para> @@ -677,6 +719,7 @@ statement: <informalexample> <programlisting role="php"> +<![CDATA[ if ($i == 0) { print "i equals 0"; } @@ -698,6 +741,7 @@ print "i equals 2"; break; } +]]> </programlisting> </informalexample> </para> @@ -717,6 +761,7 @@ following case. For example: <informalexample> <programlisting role="php"> +<![CDATA[ switch ($i) { case 0: print "i equals 0"; @@ -725,6 +770,7 @@ case 2: print "i equals 2"; } +]]> </programlisting> </informalexample> </para> @@ -750,6 +796,7 @@ passes control into the statement list for the next case. <informalexample> <programlisting role="php"> +<![CDATA[ switch ($i) { case 0: case 1: @@ -759,6 +806,7 @@ case 3: print "i is 3"; } +]]> </programlisting> </informalexample> </para> @@ -768,6 +816,7 @@ <literal>case</literal> statement. For example: <informalexample> <programlisting role="php"> +<![CDATA[ switch ($i) { case 0: print "i equals 0"; @@ -781,6 +830,7 @@ default: print "i is not equal to 0, 1 or 2"; } +]]> </programlisting> </informalexample> </para> @@ -797,6 +847,7 @@ for control structures</link> . <informalexample> <programlisting role="php"> +<![CDATA[ switch ($i): case 0: print "i equals 0"; @@ -810,6 +861,7 @@ default: print "i is not equal to 0, 1 or 2"; endswitch; +]]> </programlisting> </informalexample> </para> @@ -824,7 +876,9 @@ the syntax of other flow control constructs: <informalexample> <programlisting> +<![CDATA[ declare (directive) statement +]]> </programlisting> </informalexample> </para> @@ -865,8 +919,9 @@ <example> <title>Profile a section of PHP code</title> <programlisting role="php"> -<pre> -<?php +<![CDATA[ +<pre> +<?php // A function that records the time when it is called function profile ($dump = FALSE) { @@ -890,15 +945,16 @@ // Run a block of code, throw a tick every 2nd statement declare (ticks=2) { - for ($x = 1; $x < 50; ++$x) { + for ($x = 1; $x < 50; ++$x) { echo similar_text (md5($x), md5($x*$x)), "<br>"; } } // Display the data stored in the profiler print_r (profile (TRUE)); -?> -</pre> +?> +</pre> +]]> </programlisting> </example> The example profiles the PHP code within the 'declare' @@ -976,7 +1032,9 @@ <function>include</function> statement. <informalexample> <programlisting role="php"> +<![CDATA[ require ('header.inc'); +]]> </programlisting> </informalexample> </para> @@ -1002,24 +1060,26 @@ the local script. <informalexample> <programlisting role="php"> +<![CDATA[ /* This example assumes that someserver is configured to parse .php * files and not .txt files. Also, 'works' here means that the variables * $varone and $vartwo are available within the require()ed file. */ /* Won't work; file.txt wasn't handled by someserver. */ -require ("http://someserver/file.txt?varone=1&vartwo=2"); +require ("http://someserver/file.txt?varone=1&vartwo=2"); /* Won't work; looks for a file named 'file.php?varone=1&vartwo=2' * on the local filesystem. */ -require ("file.php?varone=1&vartwo=2"); +require ("file.php?varone=1&vartwo=2"); /* Works. */ -require ("http://someserver/file.php?varone=1&vartwo=2"); +require ("http://someserver/file.php?varone=1&vartwo=2"); $varone = 1; $vartwo = 2; require ("file.txt"); /* Works. */ require ("file.php"); /* Works. */ +]]> </programlisting> </informalexample> </para> @@ -1069,10 +1129,12 @@ different files. <informalexample> <programlisting role="php"> +<![CDATA[ $files = array ('first.inc', 'second.inc', 'third.inc'); -for ($i = 0; $i < count($files); $i++) { +for ($i = 0; $i < count($files); $i++) { include $files[$i]; } +]]> </programlisting> </informalexample> </para> @@ -1093,6 +1155,7 @@ inside a conditional block. <informalexample> <programlisting role="php"> +<![CDATA[ /* This is WRONG and will not work as desired. */ if ($condition) @@ -1107,6 +1170,7 @@ } else { include($other); } +]]> </programlisting> </informalexample> </para> @@ -1132,23 +1196,26 @@ <filename>test.inc</filename>) in the same directory as the main file: <programlisting role="php"> -<?php -echo "Before the return <br>\n"; +<![CDATA[ +<?php +echo "Before the return <br>\n"; if (1) { return 27; } -echo "After the return <br>\n"; -?> +echo "After the return <br>\n"; +?> +]]> </programlisting> </para> <para> Assume that the main file (<filename>main.html</filename>) contains the following: <programlisting role="php"> -<?php +<![CDATA[ +<?php $retval = include ('test.inc'); -echo "File returned: '$retval'<br>\n"; -?> +echo "File returned: '$retval'<br>\n"; +?> </programlisting> </para> <para> @@ -1165,10 +1232,12 @@ Now, assume that <filename>main.html</filename> has been altered to contain the following: <programlisting role="php"> -<?php +<![CDATA[ +<?php include ('test.inc'); -echo "Back in main.html<br>\n"; -?> +echo "Back in main.html<br>\n"; +?> +]]> </programlisting> </para> <para> @@ -1222,24 +1291,26 @@ the local script. <informalexample> <programlisting role="php"> +<![CDATA[ /* This example assumes that someserver is configured to parse .php * files and not .txt files. Also, 'works' here means that the variables * $varone and $vartwo are available within the include()ed file. */ /* Won't work; file.txt wasn't handled by someserver. */ -include ("http://someserver/file.txt?varone=1&vartwo=2"); +include ("http://someserver/file.txt?varone=1vartwo=2"); -/* Won't work; looks for a file named 'file.php?varone=1&vartwo=2' +/* Won't work; looks for a file named 'file.php?varone=1&vartwo=2' * on the local filesystem. */ include ("file.php?varone=1&vartwo=2"); /* Works. */ -include ("http://someserver/file.php?varone=1&vartwo=2"); +include ("http://someserver/file.php?varone=1&vartwo=2"); $varone = 1; $vartwo = 2; include ("file.txt"); /* Works. */ include ("file.php"); /* Works. */ +]]> </programlisting> </informalexample> </para> @@ -1268,20 +1339,23 @@ <example> <title>utils.inc</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php define("PHPVERSION", floor(phpversion())); echo "GLOBALS ARE NICE\n"; function goodTea() { return "Oolong tea tastes good!"; } -?> +?> +]]> </programlisting> </example> <example> <title>foolib.inc</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php require ("utils.inc"); function showVar($var) { @@ -1293,14 +1367,16 @@ } // bunch of other functions ... -?> +?> +]]> </programlisting> </example> And then you write a script <literal>cause_error_require.php</literal> <example> <title>cause_error_require.php</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php require("foolib.inc"); /* the following will generate an error */ require("utils.inc"); @@ -1310,18 +1386,21 @@ echo "Running goodTea: ".goodTea()."\n"; echo "Printing foo: \n"; showVar($foo); -?> +?> +]]> </programlisting> </example> When you try running the latter one, the resulting ouptut will be (using PHP 4.01pl2): <informalexample> - <programlisting> + <screen> +<![CDATA[ GLOBALS ARE NICE GLOBALS ARE NICE Fatal error: Cannot redeclare goodTea() in utils.inc on line 5 - </programlisting> +]]> + </screen> </informalexample> By modifying <literal>foolib.inc</literal> and <literal>cause_errror_require.php</literal> @@ -1331,26 +1410,31 @@ <example> <title>foolib.inc (fixed)</title> <programlisting role="php"> +<![CDATA[ ... require_once("utils.inc"); function showVar($var) { ... +]]> </programlisting> </example> <example> <title>avoid_error_require_once.php</title> <programlisting role="php"> +<![CDATA[ ... require_once("foolib.inc"); require_once("utils.inc"); $foo = array("1",array("complex","quaternion")); ... +]]> </programlisting> </example> And when running the latter, the output will be (using PHP 4.0.1pl2): <informalexample> - <programlisting> + <screen> +<![CDATA[ GLOBALS ARE NICE this is requiring globals.inc again which is also required in foolib.inc @@ -1358,15 +1442,16 @@ Printing foo: Array ( - [0] => 1 - [1] => Array + [0] => 1 + [1] => Array ( - [0] => complex - [1] => quaternion + [0] => complex + [1] => quaternion ) ) - </programlisting> +]]> + </screen> </informalexample> </para> <para> Index: phpdoc/en/language/expressions.xml diff -u phpdoc/en/language/expressions.xml:1.17 phpdoc/en/language/expressions.xml:1.18 --- phpdoc/en/language/expressions.xml:1.17 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/language/expressions.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.17 $ --> +<!-- $Revision: 1.18 $ --> <chapter id="language.expressions"> <title>Expressions</title> @@ -28,10 +28,12 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function foo () { return 5; } +]]> </programlisting> </informalexample></para> @@ -127,7 +129,9 @@ it in other languages, the ternary conditional operator: <informalexample><programlisting> +<![CDATA[ $first ? $second : $third +]]> </programlisting></informalexample> If the value of the first subexpression is &true; (non-zero), then @@ -142,6 +146,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function double($i) { return $i*2; @@ -162,6 +167,7 @@ value of 24. the value of the assignment (24) is then assigned into $h, and $h ends with the value of 24 as well. */ +]]> </programlisting> </informalexample> </para> Index: phpdoc/en/language/functions.xml diff -u phpdoc/en/language/functions.xml:1.18 phpdoc/en/language/functions.xml:1.19 --- phpdoc/en/language/functions.xml:1.18 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/language/functions.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.18 $ --> +<!-- $Revision: 1.19 $ --> <chapter id="functions"> <title>Functions</title> @@ -11,11 +11,13 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function foo ($arg_1, $arg_2, ..., $arg_n) { echo "Example function.\n"; return $retval; } +]]> </programlisting> </informalexample> </para> @@ -79,10 +81,12 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function takes_array($input) { echo "$input[0] + $input[1] = ", $input[0]+$input[1]; } +]]> </programlisting> </informalexample> </para> @@ -104,13 +108,15 @@ <informalexample> <programlisting role="php"> -function add_some_extra(&$string) +<![CDATA[ +function add_some_extra(&$string) { $string .= 'and something extra.'; } $str = 'This is a string, '; add_some_extra($str); echo $str; // outputs 'This is a string, and something extra.' +]]> </programlisting> </informalexample> </para> @@ -122,6 +128,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function foo ($bar) { $bar .= ' and something extra.'; @@ -129,8 +136,9 @@ $str = 'This is a string, '; foo ($str); echo $str; // outputs 'This is a string, ' -foo (&$str); +foo (&$str); echo $str; // outputs 'This is a string, and something extra.' +]]> </programlisting> </informalexample> </para> @@ -146,12 +154,14 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function makecoffee ($type = "cappucino") { return "Making a cup of $type.\n"; } echo makecoffee (); echo makecoffee ("espresso"); +]]> </programlisting> </informalexample> </para> @@ -176,12 +186,14 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function makeyogurt ($type = "acidophilus", $flavour) { return "Making a bowl of $type $flavour.\n"; } echo makeyogurt ("raspberry"); // won't work as expected +]]> </programlisting> </informalexample> </para> @@ -201,12 +213,14 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function makeyogurt ($flavour, $type = "acidophilus") { return "Making a bowl of $type $flavour.\n"; } echo makeyogurt ("raspberry"); // works as expected +]]> </programlisting> </informalexample> </para> @@ -251,11 +265,13 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function square ($num) { return $num * $num; } echo square (4); // outputs '16'. +]]> </programlisting> </informalexample> </para> @@ -266,11 +282,13 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function small_numbers() { return array (0, 1, 2); } list ($zero, $one, $two) = small_numbers(); +]]> </programlisting> </informalexample> </para> @@ -280,12 +298,14 @@ when assigning the returned value to a variable: <informalexample> <programlisting role="php"> -function &returns_reference() +<![CDATA[ +function &returns_reference() { return $someref; } -$newref =& returns_reference(); +$newref =& returns_reference(); +]]> </programlisting> </informalexample> </para> @@ -339,15 +359,16 @@ <example> <title>Variable function example</title> <programlisting role="php"> -<?php +<![CDATA[ +<?php function foo() { - echo "In foo()<br>\n"; + echo "In foo()<br>\n"; } function bar($arg = '') { - echo "In bar(); argument was '$arg'.<br>\n"; + echo "In bar(); argument was '$arg'.<br>\n"; } $func = 'foo'; @@ -355,6 +376,7 @@ $func = 'bar'; $func('test'); ?> +]]> </programlisting> </example> </para> Index: phpdoc/en/language/oop.xml diff -u phpdoc/en/language/oop.xml:1.30 phpdoc/en/language/oop.xml:1.31 --- phpdoc/en/language/oop.xml:1.30 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/language/oop.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.30 $ --> +<!-- $Revision: 1.31 $ --> <chapter id="language.oop"> <title>Classes and Objects</title> @@ -11,7 +11,8 @@ <informalexample> <programlisting role="php"> -<?php +<![CDATA[ +<?php class Cart { var $items; // Items in our shopping cart @@ -35,7 +36,8 @@ } } } -?> +?> +]]> </programlisting> </informalexample> </para> @@ -82,6 +84,8 @@ </simpara> <informalexample> <programlisting role="php"> +<![CDATA[ +<?php /* None of these will work in PHP 4. */ class Cart { @@ -106,6 +110,7 @@ /* etc. . . */ } } +]]> </programlisting> </informalexample> </note> @@ -118,11 +123,14 @@ <informalexample> <programlisting role="php"> +<![CDATA[ +<?php $cart = new Cart; $cart->add_item("10", 1); $another_cart = new Cart; $another_cart->add_item("0815", 3); +]]> </programlisting> </informalexample> @@ -154,6 +162,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ // correct, single $ $cart->items = array("10" => 1); @@ -164,6 +173,7 @@ // $cart->$myvar becomes $cart->items $myvar = 'items'; $cart->$myvar = array("10" => 1); +]]> </programlisting> </informalexample> @@ -203,6 +213,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ class Named_Cart extends Cart { var $owner; @@ -212,6 +223,7 @@ $this->owner = $name; } } +]]> </programlisting> </informalexample> @@ -225,10 +237,12 @@ <informalexample> <programlisting role="php"> +<![CDATA[ $ncart = new Named_Cart; // Create a named cart $ncart->set_owner("kris"); // Name that cart print $ncart->owner; // print the cart owners name $ncart->add_item("10", 1); // (inherited functionality from cart) +]]> </programlisting> </informalexample> @@ -256,6 +270,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ // Works in PHP 3 and PHP 4. class Auto_Cart extends Cart { @@ -264,6 +279,7 @@ $this->add_item ("10", 1); } } +]]> </programlisting> </informalexample> @@ -279,6 +295,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ // Works in PHP 3 and PHP 4. class Constructor_Cart extends Cart { @@ -295,6 +312,7 @@ // Shop for real... $different_cart = new Constructor_Cart("20", 17); +]]> </programlisting> </informalexample> @@ -308,11 +326,12 @@ <informalexample> <programlisting role="php"> +<![CDATA[ class A { function A() { - echo "I am the constructor of A.<br>\n"; + echo "I am the constructor of A.<br>\n"; } } @@ -320,12 +339,13 @@ { function C() { - echo "I am a regular function.<br>\n"; + echo "I am a regular function.<br>\n"; } } // no constructor is being called in PHP 3. $b = new B; +]]> </programlisting> </informalexample> @@ -345,17 +365,18 @@ <informalexample> <programlisting role="php"> +<![CDATA[ class A { function A() { - echo "I am the constructor of A.<br>\n"; + echo "I am the constructor of A.<br>\n"; } function B() { - echo "I am a regular function named B in class A.<br>\n"; - echo "I am not a constructor in A.<br>\n"; + echo "I am a regular function named B in class A.<br>\n"; + echo "I am not a constructor in A.<br>\n"; } } @@ -363,12 +384,13 @@ { function C() { - echo "I am a regular function.<br>\n"; + echo "I am a regular function.<br>\n"; } } // This will call B() as a constructor. $b = new B; +]]> </programlisting> </informalexample> @@ -431,11 +453,12 @@ <informalexample> <programlisting role="php"> +<![CDATA[ class A { function example() { - echo "I am the original function A::example().<br>\n"; + echo "I am the original function A::example().<br>\n"; } } @@ -443,23 +466,24 @@ { function example() { - echo "I am the redefined function B::example().<br>\n"; + echo "I am the redefined function B::example().<br>\n"; A::example(); } } // there is no object of class A. // this will print -// I am the original function A::example().<br> +// I am the original function A::example().<br> A::example(); // create an object of class B. $b = new B; // this will print -// I am the redefined function B::example().<br> -// I am the original function A::example().<br> +// I am the redefined function B::example().<br> +// I am the original function A::example().<br> $b->example(); +]]> </programlisting> </informalexample> @@ -522,11 +546,12 @@ <informalexample> <programlisting role="php"> +<![CDATA[ class A { function example() { - echo "I am A::example() and provide basic functionality.<br>\n"; + echo "I am A::example() and provide basic functionality.<br>\n"; } } @@ -534,7 +559,7 @@ { function example() { - echo "I am B::example() and provide additional functionality.<br>\n"; + echo "I am B::example() and provide additional functionality.<br>\n"; parent::example(); } } @@ -543,6 +568,7 @@ // This will call B::example(), which will in turn call A::example(). $b->example(); +]]> </programlisting> </informalexample> </sect1> @@ -591,6 +617,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ classa.inc: class A { @@ -621,6 +648,7 @@ // now use the function show_one() of the $a object. $a->show_one(); +]]> </programlisting> </informalexample> @@ -694,14 +722,14 @@ <informalexample> <programlisting role="php"> - +<![CDATA[ class Foo { function Foo($name) { // create a reference inside the global array $globalref global $globalref; - $globalref[] = &$this; + $globalref[] = &$this; // set name to passed value $this->setName($name); // and put it out @@ -710,7 +738,7 @@ function echoName() { - echo "<br>",$this->name; + echo "<br>",$this->name; } function setName($name) @@ -718,6 +746,7 @@ $this->name = $name; } } +]]> </programlisting> </informalexample> </para> @@ -731,7 +760,7 @@ <informalexample> <programlisting role="php"> - +<![CDATA[ $bar1 = new Foo('set in constructor'); $bar1->echoName(); $globalref[0]->echoName(); @@ -741,7 +770,7 @@ set in constructor set in constructor */ -$bar2 =& new Foo('set in constructor'); +$bar2 =& new Foo('set in constructor'); $bar2->echoName(); $globalref[1]->echoName(); @@ -749,7 +778,7 @@ set in constructor set in constructor set in constructor */ - +]]> </programlisting> </informalexample> </para> @@ -775,6 +804,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ // now we will change the name. what do you expect? // you could expect that both $bar1 and $globalref[0] change their names... $bar1->setName('set from outside'); @@ -798,6 +828,7 @@ /* output: set from outside set from outside */ +]]> </programlisting> </informalexample> </para> @@ -806,6 +837,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ class A { function A($i) @@ -822,27 +854,27 @@ function echoValue() { - echo "<br>","class ",get_class($this),': ',$this->value; + echo "<br>","class ",get_class($this),': ',$this->value; } } class B { - function B(&$a) + function B(&$a) { - $this->a = &$a; + $this->a = &$a; } function echoValue() { - echo "<br>","class ",get_class($this),': ',$this->a->value; + echo "<br>","class ",get_class($this),': ',$this->a->value; } } // try to undestand why using a simple copy here would yield // in an undesired result in the *-marked line -$a =& new A(10); +$a =& new A(10); $a->createRef(); $a->echoValue(); @@ -864,6 +896,7 @@ class B: 11 class B: 11 */ +]]> </programlisting> </informalexample> </para> Index: phpdoc/en/language/operators.xml diff -u phpdoc/en/language/operators.xml:1.28 phpdoc/en/language/operators.xml:1.29 --- phpdoc/en/language/operators.xml:1.28 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/language/operators.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.28 $ --> +<!-- $Revision: 1.29 $ --> <chapter id="language.operators"> <title>Operators</title> <simpara> @@ -75,7 +75,9 @@ things: <informalexample> <programlisting role="php"> +<![CDATA[ $a = ($b = 4) + 5; // $a is equal to 9 now, and $b has been set to 4. +]]> </programlisting> </informalexample> </para> @@ -86,10 +88,12 @@ value to the result of that expression. For example: <informalexample> <programlisting role="php"> +<![CDATA[ $a = 3; $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!"; +]]> </programlisting> </informalexample> </para> @@ -245,7 +249,9 @@ which operates as in C and many other languages. <informalexample> <programlisting> +<![CDATA[ (expr1) ? (expr2) : (expr3); +]]> </programlisting> </informalexample> This expression evaluates to <replaceable>expr2</replaceable> if @@ -272,7 +278,8 @@ <para> <informalexample> <programlisting role="php"> -<?php +<![CDATA[ +<?php /* Intentional file error */ $my_file = @file ('non_existent_file') or die ("Failed opening file: error was '$php_errormsg'"); @@ -281,7 +288,8 @@ $value = @$cache[$key]; // will not issue a notice if the index $key doesn't exist. -?> +?> +]]> </programlisting> </informalexample> </para> @@ -321,8 +329,10 @@ assigned to a variable). <informalexample> <programlisting role="php"> +<![CDATA[ $output = `ls -al`; -echo "<pre>$output</pre>"; +echo "<pre>$output</pre>"; +]]> </programlisting> </informalexample> </para> @@ -384,27 +394,29 @@ Here's a simple example script: <informalexample> <programlisting role="php"> -<?php -echo "<h3>Postincrement</h3>"; +<![CDATA[ +<?php +echo "<h3>Postincrement</h3>"; $a = 5; -echo "Should be 5: " . $a++ . "<br>\n"; -echo "Should be 6: " . $a . "<br>\n"; +echo "Should be 5: " . $a++ . "<br>\n"; +echo "Should be 6: " . $a . "<br>\n"; -echo "<h3>Preincrement</h3>"; +echo "<h3>Preincrement</h3>"; $a = 5; -echo "Should be 6: " . ++$a . "<br>\n"; -echo "Should be 6: " . $a . "<br>\n"; +echo "Should be 6: " . ++$a . "<br>\n"; +echo "Should be 6: " . $a . "<br>\n"; -echo "<h3>Postdecrement</h3>"; +echo "<h3>Postdecrement</h3>"; $a = 5; -echo "Should be 5: " . $a-- . "<br>\n"; -echo "Should be 4: " . $a . "<br>\n"; +echo "Should be 5: " . $a-- . "<br>\n"; +echo "Should be 4: " . $a . "<br>\n"; -echo "<h3>Predecrement</h3>"; +echo "<h3>Predecrement</h3>"; $a = 5; -echo "Should be 4: " . --$a . "<br>\n"; -echo "Should be 4: " . $a . "<br>\n"; -?> +echo "Should be 4: " . --$a . "<br>\n"; +echo "Should be 4: " . $a . "<br>\n"; +?> +]]> </programlisting> </informalexample> </para> @@ -593,11 +605,13 @@ <para> <informalexample> <programlisting role="php"> +<![CDATA[ $a = "Hello "; $b = $a . "World!"; // now $b contains "Hello World!" $a = "Hello "; $a .= "World!"; // now $a contains "Hello World!" +]]> </programlisting> </informalexample> </para> Index: phpdoc/en/language/references.xml diff -u phpdoc/en/language/references.xml:1.17 phpdoc/en/language/references.xml:1.18 --- phpdoc/en/language/references.xml:1.17 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/language/references.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.17 $ --> +<!-- $Revision: 1.18 $ --> <chapter id="language.references"> <title>References Explained</title> @@ -24,7 +24,9 @@ same content. Meaning, when you do: <informalexample> <programlisting role="php"> -$a =& $b +<![CDATA[ +$a =& $b +]]> </programlisting> </informalexample> it means that <varname>$a</varname> and <varname>$b</varname> @@ -44,8 +46,10 @@ and with <literal>new</literal> operator (in PHP 4.0.4 and later): <informalexample> <programlisting role="php"> -$bar =& new fooclass(); -$foo =& find_var ($bar); +<![CDATA[ +$bar =& new fooclass(); +$foo =& find_var ($bar); +]]> </programlisting> </informalexample> </para> @@ -65,13 +69,15 @@ a variable in the calling scope reference to the same content. Example: <informalexample> <programlisting role="php"> -function foo (&$var) +<![CDATA[ +function foo (&$var) { $var++; } $a=5; foo ($a); +]]> </programlisting> </informalexample> will make <varname>$a</varname> to be 6. This happens because in @@ -93,11 +99,13 @@ following construct won't do what you expect: <informalexample> <programlisting role="php"> +<![CDATA[ function foo (&$var) { - $var =& $GLOBALS["baz"]; + $var =& $GLOBALS["baz"]; } foo($bar); +]]> </programlisting> </informalexample> </para> @@ -122,7 +130,8 @@ its arguments. The syntax is as follows: <informalexample> <programlisting role="php"> -function foo (&$var) +<![CDATA[ +function foo (&$var) { $var++; } @@ -130,6 +139,7 @@ $a=5; foo ($a); // $a is 6 here +]]> </programlisting> </informalexample> Note that there's no reference sign on function call - only on @@ -154,12 +164,14 @@ Reference, returned from a function, i.e.: <informalexample> <programlisting role="php"> -function &bar() +<![CDATA[ +function &bar() { $a = 5; return $a; } foo(bar()); +]]> </programlisting> </informalexample> See also explanations about <link @@ -174,7 +186,8 @@ by reference are invalid: <informalexample> <programlisting role="php"> -function bar() // Note the missing & +<![CDATA[ +function bar() // Note the missing & { $a = 5; return $a; @@ -183,9 +196,10 @@ foo($a = 5) // Expression, not variable foo(5) // Constant, not variable +]]> </programlisting> </informalexample> -These requirements are for PHP 4.0.4 and later. + These requirements are for PHP 4.0.4 and later. </para> </sect1> @@ -197,14 +211,16 @@ returning references, use this syntax: <informalexample> <programlisting role="php"> -function &find_var ($param) +<![CDATA[ +function &find_var ($param) { ...code... return $found_var; } -$foo =& find_var ($bar); +$foo =& find_var ($bar); $foo->x = 2; +]]> </programlisting> </informalexample> In this example, the property of the object returned by the @@ -230,9 +246,11 @@ variable content will be destroyed. For example: <informalexample> <programlisting role="php"> +<![CDATA[ $a = 1; $b =& $a; unset ($a); +]]> </programlisting> </informalexample> won't unset <varname>$b</varname>, just <varname>$a</varname>. @@ -261,7 +279,9 @@ this is the same as: <informalexample> <programlisting role="php"> -$var =& $GLOBALS["var"]; +<![CDATA[ +$var =& $GLOBALS["var"]; +]]> </programlisting> </informalexample> </para> Index: phpdoc/en/language/types.xml diff -u phpdoc/en/language/types.xml:1.65 phpdoc/en/language/types.xml:1.66 --- phpdoc/en/language/types.xml:1.65 Fri Nov 23 16:10:34 2001 +++ phpdoc/en/language/types.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.65 $ --> +<!-- $Revision: 1.66 $ --> <chapter id="language.types"> <title>Types</title> @@ -157,7 +157,9 @@ <!-- technically they are just constants --> <informalexample> <programlisting role="php"> +<![CDATA[ $foo = True; // assign the value TRUE to $foo +]]> </programlisting> </informalexample> </para> @@ -169,19 +171,21 @@ structure</link>. <informalexample> <programlisting role="php"> +<![CDATA[ if ($action == "show_version") { // == is an <link linkend="language.operators">operator</link> which returns a <type>boolean</type> echo "The version is 1.23"; } // this is not necessary: if ($show_separators == true) { - echo "<hr>\n"; + echo "<hr>\n"; } // because you can simply type this: if ($show_separators) { - echo "<hr>\n"; + echo "<hr>\n"; } +]]> </programlisting> </informalexample> </para> @@ -282,10 +286,12 @@ <example> <title>Integer literals</title> <programlisting role="php"> +<![CDATA[ $a = 1234; # decimal number $a = -123; # a negative number $a = 0123; # octal number (equivalent to 83 decimal) $a = 0x1A; # hexadecimal number (equivalent to 26 decimal) +]]> </programlisting> </example> <!-- @@ -320,6 +326,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ $large_number = 2147483647; var_dump($large_number); // output: int(2147483647) @@ -336,6 +343,7 @@ $large_number = 50000 * $million; var_dump($large_number); // output: float(50000000000) +]]> </programlisting> </informalexample> <warning> @@ -359,8 +367,10 @@ operators, or with type-jug) --> <informalexample> <programlisting role="php"> +<![CDATA[ var_dump( 25/7 ); // output: float(3.5714285714286) +]]> </programlisting> </informalexample> </para> @@ -412,7 +422,9 @@ sometimes lead to unexpected results. <informalexample> <programlisting role="php"> +<![CDATA[ echo (int) ( (0.1+0.7) * 10 ); // echoes 7! +]]> </programlisting> </informalexample> @@ -578,6 +590,7 @@ </note> <informalexample> <programlisting role="php"> +<![CDATA[ echo 'this is a simple string'; echo 'You can also have embedded newlines in strings, like this way.'; @@ -589,6 +602,7 @@ // output: ... delete C:\*.*? echo 'I am trying to include at this point: \n a newline'; // output: ... this point: \n a newline +]]> </programlisting> </informalexample> </para> @@ -717,8 +731,9 @@ <example> <title>Here doc string quoting example</title> <programlisting role="php"> -<?php -$str = <<<EOD +<![CDATA[ +<?php +$str = <<<EOD Example of string spanning multiple lines using heredoc syntax. @@ -732,20 +747,21 @@ function foo() { - $this->foo = 'Foo'; - $this->bar = array('Bar1', 'Bar2', 'Bar3'); + $this->foo = 'Foo'; + $this->bar = array('Bar1', 'Bar2', 'Bar3'); } } $foo = new foo(); $name = 'MyName'; -echo <<<EOT +echo <<<EOT My name is "$name". I am printing some $foo->foo. -Now, I am printing some {$foo->bar[1]}. +Now, I am printing some {$foo->bar[1]}. This should print a capital 'A': \x41 EOT; ?> +]]> </programlisting> </example> </para> @@ -789,10 +805,12 @@ </simpara> <informalexample> <programlisting role="php"> +<![CDATA[ $beer = 'Heineken'; echo "$beer's taste is great"; // works, "'" is an invalid character for varnames echo "He drunk some $beers"; // won't work, 's' is a valid character for varnames echo "He drunk some ${beer}s"; // works +]]> </programlisting> </informalexample> <simpara> @@ -813,12 +831,13 @@ </simpara> <informalexample> <programlisting role="php"> -$fruits = array( 'strawberry' => 'red' , 'banana' => 'yellow' ); +<![CDATA[ +$fruits = array( 'strawberry' => 'red' , 'banana' => 'yellow' ); echo "A banana is $fruits[banana]."; // note that this works differently outside string-quotes. See <link linkend="language.types.array.foo-bar"><literal>$foo[bar]</literal> outside strings</link> -echo "This square is $square->width meters broad."; -echo "This square is $square->width00 centimeters broad."; // won't work, +echo "This square is $square->width meters broad."; +echo "This square is $square->width00 centimeters broad."; // won't work, // for a solution, see the <link linkend="language.types.string.parsing.complex">complex syntax</link>. <!-- XXX this won't work: @@ -827,7 +846,7 @@ // XXX: like the $obj->{expr} syntax outside a string works, // XXX: analogously to the ${expr} syntax for variable var's. --> - +]]> </programlisting> </informalexample> <simpara> @@ -851,16 +870,17 @@ </simpara> <informalexample> <programlisting role="php"> +<![CDATA[ $great = 'fantastic'; echo "This is { $great}"; // won't work, outputs: This is { fantastic} echo "This is {$great}"; // works, outputs: This is fantastic -echo "This square is {$square->width}00 centimeters broad."; +echo "This square is {$square->width}00 centimeters broad."; echo "This works: {$arr[4][3]}"; echo "This is wrong: {$arr[foo][3]}"; // for the same reason // as <link linkend="language.types.array.foo-bar">$foo[bar]</link > is wrong outside a string. echo "You should do it this way: {$arr['foo'][3]}"; -echo "You can even write {$obj->values[3]->name}"; +echo "You can even write {$obj->values[3]->name}"; echo "This is the value of the var named $name: {${$name}}"; <!-- <xxx> maybe it's better to leave this out?? // this works, but i disencourage its use, since this is NOT @@ -868,6 +888,7 @@ $beer = 'Heineken'; echo "I'd like to have another {${ strrev('reeb') }}, hips"; </xxx> --> +]]> </programlisting> </informalexample> </sect4> @@ -890,10 +911,11 @@ <example> <title>Some string examples</title> <programlisting role="php"> +<![CDATA[ <!-- TODO: either move these examples to a example section, as with arrays, or distribute them under the applicable sections. --> -<?php +<?php /* Assigning a string. */ $str = "This is a string"; @@ -903,13 +925,13 @@ /* Another way to append, includes an escaped newline. */ $str .= " and a newline at the end.\n"; -/* This string will end up being '<p>Number: 9</p>' */ +/* This string will end up being '<p>Number: 9</p>' */ $num = 9; -$str = "<p>Number: $num</p>"; +$str = "<p>Number: $num</p>"; -/* This one will be '<p>Number: $num</p>' */ +/* This one will be '<p>Number: $num</p>' */ $num = 9; -$str = '<p>Number: $num</p>'; +$str = '<p>Number: $num</p>'; /* Get the first character of a string */ $str = 'This is a test.'; @@ -918,7 +940,8 @@ /* Get the last character of a string. */ $str = 'This is still a test.'; $last = $str{strlen($str)-1}; -?> +?> +]]> </programlisting> </example> </para> @@ -982,6 +1005,7 @@ </simpara> <informalexample> <programlisting role="php"> +<![CDATA[ $foo = 1 + "10.5"; // $foo is float (11.5) $foo = 1 + "-1.3e3"; // $foo is float (-1299) $foo = 1 + "bob-1.3e3"; // $foo is integer (1) @@ -990,6 +1014,7 @@ $foo = 1 + "10 Little Piggies"; // $foo is integer (11) $foo = "10.0 pigs " + 1; // $foo is integer (11) $foo = "10.0 pigs " + 1.0; // $foo is float (11) +]]> </programlisting> </informalexample> <simpara> @@ -1002,7 +1027,9 @@ to see for yourself what's going on: <informalexample> <programlisting role="php"> -echo "\$foo==$foo; type is " . gettype ($foo) . "<br>\n"; +<![CDATA[ +echo "\$foo==$foo; type is " . gettype ($foo) . "<br>\n"; +]]> </programlisting> </informalexample> </para> @@ -1156,9 +1183,11 @@ You might have seen the following syntax in old scripts: <informalexample> <programlisting role="php"> +<![CDATA[ $foo[bar] = 'enemy'; echo $foo[bar]; // etc +]]> </programlisting> </informalexample> This is wrong, but it works. Then, why is it wrong? The reason is @@ -1168,7 +1197,9 @@ That means that you can write things like this: <informalexample> <programlisting role="php"> +<![CDATA[ echo $arr[ foo(true) ]; +]]> </programlisting> </informalexample> This is an example of using a function return value @@ -1178,9 +1209,11 @@ <informalexample> <programlisting role="php"> +<![CDATA[ $error_descriptions[E_ERROR] = "A fatal error has occured"; $error_descriptions[E_WARNING] = "PHP issued a warning"; $error_descriptions[E_NOTICE] = "This is just an informal notice"; +]]> </programlisting> </informalexample> Note that <literal>E_ERROR</literal> is also a valid identifier, @@ -1188,9 +1221,11 @@ example is in fact the same as writing: <informalexample> <programlisting role="php"> +<![CDATA[ $error_descriptions[1] = "A fatal error has occured"; $error_descriptions[2] = "PHP issued a warning"; $error_descriptions[8] = "This is just an informal notice"; +]]> </programlisting> </informalexample> because <literal>E_ERROR</literal> equals <literal>1</literal>, etc. @@ -1252,6 +1287,7 @@ <para> <informalexample> <programlisting role="php"> +<![CDATA[ // this $a = array( 'color' => 'red' , 'taste' => 'sweet' @@ -1272,6 +1308,7 @@ $b[] = 'c'; // will result in the array array( 0 => 'a' , 1 => 'b' , 2 => 'c' ), // or simply array('a', 'b', 'c') +]]> </programlisting> </informalexample> </para> @@ -1279,11 +1316,12 @@ <example> <title>Using array()</title> <programlisting role="php"> +<![CDATA[ // Array as (property-)map -$map = array( 'version' => 4 - , 'OS' => 'Linux' - , 'lang' => 'english' - , 'short_tags' => true +$map = array( 'version' => 4 + , 'OS' => 'Linux' + , 'lang' => 'english' + , 'short_tags' => true ); // strictly numerical keys @@ -1293,16 +1331,16 @@ , 156 , -10 ); -// this is the same as array( 0 => 7, 1 => 8, ...) +// this is the same as array( 0 => 7, 1 => 8, ...) $switching = array( 10 // key = 0 - , 5 => 6 - , 3 => 7 - , 'a' => 4 + , 5 => 6 + , 3 => 7 + , 'a' => 4 , 11 // key = 6 (maximum of integer-indices was 5) - , '8' => 2 // key = 8 (integer!) - , '02' => 77 // key = '02' - , 0 => 12 // the value 10 will be overwritten by 12 + , '8' => 2 // key = 8 (integer!) + , '02' => 77 // key = '02' + , 0 => 12 // the value 10 will be overwritten by 12 ); <!-- TODO example of @@ -1314,13 +1352,15 @@ --> // empty array -$empty = array(); +$empty = array(); +]]> </programlisting> </example> <example id="language.types.array.examples.loop"> <title>Collection</title> <programlisting role="php"> +<![CDATA[ $colors = array('red','blue','green','yellow'); foreach ( $colors as $color ) { @@ -1333,6 +1373,7 @@ Do you like green? Do you like yellow? */ +]]> </programlisting> </example> Index: phpdoc/en/language/variables.xml diff -u phpdoc/en/language/variables.xml:1.23 phpdoc/en/language/variables.xml:1.24 --- phpdoc/en/language/variables.xml:1.23 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/language/variables.xml Fri Nov 23 16:51:23 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.23 $ --> +<!-- $Revision: 1.24 $ --> <chapter id="language.variables"> <title>Variables</title> @@ -29,6 +29,7 @@ <para> <informalexample> <programlisting role="php"> +<![CDATA[ $var = "Bob"; $Var = "Joe"; echo "$var, $Var"; // outputs "Bob, Joe" @@ -36,6 +37,7 @@ $4site = 'not yet'; // invalid; starts with a number $_4site = 'not yet'; // valid; starts with an underscore $täyte = 'mansikka'; // valid; 'ä' is ASCII 228. +]]> </programlisting> </informalexample> </para> @@ -68,13 +70,14 @@ <informalexample> <programlisting role="php"> -<?php +<![CDATA[ +<?php $foo = 'Bob'; // Assign the value 'Bob' to $foo -$bar = &$foo; // Reference $foo via $bar. +$bar = &$foo; // Reference $foo via $bar. $bar = "My name is $bar"; // Alter $bar... echo $foo; // $foo is altered too. echo $bar; -?> +?> </programlisting> </informalexample> </para> @@ -84,10 +87,10 @@ assigned by reference. <informalexample> <programlisting role="php"> -<?php +<?php $foo = 25; -$bar = &$foo; // This is a valid assignment. -$bar = &(24 * 7); // Invalid; references an unnamed expression. +$bar = &$foo; // This is a valid assignment. +$bar = &(24 * 7); // Invalid; references an unnamed expression. function test() { @@ -95,7 +98,8 @@ } $bar = &test(); // Invalid. -?> +?> +]]> </programlisting> </informalexample> </para> @@ -584,8 +588,10 @@ </simpara> <informalexample> <programlisting role="php"> +<![CDATA[ $a = 1; include "b.inc"; +]]> </programlisting> </informalexample> <simpara> @@ -598,6 +604,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ $a = 1; /* global scope */ function Test() @@ -606,6 +613,7 @@ } Test(); +]]> </programlisting> </informalexample> @@ -624,6 +632,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ $a = 1; $b = 2; @@ -636,6 +645,7 @@ Sum(); echo $b; +]]> </programlisting> </informalexample> @@ -655,6 +665,7 @@ <informalexample> <programlisting role="php"> +<![CDATA[ $a = 1; $b = 2; @@ -665,6 +676,7 @@ Sum(); echo $b; +]]> </programlisting> </informalexample> @@ -684,12 +696,14 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function Test () { $a = 0; echo $a; $a++; } +]]> </programlisting> </informalexample> @@ -705,12 +719,14 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function Test() { static $a = 0; echo $a; $a++; } +]]> </programlisting> </informalexample> @@ -731,17 +747,19 @@ <informalexample> <programlisting role="php"> +<![CDATA[ function Test() { static $count = 0; $count++; echo $count; - if ($count < 10) { + if ($count < 10) { Test (); } $count--; } +]]> </programlisting> </informalexample> @@ -758,7 +776,9 @@ <informalexample> <programlisting role="php"> +<![CDATA[ $a = "hello"; +]]> </programlisting> </informalexample> @@ -771,7 +791,9 @@ <informalexample> <programlisting role="php"> +<![CDATA[ $$a = "world"; +]]> </programlisting> </informalexample> @@ -784,7 +806,9 @@ <informalexample> <programlisting role="php"> +<![CDATA[ echo "$a ${$a}"; +]]> </programlisting> </informalexample> @@ -794,7 +818,9 @@ <informalexample> <programlisting role="php"> +<![CDATA[ echo "$a $hello"; +]]> </programlisting> </informalexample> @@ -843,10 +869,12 @@ <example> <title>Simple form variable</title> <programlisting role="php"> -<form action="foo.php" method="post"> - Name: <input type="text" name="username"><br> - <input type="submit"> -</form> +<![CDATA[ +<form action="foo.php" method="post"> + Name: <input type="text" name="username"><br> + <input type="submit"> +</form> +]]> </programlisting> </example> </para> @@ -882,17 +910,19 @@ <example> <title>More complex form variables</title> <programlisting role="php"> -<form action="array.php" 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"> -</form> +<![CDATA[ +<form action="array.php" 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"> +</form> +]]> </programlisting> </example> </para> @@ -911,7 +941,9 @@ <informalexample> <programlisting role="php"> -<input type="image" src="image.gif" name="sub"> +<![CDATA[ +<input type="image" src="image.gif" name="sub"> +]]> </programlisting> </informalexample> @@ -951,7 +983,9 @@ <informalexample> <programlisting role="php"> +<![CDATA[ setcookie("MyCookie[]", "Testing", time()+3600); +]]> </programlisting> </informalexample> @@ -965,9 +999,11 @@ <example> <title>SetCookie Example</title> <programlisting role="php"> +<![CDATA[ $Count++; setcookie("Count", $Count, time()+3600); setcookie("Cart[$Count]", $item, time()+3600); +]]> </programlisting> </example> @@ -982,7 +1018,9 @@ <informalexample> <programlisting role="php"> +<![CDATA[ echo $HOME; /* Shows the HOME environment variable, if set. */ +]]> </programlisting> </informalexample> </para> @@ -1007,7 +1045,9 @@ dot (period, full stop) is not a valid character in a PHP variable name. For the reason, look at it: <programlisting role="php"> +<![CDATA[ $varname.ext; /* invalid variable name */ +]]> </programlisting> Now, what the parser sees is a variable named <varname>$varname</varname>, followed by the string concatenation Index: phpdoc/en/pear/benchmark_timer.xml diff -u phpdoc/en/pear/benchmark_timer.xml:1.8 phpdoc/en/pear/benchmark_timer.xml:1.9 --- phpdoc/en/pear/benchmark_timer.xml:1.8 Sun Nov 11 20:48:41 2001 +++ phpdoc/en/pear/benchmark_timer.xml Fri Nov 23 16:51:24 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.8 $ --> +<!-- $Revision: 1.9 $ --> <refentry id="class.benchmark-timer"> <refnamediv> <refname>Benchmark_Timer</refname> @@ -17,15 +17,17 @@ <refsect1> <example id="example.pear.benchmark.timer"> <programlisting role="php"> +<![CDATA[ require_once 'Benchmark/Timer.php'; $timer = new Benchmark_Timer; -$timer->setMarker('start of for() loop'); -for ($i = 0; $i < 1000; $i++) { /* ... */ } -$timer->setMarker('end of for() loop'); +$timer->setMarker('start of for() loop'); +for ($i = 0; $i < 1000; $i++) { /* ... */ } +$timer->setMarker('end of for() loop'); echo 'The for() loop took ' . -$timer->timeElapsed('start of for() loop', 'end of for() loop'); +$timer->timeElapsed('start of for() loop', 'end of for() loop'); +]]> </programlisting> </example> </refsect1> Index: phpdoc/en/pear/pear.xml diff -u phpdoc/en/pear/pear.xml:1.11 phpdoc/en/pear/pear.xml:1.12 --- phpdoc/en/pear/pear.xml:1.11 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/pear/pear.xml Fri Nov 23 16:51:24 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.11 $ --> +<!-- $Revision: 1.12 $ --> <reference id="pear.reference"> <title>PEAR Reference Manual</title> @@ -61,8 +61,10 @@ instantiate your class with the "=& new" operator like this: <programlisting role="php"> -$obj =& new MyClass(); -</programlisting> +<![CDATA[ +$obj =& new MyClass(); +]]> + </programlisting> </para> <simpara> If you only use "= new", the object registered in PEAR's @@ -115,6 +117,7 @@ <example id="example.pear.destructors"> <title>PEAR: emulated destructors</title> <programlisting role="php"> +<![CDATA[ require_once "PEAR.php"; class FileContainer extends PEAR @@ -157,13 +160,13 @@ } } -$fileobj =& new FileContainer("testfile"); +$fileobj =& new FileContainer("testfile"); $fileobj->append("this ends up at the end of the file\n"); // When the request is done and PHP shuts down, $fileobj's // "destructor" is called and updates the file on disk. - -</programlisting> +]]> + </programlisting> </example> <note> <simpara> @@ -188,6 +191,7 @@ <example id="example.pear.error1"> <title>PEAR error example (1)</title> <programlisting role="php"> +<![CDATA[ function mysockopen($host = "localhost", $port = 8090) { $fp = fsockopen($host, $port, $errno, $errstr); @@ -199,9 +203,10 @@ $sock = mysockopen(); if (PEAR::isError($sock)) { - print "mysockopen error: ".$sock->getMessage()."<BR>\n" + print "mysockopen error: ".$sock->getMessage()."<BR>\n" } -</programlisting> +]]> + </programlisting> </example> </para> <simpara> @@ -223,6 +228,7 @@ <example id="example.pear.error2"> <title>PEAR error example (2)</title> <programlisting role="php"> +<![CDATA[ class TCP_Socket extends PEAR { var $sock; @@ -244,8 +250,9 @@ $sock = new TCP_Socket; $sock->setErrorHandling(PEAR_ERROR_DIE); $sock->connect("localhost", 8090); -print "still alive<BR>\n"; -</programlisting> +print "still alive<BR>\n"; +]]> + </programlisting> </example> </para> <simpara> @@ -284,8 +291,10 @@ method like this: <informalexample> <programlisting role="php"> +<![CDATA[ PEAR::setErrorHandling(PEAR_ERROR_DIE); -</programlisting> +]]> + </programlisting> </informalexample> </para> </listitem> @@ -306,8 +315,10 @@ method like this: <informalexample> <programlisting role="php"> +<![CDATA[ PEAR::setErrorHandling(PEAR_ERROR_TRIGGER, E_USER_ERROR); -</programlisting> +]]> + </programlisting> </informalexample> </para> </listitem> @@ -332,8 +343,10 @@ method like this: <informalexample> <programlisting role="php"> +<![CDATA[ PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, "my_error_handler"); -</programlisting> +]]> + </programlisting> </informalexample> </para> <para> @@ -341,13 +354,15 @@ without specifying the callback function again: <informalexample> <programlisting role="php"> +<![CDATA[ PEAR::setErrorMode(PEAR_ERROR_CALLBACK, "my_function_handler"); do_some_stuff(); PEAR::setErrorMode(PEAR_ERROR_DIE); do_some_critical_stuff(); PEAR::setErrorMode(PEAR_ERROR_CALLBACK); // now we're back to using my_function_handler again -</programlisting> +]]> + </programlisting> </informalexample> </para> </listitem> @@ -371,6 +386,7 @@ <example> <title>PEAR Class Constructor Example</title> <programlisting role="php"> +<![CDATA[ class MyClass extends PEAR { var $foo, $bar; @@ -381,7 +397,8 @@ $this->bar = $bar; } } -</programlisting> +]]> + </programlisting> </example> </para> </refsect2> Index: phpdoc/en/pear/standards.xml diff -u phpdoc/en/pear/standards.xml:1.14 phpdoc/en/pear/standards.xml:1.15 --- phpdoc/en/pear/standards.xml:1.14 Sat Nov 10 16:49:43 2001 +++ phpdoc/en/pear/standards.xml Fri Nov 23 16:51:24 2001 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.14 $ --> +<!-- $Revision: 1.15 $ --> <chapter id="pear.standards"> <title>PEAR Coding Standards</title> <note> @@ -17,6 +17,7 @@ hook that will set up Emacs according to these guidelines (you will need to ensure that it is called when you are editing PHP files): <programlisting role="elisp"> +<![CDATA[ (defun php-mode-hook () (setq tab-width 4 c-basic-offset 4 @@ -25,14 +26,17 @@ (not (and (string-match "/\\(PEAR\\|pear\\)/" (buffer-file-name)) (string-match "\.php$" (buffer-file-name)))))) -</programlisting> +]]> + </programlisting> </para> <para>Here are vim rules for the same thing: <programlisting role="vim"> +<![CDATA[ set expandtab set shiftwidth=4 set tabstop=4 -</programlisting> +]]> + </programlisting> </para> </sect1> @@ -42,14 +46,16 @@ These include if, for, while, switch, etc. Here is an example if statement, since it is the most complicated of them: <programlisting role="php"> +<![CDATA[ if ((condition1) || (condition2)) { action1; -} elseif ((condition3) && (condition4)) { +} elseif ((condition3) && (condition4)) { action2; } else { defaultaction; } -</programlisting> +]]> + </programlisting> </para> <simpara> Control statements should have one space between the control keyword @@ -64,6 +70,7 @@ <para> For switch statements: <programlisting role="php"> +<![CDATA[ switch (condition) { case 1: action1; @@ -78,7 +85,8 @@ break; } -</programlisting> +]]> + </programlisting> </para> </sect1> @@ -91,8 +99,10 @@ parameter, the closing parenthesis, and the semicolon. Here's an example: <programlisting role="php"> +<![CDATA[ $var = foo($bar, $baz, $quux); -</programlisting> +]]> + </programlisting> </para> <para> As displayed above, there should be one space on either side of an @@ -100,9 +110,11 @@ variable. In the case of a block of related assignments, more space may be inserted to promote readability: <programlisting role="php"> +<![CDATA[ $short = foo($bar); $long_variable = foo($baz); -</programlisting> +]]> + </programlisting> </para> </sect1> @@ -111,6 +123,7 @@ <para> Function declaractions follow the "one true brace" convention: <programlisting role="php"> +<![CDATA[ function fooFunction($arg1, $arg2 = '') { if (condition) { @@ -118,6 +131,7 @@ } return $val; } +]]> </programlisting> </para> <para> @@ -125,10 +139,11 @@ Always attempt to return a meaningful value from a function if one is appropriate. Here is a slightly longer example: <programlisting role="php"> -function connect(&$dsn, $persistent = false) +<![CDATA[ +function connect(&$dsn, $persistent = false) { if (is_array($dsn)) { - $dsninfo = &$dsn; + $dsninfo = &$dsn; } else { $dsninfo = DB::parseDSN($dsn); } @@ -139,6 +154,7 @@ return true; } +]]> </programlisting> </para> </sect1> @@ -200,6 +216,7 @@ All source code files in the core PEAR distribution should contain the following comment block as the header: <programlisting role="php"> +<![CDATA[ /* vim: set expandtab tabstop=4 shiftwidth=4: */ // +----------------------------------------------------------------------+ // | PHP version 4.0 | @@ -214,12 +231,13 @@ // | obtain it through the world-wide-web, please send a note to | // | license@php.net so we can mail you a copy immediately. | // +----------------------------------------------------------------------+ -// | Authors: Original Author <author@example.com> | -// | Your Name <you@example.com> | +// | Authors: Original Author <author@example.com> | +// | Your Name <you@example.com> | // +----------------------------------------------------------------------+ // -// $Id$ -</programlisting> +// $Id: standards.xml,v 1.15 2001/11/23 21:51:24 hholzgra Exp $ +]]> + </programlisting> </para> <para> There's no hard rule to determine when a new code contributer