sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-15 16:38:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Normalized according to the DocBook 3.1 DTD. This mostly just adds

Browse source 
closing tags and attribute quotes, but lets a stock 3.1 install
compile the PHP docs. It still compiles with DocBook 3.0, as well.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@14695 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
cslawi 1999-10-20 22:54:01 +00:00
parent 94287a133d
commit aeb2d5524e
24 changed files with 616 additions and 698 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
appendices/debugger.sgml
View file

@ -1,4 +1,3 @@
<appendix id="debugger">
<title>The PHP Debugger</title>
@ -11,29 +10,27 @@
for every time PHP starts up. All error messages from that request
will be sent to this TCP connection. This information is intended
for "debugging server" that can run inside an
<acronym>IDE</acronym> or programmable editor (such as Emacs).
<acronym>IDE</acronym> or programmable editor (such as Emacs).</para>
<para>
How to set up the debugger:
<orderedlist>
<listitem><simpara> Set up a TCP port for the debugger in the <link
linkend="configuration.file">configuration file</link> (<link
linkend="ini.debugger.port">debugger.port</link>) and enable it
(<link linkend="ini.debugger.enabled">debugger.enabled</link>).
<listitem><simpara> Set up a TCP port for the debugger in the <link linkend="configuration.file">configuration file</link> (<link linkend="ini.debugger.port">debugger.port</link>) and enable it
(<link linkend="ini.debugger.enabled">debugger.enabled</link>).</simpara></listitem>
<listitem><simpara> Set up a TCP listener on that port somewhere
(for example <command>socket -l -s 1400</command> on UNIX).
(for example <command>socket -l -s 1400</command> on UNIX).</simpara></listitem>
<listitem><simpara> In your code, run
"debugger_on(<replaceable>host</replaceable>)", where
<replaceable>host</replaceable> is the IP number or name of the
host running the <acronym>TCP</acronym> listener.
host running the <acronym>TCP</acronym> listener.</simpara></listitem>
</orderedlist>
Now, all warnings, notices etc. will show up on that listener
socket, <emphasis>even if you them turned off with
<function>error_reporting</function></emphasis>.
<function>error_reporting</function></emphasis>.</para></sect1>
<sect1 id="debugger-protocol">
<title>Debugger Protocol</title>
@ -43,7 +40,7 @@
<emphasis>message</emphasis>. Each message starts with a line of the
type <literal>start</literal> and terminates with a line of the
type <literal>end</literal>. PHP may send lines for different
messages simultaneously.
messages simultaneously.</para>
<para>
A line has this format:

54
appendices/migration.sgml
View file

@ -1,4 +1,3 @@
<appendix id="migration">
<title>Migrating from PHP/FI 2.0 to PHP 3.0</title>
@ -9,26 +8,25 @@
that is much more robust and consistent than 2.0's. 3.0 is also
significantly faster, and uses less memory. However, some of
these improvements have not been possible without compatibility
changes, both in syntax and functionality.
changes, both in syntax and functionality.</simpara>
<simpara>
In addition, PHP's developers have tried to clean up both PHP's
syntax and semantics in version 3.0, and this has also caused some
incompatibilities. In the long run, we believe that these changes
are for the better.
are for the better.</simpara>
<simpara>
This chapter will try to guide you through the incompatibilities
you might run into when going from PHP/FI 2.0 to PHP 3.0 and help
you resolve them. New features are not mentioned here unless
necessary.
necessary.</simpara>
<simpara>
A conversion program that can automatically convert your old
PHP/FI 2.0 scripts exists. It can be found in the <filename
class=directory>convertor</filename> subdirectory of the PHP 3.0
PHP/FI 2.0 scripts exists. It can be found in the <filename class="directory">convertor</filename> subdirectory of the PHP 3.0
distribution. This program only catches the syntax changes though,
so you should read this chapter carefully anyway.
so you should read this chapter carefully anyway.</simpara></sect1>
<sect1 id="migration-startendtags">
<title>Start/end tags</title>
@ -74,7 +72,7 @@
echo "This is PHP 3.0 code!\n";
&lt;/script&gt;
</programlisting></example>
</programlisting></example></para></sect1>
<sect1 id="migration-if-endif">
@ -109,7 +107,7 @@ endif;
</programlisting></example>
Notice that the semicolons have been replaced by colons in all
statements but the one terminating the expression (endif).
statements but the one terminating the expression (endif).</para></sect1>
<sect1 id="migration-while">
<title>while syntax</title>
@ -134,7 +132,7 @@ endwhile;
If you use the old while..endwhile syntax in PHP 3.0, you will get
a never-ending loop.
</simpara>
</warning>
</warning></sect1>
<sect1 id="migration-expr">
<title>Expression types</title>
@ -142,8 +140,8 @@ endwhile;
PHP/FI 2.0 used the left side of expressions to determine what type
the result should be. PHP 3.0 takes both sides into account when
determining result types, and this may cause 2.0 scripts to behave
unexpectedly in 3.0.
<simpara>
unexpectedly in 3.0.</simpara>
<simpara></simpara>
<para>
Consider this example:
@ -175,7 +173,7 @@ while ("" != $key) {
The fix for this is simple. Replace the while statement with:
<informalexample><programlisting>
while ((string)$key != "") {
</programlisting></informalexample>
</programlisting></informalexample></para></sect1>
<sect1 id="migration-errors">
@ -185,7 +183,7 @@ while ((string)$key != "") {
but you no longer get to see the code fragment causing the error.
You will be supplied with a file name and a line number for the
error, though.
</simpara>
</simpara></sect1>
<sect1 id="migration-booleval">
@ -195,11 +193,11 @@ while ((string)$key != "") {
in an expression like <literal>(1 || test_me())</literal>, the
function <function>test_me</function> would not be executed since
nothing can change the result of the expression after the
<literal>1</literal>.
<literal>1</literal>.</simpara>
<simpara>
This is a minor compatibility issue, but may cause unexpected
side-effects.
side-effects.</simpara></sect1>
<sect1 id="migration-truefalse">
@ -212,7 +210,7 @@ while ((string)$key != "") {
fail("darn!");</literal>. Because PHP/FI 2.0 had no clear rules
for what functions should return when they failed, most such
scripts will probably have to be checked manually after using the
2.0 to 3.0 convertor.
2.0 to 3.0 convertor.</simpara>
<para>
<example>
<title>Migration from 2.0: return values, old code</title>
@ -228,7 +226,7 @@ endif;
<programlisting>
$fp = @fopen($file, "r") or print("Could not open $file for reading&lt;br&gt;\n");
</programlisting>
</example>
</example></para></sect1>
<sect1 id="migration-other">
@ -237,38 +235,38 @@ $fp = @fopen($file, "r") or print("Could not open $file for reading&lt;br&gt;\n"
<itemizedlist>
<listitem><simpara>
The PHP 3.0 Apache module no longer supports Apache versions
prior to 1.2. Apache 1.2 or later is required.
prior to 1.2. Apache 1.2 or later is required.</simpara></listitem>
<listitem><simpara> <function>echo</function> no longer
supports a format string. Use the
<function>printf</function> function instead.
<function>printf</function> function instead.</simpara></listitem>
<listitem><simpara>
In PHP/FI 2.0, an implementation side-effect caused
<literal>$foo[0]</literal> to have the same effect as
<literal>$foo</literal>. This is not true for PHP 3.0.
<literal>$foo</literal>. This is not true for PHP 3.0.</simpara></listitem>
<listitem><simpara>
Reading arrays with <literal>$array[]</literal> is no longer
supported
supported</simpara>
<simpara>
That is, you cannot traverse an array by having a loop that does
<literal>$data = $array[]</literal>. Use
<function>current</function> and <function>next</function>
instead.
instead.</simpara>
<simpara>
Also, <literal>$array1[] = $array2</literal> does not append the
values of <literal>$array2</literal> to <literal>$array1</literal>,
but appends <literal>$array2</literal> as the last entry of
<literal>$array1</literal>. See also multidimensional array
support.
support.</simpara></listitem>
<listitem>
<simpara> <literal>"+"</literal> is no longer overloaded as a
concatenation operator for strings, instead it converts it's
arguments to numbers and performs numeric addition. Use
<literal>"."</literal> instead.
<literal>"."</literal> instead.</simpara></listitem>
</itemizedlist>
<example>
@ -289,7 +287,7 @@ echo "1"."1";
$a = 1;
$b = 1;
echo $a + $b;
</programlisting>
</programlisting></para>
<para>
This would echo 2 in both PHP 2.0 and 3.0.
@ -299,8 +297,8 @@ $a = 1;
$b = 1;
echo $a.$b;
</programlisting>
This will echo 11 in PHP 3.0.
</example>
This will echo 11 in PHP 3.0.</para>
</example></sect1>
</appendix>

236
appendices/phpdevel.sgml
View file

@ -15,7 +15,7 @@ void php3_foo(INTERNAL_FUNCTION_PARAMETERS) {
}
</programlisting>
Even if your function doesn't take any arguments, this is how it is
called.
called.</para></sect2>
<sect2 id="phpdevel-addfunc-args">
<title>Function Arguments</title>
@ -23,7 +23,7 @@ void php3_foo(INTERNAL_FUNCTION_PARAMETERS) {
Arguments are always of type pval. This type contains a union
which has the actual type of the argument. So, if your function
takes two arguments, you would do something like the following at
the top of your function:
the top of your function:</para>
<para>
<example>
@ -40,27 +40,27 @@ if (ARG_COUNT(ht) != 2 || getParameters(ht,2,&amp;arg1,&amp;arg2)==FAILURE) {
both cases you will need to pass &amp;(pval *) to getParameters. If
you want to check if the n'th parameter was sent to you by
reference or not, you can use the function,
ParameterPassedByReference(ht,n). It will return either 1 or 0.
ParameterPassedByReference(ht,n). It will return either 1 or 0.</para>
<simpara>
When you change any of the passed parameters, whether they are
sent by reference or by value, you can either start over with the
parameter by calling pval_destructor on it, or if it's an ARRAY
you want to add to, you can use functions similar to the ones in
internal_functions.h which manipulate return_value as an ARRAY.
internal_functions.h which manipulate return_value as an ARRAY.</simpara>
<simpara>
Also if you change a parameter to IS_STRING make sure you first
assign the new estrdup()'ed string and the string length, and only
later change the type to IS_STRING. If you change the string of a
parameter which already IS_STRING or IS_ARRAY you should run
pval_destructor on it first.
pval_destructor on it first.</simpara></sect2>
<sect2 id="phpdevel-addfunc-varargs">
<title>Variable Function Arguments</title>
<para>
A function can take a variable number of arguments. If your function can
take either 2 or 3 arguments, use the following:
take either 2 or 3 arguments, use the following:</para>
<para>
<example>
@ -74,7 +74,7 @@ if (arg_count &lt; 2 || arg_count &gt; 3 ||
WRONG_PARAM_COUNT;
}
</programlisting>
</example>
</example></para></sect2>
<sect2 id="phpdevel-addfunc-using-args">
<title>Using the Function Arguments</title>
@ -124,7 +124,7 @@ if (arg_count &lt; 2 || arg_count &gt; 3 ||
</row>
</tbody>
</tgroup>
</table>
</table></para>
<para>
If you get an argument of one type and would like to use it as
@ -138,18 +138,18 @@ convert_to_double(arg1);
convert_to_string(arg1);
convert_to_boolean_long(arg1); /* If the string is "" or "0" it becomes 0, 1 otherwise */
convert_string_to_number(arg1); /* Converts string to either LONG or DOUBLE depending on string */
</programlisting>
</programlisting></para>
<simpara>
These function all do in-place conversion. They do not return anything.
These function all do in-place conversion. They do not return anything.</simpara>
<para>
The actual argument is stored in a union; the members are:
<itemizedlist>
<listitem><simpara>IS_STRING: arg1-&gt;value.str.val
<listitem><simpara>IS_LONG: arg1-&gt;value.lval
<listitem><simpara>IS_DOUBLE: arg1-&gt;value.dval
</itemizedlist>
<listitem><simpara>IS_STRING: arg1-&gt;value.str.val</simpara></listitem>
<listitem><simpara>IS_LONG: arg1-&gt;value.lval</simpara></listitem>
<listitem><simpara>IS_DOUBLE: arg1-&gt;value.dval</simpara></listitem>
</itemizedlist></para></sect2>
<sect2 id="phpdevel-addfunc-memmgmt">
<title>Memory Management in Functions</title>
@ -157,7 +157,7 @@ convert_string_to_number(arg1); /* Converts string to either LONG or DOUBLE dep
Any memory needed by a function should be allocated with either
emalloc() or estrdup(). These are memory handling abstraction
functions that look and smell like the normal malloc() and
strdup() functions. Memory should be freed with efree().
strdup() functions. Memory should be freed with efree().</simpara>
<simpara>
There are two kinds of memory in this program: memory which is
@ -167,7 +167,7 @@ convert_string_to_number(arg1); /* Converts string to either LONG or DOUBLE dep
make sure you first allocate the memory with either emalloc() or
estrdup(). This memory should NEVER be freed by you, unless you
later in the same function overwrite your original assignment
(this kind of programming practice is not good though).
(this kind of programming practice is not good though).</simpara>
<simpara>
For any temporary/permanent memory you need in your
@ -179,12 +179,12 @@ convert_string_to_number(arg1); /* Converts string to either LONG or DOUBLE dep
leak. The meaning of "the functions behave exactly like their
counterparts" is: if you efree() something which was not
emalloc()'ed nor estrdup()'ed you might get a segmentation
fault. So please take care and free all of your wasted memory.
fault. So please take care and free all of your wasted memory.</simpara>
<simpara>
If you compile with "-DDEBUG", PHP3 will print out a list of all
memory that was allocated using emalloc() and estrdup() but never
freed with efree() when it is done running the specified script.
freed with efree() when it is done running the specified script.</simpara></sect2>
<sect2 id="phpdevel-addfunc-symtab">
<title>Setting Variables in the Symbol Table</title>
@ -193,31 +193,31 @@ convert_string_to_number(arg1); /* Converts string to either LONG or DOUBLE dep
variable in the symbol table:
<itemizedlist>
<listitem><simpara>SET_VAR_STRING(name,value) <footnoteref linkend="symtab-1">
<listitem><simpara>SET_VAR_DOUBLE(name,value)
<listitem><simpara>SET_VAR_LONG(name,value)
</itemizedlist>
<listitem><simpara>SET_VAR_STRING(name,value) <footnoteref linkend="symtab-1"></simpara></listitem>
<listitem><simpara>SET_VAR_DOUBLE(name,value)</simpara></listitem>
<listitem><simpara>SET_VAR_LONG(name,value)</simpara></listitem>
</itemizedlist></para>
<para>
<footnote id="symtab-1">
<simpara>
Be careful here. The value part must be malloc'ed manually because
the memory management code will try to free this pointer later. Do
not pass statically allocated memory into a SET_VAR_STRING.
</footnote>
not pass statically allocated memory into a SET_VAR_STRING.</simpara>
</footnote></para>
<simpara>
Symbol tables in PHP 3.0 are implemented as hash tables. At any
given time, &amp;symbol_table is a pointer to the 'main' symbol
table, and active_symbol_table points to the currently active
symbol table (these may be identical like in startup, or
different, if you're inside a function).
different, if you're inside a function).</simpara>
<para>
The following examples use 'active_symbol_table'. You should
replace it with &amp;symbol_table if you specifically want to work
with the 'main' symbol table. Also, the same functions may be
applied to arrays, as explained below.
applied to arrays, as explained below.</para>
<para>
<example>
@ -238,18 +238,18 @@ check(pvalue.type);
Arrays in PHP 3.0 are implemented using the same hashtables as
symbol tables. This means the two above functions can also be
used to check variables inside arrays.
used to check variables inside arrays.</para>
<simpara>
If you want to define a new array in a symbol table, you should do
the following.
the following.</simpara>
<simpara>
First, you may want to check whether it exists and abort
appropiately, using hash_exists() or hash_find().
appropiately, using hash_exists() or hash_find().</simpara>
<simpara>
Next, initialize the array:
Next, initialize the array:</simpara>
<para>
<example>
@ -263,10 +263,10 @@ hash_update(active_symbol_table,"foo",sizeof("foo"),&amp;arr,sizeof(pval),NULL);
</example>
This code declares a new array, named $foo, in the active symbol
table. This array is empty.
table. This array is empty.</para>
<simpara>
Here's how to add new entries to it:
Here's how to add new entries to it:</simpara>
<para>
<example>
@ -295,22 +295,22 @@ hash_next_index_insert(arr.value.ht,&amp;entry,sizeof(pval),NULL);
you can supply a pval ** to the hash add function, and it'll be
updated with the pval * address of the inserted element inside the
hash. If that value is NULL (like in all of the above examples) -
that parameter is ignored.
that parameter is ignored.</para>
<simpara>
hash_next_index_insert() uses more or less the same logic as
"$foo[] = bar;" in PHP 2.0.
"$foo[] = bar;" in PHP 2.0.</simpara>
<simpara>
If you are building an array to return from a function, you can
initialize the array just like above by doing:
initialize the array just like above by doing:</simpara>
<programlisting>
if (array_init(return_value) == FAILURE) { failed...; }
</programlisting>
<simpara>
...and then adding values with the helper functions:
...and then adding values with the helper functions:</simpara>
<programlisting>
add_next_index_long(return_value,long_value);
@ -327,68 +327,68 @@ pval *arr;
if (hash_find(active_symbol_table,"foo",sizeof("foo"),(void **)&amp;arr)==FAILURE) { can't find... }
else { use arr-&gt;value.ht... }
</programlisting>
</programlisting></para>
<simpara>
Note that hash_find receives a pointer to a pval pointer, and not
a pval pointer.
a pval pointer.</simpara>
<simpara>
Just about any hash function returns SUCCESS or FAILURE (except
for hash_exists(), which returns a boolean truth value).
for hash_exists(), which returns a boolean truth value).</simpara></sect2>
<sect2 id="phpdevel-addfunc-retsimple">
<title>Returning simple values</title>
<simpara>
A number of macros are available to make returning values from a
function easier.
function easier.</simpara>
<para>
The RETURN_* macros all set the return value and return from the
function:
<itemizedlist>
<listitem><simpara>RETURN
<listitem><simpara>RETURN_FALSE
<listitem><simpara>RETURN_TRUE
<listitem><simpara>RETURN_LONG(l)
<listitem><simpara>RETURN_STRING(s,dup) If dup is true, duplicates the string
<listitem><simpara>RETURN_STRINGL(s,l,dup) Return string (s) specifying length (l).
<listitem><simpara>RETURN_DOUBLE(d)
</itemizedlist>
<listitem><simpara>RETURN</simpara></listitem>
<listitem><simpara>RETURN_FALSE</simpara></listitem>
<listitem><simpara>RETURN_TRUE</simpara></listitem>
<listitem><simpara>RETURN_LONG(l)</simpara></listitem>
<listitem><simpara>RETURN_STRING(s,dup) If dup is true, duplicates the string</simpara></listitem>
<listitem><simpara>RETURN_STRINGL(s,l,dup) Return string (s) specifying length (l).</simpara></listitem>
<listitem><simpara>RETURN_DOUBLE(d)</simpara></listitem>
</itemizedlist></para>
<para>
The RETVAL_* macros set the return value, but do not return.
<itemizedlist>
<listitem><simpara>RETVAL_FALSE
<listitem><simpara>RETVAL_TRUE
<listitem><simpara>RETVAL_LONG(l)
<listitem><simpara>RETVAL_STRING(s,dup) If dup is true, duplicates the string
<listitem><simpara>RETVAL_STRINGL(s,l,dup) Return string (s) specifying length (l).
<listitem><simpara>RETVAL_DOUBLE(d)
</itemizedlist>
<listitem><simpara>RETVAL_FALSE</simpara></listitem>
<listitem><simpara>RETVAL_TRUE</simpara></listitem>
<listitem><simpara>RETVAL_LONG(l)</simpara></listitem>
<listitem><simpara>RETVAL_STRING(s,dup) If dup is true, duplicates the string</simpara></listitem>
<listitem><simpara>RETVAL_STRINGL(s,l,dup) Return string (s) specifying length (l).</simpara></listitem>
<listitem><simpara>RETVAL_DOUBLE(d)</simpara></listitem>
</itemizedlist></para>
<simpara>
The string macros above will all estrdup() the passed 's'
argument, so you can safely free the argument after calling the
macro, or alternatively use statically allocated memory.
macro, or alternatively use statically allocated memory.</simpara>
<simpara>
If your function returns boolean success/error responses, always
use RETURN_TRUE and RETURN_FALSE respectively.
use RETURN_TRUE and RETURN_FALSE respectively.</simpara></sect2>
<sect2 id="phpdevel-addfunc-retcomplex">
<title>Returning complex values</title>
<simpara>
Your function can also return a complex data type such as an
object or an array.
object or an array.</simpara>
<para>
Returning an object:
<orderedlist numeration="arabic">
<listitem><simpara>Call object_init(return_value).
<listitem><simpara>Call object_init(return_value).</simpara></listitem>
<listitem><para>Fill it up with values. The functions available
for this purpose are listed below.
for this purpose are listed below.</para></listitem>
<listitem><para> Possibly, register functions for this object.
In order to obtain values from the object, the function would
have to fetch "this" from the active_symbol_table. Its type
@ -397,80 +397,80 @@ else { use arr-&gt;value.ht... }
actual registration of the function can be done using:
<programlisting>
add_method( return_value, function_name, function_ptr );
</programlisting>
</orderedlist>
</programlisting></para></listitem>
</orderedlist></para>
<para>
The functions used to populate an object are:
<itemizedlist>
<listitem><simpara>add_property_long( return_value,
property_name, l ) - Add a property named 'property_name', of
type long, equal to 'l'
type long, equal to 'l'</simpara></listitem>
<listitem><simpara>add_property_double( return_value,
property_name, d ) - Same, only adds a double
property_name, d ) - Same, only adds a double</simpara></listitem>
<listitem><simpara>add_property_string( return_value,
property_name, str ) - Same, only adds a string
property_name, str ) - Same, only adds a string</simpara></listitem>
<listitem><simpara>add_property_stringl( return_value,
property_name, str, l ) - Same, only adds a string of length 'l'
</itemizedlist>
property_name, str, l ) - Same, only adds a string of length 'l'</simpara></listitem>
</itemizedlist></para>
<para>
Returning an array:
<orderedlist numeration="arabic">
<listitem><simpara>Call array_init(return_value).
<listitem><simpara>Call array_init(return_value).</simpara></listitem>
<listitem><simpara>Fill it up with values. The functions available
for this purpose are listed below.
</orderedlist>
for this purpose are listed below.</simpara></listitem>
</orderedlist></para>
<para>
The functions used to populate an array are:
<itemizedlist>
<listitem><simpara>add_assoc_long(return_value,key,l) - add
associative entry with key 'key' and long value 'l'
<listitem><simpara>add_assoc_double(return_value,key,d)
<listitem><simpara>add_assoc_string(return_value,key,str,duplicate)
associative entry with key 'key' and long value 'l'</simpara></listitem>
<listitem><simpara>add_assoc_double(return_value,key,d)</simpara></listitem>
<listitem><simpara>add_assoc_string(return_value,key,str,duplicate)</simpara></listitem>
<listitem><simpara>add_assoc_stringl(return_value,key,str,length,duplicate)
specify the string length
specify the string length</simpara></listitem>
<listitem><simpara>add_index_long(return_value,index,l) - add
entry in index 'index' with long value 'l'
<listitem><simpara>add_index_double(return_value,index,d)
<listitem><simpara>add_index_string(return_value,index,str)
entry in index 'index' with long value 'l'</simpara></listitem>
<listitem><simpara>add_index_double(return_value,index,d)</simpara></listitem>
<listitem><simpara>add_index_string(return_value,index,str)</simpara></listitem>
<listitem><simpara>add_index_stringl(return_value,index,str,length)
- specify the string length
- specify the string length</simpara></listitem>
<listitem><simpara>add_next_index_long(return_value,l) - add an
array entry in the next free offset with long value 'l'
<listitem><simpara>add_next_index_double(return_value,d)
<listitem><simpara>add_next_index_string(return_value,str)
array entry in the next free offset with long value 'l'</simpara></listitem>
<listitem><simpara>add_next_index_double(return_value,d)</simpara></listitem>
<listitem><simpara>add_next_index_string(return_value,str)</simpara></listitem>
<listitem><simpara>add_next_index_stringl(return_value,str,length)
- specify the string length
</itemizedlist>
- specify the string length</simpara></listitem>
</itemizedlist></para></sect2>
<sect2 id="phpdevel-addfunc-reslist">
<title>Using the resource list</title>
<simpara>
PHP 3.0 has a standard way of dealing with various types of
resources. This replaces all of the local linked lists in PHP 2.0.
resources. This replaces all of the local linked lists in PHP 2.0.</simpara>
<para>
Available functions:
<itemizedlist>
<listitem><simpara>php3_list_insert(ptr, type) - returns the 'id'
of the newly inserted resource
of the newly inserted resource</simpara></listitem>
<listitem><simpara>php3_list_delete(id) - delete the resource
with the specified id
with the specified id</simpara></listitem>
<listitem><simpara>php3_list_find(id,*type)
- returns the pointer of the resource with the specified id,
updates 'type' to the resource's type
updates 'type' to the resource's type</simpara></listitem>
</itemizedlist>
Typically, these functions are used for SQL drivers but they can
be used for anything else; for instance, maintaining file
descriptors.
descriptors.</para>
<simpara>
Typical list code would look like this:
Typical list code would look like this:</simpara>
<para>
<example>
@ -518,7 +518,7 @@ php3_list_delete(resource_id-&gt;value.lval);
list_entry_type. In addition, one should add shutdown code for
any new resource type defined, in list.c's list_entry_destructor()
(even if you don't have anything to do on shutdown, you must add
an empty case).
an empty case).</para></sect2>
<sect2 id="phpdevel-addfunc-prestable">
<title>Using the persistent resource table</title>
@ -533,13 +533,13 @@ php3_list_delete(resource_id-&gt;value.lval);
<member>php3_mysql_do_connect</member>
<member>php3_mysql_connect()</member>
<member>php3_mysql_pconnect()</member>
</simplelist>
</simplelist></para>
<para>
The general idea of persistence modules is this:
<orderedlist numeration="arabic">
<listitem><simpara>Code all of your module to work with the
regular resource list mentioned in section (9).
regular resource list mentioned in section (9).</simpara></listitem>
<listitem><simpara>Code extra connect functions that check if the
resource already exists in the persistent resource list. If it
does, register it as in the regular resource list as a pointer to
@ -551,27 +551,27 @@ php3_list_delete(resource_id-&gt;value.lval);
resource would be found in the persistent resource list and be
used without having to recreate it. You should register these
resources with a different type (e.g. LE_MYSQL_LINK for
non-persistent link and LE_MYSQL_PLINK for a persistent link).
</orderedlist>
non-persistent link and LE_MYSQL_PLINK for a persistent link).</simpara></listitem>
</orderedlist></para>
<simpara>
If you read mysql.c, you'll notice that except for the more
complex connect function, nothing in the rest of the module has to
be changed.
be changed.</simpara>
<simpara>
The very same interface exists for the regular resource list and
the persistent resource list, only 'list' is replaced with
'plist':
'plist':</simpara>
<itemizedlist>
<listitem><simpara>php3_plist_insert(ptr, type) - returns the 'id'
of the newly inserted resource
of the newly inserted resource</simpara></listitem>
<listitem><simpara>php3_plist_delete(id) - delete the resource
with the specified id
with the specified id</simpara></listitem>
<listitem><simpara>php3_plist_find(id,*type)
- returns the pointer of the resource with the specified id,
updates 'type' to the resource's type
updates 'type' to the resource's type</simpara></listitem>
</itemizedlist>
<simpara>
@ -584,11 +584,11 @@ php3_list_delete(resource_id-&gt;value.lval);
that were passed to the function, and hashes the SQL link with
this string as a key. The next time someone calls a pconnect()
with the same host/user/passwd, the same key would be generated,
and the function would find the SQL link in the persistent list.
and the function would find the SQL link in the persistent list.</simpara>
<simpara>
Until further documented, you should look at mysql.c or msql.c to
see how one should use the plist's hash table abilities.
see how one should use the plist's hash table abilities.</simpara>
<simpara>
One important thing to note: resources going into the persistent
@ -599,7 +599,7 @@ php3_list_delete(resource_id-&gt;value.lval);
hit), every memory chunk that was allocated using PHP's memory
manager is deleted. Since the persistent list isn't supposed to
be erased at the end of a request, one mustn't use PHP's memory
manager for allocating resources that go to it.
manager for allocating resources that go to it.</simpara>
<simpara>
When you register a resource that's going to be in the persistent
@ -612,7 +612,7 @@ php3_list_delete(resource_id-&gt;value.lval);
every resource, even it requires no destructotion and the
destructor would be empty. Remember, since emalloc() and friends
aren't to be used in conjunction with the persistent list, you
mustn't use efree() here either.
mustn't use efree() here either.</simpara></sect2>
<sect2 id="phpdevel-addfunc-addcfg">
@ -626,36 +626,36 @@ php3_list_delete(resource_id-&gt;value.lval);
basis. This means that one directory may have a certain
safemodeexecdir for example, while another directory may have
another. This configuration granularity is especially handy when
a server supports multiple virtual hosts.
a server supports multiple virtual hosts.</para>
<para>
The steps required to add a new directive:
<orderedlist>
<listitem><simpara>Add directive to php3_ini_structure struct in mod_php3.h.
<listitem><simpara>Add directive to php3_ini_structure struct in mod_php3.h.</simpara></listitem>
<listitem><simpara>In main.c, edit the php3_module_startup
function and add the appropriate cfg_get_string() or
cfg_get_long() call.
cfg_get_long() call.</simpara></listitem>
<listitem><simpara>Add the directive, restrictions and a comment
to the php3_commands structure in mod_php3.c. Note the
restrictions part. RSRC_CONF are directives that can only be
present in the actual Apache .conf files. Any OR_OPTIONS
directives can be present anywhere, include normal .htaccess
files.
files.</simpara></listitem>
<listitem><simpara>In either php3take1handler() or
php3flaghandler() add the appropriate entry for your directive.
php3flaghandler() add the appropriate entry for your directive.</simpara></listitem>
<listitem><simpara>In the configuration section of the
_php3_info() function in functions/info.c you need to add your
new directive.
new directive.</simpara></listitem>
<listitem><simpara>And last, you of course have to use your new
directive somewhere. It will be addressable as
php3_ini.directive.
</orderedlist>
php3_ini.directive.</simpara></listitem>
</orderedlist></para></sect2></sect1>
<sect1 id="calling-user-functions">
@ -689,7 +689,7 @@ php3_list_delete(resource_id-&gt;value.lval);
<title>HashTable *function_table</title>
<simpara>
This is the hash table in which the function is to be looked up.
</simpara>
</simpara></sect2>
<sect2 id="calling-user-functions.object">
<title>pval *object</title>
@ -701,7 +701,7 @@ php3_list_delete(resource_id-&gt;value.lval);
be modified by the function that is invoked on it (that function
will have access to it via $this). If for some reason you don't
want that to happen, send a copy of the object instead.
</simpara>
</simpara></sect2>
<sect2 id="calling-user-functions.function-name">
<title>pval *function_name</title>
@ -711,7 +711,7 @@ php3_list_delete(resource_id-&gt;value.lval);
set to the appropriate values. The function_name is modified by
call_user_function() - it's converted to lowercase. If you need to
preserve the case, send a copy of the function name instead.
</simpara>
</simpara></sect2>
<sect2 id="calling-user-functions.retval">
<title>pval *retval</title>
@ -720,13 +720,13 @@ php3_list_delete(resource_id-&gt;value.lval);
the invoked function is saved. The structure must be previously
allocated - <function>call_user_function</function> does NOT allocate
it by itself.
</simpara>
</simpara></sect2>
<sect2 id="calling-user-functions.param-count">
<title>int param_count</title>
<simpara>
The number of parameters being passed to the function.
</simpara>
</simpara></sect2>
<sect2 id="calling-user-functions.params">
<title>pval *params[]</title>
@ -737,7 +737,7 @@ php3_list_delete(resource_id-&gt;value.lval);
are sent as-is to the function, which means if the function modifies
its arguments, the original values are changed (passing by reference).
If you don't want that behavior, pass a copy instead.
</simpara>
</simpara></sect2></sect1>
<sect1 id="phpdevel-errors">
<title>Reporting Errors</title>
@ -805,6 +805,8 @@ php3_list_delete(resource_id-&gt;value.lval);
</simpara>
</sect2>
</sect1>
</appendix>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

87
chapters/config.sgml
View file

@ -9,17 +9,17 @@
PHP 3.0, and simply <filename>php.ini</filename> as of PHP 4.0)
is read when PHP starts up. For the server module versions of PHP,
this happens only once when the web server is started. For the
<acronym>CGI</acronym> version, it happens on every invocation.
<acronym>CGI</acronym> version, it happens on every invocation.</simpara>
<simpara>
When using PHP as an Apache module, you can also change the
configuration settings using directives in Apache configuration
files and .htaccess files.
files and .htaccess files.</simpara>
<simpara>
With PHP 3.0, there are Apache directives that correspond to each
configuration setting in the <filename>php3.ini</filename> name,
except the name is prefixed by "php3_".
except the name is prefixed by "php3_".</simpara>
<para>
With PHP 4.0, there are just a few Apache directives that allow you
@ -33,7 +33,7 @@
</term>
<listitem>
<para>
This sets the value of the specified variable.
This sets the value of the specified variable.</para>
</listitem>
</varlistentry>
<varlistentry>
@ -44,7 +44,7 @@
</term>
<listitem>
<para>
This is used to set a Boolean configuration option.
This is used to set a Boolean configuration option.</para>
</listitem>
</varlistentry>
<varlistentry>
@ -58,7 +58,7 @@
This sets the value of the specified variable. "Admin"
configuration settings can only be set from within the
main Apache configuration files, and not from .htaccess
files.
files.</para>
</listitem>
</varlistentry>
<varlistentry>
@ -69,16 +69,16 @@
</term>
<listitem>
<para>
This is used to set a Boolean configuration option.
This is used to set a Boolean configuration option.</para>
</listitem>
</varlistentry>
</variablelist>
</variablelist></para>
<simpara>
You can view the settings of the configuration values in
the output of <function>phpinfo</function>. You can also
access the values of individial configuration settings using
<function>get_cfg_var</function>.
<function>get_cfg_var</function>.</simpara>
<sect2 id="ini.sect.general">
<title>General Configuration Directives</title>
@ -95,8 +95,7 @@
Enables the use of ASP-like &lt;% %&gt; tags in addition to
the usual &lt;?php ?&gt; tags. This includes the
variable-value printing shorthand of &lt;%= $value %&gt;. For
more information, see <link
linkend="language.basic-syntax.phpmode">Escaping from HTML</link>.
more information, see <link linkend="language.basic-syntax.phpmode">Escaping from HTML</link>.
</simpara>
<note>
@ -116,15 +115,14 @@
Specifies the name of a file that is automatically parsed
after the main file. The file is included as if it was
called with the <function>include</function> function, so
<link linkend="ini.include-path">include_path</link> is used.
<link linkend="ini.include-path">include_path</link> is used.</para>
<para>
The special value <systemitem
class="constant">none</systemitem> disables auto-appending.
The special value <systemitem class="constant">none</systemitem> disables auto-appending.
<note>
<simpara>
If the script is terminated with <function>exit</function>,
auto-append will <emphasis>not</emphasis> occur.
</note>
auto-append will <emphasis>not</emphasis> occur.</simpara>
</note></para>
</listitem>
</varlistentry>
@ -138,10 +136,9 @@
Specifies the name of a file that is automatically parsed
before the main file. The file is included as if it was
called with the <function>include</function> function, so
<link linkend="ini.include-path">include_path</link> is used.
<link linkend="ini.include-path">include_path</link> is used.</para>
<para>
The special value <systemitem
class="constant">none</systemitem> disables auto-prepending.
The special value <systemitem class="constant">none</systemitem> disables auto-prepending.</para>
</listitem>
</varlistentry>
@ -177,8 +174,7 @@
<listitem>
<para>
PHP's "root directory" on the server. Only used if
non-empty. If PHP is configured with <link
linkend="ini.safe-mode">safe mode</link>, no files outside
non-empty. If PHP is configured with <link linkend="ini.safe-mode">safe mode</link>, no files outside
this directory are served.
</para>
</listitem>
@ -213,7 +209,7 @@
special value <literal>syslog</literal> is used, the errors
are sent to the system logger instead. On UNIX, this means
syslog(3) and on Windows NT it means the event log. The
system logger is not supported on Windows 95.
system logger is not supported on Windows 95.</para>
</listitem>
</varlistentry>
@ -344,18 +340,18 @@
colon in UNIX or semicolon in Windows.
<example>
<title>UNIX include_path</title>
<programlisting role=php3.ini>
<programlisting role="php3.ini">
include_path=.:/home/httpd/php-lib
</programlisting>
</example>
<example>
<title>Windows include_path</title>
<programlisting role=php3.ini>
<programlisting role="php3.ini">
include_path=".;c:\www\phplib"
</programlisting>
</example>
The default value for this directive is <literal>.</literal>
(only the current directory).
(only the current directory).</para>
</listitem>
</varlistentry>
@ -378,7 +374,7 @@ include_path=".;c:\www\phplib"
<listitem>
<para>
Tells whether script error messages should be logged to the
server's error log. This option is thus server-specific.
server's error log. This option is thus server-specific.</para>
</listitem>
</varlistentry>
@ -482,7 +478,7 @@ include_path=".;c:\www\phplib"
PHP's open tag should be allowed. If you want to use PHP in
combination with XML, you have to disable this option. If
disabled, you must use the long form of the open tag
(<userinput>&lt;?php ?></userinput>).
(<userinput>&lt;?php ?></userinput>).</para>
</listitem>
</varlistentry>
@ -505,7 +501,7 @@ include_path=".;c:\www\phplib"
<listitem>
<para>
If enabled, the last error message will always be present in the
global variable <symbol>$php_errormsg</symbol>.
global variable <symbol>$php_errormsg</symbol>.</para>
</listitem>
</varlistentry>
@ -519,7 +515,7 @@ include_path=".;c:\www\phplib"
If enabled, GET, POST and cookie input can be found in the
global associative arrays <symbol>$HTTP_GET_VARS</symbol>,
<symbol>$HTTP_POST_VARS</symbol> and
<symbol>$HTTP_COOKIE_VARS</symbol>, respectively.
<symbol>$HTTP_COOKIE_VARS</symbol>, respectively.</para>
</listitem>
</varlistentry>
@ -532,7 +528,7 @@ include_path=".;c:\www\phplib"
<para>
The temporary directory used for storing files when doing
file upload. Must be writable by whatever user PHP is
running as.
running as.</para>
</listitem>
</varlistentry>
@ -545,7 +541,7 @@ include_path=".;c:\www\phplib"
<para>
The base name of the directory used on a user's home
directory for PHP files, for example
<literal>public_html</literal>.
<literal>public_html</literal>.</para>
</listitem>
</varlistentry>
@ -560,7 +556,7 @@ include_path=".;c:\www\phplib"
plus (<literal>+</literal>) operator is used on strings.
This is to make it easier to find scripts that need to be
rewritten to using the string concatenator instead
(<literal>.</literal>).
(<literal>.</literal>).</para>
</listitem>
</varlistentry>
@ -581,7 +577,7 @@ include_path=".;c:\www\phplib"
<para>
DNS name or IP address of the SMTP server PHP under Windows
should use for mail sent with the <function>mail</function>
function.
function.</para>
</listitem>
</varlistentry>
@ -593,7 +589,7 @@ include_path=".;c:\www\phplib"
<listitem>
<para>
Which "From:" mail address should be used in mail sent from
PHP under Windows.
PHP under Windows.</para>
</listitem>
</varlistentry>
@ -609,13 +605,13 @@ include_path=".;c:\www\phplib"
<filename>/usr/lib/sendmail</filename>
<command>configure</command> does an honest attempt of
locating this one for you and set a default, but if it fails,
you can set it here.
you can set it here.</para>
<para>
Systems not using sendmail should set this directive to the
sendmail wrapper/replacement their mail system offers, if any.
For example, <ulink url="http://www.qmail.org/">Qmail</ulink>
users can normally set it to
<filename>/var/qmail/bin/sendmail</filename>.
<filename>/var/qmail/bin/sendmail</filename>.</para>
</listitem>
</varlistentry>
@ -633,9 +629,8 @@ include_path=".;c:\www\phplib"
</term>
<listitem>
<para>
Whether to enable PHP's safe mode. Read the <link
linkend="security">Security chapter</link> for more
more information.
Whether to enable PHP's safe mode. Read the <link linkend="security">Security chapter</link> for more
more information.</para>
</listitem>
</varlistentry>
@ -648,7 +643,7 @@ include_path=".;c:\www\phplib"
<para>
If PHP is used in safe mode, <function>system</function> and
the other functions executing system programs refuse to start
programs that are not in this directory.
programs that are not in this directory.</para>
</listitem>
</varlistentry>
@ -666,7 +661,7 @@ include_path=".;c:\www\phplib"
</term>
<listitem>
<para>
DNS name or IP address of host used by the debugger.
DNS name or IP address of host used by the debugger.</para>
</listitem>
</varlistentry>
@ -677,7 +672,7 @@ include_path=".;c:\www\phplib"
</term>
<listitem>
<para>
Port number used by the debugger.
Port number used by the debugger.</para>
</listitem>
</varlistentry>
@ -688,7 +683,7 @@ include_path=".;c:\www\phplib"
</term>
<listitem>
<para>
Whether the debugger is enabled.
Whether the debugger is enabled.</para>
</listitem>
</varlistentry>
@ -732,7 +727,7 @@ include_path=".;c:\www\phplib"
<listitem>
<para>
In what directory PHP should look for dynamically loadable
extensions.
extensions.</para>
</listitem>
</varlistentry>
@ -744,7 +739,7 @@ include_path=".;c:\www\phplib"
<listitem>
<para>
Which dynamically loadable extensions to load when PHP starts
up.
up.</para>
</listitem>
</varlistentry>
@ -762,7 +757,7 @@ include_path=".;c:\www\phplib"
</term>
<listitem>
<para>
Whether to allow persistent MySQL connections.
Whether to allow persistent MySQL connections.</para>
</listitem>
</varlistentry>

8
chapters/copyright.sgml
View file

@ -4,24 +4,24 @@
<simpara>
PHP 3.0 is copyright (C) 1997 the PHP Development Team. The
members of this team are listed in the CREDITS file that comes with
the PHP 3.0 source distribution.
the PHP 3.0 source distribution.</simpara>
<simpara>
PHP 3.0 is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
option) any later version.</simpara>
<simpara>
PHP 3.0 is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
General Public License for more details.</simpara>
<simpara>
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.</simpara>
</chapter>

250
chapters/install.sgml
View file

@ -6,8 +6,7 @@
<simpara>
The source code, and binary distributions for some platforms (including
Windows), can be found at
<literal><ulink
url="http://www.php.net/">http://www.php.net/</ulink></literal>.
<literal><ulink url="http://www.php.net/">http://www.php.net/</ulink></literal>.</simpara>
</sect1>
<sect1 id="install-unix">
@ -85,24 +84,24 @@
Using the "setup" script that comes with PHP. This script
asks you a series of questions (almost like the "install"
script of PHP/FI 2.0) and runs "configure" in the end. To run
this script, type <command>./setup</command>.
this script, type <command>./setup</command>.</para>
<para>
This script will also create a file called "do-conf", this
file will contain the options passed to configure. You can
edit this file to change just a few options without having to
re-run setup. Then type <command>./do-conf</command> to run
configure with the new options.
configure with the new options.</para>
</listitem>
<listitem>
<para>
Running configure by hand. To see what options you have, type
<command>./configure --help</command>.
<command>./configure --help</command>.</para>
</listitem>
</itemizedlist>
</itemizedlist></para>
<para>
Details about some of the different configuration options are
listed below.
listed below.</para></sect2>
<sect2 id="with-apache">
<title>Apache module</title>
@ -113,10 +112,9 @@
--with-apache</link>=<replaceable>DIR</replaceable></option>
option to configure) and specify the Apache distribution base
directory. If you have unpacked your Apache distribution in
<filename class=directory>/usr/local/www/apache_1.2.4</filename>,
<filename class="directory">/usr/local/www/apache_1.2.4</filename>,
this is your Apache distribution base directory. The default
directory is <filename
class=directory>/usr/local/etc/httpd</filename>.
directory is <filename class="directory">/usr/local/etc/httpd</filename>.</para></sect2>
<sect2 id="with-fhttpd">
<title>fhttpd module</title>
@ -126,10 +124,9 @@
fhttpd module?" (the <option><link linkend="with-fhttpd">
--with-fhttpd</link>=<replaceable>DIR</replaceable></option>
option to configure) and specify the fhttpd source base
directory. The default directory is <filename
class=directory>/usr/local/src/fhttpd</filename>. If you are
directory. The default directory is <filename class="directory">/usr/local/src/fhttpd</filename>. If you are
running fhttpd, building PHP as a module will give better
performance, more control and remote execution capability.
performance, more control and remote execution capability.</para></sect2>
<sect2 id="install-cgi">
<title>CGI version</title>
@ -141,14 +138,14 @@
the CGI version enables Apache users to run different
PHP-enabled pages under different user-ids. Please make sure
you read through the <link linkend="security">Security
chapter</link> if you are going to run PHP as a CGI.
chapter</link> if you are going to run PHP as a CGI.</para></sect2>
<sect2>
<title>Database Support Options</title>
<para>
PHP has native support for a number of databases (as well as
ODBC):
ODBC):</para>
<sect3 id="with-adabas">
@ -158,10 +155,9 @@
</synopsis>
<simpara>
Compiles with Adabas D support. The parameter is the Adabas D
install directory and defaults to <filename
class=directory>/usr/local/adabasd</filename>.
install directory and defaults to <filename class="directory">/usr/local/adabasd</filename>.</simpara>
<simpara>
<ulink url="http://www.adabas.com/">Adabas home page</ulink>
<ulink url="http://www.adabas.com/">Adabas home page</ulink></simpara>
</sect3>
<sect3 id="with-dbase">
@ -171,7 +167,7 @@
</synopsis>
<simpara>
Enables the bundled DBase support. No external libraries are
required.
required.</simpara>
</sect3>
<sect3 id="with-filepro">
@ -181,7 +177,7 @@
</synopsis>
<simpara>
Enables the bundled read-only filePro support. No external
libraries are required.
libraries are required.</simpara>
</sect3>
<sect3 id="with-msql">
@ -191,19 +187,18 @@
</synopsis>
<simpara>
Enables mSQL support. The parameter to this option is the mSQL
install directory and defaults to <filename
class=directory>/usr/local/Hughes</filename>. This is the
install directory and defaults to <filename class="directory">/usr/local/Hughes</filename>. This is the
default directory of the mSQL 2.0 distribution.
<command>configure</command> automatically detects which mSQL
version you are running and PHP supports both 1.0 and 2.0, but
if you compile PHP with mSQL 1.0, you can only access mSQL 1.0
databases, and vice-versa.
databases, and vice-versa.</simpara>
<simpara>
See also <link linkend="ini.sect.msql">mSQL Configuration</link>
Directives in the <link linkend="configuration.file">configuration
file</link>.
file</link>.</simpara>
<simpara>
<ulink url="http://www.hughes.com.au">mSQL home page</ulink>
<ulink url="http://www.hughes.com.au">mSQL home page</ulink></simpara>
</sect3>
<sect3 id="with-mysql">
@ -213,15 +208,13 @@
</synopsis>
<simpara>
Enables MySQL support. The parameter to this option is the
MySQL install directory and defaults to <filename
class=directory>/usr/local</filename>. This is the default
installation directory of the MySQL distribution.
MySQL install directory and defaults to <filename class="directory">/usr/local</filename>. This is the default
installation directory of the MySQL distribution.</simpara>
<simpara>
See also <link linkend="ini.sect.mysql">MySQL
Configuration</link> Directives in the <link
linkend="configuration.file">configuration file</link>.
Configuration</link> Directives in the <link linkend="configuration.file">configuration file</link>.</simpara>
<simpara>
<ulink url="http://www.tcx.se">MySQL home page</ulink>
<ulink url="http://www.tcx.se">MySQL home page</ulink></simpara>
</sect3>
<sect3 id="with-iodbc">
@ -234,10 +227,10 @@
iODBC Driver Manager, a freely redistributable ODBC driver
manager which runs under many flavors of UNIX. The parameter to
this option is the iODBC installation directory and defaults to
<filename class=directory>/usr/local</filename>.
<filename class="directory">/usr/local</filename>.</simpara>
<simpara>
<ulink url="http://users.ids.net/~bjepson/freeODBC/">FreeODBC
home page</ulink>
home page</ulink></simpara>
</sect3>
<sect3 id="with-openlink">
@ -248,10 +241,10 @@
<simpara>
Includes OpenLink ODBC support. The parameter to this option is
the OpenLink ODBC installation directory and defaults to
<filename class=directory>/usr/local/openlink</filename>.
<filename class="directory">/usr/local/openlink</filename>.</simpara>
<simpara>
<ulink url="http://www.openlinksw.com/">OpenLink Software's home
page</ulink>
page</ulink></simpara>
</sect3>
<sect3 id="with-oracle">
@ -264,9 +257,9 @@
at least with Oracle versions 7.0 through 7.3. The parameter is
the <envar>ORACLE_HOME</envar> directory. You do not have to
specify this parameter if your Oracle environment has been set
up.
up.</simpara>
<simpara>
<ulink url="http://www.oracle.com">Oracle home page</ulink>
<ulink url="http://www.oracle.com">Oracle home page</ulink></simpara>
</sect3>
<sect3 id="with-pgsql">
@ -276,15 +269,13 @@
</synopsis>
<simpara>
Includes PostgreSQL support. The parameter is the PostgreSQL
base install directory and defaults to <filename
class=directory>/usr/local/pgsql</filename>.
base install directory and defaults to <filename class="directory">/usr/local/pgsql</filename>.</simpara>
<simpara>
See also <link linkend="ini.sect.pgsql">Postgres
Configuration</link> Directives in the <link
linkend="configuration.file">configuration file</link>.
Configuration</link> Directives in the <link linkend="configuration.file">configuration file</link>.</simpara>
<simpara>
<ulink url="http://www.postgreSQL.org/">PostgreSQL home
page</ulink>
page</ulink></simpara>
</sect3>
<sect3 id="with-solid">
@ -294,10 +285,9 @@
</synopsis>
<simpara>
Includes Solid support. The parameter is the Solid install
directory and defaults to <filename
class=directory>/usr/local/solid</filename>.
directory and defaults to <filename class="directory">/usr/local/solid</filename>.</simpara>
<simpara>
<ulink url="http://www.solidtech.com">Solid home page</ulink>
<ulink url="http://www.solidtech.com">Solid home page</ulink></simpara>
</sect3>
<sect3 id="with-sybase">
@ -307,14 +297,12 @@
</synopsis>
<simpara>
Includes Sybase support. The parameter is the Sybase install
directory and defaults to <filename
class=directory>/home/sybase</filename>.
directory and defaults to <filename class="directory">/home/sybase</filename>.</simpara>
<simpara>
See also <link linkend="ini.sect.sybase">Sybase
Configuration</link> Directives in the <link
linkend="configuration.file">configuration file</link>.
Configuration</link> Directives in the <link linkend="configuration.file">configuration file</link>.</simpara>
<simpara>
<ulink url="http://www.sybase.com">Sybase home page</ulink>
<ulink url="http://www.sybase.com">Sybase home page</ulink></simpara>
</sect3>
<sect3 id="with-sybase-ct">
@ -324,12 +312,10 @@
</synopsis>
<simpara>
Includes Sybase-CT support. The parameter is the Sybase-CT
install directory and defaults to <filename
class=directory>/home/sybase</filename>.
install directory and defaults to <filename class="directory">/home/sybase</filename>.</simpara>
<simpara>
See also <link linkend="ini.sect.sybct">Sybase-CT
Configuration</link> Directives in the <link
linkend="configuration.file">configuration file</link>.
Configuration</link> Directives in the <link linkend="configuration.file">configuration file</link>.</simpara>
</sect3>
<sect3 id="with-velocis">
@ -339,10 +325,9 @@
</synopsis>
<simpara>
Includes Velocis support. The parameter is the Velocis install
directory and defaults to <filename
class=directory>/usr/local/velocis</filename>.
directory and defaults to <filename class="directory">/usr/local/velocis</filename>.</simpara>
<simpara>
<ulink url="http://www.raima.com">Velocis home page</ulink>
<ulink url="http://www.raima.com">Velocis home page</ulink></simpara>
</sect3>
<sect3 id="with-custom-odbc">
@ -352,22 +337,21 @@
</synopsis>
<simpara>
Includes support for an arbitrary custom ODBC library. The
parameter is the base directory and defaults to <filename
class=directory>/usr/local</filename>.
parameter is the base directory and defaults to <filename class="directory">/usr/local</filename>.</simpara>
<simpara>
This option implies that you have defined CUSTOM_ODBC_LIBS when
you run the configure script. You also must have a valid odbc.h
header somewhere in your include path. If you don't have one,
create it and include your specific header from there. Your
header may also require some extra definitions, particularly
when it is multiplatform. Define them in CFLAGS.
when it is multiplatform. Define them in CFLAGS.</simpara>
<simpara>
For example, you can use Sybase SQL Anywhere on QNX as
following:
<literal>
CFLAGS=-DODBC_QNX LDFLAGS=-lunix CUSTOM_ODBC_LIBS="-ldblib
-lodbc" ./configure --with-custom-odbc=/usr/lib/sqlany50
</literal>
</literal></simpara>
</sect3>
<sect3 id="disable-unified-odbc">
@ -383,16 +367,10 @@
Anywhere. Requires that one (and only one) of these modules or
the Velocis module is enabled, or a custom ODBC library
specified. This option is only applicable if one of the
following options is used: <link
linkend="with-iodbc">--with-iodbc</link>, <link
linkend="with-solid">--with-solid</link>, <link
linkend="with-adabas">--with-adabas</link>, <link
linkend="with-velocis">--with-velocis</link>, or <link
linkend="with-adabas">--with-custom-odbc</link>,
following options is used: <link linkend="with-iodbc">--with-iodbc</link>, <link linkend="with-solid">--with-solid</link>, <link linkend="with-adabas">--with-adabas</link>, <link linkend="with-velocis">--with-velocis</link>, or <link linkend="with-adabas">--with-custom-odbc</link>,</simpara>
<simpara>
See also <link linkend="ini.sect.uodbc">Unified ODBC
Configuration</link> Directives in the <link
linkend="configuration.file">configuration file</link>.
Configuration</link> Directives in the <link linkend="configuration.file">configuration file</link>.</simpara>
</sect3>
<sect3 id="with-ldap">
@ -403,13 +381,10 @@
<simpara>
Includes <acronym>LDAP</acronym> (Lightweight Directory Access
Protocol) support. The parameter is the LDAP base install
directory, defaults to <filename
class=directory>/usr/local/ldap</filename>.
directory, defaults to <filename class="directory">/usr/local/ldap</filename>.</simpara>
<simpara>
More information about LDAP can be found in <ulink
url="ftp://ftp.isi.edu/in-notes/rfc1777.txt">RFC1777</ulink> and
<ulink
url="ftp://ftp.isi.edu/in-notes/rfc1778.txt">RFC1778</ulink>.
More information about LDAP can be found in <ulink url="ftp://ftp.isi.edu/in-notes/rfc1777.txt">RFC1777</ulink> and
<ulink url="ftp://ftp.isi.edu/in-notes/rfc1778.txt">RFC1778</ulink>.</simpara>
</sect3>
</sect2>
@ -423,8 +398,7 @@
<option>--with-mcrypt</option>
</synopsis>
<simpara>
Include support for the mcrypt library. See the <link
linkend="ref.mcrypt">mcrypt documentation</link> for more information. If
Include support for the mcrypt library. See the <link linkend="ref.mcrypt">mcrypt documentation</link> for more information. If
you use the optional <replaceable>DIR</replaceable> argument, PHP will
look for mcrypt.h in <replaceable>DIR</replaceable>/include.
</simpara>
@ -474,7 +448,7 @@
</synopsis>
<simpara>
Turns on extra dependencies and compiler warnings used by some
of the PHP developers.
of the PHP developers.</simpara>
</sect3>
<sect3 id="with-system-regex">
@ -488,7 +462,7 @@
must use the same library when building PHP as when linking the
server. Enable this if the system's library provides special
features you need. It is recommended that you use the bundled
library if possible.
library if possible.</simpara>
</sect3>
<sect3 id="with-config-file-path">
@ -498,7 +472,7 @@
</synopsis>
<simpara>
The path used to look for <link linkend="configuration.file">the configuration
file</link> when PHP starts up.
file</link> when PHP starts up.</simpara>
</sect3>
<sect3 id="with-exec-dir">
@ -508,11 +482,11 @@
</synopsis>
<simpara>
Only allow running of executables in DIR when in safe mode.
Defaults to <filename class=directory>/usr/local/bin</filename>.
Defaults to <filename class="directory">/usr/local/bin</filename>.
This option only sets the default, it may be changed with the
<link linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link>
directive in the <link linkend="configuration.file">configuration
file</link> later.
file</link> later.</simpara>
</sect3>
<sect3 id="enable-debug">
@ -524,7 +498,7 @@
Enables extra debug information. This makes it possible to gather
more detailed information when there are problems with PHP.
(Note that this doesn't have anything to do with debugging
facilities or information available to PHP scripts.)
facilities or information available to PHP scripts.)</simpara>
</sect3>
<sect3 id="enable-safe-mode">
@ -535,12 +509,11 @@
<simpara>
Enables "safe mode" by default. This imposes several
restrictions on what PHP can do, such as opening only files
within the document root. Read the <link
linkend="security">Security chapter</link> for more more
within the document root. Read the <link linkend="security">Security chapter</link> for more more
information. CGI users should always enable secure mode. This
option only sets the default, it may be enabled or disabled with
the <link linkend="ini.safe-mode">safe_mode</link> directive in
the <link linkend="configuration.file">configuration file</link> later.
the <link linkend="configuration.file">configuration file</link> later.</simpara>
</sect3>
<sect3 id="enable-track-vars">
@ -552,9 +525,8 @@
Makes PHP keep track of where GET/POST/cookie variables come
from in the arrays HTTP_GET_VARS, HTTP_POST_VARS and
HTTP_COOKIE_VARS. This option only sets the default, it may be
enabled or disabled with the <link
linkend="ini.track-vars">track_vars</link> directive in the
<link linkend="configuration.file">configuration file</link> later.
enabled or disabled with the <link linkend="ini.track-vars">track_vars</link> directive in the
<link linkend="configuration.file">configuration file</link> later.</simpara>
</sect3>
<sect3 id="enable-magic-quotes">
@ -564,14 +536,11 @@
</synopsis>
<simpara>
Enable magic quotes by default. This option only sets the
default, it may be enabled or disabled with the <link
linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link>
default, it may be enabled or disabled with the <link linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link>
directive in the <link linkend="configuration.file">configuration
file</link> later. See also the <link
linkend="ini.magic-quotes-gpc"> magic_quotes_gpc</link> and the
<link
linkend="ini.magic-quotes-sybase">magic_quotes_sybase</link>
directives.
file</link> later. See also the <link linkend="ini.magic-quotes-gpc"> magic_quotes_gpc</link> and the
<link linkend="ini.magic-quotes-sybase">magic_quotes_sybase</link>
directives.</simpara>
</sect3>
<sect3 id="enable-debugger">
@ -581,10 +550,9 @@
</synopsis>
<simpara>
Enables the internal PHP debugger support. This feature is
still in an experimental state. See also the <link
linkend="ini.sect.debugger">Debugger Configuration</link>
still in an experimental state. See also the <link linkend="ini.sect.debugger">Debugger Configuration</link>
directives in the <link linkend="configuration.file">configuration
file</link>.
file</link>.</simpara>
</sect3>
<sect3 id="enable-discard-path">
@ -595,9 +563,8 @@
<simpara>
If this is enabled, the PHP CGI binary can safely be placed
outside of the web tree and people will not be able to
circumvent .htaccess security. Read the <link
linkend="security.cgi.shell">section in the security
chapter</link> about this option.
circumvent .htaccess security. Read the <link linkend="security.cgi.shell">section in the security
chapter</link> about this option.</simpara>
</sect3>
<sect3 id="enable-bcmath">
@ -607,9 +574,8 @@
</synopsis>
<simpara>
Enables <command>bc</command> style arbitrary precision math
functions. See also the <link
linkend="ini.sect.bcmath">bcmath.scale </link> option in the
<link linkend="configuration.file">configuration file</link>.
functions. See also the <link linkend="ini.sect.bcmath">bcmath.scale </link> option in the
<link linkend="configuration.file">configuration file</link>.</simpara>
</sect3>
<sect3 id="enable-force-cgi-redirect">
@ -619,30 +585,28 @@
</synopsis>
<simpara>
Enable the security check for internal server redirects. You
should use this if you are running the CGI version with Apache.
should use this if you are running the CGI version with Apache.</simpara>
<simpara>
When using PHP as a CGI binary, PHP by default always first
checks that it is used by redirection (for example under Apache,
by using Action directives). This makes sure that the PHP
binary cannot be used to bypass standard web server
authentication procedures by calling it directly, like <filename
role=url>http://my.host/cgi-bin/php/secret/doc.html</filename>.
This example accesses <filename
role=url>http://my.host/secret/doc.html</filename> but does not
authentication procedures by calling it directly, like <filename role="url">http://my.host/cgi-bin/php/secret/doc.html</filename>.
This example accesses <filename role="url">http://my.host/secret/doc.html</filename> but does not
honour any security settings enforced by httpd for directory
<filename role=dir>/secret</filename>.
<filename role="dir">/secret</filename>.</simpara>
<simpara>
Not enabling option disables the check and enables bypassing httpd
security and authentication settings. Do this only if your
server software is unable to indicate that a safe redirection
was done and all your files under your document root and
user directories may be accessed by anyone.
user directories may be accessed by anyone.</simpara>
<simpara>
Read the <link linkend="security.cgi.force-redirect">section in
the security chapter</link> about this option.
the security chapter</link> about this option.</simpara>
</sect3>
<sect3 id="disable-short-tags">
@ -658,7 +622,7 @@
only sets the default, it may be enabled or disabled with the
<link linkend="ini.short-open-tag">short_open_tag</link>
directive in the <link linkend="configuration.file">configuration
file</link> later.
file</link> later.</simpara>
</sect3>
<sect3 id="enable-url-includes">
@ -668,10 +632,8 @@
</synopsis>
<simpara>
Makes it possible to run code on other HTTP or FTP servers
directly from PHP with <link
linkend="function.include">include()</link>. See also the <link
linkend="ini.include-path">include_path</link> option in the
<link linkend="configuration.file">configuration file</link>.
directly from PHP with <link linkend="function.include">include()</link>. See also the <link linkend="ini.include-path">include_path</link> option in the
<link linkend="configuration.file">configuration file</link>.</simpara>
</sect3>
<sect3 id="disable-syntax-hl">
@ -680,7 +642,7 @@
<option>--disable-syntax-hl</option>
</synopsis>
<simpara>
Turns off syntax highlighting.
Turns off syntax highlighting.</simpara>
</sect3>
<sect3>
@ -692,7 +654,7 @@
you are using a sensible shell, you should be able to do
<command>
LDFLAGS=-L/my/lib/dir CPPFLAGS=-I/my/include/dir ./configure
</command>
</command></para>
</sect3>
</sect2>
@ -704,8 +666,7 @@
When PHP is configured, you are ready to build the CGI
executable or the PHP library. The command
<command>make</command> should take care of this. If it fails
and you can't figure out why, see the <link
linkend="install-problems">Problems section</link>.
and you can't figure out why, see the <link linkend="install-problems">Problems section</link>.</simpara>
</sect2>
@ -716,7 +677,7 @@
by typing <command>make test</command>. It is always a good idea
to test your build. This way you may catch a problem with PHP
on your platform early instead of having to struggle with it
later.
later.</simpara>
</sect2>
<sect2>
@ -727,11 +688,9 @@
mode is on by default, the benchmark may not be able to finish if
it takes longer then the 30 seconds allowed. This is because the
<function>set_time_limit</function> can not be used in safe
mode. Use the <link
linkend="ini.max-execution-time">max_execution_time</link>
mode. Use the <link linkend="ini.max-execution-time">max_execution_time</link>
configuration setting to control this time for your own
scripts. <command>make bench</command> ignores the <link
linkend="configuration.file">configuration file</link>.
scripts. <command>make bench</command> ignores the <link linkend="configuration.file">configuration file</link>.</simpara>
</sect2>
</sect1>
@ -742,8 +701,7 @@
<simpara>
This install guide will help you install and configure PHP
on your Windows 9x/NT webservers. This guide was compiled
by &link.bob;. The latest revision can be found at <ulink
url="&url.win32install">&url.win32install</ulink>.
by &link.bob;. The latest revision can be found at <ulink url="&url.win32install">&url.win32install</ulink>.</simpara>
<para>
This guide provides installation support for:
@ -759,7 +717,7 @@
</para></listitem>
<listitem><para>Omni HTTPd 2.0b1
</para></listitem>
</itemizedlist>
</itemizedlist></para>
<sect2>
<title>General Installation Steps</title>
@ -810,8 +768,7 @@
starts. You can uncomment the: 'extension=php3_*.dll' lines
to load these modules. Some modules require you to have
additional libraries installed on your system for the
module to work correctly. The PHP <ulink
url="&url.php.faq">FAQ</ulink> has more information on
module to work correctly. The PHP <ulink url="&url.php.faq">FAQ</ulink> has more information on
where to get supporting libraries. You can also load a
module dynamically in your script using:
<command>dl("php_*.dll");</command>
@ -823,19 +780,18 @@
'c:\windows\system\inetsrv\browscap.ini' on Windows 95/98
and 'c:\winnt\system32\inetsrv\browscap.ini' on NT
Server. Additional information on using the browscap
functionality in PHP can be found at this <ulink
url="&url.browscap;">mirror</ulink>, select the "source"
functionality in PHP can be found at this <ulink url="&url.browscap;">mirror</ulink>, select the "source"
button to see it in action.
</simpara>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</itemizedlist></para>
<simpara>
The DLLs for PHP extensions are prefixed with 'php3_'. This prevents
confusion between PHP extensions and their supporting libraries.
confusion between PHP extensions and their supporting libraries.</simpara>
</sect2>
@ -972,12 +928,11 @@
Exit Regedit.
</simpara>
</listitem>
</itemizedlist>
</itemizedlist></para>
<simpara>
PWS and IIS 3 users now have a fully operational system. IIS 3
users can use a nifty <ulink
url="http://www.genusa.com/iis/iiscfg.html">tool</ulink> from
users can use a nifty <ulink url="http://www.genusa.com/iis/iiscfg.html">tool</ulink> from
Steven Genusa to configure their script maps.
</simpara>
@ -1054,7 +1009,7 @@
Although there can be a few variations of configuring PHP under
Apache, this one is simple enough to be used by the
newcomer. Please consult the Apache Docs for further
configuration directives.
configuration directives.</simpara>
<para>
<itemizedlist>
@ -1126,7 +1081,7 @@
<member>
Step 6: Click <literal>OK</literal>
</member>
</simplelist>
</simplelist></para>
<simpara>
Repeat steps 2 - 6 for each extension you want to associate with
@ -1228,8 +1183,7 @@
<title>Read the FAQ</title>
<simpara>
Some problems are more common than others. The most common ones
are listed in the PHP FAQ, found at <ulink
url="&url.php.faq;">&url.php.faq;</ulink>
are listed in the PHP FAQ, found at <ulink url="&url.php.faq;">&url.php.faq;</ulink></simpara>
</sect2>
<sect2>
@ -1239,8 +1193,7 @@
If you think you have found a bug in PHP, please report
it. The PHP developers probably don't know about it, and
unless you report it, chances are it won't be fixed. You
can report bugs using the bug-tracking system at <ulink
url="&url.php.bugs;">&url.php.bugs;</ulink>.
can report bugs using the bug-tracking system at <ulink url="&url.php.bugs;">&url.php.bugs;</ulink>.</simpara>
</sect2>
<sect2>
@ -1252,9 +1205,8 @@
case someone already answered someone else who had the same
problem as you. The archives are available from the support
page on <ulink url="&url.php;">&url.php;</ulink>. To
subscribe to the PHP mailing list, send an empty mail to <ulink
url="mailto:&email.php3.subscribe;">&email.php3.subscribe;</ulink>.
The mailing list address is <literal>&email.php3;</literal>.
subscribe to the PHP mailing list, send an empty mail to <ulink url="mailto:&email.php3.subscribe;">&email.php3.subscribe;</ulink>.
The mailing list address is <literal>&email.php3;</literal>.</simpara>
<simpara>
If you want to get help on the mailing list, please try to be
@ -1262,7 +1214,7 @@
(which operating system, what PHP version, what web server, if
you are running PHP as CGI or a server module, etc.), and
preferably enough code to make others able to reproduce and test
your problem.
your problem.</simpara></sect2></sect1>
</chapter>

109
chapters/security.sgml
View file

@ -10,7 +10,7 @@
PHP is designed specifically to be a more secure language for
writing CGI programs than Perl or C, and with correct selection of
compile-time and runtime configuration options it gives you
exactly the combination of freedom and security you need.
exactly the combination of freedom and security you need.</simpara>
<simpara>
As there are many different ways of utilizing PHP, there are many
@ -19,7 +19,7 @@
purposes, but it also means there are combinations of these
options and server configurations that result in an insecure
setup. This chapter explains the different configuration option
combinations and the situations they can be safely used.
combinations and the situations they can be safely used.</simpara>
<sect1 id="security.cgi">
<title>CGI binary</title>
@ -34,64 +34,55 @@
different kinds of CGI wrappers to create safe chroot and setuid
environments for scripts. This setup usually involves
installing executable PHP binary to the web server cgi-bin
directory. CERT advisory <ulink
url="http://www.cert.org/advisories/CA-96.11.interpreters_in_cgi_bin_dir.html">CA-96.11</ulink>
directory. CERT advisory <ulink url="http://www.cert.org/advisories/CA-96.11.interpreters_in_cgi_bin_dir.html">CA-96.11</ulink>
recommends against placing any interpreters into cgi-bin. Even
if the PHP binary can be used as a standalone interpreter, PHP
is designed to prevent the attacks this setup makes possible:
is designed to prevent the attacks this setup makes possible:</simpara>
<itemizedlist>
<listitem><simpara>Accessing system files:
<filename role=url>http://my.host/cgi-bin/php?/etc/passwd</filename>
<filename role="url">http://my.host/cgi-bin/php?/etc/passwd</filename></simpara>
<simpara>
The query information in a url after the question mark (?)
is passed as command line arguments to the interpreter by the
CGI interface. Usually interpreters open and execute the
file specified as the first argument on the command line.
file specified as the first argument on the command line.</simpara>
<simpara>
When invoked as a CGI binary, PHP refuses to interpret the
command line arguments.
</simpara></listitem>
<listitem><simpara>Accessing any web document on server:
<filename
role=url>http://my.host/cgi-bin/php/secret/doc.html</filename>
<filename role="url">http://my.host/cgi-bin/php/secret/doc.html</filename></simpara>
<simpara>
The path information part of the url after the PHP binary
name, <filename role=uri>/secret/doc.html</filename> is
name, <filename role="uri">/secret/doc.html</filename> is
conventionally used to specify the name of the file to be
opened and interpreted by the <acronym>CGI</acronym> program.
Usually some web server configuration directives (Apache:
Action) are used to redirect requests to documents like
<filename
role=url>http://my.host/secret/script.php3</filename> to the
<filename role="url">http://my.host/secret/script.php3</filename> to the
PHP interpreter. With this setup, the web server first checks
the access permissions to the directory <filename
role=uri>/secret</filename>, and after that creates the
redirected request <filename
role=url>http://my.host/cgi-bin/php/secret/script.php3</filename>.
the access permissions to the directory <filename role="uri">/secret</filename>, and after that creates the
redirected request <filename role="url">http://my.host/cgi-bin/php/secret/script.php3</filename>.
Unfortunately, if the request is originally given in this
form, no access checks are made by web server for file
<filename role=uri>/secret/script.php3</filename>, but only
for the <filename role=uri>/cgi-bin/php</filename> file. This
way any user able to access <filename
role=uri>/cgi-bin/php</filename> is able to access any
protected document on the web server.
<filename role="uri">/secret/script.php3</filename>, but only
for the <filename role="uri">/cgi-bin/php</filename> file. This
way any user able to access <filename role="uri">/cgi-bin/php</filename> is able to access any
protected document on the web server.</simpara>
<simpara>
In PHP, compile-time configuration option <link
linkend="enable-force-cgi-redirect">--enable-force-cgi-redirect</link>
and runtime configuration directives <link
linkend="ini.doc-root">doc_root</link> and <link
linkend="ini.user-dir">user_dir</link> can be used to prevent
In PHP, compile-time configuration option <link linkend="enable-force-cgi-redirect">--enable-force-cgi-redirect</link>
and runtime configuration directives <link linkend="ini.doc-root">doc_root</link> and <link linkend="ini.user-dir">user_dir</link> can be used to prevent
this attack, if the server document tree has any directories
with access restrictions. See below for full the explanation of
the different combinations.
</simpara></listitem>
</itemizedlist>
</itemizedlist></sect2>
<sect2 id="security.cgi.default">
<title>Case 1: only public files served</title>
@ -101,30 +92,26 @@
these configuration options. If your web server does not allow
you to do redirects, or the server does not have a way to
communicate to the PHP binary that the request is a safely
redirected request, you can specify the option <link
linkend="enable-force-cgi-redirect">--disable-force-cgi-redirect</link>
redirected request, you can specify the option <link linkend="enable-force-cgi-redirect">--disable-force-cgi-redirect</link>
to the configure script. You still have to make sure your PHP
scripts do not rely on one or another way of calling the script,
neither by directly <filename
role=php>http://my.host/cgi-bin/php/dir/script.php3</filename>
nor by redirection <filename
role=php>http://my.host/dir/script.php3</filename>.
neither by directly <filename role="php">http://my.host/cgi-bin/php/dir/script.php3</filename>
nor by redirection <filename role="php">http://my.host/dir/script.php3</filename>.</simpara>
<simpara>
Redirection can be configured in Apache by
using AddHandler and Action directives (see below).
using AddHandler and Action directives (see below).</simpara></sect2>
<sect2 id="security.cgi.force-redirect">
<title>Case 2: using --enable-force-cgi-redirect</title>
<simpara>
This compile-time option prevents anyone from calling PHP
directly with a url like <filename
role=php>http://my.host/cgi-bin/php/secretdir/script.php3</filename>.
directly with a url like <filename role="php">http://my.host/cgi-bin/php/secretdir/script.php3</filename>.
Instead, PHP will only parse in this mode if it has gone through
a web server redirect rule.
a web server redirect rule.</simpara>
<simpara>
Usually the redirection in the Apache configuration is done with
the following directives:
the following directives:</simpara>
<programlisting role="apache-conf">
Action php3-script /cgi-bin/php
AddHandler php3-script .php3
@ -137,7 +124,7 @@ AddHandler php3-script .php3
If your web server does not support any way of telling if the
request is direct or redirected, you cannot use this option and
you must use one of the other ways of running the CGI version
documented here.
documented here.</simpara></sect2>
<sect2 id="security.cgi.doc-root">
<title>Case 3: setting doc_root or user_dir</title>
@ -150,57 +137,50 @@ AddHandler php3-script .php3
information like passwords. Therefore many sysadmins will
prefer setting up another directory structure for scripts that
are accessible only through the PHP CGI, and therefore always
interpreted and not displayed as such.
interpreted and not displayed as such.</simpara>
<simpara>
Also if the method for making sure the requests are not
redirected, as described in the previous section, is not
available, it is necessary to set up a script doc_root that is
different from web document root.
different from web document root.</simpara>
<simpara>
You can set the PHP script document root by the configuration
directive <link linkend="ini.doc-root">doc_root</link> in the <link
linkend="configuration.file">configuration file</link>, or you
directive <link linkend="ini.doc-root">doc_root</link> in the <link linkend="configuration.file">configuration file</link>, or you
can set the environment variable <envar>PHP_DOCUMENT_ROOT</envar>.
If it is set, the CGI version of PHP will always construct the file
name to open with this <parameter>doc_root</parameter> and the path
information in the request, so you can be sure no script is executed
outside this directory (except for <parameter>user_dir</parameter>
below).
below).</simpara>
<simpara>
Another option usable here is <link
linkend="ini.user-dir">user_dir</link>. When user_dir is unset,
Another option usable here is <link linkend="ini.user-dir">user_dir</link>. When user_dir is unset,
only thing controlling the opened file name is
<parameter>doc_root</parameter>. Opening an url like <filename
role=url>http://my.host/~user/doc.php3</filename> does not
<parameter>doc_root</parameter>. Opening an url like <filename role="url">http://my.host/~user/doc.php3</filename> does not
result in opening a file under users home directory, but a file
called <filename role=uri>~user/doc.php3</filename> under
called <filename role="uri">~user/doc.php3</filename> under
doc_root (yes, a directory name starting with a tilde
[<literal>~</literal>]).
[<literal>~</literal>]).</simpara>
<simpara>
If user_dir is set to for example <filename
role=dir>public_php</filename>, a request like <filename
role=url>http://my.host/~user/doc.php3</filename> will open a
If user_dir is set to for example <filename role="dir">public_php</filename>, a request like <filename role="url">http://my.host/~user/doc.php3</filename> will open a
file called <filename>doc.php3</filename> under the directory
named <filename role=dir>public_php</filename> under the home
directory of the user. If the home of the user is <filename
role=dir>/home/user</filename>, the file executed is
<filename>/home/user/public_php/doc.php3</filename>.
named <filename role="dir">public_php</filename> under the home
directory of the user. If the home of the user is <filename role="dir">/home/user</filename>, the file executed is
<filename>/home/user/public_php/doc.php3</filename>.</simpara>
<simpara>
<parameter>user_dir</parameter> expansion happens regardless of
the <parameter>doc_root</parameter> setting, so you can control
the document root and user directory access separately.
the document root and user directory access separately.</simpara></sect2>
<sect2 id="security.cgi.shell">
<title>Case 4: PHP parser outside of web tree</title>
<para>
A very secure option is to put the PHP parser binary somewhere
outside of the web tree of files. In <filename
role=dir>/usr/local/bin</filename>, for example. The only real
outside of the web tree of files. In <filename role="dir">/usr/local/bin</filename>, for example. The only real
downside to this option is that you will now have to put a line
similar to:
@ -215,19 +195,18 @@ AddHandler php3-script .php3
exactly as you would treat any other CGI script written in Perl
or sh or any other common scripting language which uses the
<literal>#!</literal> shell-escape mechanism for launching
itself.
itself.</para>
<para>
To get PHP to handle <envar>PATH_INFO</envar> and
<envar>PATH_TRANSLATED</envar> information correctly with this
setup, the php parser should be compiled with the <link
linkend="enable-discard-path">--enable-discard-path</link>
configure option.
setup, the php parser should be compiled with the <link linkend="enable-discard-path">--enable-discard-path</link>
configure option.</para></sect2></sect1>
<sect1 id="security.apache">
<title>Apache module</title>
<simpara>
When PHP is used as an Apache module it inherits Apache's user
permissions (typically those of the "nobody" user).
permissions (typically those of the "nobody" user).</simpara></sect1>
</chapter>

14
features/connection-handling.sgml
View file

@ -9,9 +9,9 @@
Internally in PHP a connection status is maintained. There are 3
possible states:
<itemizedlist>
<listitem><simpara>0 - NORMAL
<listitem><simpara>1 - ABORTED
<listitem><simpara>2 - TIMEOUT
<listitem><simpara>0 - NORMAL</simpara></listitem>
<listitem><simpara>1 - ABORTED</simpara></listitem>
<listitem><simpara>2 - TIMEOUT</simpara></listitem>
</itemizedlist>
</para>
@ -21,7 +21,7 @@
turned on. A remote client disconnect is usually caused by the
user hitting his STOP button. If the PHP-imposed time limit (see
<function>set_time_limit</function>) is hit, the TIMEOUT state flag
is turned on.
is turned on.</simpara>
<simpara>
You can decide whether or not you want a client disconnect to cause
@ -42,7 +42,7 @@
terminating normally, so to do something different in case of a client
diconnect you can use the <function>connection_aborted</function>
function. This function will return true if the connection was
aborted.
aborted.</simpara>
<simpara>
Your script can also be terminated by the built-in script timer.
@ -55,7 +55,7 @@
be called. Within this shutdown function you can check to see if
a timeout caused the shutdown function to be called by calling the
<function>connection_timeout</function> function. This function will
return true if a timeout caused the shutdown function to be called.
return true if a timeout caused the shutdown function to be called.</simpara>
<simpara>
One thing to note is that both the ABORTED and the TIMEOUT states
@ -69,7 +69,7 @@
You can also check both states in a single call by using the
<function>connection_status</function>. This function returns a
bitfield of the active states. So, if both states are active it
would return 3, for example.
would return 3, for example.</simpara>
</chapter>

4
features/cookies.sgml
View file

@ -8,14 +8,14 @@
<function>setcookie</function> function. Cookies are part of the
HTTP header, so <function>setcookie</function> must be called before
any output is sent to the browser. This is the same limitation that
<function>header</function> has.
<function>header</function> has.</para>
<para>
Any cookies sent to you from the client will automatically be
turned into a PHP variable just like GET and POST method data. If
you wish to assign multiple values to a single cookie, just add
<emphasis>[]</emphasis> to the cookie name. For more details see
the <function>setcookie</function> function.
the <function>setcookie</function> function.</para>
</chapter>

14
features/error-handling.sgml
View file

@ -5,12 +5,12 @@
There are 4 types of errors and warnings in PHP. They are:
<itemizedlist>
<listitem><simpara>1 - Normal Function Errors
<listitem><simpara>2 - Normal Warnings
<listitem><simpara>4 - Parser Errors
<listitem><simpara>1 - Normal Function Errors</simpara></listitem>
<listitem><simpara>2 - Normal Warnings</simpara></listitem>
<listitem><simpara>4 - Parser Errors</simpara></listitem>
<listitem><simpara>8 - Notices (warnings you can ignore but which
may imply a bug in your code)
</itemizedlist>
may imply a bug in your code)</simpara></listitem>
</itemizedlist></para>
<simpara>
The above 4 numbers are added up to define an error reporting
@ -19,7 +19,7 @@
php3.ini file with the error_reporting directive. It can also be
set in your Apache httpd.conf file with the php3_error_reporting
directive or lastly it may be set at runtime within a script using
the <function>error_reporting</function> function.
the <function>error_reporting</function> function.</simpara>
<simpara>
All <link linkend="expressions">PHP expressions</link> can also be called
@ -27,7 +27,7 @@
expression. If an error occurred during such an expression and the
<link linkend="ini.track-errors">track_errors</link> feature
is enabled, you can find the error message in the global variable
$php_errormsg.
$php_errormsg.</simpara>
</chapter>

31
features/file-upload.sgml
View file

@ -16,9 +16,8 @@
<para>
Note that PHP also supports PUT-method file uploads as used by
Netscape Composer and W3C's Amaya clients. See the <link
linkend="features.file-upload.put-method">PUT Method Support</link>
for more details.
Netscape Composer and W3C's Amaya clients. See the <link linkend="features.file-upload.put-method">PUT Method Support</link>
for more details.</para>
<para>
A file upload screen can be built by creating a special form which
@ -38,7 +37,7 @@ Send this file: &lt;INPUT NAME=&quot;userfile&quot; TYPE=&quot;file&quot;&gt;
The _URL_ should point to a PHP file. The MAX_FILE_SIZE hidden
field must precede the file input field and its value is the maximum
filesize accepted. The value is in bytes. In this destination file,
the following variables will be defined upon a successful upload:
the following variables will be defined upon a successful upload:</para>
<para>
<itemizedlist>
@ -71,14 +70,14 @@ Send this file: &lt;INPUT NAME=&quot;userfile&quot; TYPE=&quot;file&quot;&gt;
Note that the &quot;$userfile&quot; part of the above variables is
whatever the name of the INPUT field of TYPE=file is in the upload
form. In the above upload form example, we chose to call it
&quot;userfile&quot;.
&quot;userfile&quot;.</para>
<simpara>
Files will by default be stored in the server's default temporary
directory. This can be changed by setting the environment variable
<envar>TMPDIR</envar> in the environment in which PHP runs. Setting
it using <function>putenv</function> from within a PHP script will
not work.
not work.</simpara>
<simpara>
The PHP script which receives the uploaded file should implement
@ -88,11 +87,11 @@ Send this file: &lt;INPUT NAME=&quot;userfile&quot; TYPE=&quot;file&quot;&gt;
big. You could use the $file_type variable to throw away any
files that didn't match a certain type criteria. Whatever the
logic, you should either delete the file from the temporary
directory or move it elsewhere.
directory or move it elsewhere.</simpara>
<simpara>
The file will be deleted from the temporary directory at the end
of the request if it has not been moved away or renamed.
of the request if it has not been moved away or renamed.</simpara></sect1>
<sect1 id="features.file-upload.common-pitfalls">
<title>Common Pitfalls</title>
@ -100,12 +99,12 @@ Send this file: &lt;INPUT NAME=&quot;userfile&quot; TYPE=&quot;file&quot;&gt;
The MAX_FILE_SIZE item cannot specify a file size greater than the file
size that has been set in the upload_max_filesize in the PHP3.ini file
or the corresponding php3_upload_max_filesize Apache .conf directive.
The default is 2 Megabytes.
The default is 2 Megabytes.</simpara>
<simpara>
Please note that the CERN httpd seems to strip off everything
starting at the first whitespace in the content-type mime header
it gets from the client. As long as this is the case, CERN httpd
will not support the file upload feature.
will not support the file upload feature.</simpara>
</sect1>
<sect1 id="feature-fileupload.multiple">
@ -114,10 +113,10 @@ Send this file: &lt;INPUT NAME=&quot;userfile&quot; TYPE=&quot;file&quot;&gt;
It is possible to upload multiple files simultaneously and have
the information organized automatically in arrays for you. To
do so, you need to use the same array submission syntax in the
HTML form as you do with multiple selects and checkboxes:
HTML form as you do with multiple selects and checkboxes:</simpara>
<note>
<para>
Support for multiple file uploads was added in version 3.0.10.
Support for multiple file uploads was added in version 3.0.10.</para>
</note>
<para>
@ -131,7 +130,7 @@ Send this file: &lt;INPUT NAME=&quot;userfile&quot; TYPE=&quot;file&quot;&gt;
&lt;input type=&quot;submit&quot; value=&quot;Send files&quot;&gt;
&lt;/form&gt;
</programlisting>
</example>
</example></para>
<simpara>
When the above form is submitted, the arrays <computeroutput>$userfile</computeroutput>,
@ -139,7 +138,7 @@ Send this file: &lt;INPUT NAME=&quot;userfile&quot; TYPE=&quot;file&quot;&gt;
<computeroutput>$userfile_size</computeroutput> will be formed in the global
scope (as well as in $HTTP_POST_VARS). Each of these will be a
numerically indexed array of the appropriate values for the
submitted files.
submitted files.</simpara>
<simpara>
For instance, assume that the filenames
@ -150,7 +149,7 @@ Send this file: &lt;INPUT NAME=&quot;userfile&quot; TYPE=&quot;file&quot;&gt;
<computeroutput>$userfile_name[1]</computeroutput> would contain the
value <computeroutput>xwp.out</computeroutput>. Similarly,
<computeroutput>$userfile_size[0]</computeroutput> would contain
<filename>review.html</filename>'s filesize, and so forth.
<filename>review.html</filename>'s filesize, and so forth.</simpara></sect1>
<sect1 id="features.file-upload.put-method">
<title>PUT method support</title>
@ -210,7 +209,7 @@ Script PUT /put.php3
(may vary on non-Apache web servers). This destination filename is
the one that the remote client specified. You do not have to listen
to this client. You could, for example, copy all uploaded files to
a special uploads directory.
a special uploads directory.</simpara></sect1>
</chapter>

24
features/http-auth.sgml
View file

@ -12,7 +12,7 @@
$PHP_AUTH_USER, $PHP_AUTH_PW and $PHP_AUTH_TYPE set to the user
name, password and authentication type respectively. Only "Basic"
authentication is supported at this point. See the <function>Header</function>
function for more information.
function for more information.</simpara>
<para>
An example script fragment which would force client authentication
@ -20,7 +20,7 @@
<example>
<title>HTTP Authentication example</title>
<programlisting role=php>
<programlisting role="php">
&lt;?php
if(!isset($PHP_AUTH_USER)) {
Header(&quot;WWW-Authenticate: Basic realm=\&quot;My Realm\&quot;&quot;);
@ -33,20 +33,20 @@
}
?>
</programlisting>
</example>
</example></para>
<para>
Instead of simply printing out the $PHP_AUTH_USER and
$PHP_AUTH_PW, you would probably want to check the username and
password for validity. Perhaps by sending a query to a database,
or by looking up the user in a dbm file.
or by looking up the user in a dbm file.</para>
<para>
Watch out for buggy Internet Explorer browsers out there. They
seem very picky about the order of the headers. Sending the
<emphasis>WWW-Authenticate</emphasis> header before the
<errorcode>HTTP/1.0 401</errorcode> header seems to do the trick
for now.
for now.</para>
<simpara>
In order to prevent someone from writing a script which reveals
@ -54,22 +54,22 @@
traditional external mechanism, the PHP_AUTH variables will not be
set if external authentication is enabled for that particular
page. In this case, the $REMOTE_USER variable can be used to
identify the externally-authenticated user.
identify the externally-authenticated user.</simpara>
<simpara>
Note, however, that the above does not prevent someone who
controls a non-authenticated URL from stealing passwords from
authenticated URLs on the same server.
authenticated URLs on the same server.</simpara>
<simpara>
Both Netscape and Internet Explorer will clear the local browser
window's authentication cache for the realm upon receiving a
server response of 401. This can effectively "log out" a user,
forcing them to re-enter their username and password. Some people
use this to "time out" logins, or provide a "log-out" button.
<simpara>
use this to "time out" logins, or provide a "log-out" button.</simpara>
<simpara></simpara>
<example>
<title>HTTP Authentication example forcing a new name/password</title>
<programlisting role=php>
<programlisting role="php">
&lt;?php
function authenticate() {
Header( &quot;WWW-authenticate: basic realm='Test Authentication System'&quot;);
@ -100,10 +100,10 @@
has shown that Lynx does not clear the authentication credentials
with a 401 server response, so pressing back and then forward
again will open the resource (as long as the credential
requirements haven't changed).
requirements haven't changed).</simpara>
<simpara>
Also note that this does not work using Microsoft's IIS server and
the CGI version of PHP due to a limitation of IIS.
the CGI version of PHP due to a limitation of IIS.</simpara>
</chapter>

2
features/images.sgml
View file

@ -11,7 +11,7 @@
<para>
<example>
<title>GIF creation with PHP</title>
<programlisting role=php>
<programlisting role="php">
&lt;?php
Header("Content-type: image/gif");
$string=implode($argv," ");

20
features/persistent-connections.sgml
View file

@ -8,7 +8,7 @@
connection (that remained open from earlier) - and if it exists, it
uses it. If it does not exist, it creates the link. An 'identical'
connection is a connection that was opened to the same host, with
the same username and the same password (where applicable).
the same username and the same password (where applicable).</simpara>
<simpara>
People who aren't thoroughly familiar with the way web servers work
@ -19,14 +19,14 @@
transaction efficently, and they don't do a whole lot of other
things. In fact, to be extremely clear about the subject, persistent
connections don't give you <emphasis>any</emphasis> functionality
that wasn't possible with their non-persistent brothers.
that wasn't possible with their non-persistent brothers.</simpara>
<simpara>
Why?
Why?</simpara>
<simpara>
This has to do with the way web servers work. There are three ways
in which your web server can utilize PHP to generate web pages.
in which your web server can utilize PHP to generate web pages.</simpara>
<simpara>
The first method is to use PHP as a CGI "wrapper". When run this
@ -35,7 +35,7 @@
is destroyed after every request, any resources that it acquires
(such as a link to an SQL database server) are closed when it is
destroyed. In this case, you do not gain anything from trying to use
persistent connections -- they simply don't persist.
persistent connections -- they simply don't persist.</simpara>
<simpara>
The second, and most popular, method is to run PHP as a module in
@ -50,7 +50,7 @@
this case it make it so each child process only needs to connect to
your SQL server the first time that it serves a page that makes us of
such a connection. When another page then requires a connection to the
SQL server, it can reuse the connection that child established earlier.
SQL server, it can reuse the connection that child established earlier.</simpara>
<simpara>
The last method is to use PHP as a plug-in for a multithreaded web
@ -60,11 +60,11 @@
all allow PHP to be used as a plug-in on multithreaded servers like
Netscape FastTrack, Microsoft's Internet Information Server (IIS),
and O'Reilly's WebSite Pro. When this happens, the behavior will be
essentially the same as for the multiprocess model described before.
essentially the same as for the multiprocess model described before.</simpara>
<simpara>
If persistent connections don't have any added functionality, what
are they good for?
are they good for?</simpara>
<simpara>
The answer here is extremely simple -- efficiency. Persistent
@ -81,7 +81,7 @@
open persistent connection to the server. For example, if you had 20
different child processes that ran a script that made a persistent
connection to your SQL server, you'd have 20 different connections
to the SQL server, one from each child.
to the SQL server, one from each child.</simpara>
<simpara>
An important summary. Persistent connections were designed to have
@ -89,7 +89,7 @@
<emphasis>always</emphasis> be able to replace persistent connections
with non-persistent connections, and it won't change the way your
script behaves. It <emphasis>may</emphasis> (and probably will)
change the efficiency of the script, but not its behavior!
change the efficiency of the script, but not its behavior!</simpara>
</chapter>

14
features/remote-files.sgml
View file

@ -12,14 +12,14 @@
<note>
<para>
You can't use remote files in <function>include</function> and
<function>require</function> statements on Windows.
</note>
<function>require</function> statements on Windows.</para>
</note></para>
<para>
For example, you can use this to open a file on a remote web server,
parse the output for the data you want, and then use that data in a
database query, or simply to output it in a style matching the rest
of your website.
of your website.</para>
<para>
<example>
@ -42,7 +42,7 @@
fclose($file);
?&gt;
</programlisting>
</example>
</example></para>
<para>
You can also write to files on an FTP as long you connect as a user
@ -51,7 +51,7 @@
the username (and possibly password) within the URL, such as
'ftp://user:password@ftp.example.com/path/to/file'. (You can use the
same sort of syntax to access files via HTTP when they require Basic
authentication.)
authentication.)</para>
<para>
<example>
@ -75,8 +75,8 @@
You might get the idea from the example above to use this technique to
write to a remote log, but as mentioned above, you can only write to
a new file using the URL fopen() wrappers. To do distributed logging
like that, you should take a look at <function>syslog</function>.
</note>
like that, you should take a look at <function>syslog</function>.</para>
</note></para>
</chapter>

25
language/basic-syntax.sgml
View file

@ -6,7 +6,7 @@
<para>
There are four ways of escaping from HTML and entering "PHP code
mode":
mode":</para>
<para>
<example>
@ -24,15 +24,14 @@
4. &lt;% echo ("You may optionally use ASP-style tags"); %>
&lt;%= $variable; # This is a shortcut for "&lt;%echo .." %>
</programlisting>
</example>
</example></para>
<para>
The first way is only available if short tags have been
enabled. This can be done via the <function>short_tags</function>
function, by enabling the <link
linkend="ini.short-open-tag">short_open_tag</link> configuration
function, by enabling the <link linkend="ini.short-open-tag">short_open_tag</link> configuration
setting in the PHP config file, or by compiling PHP with the
--enable-short-tags option to <command>configure</command>.
--enable-short-tags option to <command>configure</command>.</para>
<para>
The fourth way is only available if ASP-style tags have been
@ -41,18 +40,18 @@
<note>
<para>Support for ASP-style tags was added in 3.0.4.</para>
</note>
</note></para>
<para>
The closing tag for the block will include the immediately
trailing newline if one is present.
trailing newline if one is present.</para></sect1>
<sect1 id="language.basic-syntax.instruction-separation">
<title>Instruction separation</title>
<simpara>
Instructions are separated the same as in C or perl - terminate
each statement with a semicolon.
each statement with a semicolon.</simpara>
<para>
The closing tag (?&gt;) also implies the end of the statement, so the
@ -66,7 +65,7 @@
&lt;?php echo "This is a test" ?>
</programlisting>
</informalexample>
</informalexample></para></sect1>
<sect1 id="language.basic-syntax.comments">
<title>Comments</title>
@ -83,12 +82,12 @@
echo "One Final Test"; # This is shell-style style comment
?>
</programlisting>
</informalexample>
</informalexample></para>
<simpara>
The "one-line" comment styles actually only comment to the
end of the line or the current block of PHP code, whichever
comes first.
comes first.</simpara>
<informalexample><programlisting>
&lt;h1>This is an &lt;?# echo "simple";?> example.&lt;/h1>
&lt;p>The header above will say 'This is an example'.
@ -96,7 +95,7 @@
<simpara>
You should be careful not to nest 'C' style comments, which can
happen when commenting out large blocks.
happen when commenting out large blocks.</simpara>
<informalexample><programlisting>
&lt;?php
@ -104,7 +103,7 @@
echo "This is a test"; /* This comment will cause a problem */
*/
?>
</programlisting></informalexample>
</programlisting></informalexample></sect1>
</chapter>
<!-- Keep this comment at the end of the file

10
language/constants.sgml
View file

@ -6,7 +6,7 @@
defining more at run-time. Constants are much like variables,
save for the two facts that constants must be defined using the
<function>define</function> function, and that they cannot later be
redefined to another value.
redefined to another value.</simpara>
<para>
The predefined constants (always available) are:
@ -116,16 +116,16 @@
</simpara>
</listitem>
</varlistentry>
</variablelist>
</variablelist></para>
<para>
The E_* constants are typically used with the
<function>error_reporting</function> function for setting the
error reporting level.
error reporting level.</para>
<para>
You can define additional constants using the
<function>define</function> function.
<function>define</function> function.</para>
<para>
Note that these are constants, not C-style macros; only valid
@ -152,7 +152,7 @@ function report_error($file, $line, $message) {
report_error(__FILE__,__LINE__, "Something went wrong!");
?&gt;
</programlisting>
</example>
</example></para>
</chapter>

108
language/control-structures.sgml
View file

@ -8,7 +8,7 @@
usually end with a semicolon. In addition, statements can be grouped
into a statement-group by encapsulating a group of statements with
curly braces. A statement-group is a statement by itself as well. The
various statement types are described in this chapter.
various statement types are described in this chapter.</simpara>
<sect1 id="control-structures.if">
<title><literal>if</literal></title>
@ -22,13 +22,13 @@
<informalexample><programlisting>
if (expr)
statement
</programlisting></informalexample>
</programlisting></informalexample></para>
<simpara>
As described in the section about expressions, expr is evaluated
to its truth value. If <replaceable>expr</replaceable> evaluates
to <literal>TRUE</literal>, PHP will execute statement, and if it
evaluates to <literal>FALSE</literal> - it'll ignore it.
evaluates to <literal>FALSE</literal> - it'll ignore it.</simpara>
<para>
The following example would display <computeroutput>a is bigger
@ -38,7 +38,7 @@
<informalexample><programlisting>
if ($a > $b)
print "a is bigger than b";
</programlisting></informalexample>
</programlisting></informalexample></para>
<para>
Often you'd want to have more than one statement to be executed
@ -55,13 +55,13 @@
print "a is bigger than b";
$b = $a;
}
</programlisting></informalexample>
</programlisting></informalexample></para>
<simpara>
If statements can be nested indefinitely within other
<literal>if</literal> statements, which provides you with complete
flexibility for conditional execution of the various parts of
your program.
your program.</simpara></sect1>
<sect1 id="control-structures.else">
<title><literal>else</literal></title>
@ -91,7 +91,7 @@
if the <literal>if</literal> expression evaluated to
<literal>FALSE</literal>, and if there were any <literal>elseif</literal>
expressions - only if they evaluated to <literal>FALSE</literal>
as well (see below).
as well (see below).</para></sect1>
<sect1 id="control-structures.elseif">
<title><literal>elseif</literal></title>
@ -120,7 +120,7 @@
print "a is smaller than b";
}
</programlisting>
</informalexample>
</informalexample></para>
<simpara>
There may be several <literal>elseif</literal>s within the same
@ -130,13 +130,13 @@
words) and the behavior would be identical to the one of 'elseif'
(in a single word). The syntactic meaning is slightly different
(if you're familiar with C, this is the same behavior) but the
bottom line is that both would result in exactly the same behavior.
bottom line is that both would result in exactly the same behavior.</simpara>
<simpara>
The <literal>elseif</literal> statement is only executed if the preceding
<literal>if</literal> expression and any
preceding <literal>elseif</literal> expressions evaluated to <literal>FALSE</literal>, and the current
<literal>elseif</literal> expression evaluated to <literal>TRUE</literal>.
<literal>elseif</literal> expression evaluated to <literal>TRUE</literal>.</simpara></sect1>
<sect1 id="control-structures.alternative-syntax">
<title>Alternative syntax for <literal>if</literal> structures: <literal>if(): ... endif;</literal></title>
@ -156,12 +156,12 @@
A = 5
&lt;?php endif; ?&gt;
</programlisting>
</informalexample>
</informalexample></para>
<simpara>
In the above example, the HTML block "A = 5" is nested within an
<literal>if</literal> statement written in the alternative syntax.
The HTML block would be displayed only if $a is equal to 5.
The HTML block would be displayed only if $a is equal to 5.</simpara>
<para>
The alternative syntax applies to <literal>else</literal>
@ -181,7 +181,7 @@
print "a is neither 5 nor 6";
endif;
</programlisting>
</informalexample>
</informalexample></para></sect1>
<sect1 id="control-structures.while">
<title><literal>while</literal></title>
@ -195,7 +195,7 @@
<programlisting>
while (expr) statement
</programlisting>
</informalexample>
</informalexample></para>
<simpara>
The meaning of a <literal>while</literal> statement is simple.
@ -208,7 +208,7 @@
time PHP runs the statements in the loop is one iteration).
Sometimes, if the <literal>while</literal> expression evaluates
to <literal>FALSE</literal> from the very beginning, the nested
statement(s) won't even be run once.
statement(s) won't even be run once.</simpara>
<para>
Like with the <literal>if</literal> statement, you can group
@ -219,7 +219,7 @@
<informalexample>
<programlisting>
while (expr): statement ... endwhile;
</programlisting></informalexample>
</programlisting></informalexample></para>
<para>
The following examples are identical, and both print numbers from
@ -244,7 +244,7 @@
$i++;
endwhile;
</programlisting>
</informalexample>
</informalexample></para></sect1>
<sect1 id="control-structures.do.while">
@ -261,7 +261,7 @@
with a regular <literal>while</literal> loop (the truth expression
is checked at the beginning of each iteration, if it evaluates
to <literal>FALSE</literal> right from the beginning, the loop
execution would end immediately).
execution would end immediately).</simpara>
<para>
There is just one syntax for <literal>do..while</literal> loops:
@ -273,20 +273,19 @@
print $i;
} while ($i>0);
</programlisting>
</informalexample>
</informalexample></para>
<simpara>
The above loop would run one time exactly, since after the first
iteration, when truth expression is checked, it evaluates to
<literal>FALSE</literal> ($i is not bigger than 0) and the loop
execution ends.
execution ends.</simpara>
<para>
Advanced C users may be familiar with a different usage of
the <literal>do..while</literal> loop, to allow stopping
execution in the middle of code blocks, by encapsulating
them with <literal>do..while</literal>(0), and using the <link
linkend="control-structures.break"><literal>break</literal></link> statement.
them with <literal>do..while</literal>(0), and using the <link linkend="control-structures.break"><literal>break</literal></link> statement.
The following code fragment demonstrates this:
<informalexample>
@ -304,12 +303,12 @@
...process i...
} while(0);
</programlisting>
</informalexample>
</informalexample></para>
<simpara>
Don't worry if you don't understand this right away or at all.
You can code scripts and even powerful scripts without using this
`feature'.
`feature'.</simpara></sect1>
<sect1 id="control-structures.for">
<title><literal>for</literal></title>
@ -323,21 +322,21 @@
<programlisting>
for (expr1; expr2; expr3) statement
</programlisting>
</informalexample>
</informalexample></para>
<simpara>
The first expression (<replaceable>expr1</replaceable>) is evaluated
(executed) once unconditionally at the beginning of the loop.
(executed) once unconditionally at the beginning of the loop.</simpara>
<simpara>
In the beginning of each iteration, <replaceable>expr2</replaceable>
is evaluated. If it evaluates to <literal>TRUE</literal>, the
loop continues and the nested statement(s) are executed. If it
evaluates to <literal>FALSE</literal>, the execution of the loop ends.
evaluates to <literal>FALSE</literal>, the execution of the loop ends.</simpara>
<simpara>
At the end of each iteration, <replaceable>expr3</replaceable>
is evaluated (executed).
is evaluated (executed).</simpara>
<simpara>
Each of the expressions can be empty.
@ -345,9 +344,8 @@ for (expr1; expr2; expr3) statement
the loop should be run indefinitely (PHP implicitly
considers it as <literal>TRUE</literal>, like C).
This may not be as useless as you might think, since
often you'd want to end the loop using a conditional <link
linkend="control-structures.break"><literal>break</literal></link> statement
instead of using the <literal>for</literal> truth expression.
often you'd want to end the loop using a conditional <link linkend="control-structures.break"><literal>break</literal></link> statement
instead of using the <literal>for</literal> truth expression.</simpara>
<para>
Consider the following examples. All of them display numbers from
@ -385,13 +383,13 @@ for (expr1; expr2; expr3) statement
for ($i = 1; $i <= 10; print $i, $i++) ;
</programlisting>
</informalexample>
</informalexample></para>
<simpara>
Of course, the first example appears to be the nicest one (or
perhaps the fourth), but you may find that being able to use empty
expressions in <literal>for</literal> loops comes in handy in
many occasions.
many occasions.</simpara>
<para>
PHP also supports the alternate "colon syntax" for
@ -401,13 +399,13 @@ for (expr1; expr2; expr3) statement
<programlisting>
for (expr1; expr2; expr3): statement; ...; endfor;
</programlisting>
</informalexample>
</informalexample></para>
<para>
Other languages have a foreach statement to traverse an array or
hash. PHP uses the while statement and the <function>list</function>
and <function>each</function> functions for this. See the
documentation for these functions for an example.
documentation for these functions for an example.</para></sect1>
<sect1 id="control-structures.break">
@ -426,7 +424,7 @@ for (expr1; expr2; expr3) statement
$i++;
}
</programlisting>
</informalexample>
</informalexample></para></sect1>
<sect1 id="control-structures.continue">
<title><literal>continue</literal></title>
@ -445,7 +443,7 @@ for (expr1; expr2; expr3) statement
do_something_odd ($value);
}
</programlisting>
</informalexample>
</informalexample></para></sect1>
<sect1 id="control-structures.switch">
<title><literal>switch</literal></title>
@ -456,7 +454,7 @@ for (expr1; expr2; expr3) statement
you may want to compare the same variable (or expression) with
many different values, and execute a different piece of code
depending on which value it equals to. This is exactly what the
<literal>switch</literal> statement is for.
<literal>switch</literal> statement is for.</simpara>
<para>
The following two examples are two different ways to write the
@ -487,7 +485,7 @@ for (expr1; expr2; expr3) statement
break;
}
</programlisting>
</informalexample>
</informalexample></para>
<para>
It is important to understand how the <literal>switch</literal>
@ -514,7 +512,7 @@ for (expr1; expr2; expr3) statement
print "i equals 2";
}
</programlisting>
</informalexample>
</informalexample></para>
<simpara>
Here, if $i equals to 0, PHP would execute all of the print
@ -523,7 +521,7 @@ for (expr1; expr2; expr3) statement
'expected' behavior and only 'i equals 2' would be displayed. So,
it's important not to forget <literal>break</literal> statements
(even though you may want to avoid supplying them on purpose under
certain circumstances).
certain circumstances).</simpara>
<para>
The statement list for a case can also be empty, which simply
@ -540,7 +538,7 @@ for (expr1; expr2; expr3) statement
print "i is 3";
}
</programlisting>
</informalexample>
</informalexample></para>
<para>
A special case is the default case. This case matches anything
@ -562,20 +560,20 @@ for (expr1; expr2; expr3) statement
print "i is not equal to 0, 1 or 2";
}
</programlisting>
</informalexample>
</informalexample></para>
<para>
The <literal>case</literal> expression may be any expression that
evaluates to a scalar type, that is, integer or floating-point
numbers and strings. Arrays or objects are meaningless in that
context.
context.</para></sect1>
<sect1 id="function.require">
<title><literal>require</literal></title>
<simpara>
The <literal>require</literal> statement replaces itself with the
specified file, much like the C preprocessor's #include works.
specified file, much like the C preprocessor's #include works.</simpara>
<para>
This means that you can't put a <literal>require</literal>
@ -587,14 +585,14 @@ for (expr1; expr2; expr3) statement
<programlisting>
require 'header.inc';
</programlisting>
</informalexample>
</informalexample></para></sect1>
<sect1 id="function.include">
<title><literal>include</literal></title>
<simpara>
The <literal>include</literal> statement includes and evaluates
the specified file.
the specified file.</simpara>
<para>
This happens each time the <literal>include</literal> statement is
@ -608,23 +606,21 @@ for (expr1; expr2; expr3) statement
include $files[$i];
}
</programlisting>
</informalexample>
</informalexample></para>
<para>
<link linkend="function.include"><literal>include</literal></link>
differs from <link
linkend="function.require"><literal>require</literal></link>
differs from <link linkend="function.require"><literal>require</literal></link>
in that the include statement is re-evaluated each time it is
encountered (and only when it is being executed), whereas the
<link linkend="function.require"><literal>require</literal></link>
statement is replaced by the required file when it is first
encountered, whether the contents of the file will be evaluated or
not (for example, if it is inside an if statement whose condition
evaluated to false).
evaluated to false).</para>
<para>
Because <link
linkend="function.include"><literal>include</literal></link> is a
Because <link linkend="function.include"><literal>include</literal></link> is a
special language construct, you must enclose it within a statement
block if it is inside a conditional block.
@ -645,16 +641,16 @@ for (expr1; expr2; expr3) statement
include($other);
}
</programlisting>
</informalexample>
</informalexample></para>
<para>
When the file is evaluated, the parser begins in "HTML-mode" which
will output the contents of the file until the first PHP start tag
(&lt;?) is encountered.
(&lt;?) is encountered.</para>
<para>
See also <function>readfile</function>, <function>require</function>,
<function>virtual</function>.
<function>virtual</function>.</para></sect1>
</chapter>

30
language/expressions.sgml
View file

@ -5,20 +5,20 @@
Expressions are the most important building stones of PHP. In PHP,
almost anything you write is an expression. The simplest yet
most accurate way to define an expression is "anything that has a
value".
value".</simpara>
<simpara>
The most basic forms of expressions are constants and variables.
When you type "$a = 5", you're assigning '5' into $a. '5', obviously,
has the value 5, or in other words '5' is an expression with the
value of 5 (in this case, '5' is an integer constant).
value of 5 (in this case, '5' is an integer constant).</simpara>
<simpara>
After this assignment, you'd expect $a's value to be 5 as
well, so if you wrote $b = $a, you'd expect it to behave just as
if you wrote $b = 5. In other words, $a is an expression with the
value of 5 as well. If everything works right, this is exactly
what will happen.
what will happen.</simpara>
<para>
Slightly more complex examples for expressions are functions. For
@ -30,7 +30,7 @@ function foo () {
return 5;
}
</programlisting>
</informalexample>
</informalexample></para>
<simpara>
Assuming you're familiar with the concept of functions (if you're
@ -39,7 +39,7 @@ function foo () {
writing <literal>$c = 5</literal>, and you're right. Functions
are expressions with the value of their return value. Since foo()
returns 5, the value of the expression 'foo()' is 5. Usually
functions don't just return a static value but compute something.
functions don't just return a static value but compute something.</simpara>
<simpara>
Of course, values in PHP don't have to be integers, and very often
@ -48,7 +48,7 @@ function foo () {
you can't 'break' into smaller pieces, unlike arrays, for instance).
PHP also supports two composite (non-scalar) types: arrays and
objects. Each of these value types can be assigned into variables or
returned from functions.
returned from functions.</simpara>
<simpara>
So far, users of PHP/FI 2 shouldn't feel any change. However, PHP
@ -65,7 +65,7 @@ function foo () {
is an expression with the value 5. Thus, writing something like
'$b = ($a = 5)' is like writing '$a = 5; $b = 5;' (a semicolon
marks the end of a statement). Since assignments are parsed in a
right to left order, you can also write '$b = $a = 5'.
right to left order, you can also write '$b = $a = 5'.</simpara>
<simpara>
Another good example of expression orientation is pre- and
@ -85,7 +85,7 @@ function foo () {
value, thus the name 'pre-increment'). Post-increment, which is
written '$variable++' evaluates to the original value of
$variable, before it was incremented (PHP increments the variable
after reading its value, thus the name 'post-increment').
after reading its value, thus the name 'post-increment').</simpara>
<simpara>
A very common type of expressions are comparison expressions.
@ -94,7 +94,7 @@ function foo () {
or equal to), == (equal), != (not equal), < (smaller than) and <=
(smaller than or equal to). These expressions are most commonly used
inside conditional execution, such as <literal>if</literal>
statements.
statements.</simpara>
<simpara>
The last example of expressions we'll deal with here is combined
@ -116,7 +116,7 @@ function foo () {
3, but the combined value of $a plus 3 (this is the value that's
assigned into $a). Any two-place operator can be used in this
operator-assignment mode, for example '$a -= 5' (subtract 5 from
the value of $a), '$b *= 7' (multiply the value of $b by 7), etc.
the value of $a), '$b *= 7' (multiply the value of $b by 7), etc.</simpara>
<para>
There is one more expression that may seem odd if you haven't seen
@ -129,7 +129,7 @@ $first ? $second : $third
If the value of the first subexpression is true (non-zero), then
it the second subexpression is evaluated, and that is the result
of the conditional expression. Otherwise, the third subexpression
is evaluated, and that is the value.
is evaluated, and that is the value.</para>
<para>
The following example should help you understand pre- and
@ -156,7 +156,7 @@ $h = $g += 10; /* first, $g is incremented by 10 and ends with the
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>
</programlisting></informalexample></para>
<simpara>
In the beginning of the chapter we said that we'll be describing
@ -165,7 +165,7 @@ $h = $g += 10; /* first, $g is incremented by 10 and ends with the
this case, a statement has the form of 'expr' ';' that is, an
expression followed by a semicolon. In '$b=$a=5;', $a=5 is a
valid expression, but it's not a statement by itself. '$b=$a=5;'
however is a valid statement.
however is a valid statement.</simpara>
<simpara>
One last thing worth mentioning is the truth value of expressions.
@ -179,7 +179,7 @@ $h = $g += 10; /* first, $g is incremented by 10 and ends with the
string and the string "0" are FALSE; all other strings are TRUE.
With non-scalar values (arrays and objects) - if the value
contains no elements it's considered FALSE, otherwise it's
considered TRUE.
considered TRUE.</simpara>
<simpara>
PHP provides a full and powerful implementation of expressions, and
@ -187,7 +187,7 @@ $h = $g += 10; /* first, $g is incremented by 10 and ends with the
above examples should give you a good idea about what expressions
are and how you can construct useful expressions. Throughout the
rest of this manual we'll write <replaceable>expr</replaceable>
to indicate any valid PHP expression.
to indicate any valid PHP expression.</simpara>
</chapter>

48
language/functions.sgml
View file

@ -14,15 +14,15 @@ function foo ($arg_1, $arg_2, ..., $arg_n) {
return $retval;
}
</programlisting>
</informalexample>
</informalexample></para>
<simpara>
Any valid PHP code may appear inside a function, even other
functions and <link linkend="keyword.class">class</link>
definitions.
definitions.</simpara>
<simpara>
Functions must be defined before they are referenced.
Functions must be defined before they are referenced.</simpara></sect1>
<sect1 id="functions.returning-values">
<title>Returning values</title>
@ -38,7 +38,7 @@ function square ($num) {
}
echo square (4); // outputs '16'.
</programlisting>
</informalexample>
</informalexample></para>
<para>
You can't return multiple values from a function, but similar
@ -51,20 +51,18 @@ function small_numbers() {
}
list ($zero, $one, $two) = small_numbers();
</programlisting>
</informalexample>
</informalexample></para></sect1>
<sect1 id="functions.arguments">
<title>Function arguments</title>
<simpara>
Information may be passed to functions via the argument list,
which is a comma-delimited list of variables and/or constants.
which is a comma-delimited list of variables and/or constants.</simpara>
<para>
PHP supports passing arguments by value (the default), <link
linkend="functions.arguments.by-reference">passing by
reference</link>, and <link
linkend="functions.arguments.default">default argument
PHP supports passing arguments by value (the default), <link linkend="functions.arguments.by-reference">passing by
reference</link>, and <link linkend="functions.arguments.default">default argument
values</link>. Variable-length argument lists are not supported,
but a similar effect may be obtained by passing arrays.
@ -74,7 +72,7 @@ function takes_array($input) {
echo "$input[0] + $input[1] = ", $input[0]+$input[1];
}
</programlisting>
</informalexample>
</informalexample></para>
<sect2 id="functions.arguments.by-reference">
<title>Making arguments be passed by reference</title>
@ -84,7 +82,7 @@ function takes_array($input) {
if you change the value of the argument within the function,
it does not get changed outside of the function). If you wish
to allow a function to modify its arguments, you must pass them
by reference.
by reference.</simpara>
<para>
If you want an argument to a function to always be passed by
@ -100,7 +98,7 @@ $str = 'This is a string, ';
add_some_extra($str);
echo $str; // outputs 'This is a string, and something extra.'
</programlisting>
</informalexample>
</informalexample></para>
<para>
If you wish to pass a variable by reference to a function which
@ -118,7 +116,7 @@ echo $str; // outputs 'This is a string, '
foo (&amp;$str);
echo $str; // outputs 'This is a string, and something extra.'
</programlisting>
</informalexample>
</informalexample></para></sect2>
<sect2 id="functions.arguments.default">
<title>Default argument values</title>
@ -135,7 +133,7 @@ function makecoffee ($type = "cappucino") {
echo makecoffee ();
echo makecoffee ("espresso");
</programlisting>
</informalexample>
</informalexample></para>
<para>
The output from the above snippet is:
@ -143,16 +141,16 @@ echo makecoffee ("espresso");
<screen>
Making a cup of cappucino.
Making a cup of espresso.
</screen>
</screen></para>
<simpara>
The default value must be a constant expression, not (for
example) a variable or class member.
example) a variable or class member.</simpara>
<para>
In PHP 4.0 it's also possible to specify <literal>unset</literal>
for default argument. This means that the argument will not be
set at all, if a value is not supplied.
set at all, if a value is not supplied.</para>
<para>
Note that when using default arguments, any defaults should be
@ -168,7 +166,7 @@ function makeyogurt ($type = "acidophilus", $flavour) {
echo makeyogurt ("raspberry"); // won't work as expected
</programlisting>
</informalexample>
</informalexample></para>
<para>
The output of the above example is:
@ -177,7 +175,7 @@ echo makeyogurt ("raspberry"); // won't work as expected
Warning: Missing argument 2 in call to makeyogurt() in
/usr/local/etc/httpd/htdocs/php3test/functest.html on line 41
Making a bowl of raspberry .
</screen>
</screen></para>
<para>
Now, compare the above with this:
@ -190,14 +188,14 @@ function makeyogurt ($flavour, $type = "acidophilus") {
echo makeyogurt ("raspberry"); // works as expected
</programlisting>
</informalexample>
</informalexample></para>
<para>
The output of this example is:
<screen>
Making a bowl of acidophilus raspberry.
</screen>
</screen></para></sect2></sect1>
<sect1 id="functions.old-syntax">
<title><literal>old_function</literal></title>
@ -205,10 +203,10 @@ Making a bowl of acidophilus raspberry.
<simpara>
The <literal>old_function</literal> statement allows you to declare
a function using a syntax identical to PHP/FI2 (except you must
replace 'function' with 'old_function'.
replace 'function' with 'old_function'.</simpara>
<simpara>
This is a deprecated feature, and should only be used by the
PHP/FI2->PHP3 convertor.
PHP/FI2->PHP3 convertor.</simpara>
<warning>
<para>
Functions declared as <literal>old_function</literal>
@ -219,7 +217,7 @@ Making a bowl of acidophilus raspberry.
this limitation by writing a wrapper function (in normal PHP3 form)
to call the <literal>old_function</literal>.
</para>
</warning>
</warning></sect1>
</chapter>

18
language/oop.sgml
View file

@ -8,7 +8,7 @@
these variables. A class is defined using the following syntax:
<informalexample>
<programlisting role=php>
<programlisting role="php">
&lt;?php
class Cart {
var $items; // Items in our shopping cart
@ -32,7 +32,7 @@
}
?>
</programlisting>
</informalexample>
</informalexample></para>
<para>
This defines a class named Cart that consists of an associative
@ -46,7 +46,7 @@
</para>
<informalexample>
<programlisting role=php>
<programlisting role="php">
$cart = new Cart;
$cart->add_item("10", 1);
</programlisting>
@ -64,7 +64,7 @@
</para>
<informalexample>
<programlisting role=php>
<programlisting role="php">
class Named_Cart extends Cart {
var $owner;
@ -84,7 +84,7 @@
</para>
<informalexample>
<programlisting role=php>
<programlisting role="php">
$ncart = new Named_Cart; // Create a named cart
$ncart->set_owner ("kris"); // Name that cart
print $ncart->owner; // print the cart owners name
@ -105,7 +105,7 @@
</para>
<informalexample>
<programlisting role=php>
<programlisting role="php">
class Auto_Cart extends Cart {
function Auto_Cart () {
$this->add_item ("10", 1);
@ -123,7 +123,7 @@
</para>
<informalexample>
<programlisting role=php>
<programlisting role="php">
class Constructor_Cart {
function Constructor_Cart ($item = "10", $num = 1) {
$this->add_item ($item, $num);
@ -143,8 +143,8 @@
<caution>
<simpara>
For derived classes, the constructor of the parent class is not
automatically called when the derived class's constructor is called.
</caution>
automatically called when the derived class's constructor is called.</simpara>
</caution></sect1>
</chapter>

16
language/operators.sgml
View file

@ -57,7 +57,7 @@
strings that get converted to integers). If either operand is a
floating-point value, floating-point division is performed.
</simpara>
-->
--></sect1>
<sect1 id="language.operators.string">
<title>String Operators</title>
@ -70,7 +70,7 @@
$a = "Hello ";
$b = $a . "World!"; // now $b = "Hello World!"
</programlisting></informalexample>
</para>
</para></sect1>
<sect1 id="language.operators.assignment">
<title>Assignment Operators</title>
@ -97,7 +97,7 @@ $a += 5; // sets $a to 8, as if we had said: $a = $a + 5;
$b = "Hello ";
$b .= "There!"; // sets $b to "Hello There!", just like $b = $b . "There!";
</programlisting></informalexample>
</para>
</para></sect1>
<sect1 id="language.operators.bitwise">
<title>Bitwise Operators</title>
@ -149,7 +149,7 @@ $b .= "There!"; // sets $b to "Hello There!", just like $b = $b . "There!";
</row>
</tbody>
</tgroup>
</table>
</table></sect1>
<sect1 id="language.operators.logical">
<title>Logical Operators</title>
@ -202,7 +202,7 @@ $b .= "There!"; // sets $b to "Hello There!", just like $b = $b . "There!";
<simpara>
The reason for the two different variations of "and" and "or"
operators is that they operate at different precedences. (See below.)
</simpara>
</simpara></sect1>
<sect1 id="language.operators.comparison">
<title>Comparison Operators</title>
@ -262,7 +262,7 @@ $b .= "There!"; // sets $b to "Hello There!", just like $b = $b . "There!";
<informalexample><programlisting>(expr1) ? (expr2) : (expr3);</programlisting></informalexample>
This expression returns to <replaceable>expr2</replaceable> if
<replaceable>expr1</replaceable> evalutes to true, and expr3 if
<replaceable>expr1</replaceable> evaluates to false.
<replaceable>expr1</replaceable> evaluates to false.</para></sect1>
<sect1 id="language.operators.precedence">
<title>Operator Precedence</title>
@ -271,7 +271,7 @@ $b .= "There!"; // sets $b to "Hello There!", just like $b = $b . "There!";
two expressions together. For example, in the expression
<literal>1 + 5 * 3</literal>, the answer is 16 and not
18 because the multiplication ("*") operator has a higher precedence
than the addition ("+") operator.
than the addition ("+") operator.</para>
<para>
The following table lists the precedence of operators with the
lowest-precedence operators listed first.
@ -368,7 +368,7 @@ $b .= "There!"; // sets $b to "Hello There!", just like $b = $b . "There!";
</row>
</tbody>
</tgroup>
</table>
</table></para></sect1>
</chapter>

105
language/types.sgml
View file

@ -5,29 +5,27 @@
PHP supports the following types:
<itemizedlist>
<listitem><simpara><link linkend="language.types.integer">integer</link>
<listitem><simpara><link linkend="language.types.double">floating-point numbers</link>
<listitem><simpara><link linkend="language.types.string">string</link>
<listitem><simpara><link linkend="language.types.array">array</link>
<listitem><simpara><link linkend="language.types.object">object</link>
</itemizedlist>
<listitem><simpara><link linkend="language.types.integer">integer</link></simpara></listitem>
<listitem><simpara><link linkend="language.types.double">floating-point numbers</link></simpara></listitem>
<listitem><simpara><link linkend="language.types.string">string</link></simpara></listitem>
<listitem><simpara><link linkend="language.types.array">array</link></simpara></listitem>
<listitem><simpara><link linkend="language.types.object">object</link></simpara></listitem>
</itemizedlist></para>
<simpara>
The type of a variable is usually not set by the programmer;
rather, it is decided at runtime by PHP depending on the context
in which that variable is used.
in which that variable is used.</simpara>
<simpara>
If you would like to force a variable to be converted to a certain
type, you may either <link
linkend="language.types.typecasting">cast</link> the variable or use
the <function>settype</function> function on it.
type, you may either <link linkend="language.types.typecasting">cast</link> the variable or use
the <function>settype</function> function on it.</simpara>
<simpara>
Note that a variable may behave in different manners in certain
situations, depending on what type it is a the time. For more
information, see the section on <link
linkend="language.types.type-juggling">Type Juggling</link>.
situations, depending on what type it is at the time. For more
information, see the section on <link linkend="language.types.type-juggling">Type Juggling</link>.</simpara>
<sect1 id="language.types.integer">
<title>Integers</title>
@ -38,7 +36,7 @@ $a = 1234; # decimal number
$a = -123; # a negative number
$a = 0123; # octal number (equivalent to 83 decimal)
$a = 0x12; # hexadecimal number (equivalent to 18 decimal)
</programlisting></informalexample>
</programlisting></informalexample></para></sect1>
<sect1 id="language.types.double">
<title>Floating point numbers</title>
@ -48,12 +46,12 @@ $a = 0x12; # hexadecimal number (equivalent to 18 decimal)
<informalexample><programlisting>
$a = 1.234;
$a = 1.2e3;
</programlisting></informalexample>
</programlisting></informalexample></para></sect1>
<sect1 id="language.types.string">
<title>Strings</title>
<para>
Strings can be specified using one of two sets of delimiters.
Strings can be specified using one of two sets of delimiters.</para>
<para>
If the string is enclosed in double-quotes ("), variables
within the string will be expanded (subject to some parsing
@ -109,27 +107,27 @@ $a = 1.2e3;
</row>
</tbody>
</tgroup>
</table>
</table></para>
<para>
You can escape any other character, but a warning will be issued
at the highest warning level.
at the highest warning level.</para>
<para>
The second way to delimit a string uses the single-quote ("'")
character, which does not do any variable expansion or backslash
processing (except for "\\" and "\'" so you can insert backslashes
and single-quotes in a singly-quoted string).
and single-quotes in a singly-quoted string).</para>
<sect2 id="language.types.string.conversion">
<title>String conversion</title>
<simpara>
When a string is evaluated as a numeric value, the resulting
value and type are determined as follows.
value and type are determined as follows.</simpara>
<simpara>
The string will evaluate as a double if it contains any of the
characters '.', 'e', or 'E'. Otherwise, it will evaluate as an
integer.
integer.</simpara>
<para>
The value is given by the initial portion of the string. If the
@ -138,11 +136,11 @@ $a = 1.2e3;
is an optional sign, followed by one or more digits (optionally
containing a decimal point), followed by an optional
exponent. The exponent is an 'e' or 'E' followed by one or more
digits.
digits.</para>
<simpara>
When the first expression is a string, the type of the variable
will depend on the second expression.
will depend on the second expression.</simpara>
<informalexample>
<programlisting>
@ -159,14 +157,14 @@ $foo = "10.0 pigs " + 1.0; // $foo is double (11)
<simpara>
For more information on this conversion, see the Unix manual
page for strtod(3).
page for strtod(3).</simpara></sect2></sect1>
<sect1 id="language.types.array">
<title>Arrays</title>
<para>
Arrays actually act like both hash tables (associative arrays)
and indexed arrays (vectors).
and indexed arrays (vectors).</para>
<sect2 id="language.types.array.single-dim">
<title>Single Dimension Arrays</title>
@ -183,7 +181,7 @@ $a[0] = "abc";
$a[1] = "def";
$b["foo"] = 13;
</programlisting>
</informalexample>
</informalexample></para>
<para>
You can also create an array by simply adding values to
@ -194,7 +192,7 @@ $b["foo"] = 13;
$a[] = "hello"; // $a[2] == "hello"
$a[] = "world"; // $a[3] == "world"
</programlisting>
</informalexample>
</informalexample></para>
<para>
Arrays may be sorted using the <function>asort</function>,
@ -202,17 +200,17 @@ $a[] = "world"; // $a[3] == "world"
<function>rsort</function>, <function>sort</function>,
<function>uasort</function>, <function>usort</function>, and
<function>uksort</function> functions depending on the type of
sort you want.
sort you want.</para>
<para>
You can count the number of items in an array using the
<function>count</function> function.
<function>count</function> function.</para>
<para>
You can traverse an array using <function>next</function> and
<function>prev</function> functions. Another common way to
traverse an array is to use the <function>each</function>
function.
function.</para></sect2>
<sect2 id="language.types.array.multi-dim">
<title>Multi-Dimensional Arrays</title>
@ -232,7 +230,7 @@ $a[3]["bar"] = $f; # (you can mix numeric and associative indices)
$a["foo"][4]["bar"][0] = $f; # four dimensional!
</programlisting>
</informalexample>
</informalexample></para>
<para>
You can "fill up" multi-dimensional arrays in many ways,
@ -261,7 +259,7 @@ $a = array(
3 => 4
);
</programlisting>
</informalexample>
</informalexample></para>
<para>
The <function>array</function> function can be nested for
@ -291,7 +289,7 @@ $a = array(
echo $a["apple"]["taste"]; # will output "sweet"
?>
</programlisting>
</informalexample>
</informalexample></para></sect2></sect1>
<sect1 id="language.types.object">
<title>Objects</title>
@ -312,9 +310,9 @@ class foo {
}
$bar = new foo;
$bar -> do_foo ();
$bar->do_foo();
</programlisting>
</informalexample>
</informalexample></para></sect2></sect1>
<sect1 id="language.types.type-juggling">
<title>Type juggling</title>
@ -326,7 +324,7 @@ $bar -> do_foo ();
assign a string value to variable <parameter>var</parameter>,
<parameter>var</parameter> becomes a string. If you then assign
an integer value to <parameter>var</parameter>, it becomes an
integer.
integer.</simpara>
<para>
An example of PHP's automatic type conversion is the addition
@ -346,18 +344,16 @@ $foo = $foo + 1.3; // $foo is now a double (3.3)
$foo = 5 + "10 Little Piggies"; // $foo is integer (15)
$foo = 5 + "10 Small Pigs"; // $foo is integer (15)
</programlisting>
</informalexample>
</informalexample></para>
<simpara>
If the last two examples above seem odd, see <link
linkend="language.types.string.conversion">String conversion</link>.
If the last two examples above seem odd, see <link linkend="language.types.string.conversion">String conversion</link>.</simpara>
<simpara>
If you wish to force a variable to be evaluated as a certain
type, see the section on <link
linkend="language.types.typecasting">Type casting</link>. If you
type, see the section on <link linkend="language.types.typecasting">Type casting</link>. If you
wish to change the type of a variable, see
<function>settype</function>.
<function>settype</function>.</simpara>
<sect2 id="language.types.typecasting">
<title>Type casting</title>
@ -372,17 +368,17 @@ $foo = 5 + "10 Small Pigs"; // $foo is integer (15)
$foo = 10; // $foo is an integer
$bar = (double) $foo; // $bar is a double
</programlisting>
</informalexample>
</informalexample></para>
<para>
The casts allowed are:
<itemizedlist>
<listitem><simpara>(int), (integer) - cast to integer
<listitem><simpara>(real), (double), (float) - cast to double
<listitem><simpara>(string) - cast to string
<listitem><simpara>(array) - cast to array
<listitem><simpara>(object) - cast to object
</itemizedlist>
<listitem><simpara>(int), (integer) - cast to integer</simpara></listitem>
<listitem><simpara>(real), (double), (float) - cast to double</simpara></listitem>
<listitem><simpara>(string) - cast to string</simpara></listitem>
<listitem><simpara>(array) - cast to array</simpara></listitem>
<listitem><simpara>(object) - cast to object</simpara></listitem>
</itemizedlist></para>
<para>
Note that tabs and spaces are allowed inside the parentheses, so
@ -393,7 +389,16 @@ $bar = (double) $foo; // $bar is a double
$foo = (int) $bar;
$foo = ( int ) $bar;
</programlisting>
</informalexample>
</informalexample></para>
<para>
It may not be obvious exactly what will happen when casting
between certain types. For instance, the following should be
noted:
</para></sect2></sect1>
</chapter>

70
language/variables.sgml
View file

@ -9,7 +9,7 @@
For the most part all PHP variables only have a single scope.
However, within user-defined functions a local function scope is
introduced. Any variable used inside a function is by default
limited to the local function scope. For example:
limited to the local function scope. For example:</simpara>
<informalexample>
<programlisting>
@ -32,7 +32,7 @@ Test ();
overridden by a local definition. This can cause some problems in
that people may inadvertently change a global variable. In PHP
global variables must be declared global inside a function if they
are going to be used in that function. An example:
are going to be used in that function. An example:</simpara>
<informalexample>
<programlisting>
@ -54,12 +54,12 @@ echo $b;
The above script will output &quot;3&quot;. By declaring $a and
$b global within the function, all references to either variable
will refer to the global version. There is no limit to the number
of global variables that can be manipulated by a function.
of global variables that can be manipulated by a function.</simpara>
<simpara>
A second way to access variables from the global scope is to use
the special PHP-defined $GLOBALS array. The previous example can
be rewritten as:
be rewritten as:</simpara>
<informalexample>
<programlisting>
@ -78,14 +78,14 @@ echo $b;
<simpara>
The $GLOBALS array is an associative array with the name of the
global variable being the key and the contents of that variable
being the value of the array element.
being the value of the array element.</simpara>
<simpara>
Another important feature of variable scoping is the
<emphasis>static</emphasis> variable. A static variable exists
only in a local function scope, but it does not lose its value
when program execution leaves this scope. Consider the following
example:
example:</simpara>
<informalexample>
<programlisting>
@ -103,7 +103,7 @@ Function Test () {
the variable serves no purpose since as soon as the function exits
the $a variable disappears. To make a useful counting function
which will not lose track of the current count, the $a variable is
declared static:
declared static:</simpara>
<informalexample>
<programlisting>
@ -117,7 +117,7 @@ Function Test () {
<simpara>
Now, every time the Test() function is called it will print the
value of $a and increment it.
value of $a and increment it.</simpara>
<simpara>
Static variables are also essential when functions are called
@ -125,7 +125,7 @@ Function Test () {
Care must be taken when writing a recursive function because it is
possible to make it recurse indefinitely. You must make sure you
have an adequate way of terminating the recursion. The following
simple function recursively counts to 10:
simple function recursively counts to 10:</simpara>
<informalexample>
<programlisting>
@ -140,7 +140,7 @@ Function Test () {
$count--;
}
</programlisting>
</informalexample>
</informalexample></sect1>
<sect1 id="language.variables.variable">
<title>Variable variables</title>
@ -148,7 +148,7 @@ Function Test () {
<simpara>
Sometimes it is convenient to be able to have variable variable
names. That is, a variable name which can be set and used
dynamically. A normal variable is set with a statement such as:
dynamically. A normal variable is set with a statement such as:</simpara>
<informalexample>
<programlisting>
@ -159,7 +159,7 @@ $a = "hello";
<simpara>
A variable variable takes the value of a variable and treats that as the
name of a variable. In the above example, <emphasis>hello</emphasis>, can
be used as the name of a variable by using two dollar signs. ie.
be used as the name of a variable by using two dollar signs. ie.</simpara>
<informalexample>
<programlisting>
@ -170,7 +170,7 @@ $$a = "world";
<simpara>
At this point two variables have been defined and stored in the
PHP symbol tree: $a with contents "hello" and $hello with contents
"world". Therefore, this statement:
"world". Therefore, this statement:</simpara>
<informalexample>
<programlisting>
@ -179,7 +179,7 @@ echo "$a ${$a}";
</informalexample>
<simpara>
produces the exact same output as:
produces the exact same output as:</simpara>
<informalexample>
<programlisting>
@ -188,7 +188,7 @@ echo "$a $hello";
</informalexample>
<simpara>
ie. they both produce: <emphasis>hello world</emphasis>.
ie. they both produce: <emphasis>hello world</emphasis>.</simpara>
<simpara>
In order to use variable variables with arrays, you have to
@ -196,7 +196,7 @@ echo "$a $hello";
the parser needs to know if you meant to use $a[1] as a variable,
or if you wanted $$a as the variable and then the [1] index from
that variable. The syntax for resolving this ambiguity is:
${$a[1]} for the first case and ${$a}[1] for the second.
${$a[1]} for the first case and ${$a}[1] for the second.</simpara></sect1>
<sect1 id="language.variables.external">
<title>Variables from outside PHP</title>
@ -207,7 +207,7 @@ echo "$a $hello";
<simpara>
When a form is submitted to a PHP script, any variables from that
form will be automatically made available to the script by
PHP. For instance, consider the following form:
PHP. For instance, consider the following form:</simpara>
<para>
<example>
@ -218,19 +218,19 @@ echo "$a $hello";
&lt;input type="submit">
&lt;/form>
</programlisting>
</example>
</example></para>
<simpara>
When submitted, PHP will create the variable
<computeroutput>$name</computeroutput>, which will will contain
whatever what entered into the <emphasis>Name:</emphasis> field
on the form.
on the form.</simpara>
<simpara>
PHP also understands arrays in the context of form variables, but
only in one dimension. You may, for example, group related
variables together, or use this feature to retrieve values from a
multiple select input:
multiple select input:</simpara>
<para>
<example>
@ -247,22 +247,21 @@ echo "$a $hello";
&lt;input type="submit">
&lt;/form>
</programlisting>
</example>
</example></para>
<simpara>
If PHP's track_vars feature is turned on, either by the <link
linkend="ini.track-vars">track_vars</link> configuration setting
If PHP's track_vars feature is turned on, either by the <link linkend="ini.track-vars">track_vars</link> configuration setting
or the <computeroutput>&lt;?php_track_vars?&gt;</computeroutput>
directive, then variables submitted via the POST or GET methods
will also be found in the global associative arrays
$HTTP_POST_VARS and $HTTP_GET_VARS as appropriate.
$HTTP_POST_VARS and $HTTP_GET_VARS as appropriate.</simpara>
<sect3>
<title>IMAGE SUBMIT variable names</TITLE>
<title>IMAGE SUBMIT variable names</title>
<simpara>
When submitting a form, it is possible to use an image instead
of the standard submit button with a tag like:
of the standard submit button with a tag like:</simpara>
<informalexample>
<programlisting>
@ -277,14 +276,13 @@ echo "$a $hello";
the user click within the image. The experienced may note that
the actual variable names sent by the browser contains a period
rather than an underscore, but PHP converts the period to an
underscore automatically.
underscore automatically.</simpara></sect3></sect2>
<sect2 id="language.variables.external.cookies">
<title>HTTP Cookies</title>
<simpara>
PHP transparently supports HTTP cookies as defined by <ulink
url="&spec.cookies;">Netscape's Spec</ulink>. Cookies are a
PHP transparently supports HTTP cookies as defined by <ulink url="&spec.cookies;">Netscape's Spec</ulink>. Cookies are a
mechanism for storing data in the remote browser and thus
tracking or identifying return users. You can set cookies using
the <function>SetCookie</function> function. Cookies are part
@ -292,11 +290,11 @@ echo "$a $hello";
before any output is sent to the browser. This is the same
restriction as for the <function>Header</function> function.
Any cookies sent to you from the client will automatically be
turned into a PHP variable just like GET and POST method data.
turned into a PHP variable just like GET and POST method data.</simpara>
<simpara>
If you wish to assign multiple values to a single cookie, just
add <emphasis>[]</emphasis> to the cookie name. For example:
add <emphasis>[]</emphasis> to the cookie name. For example:</simpara>
<informalexample>
<programlisting>
@ -308,7 +306,7 @@ SetCookie ("MyCookie[]", "Testing", time()+3600);
Note that a cookie will replace a previous cookie by the same
name in your browser unless the path or domain is different. So,
for a shopping cart application you may want to keep a counter
and pass this along. i.e.
and pass this along. i.e.</simpara>
<example>
<title>SetCookie Example</title>
@ -317,7 +315,7 @@ $Count++;
SetCookie ("Count", $Count, time()+3600);
SetCookie ("Cart[$Count]", $item, time()+3600);
</programlisting>
</example>
</example></sect2>
<sect2 id="language.variables.external.environment">
<title>Environment variables</title>
@ -330,7 +328,7 @@ SetCookie ("Cart[$Count]", $item, time()+3600);
<programlisting>
echo $HOME; /* Shows the HOME environment variable, if set. */
</programlisting>
</informalexample>
</informalexample></para>
<para>
Since information coming in via GET, POST and Cookie mechanisms
@ -339,7 +337,7 @@ echo $HOME; /* Shows the HOME environment variable, if set. */
sure that you are getting the right version. The
<function>getenv</function> function can be used for this. You
can also set an environment variable with the
<function>putenv</function> function.
<function>putenv</function> function.</para></sect2>
<sect2>
<title>Determining variable types</title>
@ -352,7 +350,7 @@ echo $HOME; /* Shows the HOME environment variable, if set. */
<function>gettype</function>, <function>is_long</function>,
<function>is_double</function>, <function>is_string</function>,
<function>is_array</function>, and
<function>is_object</function>.
<function>is_object</function>.</para></sect2></sect1>
</chapter>