glace Sun Apr 8 03:02:07 2001 EDT
Added files:
/phpdoc/hk bookinfo.xml language-defs.ent make_chm_index_hk.html
preface.xml
/phpdoc/hk/chapters config.xml install.xml intro.xml security.xml
/phpdoc/hk/features connection-handling.xml cookies.xml
error-handling.xml file-upload.xml
http-auth.xml images.xml
persistent-connections.xml remote-files.xml
Log:
draft
Index: phpdoc/hk/bookinfo.xml
+++ phpdoc/hk/bookinfo.xml
<bookinfo id="bookinfo">
<authorgroup id="authors">
<author>
<firstname>Stig</firstname><surname>Sæther Bakken</surname>
</author>
<author>
<firstname>Alexander</firstname><surname>Aulbach</surname>
</author>
<author>
<firstname>Egon</firstname><surname>Schmid</surname>
</author>
<author>
<firstname>Jim</firstname><surname>Winstead</surname>
</author>
<author>
<firstname>Lars Torben</firstname><surname>Wilson</surname>
</author>
<author>
<firstname>Rasmus</firstname><surname>Lerdorf</surname>
</author>
<author>
<firstname>Zeev</firstname><surname>Suraski</surname>
</author>
<author>
<firstname>Andrei</firstname><surname>Zmievski</surname>
</author>
<author>
<firstname>Jouni</firstname><surname>Ahto</surname>
</author>
</authorgroup>
<pubdate>&php.build-date;</pubdate>
<authorgroup id="editors">
<editor>
<firstname>Stig</firstname><surname>Sæther Bakken</surname>
</editor>
<editor>
<firstname>Egon</firstname><surname>Schmid</surname>
</editor>
</authorgroup>
<copyright>
<year>1997</year>
<year>1998</year>
<year>1999</year>
<year>2000</year>
<year>2001</year>
<holder>the PHP 文獻組 </holder>
</copyright>
<legalnotice id="copyright">
<title>版權</title>
<simpara>
本手冊的版權由 PHP 文獻小組所持有； 1997, 1998, 1999, 2000, 2001。小組成員名單列於
<link linkend="authors">手冊的第一頁</link>.
</simpara>
<simpara>
本手冊內容可按 Free Software Foundation 所發表的 GNU General Public License
中的條款分發。(你可選擇跟隨該條款的第 2 版或以後的版本。)
</simpara>
</legalnotice>
</bookinfo>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
Index: phpdoc/hk/language-defs.ent
+++ phpdoc/hk/language-defs.ent
<!ENTITY PHPManual "PHP 手冊">
<!ENTITY Date "日期:">
<!ENTITY GettingStarted "入門篇">
<!ENTITY LanguageReference "語法篇">
<!ENTITY Features "語言特徵">
<!ENTITY FunctionReference "函數目錄">
<!ENTITY Appendixes "附件">
<!ENTITY PEAR "PEAR: PHP Extension and Application Repository">
<!ENTITY available "available in">
Index: phpdoc/hk/make_chm_index_hk.html
+++ phpdoc/hk/make_chm_index_hk.html
<HTML>
<HEAD>
<TITLE>PHP Manual</TITLE>
<META NAME="HTTP_EQUIV" CONTENT="text/html; charset=ISO-8859-1">
<LINK REL="STYLESHEET" HREF="style.css">
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF"
TOPMARGIN="0" LEFTMARGIN="0">
<TABLE BORDER="0" WIDTH="100%" HEIGHT="100%" CELLSPACING="0" CELLPADDING="0">
<TR><TD COLSPAN="3"><DIV CLASS="NAVHEADER"><TABLE BGCOLOR="#CCCCFF" BORDER="0"
CELLPADDING="0" CELLSPACING="0" WIDTH="100%"><TR><TD><TABLE WIDTH="100%" BORDER="0"
CELLPADDING="3" CELLSPACING="0"><TR><TH COLSPAN="3">PHP Manual</TH></TR><TR><TD
COLSPAN="3" ALIGN="center"> </TD></TR></TABLE></TD></TR><TR BGCOLOR="#333366">
<TD><IMG SRC="spacer.gif" BORDER="0" WIDTH="1"
HEIGHT="1"><BR></TD></TR></TABLE></DIV></TD></TR>
<TR><TD><IMG SRC="spacer.gif" WIDTH="10" HEIGHT="1"></TD><TD HEIGHT="100%"
VALIGN="MIDDLE" WIDTH="100%"><BR>
<P><TABLE ALIGN="CENTER">
<TR><TD ALIGN="CENTER">
<H1 CLASS="title">PHP Manual</H1>
<DIV CLASS="author">Stig Sæther Bakken</DIV>
<DIV CLASS="author">Alexander Aulbach</DIV>
<DIV CLASS="author">Egon Schmid</DIV>
<DIV CLASS="author">Jim Winstead</DIV>
<DIV CLASS="author">Lars Torben Wilson</DIV>
<DIV CLASS="author">Rasmus Lerdorf</DIV>
<DIV CLASS="author">Zeev Suraski</DIV>
<DIV CLASS="author">Andrei Zmievski</DIV>
<DIV CLASS="author">Jouni Ahto</DIV>
<H4 CLASS="EDITEDBY">Edited by</H4>
<H3 CLASS="editor">Stig Sæther Bakken</H3>
<H3 CLASS="editor">Egon Schmid</H3>
</TD></TR></TABLE>
<BR><P ALIGN="CENTER">This file was generated: [GENTIME]<BR>
Go to <A HREF="http://www.php.net/docs.php">http://www.php.net/docs.php</A>
to get the actual version.</P>
<BR><P CLASS="copyright" ALIGN="CENTER"><A HREF="copyright.html">Copyright</A> ©
1997,
1998, 1999, 2000, 2001 the PHP Documentation Group</P>
</TD><TD><IMG SRC="spacer.gif" WIDTH="10" HEIGHT="1"></TD></TR>
<TR><TD COLSPAN="3"><DIV CLASS="NAVFOOTER"><TABLE BGCOLOR="#CCCCFF" BORDER="0"
CELLPADDING="0" CELLSPACING="0" WIDTH="100%"><TR BGCOLOR="#333366">
<TD><IMG SRC="spacer.gif" BORDER="0" WIDTH="1" HEIGHT="1"><BR></TD></TR>
<TR><TD><TABLE WIDTH="100%" BORDER="0" CELLPADDING="3" CELLSPACING="0">
<TR><TD COLSPAN="3"> </TD></TR><TR><TD COLSPAN="3" ALIGN="center"> </TD>
</TR></TABLE></TD></TR></TABLE></DIV></TD></TR></TABLE>
</BODY></HTML>
Index: phpdoc/hk/preface.xml
+++ phpdoc/hk/preface.xml
<preface id="preface">
<title>前言</title>
<abstract>
<simpara>
<acronym>PHP</acronym>乃指 "PHP: Hypertext Preprocessor"， 是一種包含在 HTML
文件中的翻譯器語言。 它所用的句法多數是借用 C, Java 和 Perl
另加上一些它自己的獨有特徵。
開發這種語言的目的是讓網頁工程師能更快的寫出能根據需要自動產生 HTML 頁面的程式。
</simpara>
</abstract>
<sect1 id="about">
<title>關於本手冊</title>
<para>
本手冊採用 XML標籤語言， 利用 <ulink
url="&url.docbook.xml;">DocBook XML DTD</ulink>作編寫工具，並使用了<ulink
url="&url.dsssl;"><acronym>DSSSL</acronym></ulink> (Document
Style and Semantics Specification Language) 來編排內容。 寫作 HTML, TeX and RTF
版本的軟件是
<ulink url="&url.jclark;">James Clark</ulink> 所開發的
<ulink url="&url.jade;">Jade</ulink> 以及 <ulink url="&url.nwalsh;">Norman
Walsh</ulink>開發的
<ulink url="&url.dbstyle;">The Modular DocBook Stylesheets</ulink>
。 整個 PHP 文獻紀錄的框架是由 &link.stig; 所整理出來的。
</para>
<para>
You can download the manual in various languages and formats,
including <acronym>PDF</acronym>, plain text, plain
<acronym>HTML</acronym>, WinHelp, and <acronym>RTF</acronym>
from <ulink url="&url.php.docs;">&url.php.docs;</ulink>.
</para>
<para>
Daily HTML snapshots of the manual, including translations, can be
found at <ulink
url="&url.php.snaps.manual;">&url.php.snaps.manual;</ulink>.
</para>
<para>
You can find more information about downloading the
<acronym>XML</acronym> source code of this documentation
at <ulink url="&url.php.cvs;">&url.php.cvs;</ulink>. The
documentation is stored in the <literal>phpdoc</literal> module.
</para>
</sect1>
</preface>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
Index: phpdoc/hk/chapters/config.xml
+++ phpdoc/hk/chapters/config.xml
<chapter id="configuration">
<title>Configuration</title>
<sect1 id="configuration.file">
<title>The configuration file</title>
<simpara>
The configuration file (called <filename>php3.ini</filename> in
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.</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.</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_".</simpara>
<para>
With PHP 4.0, there are just a few Apache directives that allow you
to change the PHP configuration settings.
<variablelist>
<varlistentry>
<term>
<systemitem role="directive">php_value</systemitem>
<parameter>name</parameter>
<parameter>value</parameter>
</term>
<listitem>
<para>
This sets the value of the specified variable.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<systemitem role="directive">php_flag</systemitem>
<parameter>name</parameter>
<parameter>on|off</parameter>
</term>
<listitem>
<para>
This is used to set a Boolean configuration option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<systemitem role="directive">php_admin_value</systemitem>
<parameter>name</parameter>
<parameter>value</parameter>
</term>
<listitem>
<para>
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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<systemitem role="directive">php_admin_flag</systemitem>
<parameter>name</parameter>
<parameter>on|off</parameter>
</term>
<listitem>
<para>
This is used to set a Boolean configuration option.</para>
</listitem>
</varlistentry>
</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>.</simpara>
<sect2 id="ini.sect.general">
<title>General Configuration Directives</title>
<para>
<variablelist>
<varlistentry id="ini.allow-url-fopen">
<term>
<parameter>allow_url_fopen</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
This option enables the URL-aware fopen wrappers that enable accessing URL
object
like files. Default wrappers are provided for the access of
<link linkend="features.remote-files">remote files</link>
using the ftp or http protocol, some extensions like zlib may register
additional wrappers.
</para>
<note>
<para>
This option was introduced immediately after the release of version 4.0.3.
For versions up to and including 4.0.3 you can only disable this feature at
compile time by using the configuration switch
<link
linkend="install.configure.disable-url-fopen-wrapper"><parameter>--disable-url-fopen-wrapper</parameter></link>.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry id="ini.asp-tags">
<term>
<parameter>asp_tags</parameter>
<type>boolean</type>
</term>
<listitem>
<simpara>
Enables the use of ASP-like <% %> tags in addition to
the usual <?php ?> tags. This includes the
variable-value printing shorthand of <%= $value %>. For
more information, see <link linkend="language.basic-syntax.phpmode">Escaping
from HTML</link>.
</simpara>
<note>
<para>Support for ASP-style tags was added in 3.0.4.</para>
</note>
</listitem>
</varlistentry>
<varlistentry id="ini.auto-append-file">
<term>
<parameter>auto_append_file</parameter>
<type>string</type>
</term>
<listitem>
<para>
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.</para>
<para>
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.</simpara>
</note></para>
</listitem>
</varlistentry>
<varlistentry id="ini.auto-prepend-file">
<term>
<parameter>auto_prepend_file</parameter>
<type>string</type>
</term>
<listitem>
<para>
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.</para>
<para>
The special value <systemitem class="constant">none</systemitem> disables
auto-prepending.</para>
</listitem>
</varlistentry>
<varlistentry id="ini.cgi-ext">
<term>
<parameter>cgi_ext</parameter>
<type>string</type>
</term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.display-errors">
<term>
<parameter>display_errors</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
This determines whether errors should be printed to the screen
as part of the HTML output or not.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.doc-root">
<term>
<parameter>doc_root</parameter>
<type>string</type>
</term>
<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
this directory are served.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.engine">
<term>
<parameter>engine</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
This directive is really only useful in the Apache module
version of PHP. It is used by sites that would like to turn
PHP parsing on and off on a per-directory or per-virtual
server basis. By putting <userinput>engine
off</userinput> in the appropriate places in the
<filename>httpd.conf</filename> file, PHP can be enabled or
disabled.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.error-log">
<term>
<parameter>error_log</parameter>
<type>string</type>
</term>
<listitem>
<para>
Name of file where script errors should be logged. If the
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.</para>
</listitem>
</varlistentry>
<varlistentry id="ini.error-reporting">
<term>
<parameter>error_reporting</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Set the error reporting level. The parameter is an integer
representing a bit field. Add the values of the error
reporting levels you want.
<table>
<title>Error Reporting Levels</title>
<tgroup cols="2">
<thead>
<row>
<entry>bit value</entry>
<entry>enabled reporting</entry>
</row>
</thead>
<tbody>
<row>
<entry>1</entry>
<entry>normal errors</entry>
</row>
<row>
<entry>2</entry>
<entry>normal warnings</entry>
</row>
<row>
<entry>4</entry>
<entry>parser errors</entry>
</row>
<row>
<entry>8</entry>
<entry>non-critical style-related warnings</entry>
</row>
</tbody>
</tgroup>
</table>
The default value for this directive is 7 (normal errors,
normal warnings and parser errors are shown).
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.open-basedir">
<term>
<parameter>open_basedir</parameter>
<type>string</type>
</term>
<listitem>
<para>
Limit the files that can be opened by PHP to the specified
directory-tree.
</para>
<para>
When a script tries to open a file with,
for example, fopen or gzopen, the location of the file is
checked. When the file is outside the specified directory-tree,
PHP will refuse to open it. All symbolic links are resolved,
so it's not possible to avoid this restriction with a symlink.
</para>
<para>
The special value <systemitem class="constant">.</systemitem>
indicates that the directory in which the script is stored will
be used as base-directory.
</para>
<para>
Under Windows, separate the directories with a semicolon. On all
other systems, separate the directories with a colon. As an Apache
module, open_basedir paths from parent directories are now
automatically inherited.
</para>
<note>
<para>Support for multiple directories was added in 3.0.7.</para>
</note>
<para>
The default is to allow all files to be opened.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.gpc-order">
<term>
<parameter>gpc_order</parameter>
<type>string</type>
</term>
<listitem>
<para>
Set the order of GET/POST/COOKIE variable parsing. The
default setting of this directive is "GPC". Setting this to
"GP", for example, will cause PHP to completely ignore cookies
and to overwrite any GET method variables with POST-method
variables of the same name.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.ignore-user-abort">
<term>
<parameter>ignore_user_abort</parameter>
<type>string</type>
</term>
<listitem>
<para>
On by default. If changed to Off scripts will be terminated as
soon as they try to output something after a client has aborted
their connection.
<function>ignore_user_abort</function>.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.include-path">
<term>
<parameter>include_path</parameter>
<type>string</type>
</term>
<listitem>
<para>
Specifies a list of directories where the
<function>require</function>, <function>include</function>
and <function>fopen_with_path</function> functions look for
files. The format is like the system's <envar>PATH</envar>
environment variable: a list of directories separated with a
colon in UNIX or semicolon in Windows.
<example>
<title>UNIX include_path</title>
<programlisting role="php3.ini">
include_path=.:/home/httpd/php-lib
</programlisting>
</example>
<example>
<title>Windows include_path</title>
<programlisting role="php3.ini">
include_path=".;c:\www\phplib"
</programlisting>
</example>
The default value for this directive is <literal>.</literal>
(only the current directory).</para>
</listitem>
</varlistentry>
<varlistentry id="ini.isapi-ext">
<term>
<parameter>isapi_ext</parameter>
<type>string</type>
</term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.log-errors">
<term>
<parameter>log_errors</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Tells whether script error messages should be logged to the
server's error log. This option is thus server-specific.</para>
</listitem>
</varlistentry>
<varlistentry id="ini.magic-quotes-gpc">
<term>
<parameter>magic_quotes_gpc</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Sets the magic_quotes state for GPC (Get/Post/Cookie)
operations. When magic_quotes are on, all ' (single-quote),
" (double quote), \ (backslash) and NUL's are escaped
with a backslash automatically. If magic_quotes_sybase is
also on, a single-quote is escaped with a single-quote
instead of a backslash.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.magic-quotes-runtime">
<term>
<parameter>magic_quotes_runtime</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
If <parameter>magic_quotes_runtime</parameter> is enabled,
most functions that return data from any sort of external
source including databases and text files will have quotes
escaped with a backslash. If
<parameter>magic_quotes_sybase</parameter> is also on, a
single-quote is escaped with a single-quote instead of a
backslash.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.magic-quotes-sybase">
<term>
<parameter>magic_quotes_sybase</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
If <parameter>magic_quotes_sybase</parameter> is also on, a
single-quote is escaped with a single-quote instead of a
backslash if <parameter>magic_quotes_gpc</parameter> or
<parameter>magic_quotes_runtime</parameter> is enabled.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.max-execution-time">
<term>
<parameter>max_execution_time</parameter>
<type>integer</type>
</term>
<listitem>
<para>
This sets the maximum time in seconds a script is allowed to
take before it is terminated by the parser. This helps
prevent poorly written scripts from tying up the server. The
default setting is <literal>30</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.memory-limit">
<term>
<parameter>memory_limit</parameter>
<type>integer</type>
</term>
<listitem>
<para>
This sets the maximum amount of memory in bytes that a script
is allowed to allocate. This helps prevent poorly written
scripts for eating up all available memory on a server.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.nsapi-ext">
<term>
<parameter>nsapi_ext</parameter>
<type>string</type>
</term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.register-globals">
<term>
<parameter>register_globals</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Tells whether or not to register the EGPCS (Environment, GET,
POST, Cookie, Server) variables as global variables. You may
want to turn this off if you don't want to clutter your
scripts' global scope with user data. This makes the most
sense when coupled with <link
linkend="ini.track-vars">track_vars</link> - in which case
you can access all of the EGPCS variables through the
<varname>$HTTP_ENV_VARS</varname>,
<varname>$HTTP_GET_VARS</varname>,
<varname>$HTTP_POST_VARS</varname>,
<varname>$HTTP_COOKIE_VARS</varname>, and
<varname>$HTTP_SERVER_VARS</varname>
arrays in the global scope.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.short-open-tag">
<term>
<parameter>short_open_tag</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Tells whether the short form (<userinput><? ?></userinput>)
of 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><?php ?></userinput>).</para>
</listitem>
</varlistentry>
<varlistentry id="ini.sql.safe-mode">
<term>
<parameter>sql.safe_mode</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.track-errors">
<term>
<parameter>track_errors</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
If enabled, the last error message will always be present in the
global variable <symbol>$php_errormsg</symbol>.</para>
</listitem>
</varlistentry>
<varlistentry id="ini.track-vars">
<term>
<parameter>track_vars</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
If enabled, then Environment, GET, POST, Cookie, and Server
variables can be found in the global associative arrays
<varname>$HTTP_ENV_VARS</varname>,
<varname>$HTTP_GET_VARS</varname>,
<varname>$HTTP_POST_VARS</varname>,
<varname>$HTTP_COOKIE_VARS</varname>, and
<varname>$HTTP_SERVER_VARS</varname>.
</para>
<para>
Note that as of PHP 4.0.3, <systemitem
role="directive">track_vars</systemitem> is always turned on.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.upload-tmp-dir">
<term>
<parameter>upload_tmp_dir</parameter>
<type>string</type>
</term>
<listitem>
<para>
The temporary directory used for storing files when doing
file upload. Must be writable by whatever user PHP is
running as.</para>
</listitem>
</varlistentry>
<varlistentry id="ini.user-dir">
<term>
<parameter>user_dir</parameter>
<type>string</type>
</term>
<listitem>
<para>
The base name of the directory used on a user's home
directory for PHP files, for example
<literal>public_html</literal>.</para>
</listitem>
</varlistentry>
<varlistentry id="ini.warn-plus-overloading">
<term>
<parameter>warn_plus_overloading</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
If enabled, this option makes PHP output a warning when the
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>).</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 id="ini.sect.mail">
<title>Mail Configuration Directives</title>
<variablelist>
<varlistentry id="ini.smtp">
<term>
<parameter>SMTP</parameter>
<type>string</type>
</term>
<listitem>
<para>
DNS name or IP address of the SMTP server PHP under Windows
should use for mail sent with the <function>mail</function>
function.</para>
</listitem>
</varlistentry>
<varlistentry id="ini.sendmail-from">
<term>
<parameter>sendmail_from</parameter>
<type>string</type>
</term>
<listitem>
<para>
Which "From:" mail address should be used in mail sent from
PHP under Windows.</para>
</listitem>
</varlistentry>
<varlistentry id="ini.sendmail-path">
<term>
<parameter>sendmail_path</parameter>
<type>string</type>
</term>
<listitem>
<para>
Where the <command>sendmail</command> program can be found,
usually <filename>/usr/sbin/sendmail</filename> or
<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.</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="&url.qmail;">Qmail</ulink>
users can normally set it to
<filename>/var/qmail/bin/sendmail</filename>.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="ini.sect.safe-mode">
<title>Safe Mode Configuration Directives</title>
<variablelist>
<varlistentry id="ini.safe-mode">
<term>
<parameter>safe_mode</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Whether to enable PHP's safe mode. Read the <link linkend="security">Security
chapter</link> for more
more information.</para>
</listitem>
</varlistentry>
<varlistentry id="ini.safe-mode-exec-dir">
<term>
<parameter>safe_mode_exec_dir</parameter>
<type>string</type>
</term>
<listitem>
<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.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="ini.sect.debugger">
<title>Debugger Configuration Directives</title>
<variablelist>
<varlistentry id="ini.debugger.host">
<term>
<parameter>debugger.host</parameter>
<type>string</type>
</term>
<listitem>
<para>
DNS name or IP address of host used by the debugger.</para>
</listitem>
</varlistentry>
<varlistentry id="ini.debugger.port">
<term>
<parameter>debugger.port</parameter>
<type>string</type>
</term>
<listitem>
<para>
Port number used by the debugger.</para>
</listitem>
</varlistentry>
<varlistentry id="ini.debugger.enabled">
<term>
<parameter>debugger.enabled</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Whether the debugger is enabled.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="ini.sect.extension">
<title>Extension Loading Directives</title>
<variablelist>
<varlistentry id="ini.enable-dl">
<term>
<parameter>enable_dl</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
This directive is really only useful in the Apache module
version of PHP. You can turn dynamic loading of PHP
extensions with <function>dl</function> on and off per
virtual server or per directory.
</para>
<para>
The main reason for turning dynamic loading off is
security. With dynamic loading, it's possible to ignore all
the safe_mode and open_basedir restrictions.
</para>
<para>
The default is to allow dynamic loading, except when using
safe-mode. In safe-mode, it's always imposible to use
<function>dl</function>.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.extension-dir">
<term>
<parameter>extension_dir</parameter>
<type>string</type>
</term>
<listitem>
<para>
In what directory PHP should look for dynamically loadable
extensions.</para>
</listitem>
</varlistentry>
<varlistentry id="ini.extension">
<term>
<parameter>extension</parameter>
<type>string</type>
</term>
<listitem>
<para>
Which dynamically loadable extensions to load when PHP starts
up.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="ini.sect.mysql">
<title>MySQL Configuration Directives</title>
<variablelist>
<varlistentry id="ini.mysql.allow-persistent">
<term>
<parameter>mysql.allow_persistent</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Whether to allow persistent MySQL connections.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.mysql.default-host">
<term>
<parameter>mysql.default_host</parameter>
<type>string</type>
</term>
<listitem>
<para>
The default server host to use when connecting to the database
server if no other host is specified.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.mysql.default-user">
<term>
<parameter>mysql.default_user</parameter>
<type>string</type>
</term>
<listitem>
<para>
The default user name to use when connecting to the database
server if no other name is specified.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.mysql.default-password">
<term>
<parameter>mysql.default_password</parameter>
<type>string</type>
</term>
<listitem>
<para>
The default password to use when connecting to the database
server if no other password is specified.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.mysql.max-persistent">
<term>
<parameter>mysql.max_persistent</parameter>
<type>integer</type>
</term>
<listitem>
<para>
The maximum number of persistent MySQL connections per
process.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.mysql.max-links">
<term>
<parameter>mysql.max_links</parameter>
<type>integer</type>
</term>
<listitem>
<para>
The maximum number of MySQL connections per process, including
persistent connections.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="ini.sect.msql">
<title>mSQL Configuration Directives</title>
<variablelist>
<varlistentry id="ini.msql.allow-persistent">
<term>
<parameter>msql.allow_persistent</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Whether to allow persistent mSQL connections.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.msql.max-persistent">
<term>
<parameter>msql.max_persistent</parameter>
<type>integer</type>
</term>
<listitem>
<para>
The maximum number of persistent mSQL connections per process.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.msql.max-links">
<term>
<parameter>msql.max_links</parameter>
<type>integer</type>
</term>
<listitem>
<para>
The maximum number of mSQL connections per process, including
persistent connections.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="ini.sect.pgsql">
<title>Postgres Configuration Directives</title>
<variablelist>
<varlistentry id="ini.pgsql.allow-persistent">
<term>
<parameter>pgsql.allow_persistent</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Whether to allow persistent Postgres connections.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.pgsql.max-persistent">
<term>
<parameter>pgsql.max_persistent</parameter>
<type>integer</type>
</term>
<listitem>
<para>
The maximum number of persistent Postgres connections per
process.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.pgsql.max-links">
<term>
<parameter>pgsql.max_links</parameter>
<type>integer</type>
</term>
<listitem>
<para>
The maximum number of Postgres connections per process,
including persistent connections.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="ini.sect.sesam">
<title>SESAM Configuration Directives</title>
<variablelist>
<varlistentry id="ini.sesam-oml">
<term>
<parameter>sesam_oml</parameter>
<type>string</type>
</term>
<listitem>
<para>
Name of BS2000 PLAM library containing the loadable SESAM
driver modules. Required for using SESAM functions. The
BS2000 PLAM library must be set ACCESS=READ,SHARE=YES
because it must be readable by the apache server's user id.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.sesam-configfile">
<term>
<parameter>sesam_configfile</parameter>
<type>string</type>
</term>
<listitem>
<para>
Name of SESAM application configuration file. Required for
using SESAM functions. The BS2000 file must be readable by
the apache server's user id.
</para>
<para>
The application configuration file will usually contain a
configuration like (see SESAM
reference manual):
<informalexample>
<programlisting role="bs2000">
CNF=B
NAM=K
NOTYPE</programlisting>
</informalexample>
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.sesam-messagecatalog">
<term>
<parameter>sesam_messagecatalog</parameter>
<type>string</type>
</term>
<listitem>
<para>
Name of SESAM message catalog file. In most cases, this
directive is not neccessary. Only if the SESAM message file
is not installed in the system's BS2000 message file table,
it can be set with this directive.
</para>
<para>
The message catalog must be set ACCESS=READ,SHARE=YES because
it must be readable by the apache server's user id.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="ini.sect.sybase">
<title>Sybase Configuration Directives</title>
<variablelist>
<varlistentry id="ini.sybase.allow-persistent">
<term>
<parameter>sybase.allow_persistent</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Whether to allow persistent Sybase connections.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.sybase.max-persistent">
<term>
<parameter>sybase.max_persistent</parameter>
<type>integer</type>
</term>
<listitem>
<para>
The maximum number of persistent Sybase connections per
process.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.sybase.max-links">
<term>
<parameter>sybase.max_links</parameter>
<type>integer</type>
</term>
<listitem>
<para>
The maximum number of Sybase connections per process,
including persistent connections.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="ini.sect.sybct">
<title>Sybase-CT Configuration Directives</title>
<variablelist>
<varlistentry id="ini.sybct.allow-persistent">
<term>
<parameter>sybct.allow_persistent</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Whether to allow persistent Sybase-CT connections.
The default is on.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.sybct.max-persistent">
<term>
<parameter>sybct.max_persistent</parameter>
<type>integer</type>
</term>
<listitem>
<para>
The maximum number of persistent Sybase-CT connections per
process. The default is -1 meaning unlimited.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.sybct.max-links">
<term>
<parameter>sybct.max_links</parameter>
<type>integer</type>
</term>
<listitem>
<para>
The maximum number of Sybase-CT connections per process,
including persistent connections. The default is -1 meaning
unlimited.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.sybct.min-server-severity">
<term>
<parameter>sybct.min_server_severity</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Server messages with severity greater than or equal to
sybct.min_server_severity will be reported as warnings. This
value can also be set from a script by calling
<function>sybase_min_server_severity</function>. The default
is 10 which reports errors of information severity or greater.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.sybct.min-client-severity">
<term>
<parameter>sybct.min_client_severity</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Client library messages with severity greater than or equal to
sybct.min_client_severity will be reported as warnings. This
value can also be set from a script by calling
<function>sybase_min_client_severity</function>. The default
is 10 which effectively disables reporting.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.sybct.login-timeout">
<term>
<parameter>sybct.login_timeout</parameter>
<type>integer</type>
</term>
<listitem>
<para>
The maximum time in seconds to wait for a connection attempt
to succeed before returning failure. Note that if
max_execution_time has been exceeded when a connection attempt
times out, your script will be terminated before it can take
action on failure. The default is one minute.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.sybct.timeout">
<term>
<parameter>sybct.timeout</parameter>
<type>integer</type>
</term>
<listitem>
<para>
The maximum time in seconds to wait for a select_db or query
operation to succeed before returning failure. Note that if
max_execution_time has been exceeded when am operation times
out, your script will be terminated before it can take action
on failure. The default is no limit.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.sybct.hostname">
<term>
<parameter>sybct.hostname</parameter>
<type>string</type>
</term>
<listitem>
<para>
The name of the host you claim to be connecting from, for
display by sp_who. The default is none.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="ini.sect.informix">
<title>Informix Configuration Directives</title>
<variablelist>
<varlistentry id="ini.ifx.allow-persistent">
<term>
<parameter>ifx.allow_persistent</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Whether to allow persistent Informix connections.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.ifx.max-persistent">
<term>
<parameter>ifx.max_persistent</parameter>
<type>integer</type>
</term>
<listitem>
<para>
The maximum number of persistent Informix connections per
process.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.ifx.max-links">
<term>
<parameter>ifx.max_links</parameter>
<type>integer</type>
</term>
<listitem>
<para>
The maximum number of Informix connections per process, including
persistent connections.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.ifx.default-host">
<term>
<parameter>ifx.default_host</parameter>
<type>string</type>
</term>
<listitem>
<para>
The default host to connect to when no host is specified
in <function>ifx_connect</function> or
<function>ifx_pconnect</function>.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.ifx.default-user">
<term>
<parameter>ifx.default_user</parameter>
<type>string</type>
</term>
<listitem>
<para>
The default user id to use when none is specified
in <function>ifx_connect</function> or
<function>ifx_pconnect</function>.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.ifx.default-password">
<term>
<parameter>ifx.default_password</parameter>
<type>string</type>
</term>
<listitem>
<para>
The default password to use when none is specified
in <function>ifx_connect</function> or
<function>ifx_pconnect</function>.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.ifx.blobinfile">
<term>
<parameter>ifx.blobinfile</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Set to true if you want to return blob columns
in a file, false if you want them in memory. You can
override the setting at runtime
with <function>ifx_blobinfile_mode</function>.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.ifx.textasvarchar">
<term>
<parameter>ifx.textasvarchar</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Set to true if you want to return TEXT columns
as normal strings in select statements,
false if you want to use blob id parameters. You can
override the setting at runtime with
<function>ifx_textasvarchar</function>.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.ifx.byteasvarchar">
<term>
<parameter>ifx.byteasvarchar</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Set to true if you want to return BYTE columns
as normal strings in select queries,
false if you want to use blob id parameters. You can
override the setting at runtime with
<function>ifx_textasvarchar</function>.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.ifx.charasvarchar">
<term>
<parameter>ifx.charasvarchar</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Set to true if you want to trim trailing spaces
from CHAR columns when fetching them.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.ifx.nullformat">
<term>
<parameter>ifx.nullformat</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Set to true if you want to return NULL columns
as the literal string "NULL", false if you want
them returned as the empty string "". You can
override this setting at runtime with
<function>ifx_nullformat</function>.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="ini.sect.bcmath">
<title>BC Math Configuration Directives</title>
<variablelist>
<varlistentry id="ini.bcmath.scale">
<term>
<parameter>bcmath.scale</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Number of decimal digits for all bcmath functions.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="ini.sect.browscap">
<title>Browser Capability Configuration Directives</title>
<variablelist>
<varlistentry id="ini.browscap">
<term>
<parameter>browscap</parameter>
<type>string</type>
</term>
<listitem>
<para>
Name of browser capabilities file. See also
<function>get_browser</function>.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="ini.sect.uodbc">
<title>Unified ODBC Configuration Directives</title>
<variablelist>
<varlistentry id="ini.uodbc.default-db">
<term>
<parameter>uodbc.default_db</parameter>
<type>string</type>
</term>
<listitem>
<para>
ODBC data source to use if none is specified in
<function>odbc_connect</function> or
<function>odbc_pconnect</function>.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.uodbc.default-user">
<term>
<parameter>uodbc.default_user</parameter>
<type>string</type>
</term>
<listitem>
<para>
User name to use if none is specified in
<function>odbc_connect</function> or
<function>odbc_pconnect</function>.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.uodbc.default-pw">
<term>
<parameter>uodbc.default_pw</parameter>
<type>string</type>
</term>
<listitem>
<para>
Password to use if none is specified in
<function>odbc_connect</function> or
<function>odbc_pconnect</function>.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.uodbc.allow-persistent">
<term>
<parameter>uodbc.allow_persistent</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Whether to allow persistent ODBC connections.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.uodbc.max-persistent">
<term>
<parameter>uodbc.max_persistent</parameter>
<type>integer</type>
</term>
<listitem>
<para>
The maximum number of persistent ODBC connections per process.
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.uodbc.max-links">
<term>
<parameter>uodbc.max_links</parameter>
<type>integer</type>
</term>
<listitem>
<para>
The maximum number of ODBC connections per process, including
persistent connections.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
Index: phpdoc/hk/chapters/install.xml
+++ phpdoc/hk/chapters/install.xml
<chapter id="installation">
<title>Installation</title>
<sect1 id="install.downloading">
<title>Downloading the latest version</title>
<simpara>
The source code, and binary distributions for some platforms
(including Windows), can be found at <literal><ulink
url="&url.php;">&url.php;</ulink></literal>. We recommend
you to choose <ulink url="&url.mirrors;">mirror</ulink> nearest
to you for downloading the distributions.
</simpara>
</sect1>
<sect1 id="install.unix">
<title>Installation on UNIX systems</title>
<para>
This section will guide you through the general configuration and
installation of PHP on unix systems. Be sure to investigate any
sections specific to your platform or web server before you begin
the process.
</para>
<para>
Prerequisite knowledge and software:
<itemizedlist>
<listitem>
<simpara>
Basic UNIX skills (being able to operate "make" and a C
compiler, if compiling)
</simpara>
</listitem>
<listitem>
<simpara>
An ANSI C compiler (if compiling)
</simpara>
</listitem>
<listitem>
<simpara>
flex (for compiling)
</simpara>
</listitem>
<listitem>
<simpara>
bison (for compiling)
</simpara>
</listitem>
<listitem>
<simpara>
A web server
</simpara>
</listitem>
<listitem>
<simpara>
Any module specific components (such as gd, pdf libs, etc.)
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
There are several ways to install PHP for the Unix platform, either
with a compile and configure process, or through various
pre-packaged methods. This documentation is mainly focused around
the process of compiling and configuring PHP.
</para>
<para>
The initial PHP setup and configuration process is controlled by the
use of the commandline options of the <filename>configure</filename>
script. This page outlines the usage of the most common options,
but there are many others to play with. Check out the <link
linkend="install.configure">Complete list of configure
options</link> for an exhaustive rundown. There are several ways
to install PHP:
<itemizedlist>
<listitem>
<simpara>
As an <link linkend="install.apache">Apache module</link>
</simpara>
</listitem>
<listitem>
<simpara>
As an <link linkend="install.fhttpd">fhttpd module</link>
</simpara>
</listitem>
<listitem>
<simpara>
For use with <link
linkend="install.otherhttpd">AOLServer, NSAPI,
phttpd, Pi3Web, Roxen, thttpd, or Zeus.</link>
</simpara>
</listitem>
<listitem>
<simpara>
As a <link linkend="install.commandline">CGI executable</link>
</simpara>
</listitem>
</itemizedlist>
</para>
<sect2 id="install.unix.apache-module">
<title>Apache Module Quick Reference</title>
<para>
PHP can be compiled in a number of different ways, but one of
the most popular is as an Apache module. The following is a quick
installation overview.
</para>
<example id="install.unix.apache-module.quick">
<title>
Quick Installation Instructions for PHP 4 (Apache Module Version)
</title>
<programlisting>
1. gunzip apache_1.3.x.tar.gz
2. tar xvf apache_1.3.x.tar
3. gunzip php-x.x.x.tar.gz
4. tar xvf php-x.x.x.tar
5. cd apache_1.3.x
6. ./configure --prefix=/www
7. cd ../php-x.x.x
8. ./configure --with-mysql --with-apache=../apache_1.3.x --enable-track-vars
9. make
10. make install
11. cd ../apache_1.3.x
12. ./configure --activate-module=src/modules/php4/libphp4.a
13. make
14. make install
15. cd ../php-x.x.x
16. cp php.ini-dist /usr/local/lib/php.ini
17. Edit your httpd.conf or srm.conf file and add:
AddType application/x-httpd-php .php
18. Use your normal procedure for restarting the Apache server. (You must
stop and restart the server, not just cause the server to reload by
use a HUP or USR1 signal.)
</programlisting>
</example>
</sect2>
<sect2 id="install.building">
<title>Building</title>
<simpara>
When PHP is configured, you are ready to build the CGI executable.
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>.
</simpara>
</sect2>
</sect1>
<sect1 id="install.linux">
<title>Unix/Linux installs</title>
<para>
This section contains notes and hints specific to installing
PHP on Linux distributions.
</para>
<sect2 id="install.linux.packages">
<title>Using Packages</title>
<simpara>
Many Linux distributions have some sort of package installation,
such as RPM. This can assist in setting up a standard
configuration, but if you need to have a different set of features
(such as a secure server, or a different database driver), you may
need to build php and/or your webserver. If you are unfamiliar
with building and compiling your own software, it is worth
checking to see whether somebody has already built a packaged
version of PHP with the features you need.
</simpara>
</sect2>
</sect1>
<sect1 id="install.hpux">
<title>Unix/HP-UX installs</title>
<para>
This section contains notes and hints specific to installing PHP
on HP-UX systems.
</para>
<example id="install.hpux.example">
<title>
Installation Instructions for HP-UX 10
</title>
<programlisting>
From: [EMAIL PROTECTED]
04-Jan-2001 09:49
(These tips are for PHP 4.0.4 and Apache v1.3.9)
So you want to install PHP and Apache on a HP-UX 10.20 box?
1. You need gzip, download a binary distribution from
http://hpux.connect.org.uk/ftp/hpux/Gnu/gzip-1.2.4a/gzip-1.2.4a-sd-10.20.depot.Z
uncompress the file and install using swinstall
2. You need gcc, download a binary distribution from
http://gatekeep.cs.utah.edu/ftp/hpux/Gnu/gcc-2.95.2/gcc-2.95.2-sd-10.20.depot.gz
gunzip this file and install gcc using swinstall.
3. You need the GNU binutils, you can download a binary distribution from
http://hpux.connect.org.uk/ftp/hpux/Gnu/binutils-2.9.1/binutils-2.9.1-sd-10.20.depot.gz
gunzip and install using swinstall.
4. You now need bison, you can download a binary distribution from
http://hpux.connect.org.uk/ftp/hpux/Gnu/bison-1.28/bison-1.28-sd-10.20.depot.gz
install as above.
5. You now need flex, you need to download the source from one of the
http://www.gnu.org mirrors. It is in the <filename>non-gnu</filename> directory of the
ftp site.
Download the file, gunzip, then tar -xvf it. Go into the newly created flex
directory and do a ./configure, then a make, and then a make install
If you have errors here, it's probably because gcc etc. are not in your
PATH so add them to your PATH.
Right, now into the hard stuff.
6. Download the PHP and apache sources.
7. gunzip and tar -xvf them.
We need to hack a couple of files so that they can compile ok.
8. Firstly the configure file needs to be hacked because it seems to lose
track of the fact that you are a hpux machine, there will be a
better way of doing this but a cheap and cheerful hack is to put
lt_target=hpux10.20
on line 47286 of the configure script.
9. Next, the Apache GuessOS file needs to be hacked. Under
apache_1.3.9/src/helpers change line 89 from
"echo "hp${HPUXMACH}-hpux${HPUXVER}"; exit 0"
to:
"echo "hp${HPUXMACH}-hp-hpux${HPUXVER}"; exit 0"
10. You cannot install PHP as a shared object under HP-UX so you must compile
it as a static, just follow the instructions at the Apache page.
11. PHP and apache should have compiled OK, but Apache won't start. you need
to create a new user for Apache, eg www, or apache. You then change lines 252
and 253 of the conf/httpd.conf in Apache so that instead of
User nobody
Group nogroup
you have something like
User www
Group sys
This is because you can't run Apache as nobody under hp-ux.
Apache and PHP should then work.
Hope this helps somebody,
Paul Mckay.
</programlisting>
</example>
</sect1>
<sect1 id="install.solaris">
<title>Unix/Solaris installs</title>
<para>
This section contains notes and hints specific to installing
PHP on Solaris systems.
</para>
<sect2 id="install.solaris.required">
<title>Required software</title>
<para>
Solaris installs often lack C compilers and their related tools.
The required software is as follows:
<itemizedlist>
<listitem>
<simpara>
gcc (recommended, other C compilers may work)
</simpara>
</listitem>
<listitem>
<simpara>
make
</simpara>
</listitem>
<listitem>
<simpara>
flex
</simpara>
</listitem>
<listitem>
<simpara>
bison
</simpara>
</listitem>
<listitem>
<simpara>
m4
</simpara>
</listitem>
<listitem>
<simpara>
autoconf
</simpara>
</listitem>
<listitem>
<simpara>
automake
</simpara>
</listitem>
<listitem>
<simpara>
perl
</simpara>
</listitem>
<listitem>
<simpara>
gzip
</simpara>
</listitem>
<listitem>
<simpara>
tar
</simpara>
</listitem>
</itemizedlist>
In addition, you will need to install (and possibly compile) any
additional software specific to your configuration (such as Oracle
or MySQL.
</para>
</sect2>
<sect2 id="install.solaris.packages">
<title>Using Packages</title>
<simpara>
You can simplify the Solaris install process by using pkgadd to
install most of your needed components.
</simpara>
</sect2>
</sect1>
<sect1 id="install.openbsd">
<title>Unix/OpenBSD installs</title>
<para>
This section contains notes and hints specific to installing
PHP on <ulink url="&url.openbsd;">OpenBSD</ulink>.
</para>
<sect2 id="install.openbsd.ports">
<title>Using Ports</title>
<simpara>
This is the recommended method of installing PHP on OpenBSD, as it will have
the latest patches and security fixes applied to it by the maintainers. To
use this method, ensure that you have a <ulink url="&url.openbsd.ports;">
recent ports tree</ulink>. Then simply find out which flavors you wish
to install, and issue the <command>make install</command> command. Below
is an example of how to do this.
</simpara>
<example id="install.openbsd.ports.example">
<title>OpenBSD Ports Install Example</title>
<programlisting>
$ cd /usr/ports/www/php4
$ make show VARNAME=FLAVORS
(choose which flavors you want from the list)
$ FLAVOR="imap gettext ldap mysql gd pdflib" make install
$ php4-enable
</programlisting>
</example>
</sect2>
<sect2 id="install.openbsd.packages">
<title>Using Packages</title>
<simpara>
There are pre-compiled packages available for your release
of <ulink url="&url.openbsd;">OpenBSD</ulink>. These integrate
automatically with the version of Apache installed with the OS.
However, since there are a large number of options (called
<emphasis>flavors</emphasis>) available for this port,
you may find it easier to compile it from source using the ports tree.
Read the <ulink url="&url.openbsd.packages;">packages(7)</ulink>
manual page for more information in what packages are available.
</simpara>
</sect2>
</sect1>
<sect1 id="install.macosx">
<title>Unix/Mac OS X installs</title>
<para>
This section contains notes and hints specific to installing
PHP on Mac OS X.
</para>
<sect2 id="install.macosx.packages">
<title>Using Packages</title>
<simpara>
There are a few pre-packaged and pre-compiled versions of PHP for
Mac OS X. This can help in setting up a standard
configuration, but if you need to have a different set of features
(such as a secure server, or a different database driver), you may
need to build PHP and/or your web server yourself. If you are unfamiliar
with building and compiling your own software, it's worth
checking whether somebody has already built a packaged
version of PHP with the features you need.
<ulink url="&url.lightyear;">Lightyear Design</ulink> offers a
pre-built version of PHP for OS X, as does
<ulink url="&url.tenon;">Tenon Intersystems</ulink>.
</simpara>
</sect2>
<sect2 id="install.macosx.compile">
<title>Compiling for OS X server</title>
<simpara>
There are two slightly different versions of Mac OS X, client and
server. The following is for OS X Server.
</simpara>
<example id="install.macosx.compile.example">
<title>Mac OS X server install</title>
<programlisting>
1. Get the latest distributions of Apache and PHP
2. Untar them, and run the configure program on Apache like so.
./configure --exec-prefix=/usr \
--localstatedir=/var \
--mandir=/usr/share/man \
--libexecdir=/System/Library/Apache/Modules \
--iconsdir=/System/Library/Apache/Icons \
--includedir=/System/Library/Frameworks/Apache.framework/Versions/1.3/Headers \
--enable-shared=max \
--enable-module=most \
--target=apache
4. You may also want to add this line:
setenv OPTIM=-O2
If you want the compiler to do some optimization.
5. Next, go to the PHP 4 source directory and configure it.
./configure --prefix=/usr \
--sysconfdir=/etc \
--localstatedir=/var \
--mandir=/usr/share/man \
--with-xml \
--with-apache=/src/apache_1.3.12
If you have any other addiitons (MySQL, GD, etc.), be sure to add
them here. For the --with-apache string, put in the path to your
apache source directory, for example "/src/apache_1.3.12".
6. make
7. make install
This will add a directory to your Apache source directory under
src/modules/php4.
8. Now, reconfigure Apache to build in PHP 4.
./configure --exec-prefix=/usr \
--localstatedir=/var \
--mandir=/usr/share/man \
--libexecdir=/System/Library/Apache/Modules \
--iconsdir=/System/Library/Apache/Icons \
--includedir=/System/Library/Frameworks/Apache.framework/Versions/1.3/Headers \
--enable-shared=max \
--enable-module=most \
--target=apache \
--activate-module=src/modules/php4/libphp4.a
You may get a message telling you that libmodphp4.a is out of date.
If so, go to the src/modules/php4 directory inside your apache
source directory and run this command:
ranlib libmodphp4.a
Then go back to the root of the apache source directory and run the
above configure command again. That'll bring the link table up to
date.
9. make
10. make install
11. copy and rename the php.ini-dist file to your "bin" directory from your
PHP 4 source directory:
cp php.ini-dist /usr/local/bin/php.ini
or (if your don't have a local directory)
cp php.ini-dist /usr/bin/php.ini
</programlisting>
</example>
<simpara>
Other examples for
<ulink url="&url.stepwise.macosx-client;">Mac OS X client</ulink>
and
<ulink url="&url.stepwise.macosx-client;">Mac OS X server</ulink>
are available at <ulink url="&url.stepwise;">Stepwise</ulink>.
</simpara>
</sect2>
</sect1>
<sect1 id="install.configure">
<title>Complete list of configure options</title>
<note>
<para>
These are only used at compile time. If you want to alter PHP's
runtime configuration, please see the chapter on <link
linkend="configuration">Configuration</link>.
</para>
</note>
<para>
The following is a complete list of options supported by the PHP 3
and PHP 4 <filename>configure</filename> scripts, used when
compiling in Unix-like environments. Some are available in PHP 3,
some in PHP 4, and some in both, as noted. There are many options
the names of which have changed between PHP 3 and PHP 4, but which
accomplish the same things. These entries are cross-referenced to
each other, so if you have a problem getting your PHP 3-era
configuration options to work, check here to see whether the names
have changed.
</para>
<itemizedlist>
<listitem>
<para>
<link linkend="install.configure.databases">Database</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="install.configure.ecommerce">Ecommerce</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="install.configure.graphics">Graphics</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="install.configure.misc">Miscellaneous</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="install.configure.networking">Networking</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="install.configure.php">PHP Behaviour</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="install.configure.servers">Server</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="install.configure.text">Text and language</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="install.configure.xml">XML</link>
</para>
</listitem>
</itemizedlist>
<sect2 id="install.configure.databases">
<title>Database</title>
<variablelist>
<varlistentry id="install.configure.with-adabas">
<term>
<parameter>--with-adabas[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include Adabas D support. DIR is the Adabas base
install directory, defaults to /usr/local.
</para>
<para>
<ulink url="&url.adabas;">Adabas home page</ulink>
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-dba">
<term>
<parameter>--enable-dba=shared</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Build DBA as a shared module
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-dbase">
<term>
<parameter>--enable-dbase</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available; use <link
linkend="install.configure.with-dbase">--with-dbase</link>
instead.
</para>
<para>
PHP 4: Enable the bundled dbase library. No external libraries
are required.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-dbase">
<term>
<parameter>--with-dbase</parameter>
</term>
<listitem>
<para>
PHP 3: Include the bundled dbase library. No external
libraries are required.
</para>
<para>
PHP 4: Option not available; use <link
linkend="install.configure.enable-dbase">--enable-dbase</link>
instead.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-db2">
<term>
<parameter>--with-db2[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include Berkeley DB2 support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-db3">
<term>
<parameter>--with-db3[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include Berkeley DB3 support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-dbm">
<term>
<parameter>--with-dbm[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include DBM support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-dbmaker">
<term>
<parameter>--with-dbmaker[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include DBMaker support. DIR is the DBMaker base install
directory, defaults to where the latest version of DBMaker is installed
(such as /home/dbmaker/3.6).
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-empress">
<term>
<parameter>--with-empress[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include Empress support. DIR is the Empress base install
directory, defaults to $EMPRESSPATH
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-filepro">
<term>
<parameter>--enable-filepro</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available; use <link
linkend="install.configure.with-filepro">--with-filepro</link>
instead.
</para>
<para>
PHP 4: Enable the bundled read-only filePro support. No
external libraries are required.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-filepro">
<term>
<parameter>--with-filepro</parameter>
</term>
<listitem>
<para>
PHP 3: Include the bundled read-only filePro support. No
external libraries are required.
</para>
<para>
PHP 4: Option not available; use <link
linkend="install.configure.enable-filepro">--enable-filepro</link>
instead.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-gdbm">
<term>
<parameter>--with-gdbm[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include GDBM support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-hyperwave">
<term>
<parameter>--with-hyperwave</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include Hyperwave support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-ibm-db2">
<term>
<parameter>--with-ibm-db2[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include IBM DB2 support. DIR is the DB2 base
install directory, defaults to
<filename>/home/db2inst1/sqllib</filename>.
</para>
<para>
<ulink url="&url.ibmdb2;">IBM DB2 home page</ulink>
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-informix">
<term>
<parameter>--with-informix[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include Informix support. DIR is the Informix base install
directory, defaults to nothing.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-ingres">
<term>
<parameter>--with-ingres[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include Ingres II support. DIR is the Ingres base directory
(default /II/ingres)
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-interbase">
<term>
<parameter>--with-interbase[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include InterBase support. DIR is the InterBase base
install directory, which defaults to <filename>/usr/interbase</filename>.
</para>
<simpara>
<link linkend="ref.ibase">Interbase functions</link>
</simpara>
<simpara>
<ulink url="&url.ibase;">Interbase home page</ulink>
</simpara>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-ldap">
<term>
<parameter>--with-ldap[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Include LDAP support. DIR is the LDAP base install
directory. Defaults to <filename>/usr</filename> and
<filename>/usr/local</filename>
</para>
<para>
PHP 4: Include LDAP support. DIR is the LDAP base install directory.
</para>
<simpara>
This provides <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>.
</simpara>
<simpara>
More information about LDAP can be found in <ulink
url="&url.rfc;rfc1777.html">RFC1777</ulink> and
<ulink
url="&url.rfc;rfc1778.html">RFC1778</ulink>.
</simpara>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-msql">
<term>
<parameter>--with-msql[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: 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
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.
</para>
<simpara>
See also <link linkend="ini.sect.msql">mSQL
Configuration</link> Directives in the <link
linkend="configuration.file">configuration file</link>.
</simpara>
<simpara>
<ulink url="&url.msql;">mSQL home page</ulink>
</simpara>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-mysql">
<term>
<parameter>--with-mysql[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Include MySQL support. DIR is the MySQL base install directory,
defaults to searching through a number of common places for the MySQL
files.
</para>
<para>
PHP 4: Include MySQL support. DIR is the MySQL base directory. If
unspecified, the bundled MySQL library will be used. This
option is turned on by default.
</para>
<para>
See also <link linkend="ini.sect.mysql">MySQL
Configuration</link> Directives in the <link
linkend="configuration.file">configuration file</link>.
</para>
<para>
<ulink url="&url.mysql;">MySQL home page</ulink>
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-ndbm">
<term>
<parameter>--with-ndbm[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include NDBM support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-ovrimos">
<term>
<parameter>--with-ovrimos</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include Ovrimos support.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-oci8">
<term>
<parameter>--with-oci8[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include Oracle-oci8 support. Default DIR is ORACLE_HOME.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-oracle">
<term>
<parameter>--with-oracle[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Include Oracle database support. DIR is Oracle's home directory,
defaults to $ORACLE_HOME.
</para>
<para>
PHP 4: Include Oracle-oci7 support. Default DIR is ORACLE_HOME.
</para>
<simpara>
Includes Oracle support. Has been tested and should be
working 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.
</simpara>
<simpara>
<ulink url="&url.oracle;">Oracle home page</ulink>
</simpara>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-pgsql">
<term>
<parameter>--with-pgsql[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Include PostgresSQL support. DIR is the PostgresSQL base
install directory, which defaults to
<filename>/usr/local/pgsql</filename>.
</para>
<para>
PHP 4: Include PostgreSQL support. DIR is the PostgreSQL base
install directory, which defaults to
<filename>/usr/local/pgsql</filename>. Set DIR to shared to
build as a dl, or shared,DIR to build as a dl and still specify
DIR.
</para>
<simpara>
See also <link linkend="ini.sect.pgsql">Postgres
Configuration</link> Directives in the <link
linkend="configuration.file">configuration file</link>.
</simpara>
<simpara>
<ulink url="&url.pgsql;">PostgreSQL home page</ulink>
</simpara>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-solid">
<term>
<parameter>--with-solid[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include Solid support. DIR is the Solid base install
directory, defaults to /usr/local/solid
</para>
<simpara>
<ulink url="&url.solid;">Solid home page</ulink>
</simpara>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-sybase-ct">
<term>
<parameter>--with-sybase-ct[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include Sybase-CT support. DIR is the Sybase home
directory, defaults to /home/sybase.
</para>
<simpara>
See also <link linkend="ini.sect.sybct">Sybase-CT
Configuration</link> Directives in the <link
linkend="configuration.file">configuration
file</link>.
</simpara>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-sybase">
<term>
<parameter>--with-sybase[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include Sybase-DB support. DIR is the Sybase home
directory, which defaults to <filename>/home/sybase</filename>.
</para>
<simpara>
See also <link linkend="ini.sect.sybase">Sybase
Configuration</link> Directives in the <link
linkend="configuration.file">configuration file</link>.
</simpara>
<simpara>
<ulink url="&url.sybase;">Sybase home page</ulink>
</simpara>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-openlink">
<term>
<parameter>--with-openlink[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include OpenLink ODBC support. DIR is the OpenLink base
install directory, defaults to /usr/local/openlink.
</para>
<simpara>
<ulink url="&url.openlink;">OpenLink Software's home page</ulink>
</simpara>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-iodbc">
<term>
<parameter>--with-iodbc[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include iODBC support. DIR is the iODBC base install
directory, defaults to <filename>/usr/local</filename>.
</para>
<para>
This feature was first developed for iODBC Driver Manager, a
freely redistributable ODBC driver manager which runs under
many flavors of UNIX.
</para>
<simpara>
<ulink url="&url.freeodbc;">FreeODBC home page</ulink>
or <ulink url="&url.iodbc;">iODBC home page</ulink>
</simpara>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-custom-odbc">
<term>
<parameter>--with-custom-odbc[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Includes support for an arbitrary custom ODBC
library. The parameter is the base directory and defaults to
<filename class="directory">/usr/local</filename>.
</para>
<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.
</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>
</simpara>
</listitem>
</varlistentry>
<varlistentry id="install.configure.disable-unified-odbc">
<term>
<parameter>--disable-unified-odbc</parameter>
</term>
<listitem>
<para>
PHP 3: Disable unified ODBC support. Only applicable if iODBC, Adabas,
Solid, Velocis or a custom ODBC interface is enabled.
</para>
<para>
PHP 4: Option not available in PHP 4
</para>
<simpara>
The Unified ODBC module, which is a common interface to all
the databases with ODBC-based interfaces, such as Solid, IBM
DB2 and Adabas D. It also works for normal ODBC libraries.
Has been tested with iODBC, Solid, Adabas D, IBM DB2 and
Sybase SQL Anywhere. Requires that one (and only one) of these
extensions or the Velocis extension is enabled, or a custom ODBC
library specified. This option is only applicable if one of
the following options is used: <link
linkend="install.configure.with-iodbc">--with-iodbc</link>,
<link
linkend="install.configure.with-solid">--with-solid</link>,
<link
linkend="install.configure.with-ibm-db2">--with-ibm-db2</link>,
<link
linkend="install.configure.with-adabas">--with-adabas</link>,
<link
linkend="install.configure.with-velocis">--with-velocis</link>,
or <link
linkend="install.configure.with-custom-odbc">--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>.
</simpara>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-unixODBC">
<term>
<parameter>--with-unixODBC[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include unixODBC support. DIR is the unixODBC base install
directory, defaults to /usr/local.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-velocis">
<term>
<parameter>--with-velocis[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include Velocis support. DIR is the Velocis base install
directory, defaults to /usr/local/velocis.
</para>
<simpara>
<ulink url="&url.velocis;">Velocis home page</ulink>
</simpara>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="install.configure.ecommerce">
<title>Ecommerce</title>
<variablelist>
<varlistentry id="install.configure.with-ccvs">
<term>
<parameter>--with-ccvs[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Compile CCVS support into PHP 4. Please specify your CCVS base
install directory as DIR.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-mck">
<term>
<parameter>--with-mck[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Include Cybercash MCK support. DIR is the cybercash mck
build directory, which defaults to
<filename>/usr/src/mck-3.2.0.3-linux</filename>. For help, look
in <filename>extra/cyberlib</filename>.
</para>
<para>
PHP 4: Option not available; use <link
linkend="install.configure.with-cybercash">--with-cybercash</link>
instead.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-cybercash">
<term>
<parameter>--with-cybercash[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available; use <link
linkend="install.configure.with-mck">--with-mck</link>
instead.
</para>
<para>
PHP 4: Include CyberCash support. DIR is the CyberCash MCK install
directory.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-pfpro">
<term>
<parameter>--with-pfpro[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include Verisign Payflow Pro support
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="install.configure.graphics">
<title>Graphics</title>
<variablelist>
<varlistentry id="install.configure.enable-freetype-4bit-antialias-hack">
<term>
<parameter>--enable-freetype-4bit-antialias-hack</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include support for FreeType2 (experimental).
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-gd">
<term>
<parameter>--with-gd[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Include GD support (DIR is GD's install dir).
</para>
<para>
PHP 4: Include GD support (DIR is GD's install dir). Set DIR to shared
to build as a dl, or shared,DIR to build as a dl and still specify DIR.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.without-gd">
<term>
<parameter>--without-gd</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Disable GD support.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-imagick">
<term>
<parameter>--with-imagick[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Include ImageMagick support. DIR is the install
directory, and if left out, PHP will try to find it on its
own. [experimental]
</para>
<para>
PHP 4: Option not available in PHP 4
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-jpeg-dir">
<term>
<parameter>--with-jpeg-dir[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: jpeg dir for pdflib 2.0
</para>
<para>
PHP 4: jpeg dir for pdflib 3.x
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-png-dir">
<term>
<parameter>--with-png-dir[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: png dir for pdflib 3.x
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-t1lib">
<term>
<parameter>--enable-t1lib</parameter>
</term>
<listitem>
<para>
PHP 3: Enable t1lib support.
</para>
<para>
PHP 4: Option not available; use <link
linkend="install.configure.with-t1lib">--with-t1lib</link>
instead.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-t1lib">
<term>
<parameter>--with-t1lib[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available; use <link
linkend="install.configure.enable-t1lib">--enable-t1lib</link>
instead.
</para>
<para>
PHP 4: Include T1lib support.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-tiff-dir">
<term>
<parameter>--with-tiff-dir[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: tiff dir for pdflib 2.0
</para>
<para>
PHP 4: tiff dir for pdflib 3.x
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-ttf">
<term>
<parameter>--with-ttf[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include FreeType support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-xpm-dir">
<term>
<parameter>--with-xpm-dir[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: xpm dir for gd-1.8+
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="install.configure.misc">
<title>Miscellaneous</title>
<para>
These are being classified over time, where appropriate.
</para>
<variablelist>
<varlistentry id="install.configure.gmp">
<term>
<parameter>--with-gmp</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4 : Include GMP support.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.disable-bcmath">
<term>
<parameter>--disable-bcmath</parameter>
</term>
<listitem>
<para>
PHP 3: Compile without BC arbitrary precision math
functions. These functions allow you to operate with numbers
outside of the ranges allowed by regular integers and floats;
see <link linkend="ref.bc">BCMath Arbitrary Precision
Mathematics Functions</link> for more information.
</para>
<para>
PHP 4: Option not available; bcmath is not compiled in by
default. Use <link
linkend="install.configure.enable-bcmath">--enable-bcmath</link>
to compile it in.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.disable-display-source">
<term>
<parameter>--disable-display-source</parameter>
</term>
<listitem>
<para>
PHP 3: Compile without displaying source support
</para>
<para>
PHP 4: Option not available in PHP 4
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.disable-libtool-lock">
<term>
<parameter>--disable-libtool-lock</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: avoid locking (might break parallel builds)
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.disable-pear">
<term>
<parameter>--disable-pear</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Do not install PEAR
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.disable-pic">
<term>
<parameter>--disable-pic</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Disable PIC for shared objects
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.disable-posix">
<term>
<parameter>--disable-posix</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3; use <link
linkend="install.configure.without-posix">--without-posix</link>
instead.
</para>
<para>
PHP 4: Disable POSIX-like functions
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.disable-rpath">
<term>
<parameter>--disable-rpath</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Disable passing additional runtime library search paths
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.disable-session">
<term>
<parameter>--disable-session</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Disable session support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-bcmath">
<term>
<parameter>--enable-bcmath</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3; bcmath is compiled in
by default. Use <link
linkend="install.configure.disable-bcmath">--disable-bcmath</link>
to disable it.
</para>
<para>
PHP 4: Compile with bc style precision math functions. Read
README-BCMATH for instructions on how to get this module
installed. These functions allow you to operate with numbers
outside of the ranges allowed by regular integers and floats;
see <link linkend="ref.bc">BCMath Arbitrary Precision
Mathematics Functions</link> for more information.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-c9x-inline">
<term>
<parameter>--enable-c9x-inline</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Enable C9x-inline semantics
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-calendar">
<term>
<parameter>--enable-calendar</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Enable support for calendar conversion
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-debug">
<term>
<parameter>--enable-debug</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Compile with debugging symbols.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-debugger">
<term>
<parameter>--enable-debugger</parameter>
</term>
<listitem>
<para>
PHP 3: Compile with remote debugging functions
</para>
<para>
PHP 4: Option not available in PHP 4
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-discard-path">
<term>
<parameter>--enable-discard-path</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: 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.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-dmalloc">
<term>
<parameter>--enable-dmalloc</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Enable dmalloc
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-exif">
<term>
<parameter>--enable-exif</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Enable exif support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-experimental-zts">
<term>
<parameter>--enable-experimental-zts</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: This will most likely break your build
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-fast-install">
<term>
<parameter>--enable-fast-install[=PKGS]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: optimize for fast installation [default=yes]
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-force-cgi-redirect">
<term>
<parameter>--enable-force-cgi-redirect</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Enable the security check for internal server redirects.
You should use this if you are running the CGI version with Apache.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-inline-optimization">
<term>
<parameter>--enable-inline-optimization</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: If you have much memory and are using gcc, you might try this.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-libgcc">
<term>
<parameter>--enable-libgcc</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Enable explicitly linking against libgcc
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-maintainer-mode">
<term>
<parameter>--enable-maintainer-mode</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: enable make rules and dependencies not useful (and
sometimes confusing) to the casual installer
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-memory-limit">
<term>
<parameter>--enable-memory-limit</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Compile with memory limit support. [default=no]
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-safe-mode">
<term>
<parameter>--enable-safe-mode</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Enable safe mode by default.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-satellite">
<term>
<parameter>--enable-satellite</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Enable CORBA support via Satellite (Requires ORBit)
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-shared">
<term>
<parameter>--enable-shared[=PKGS]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: build shared libraries [default=yes]
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-sigchild">
<term>
<parameter>--enable-sigchild</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Enable PHP's own SIGCHLD handler.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-static">
<term>
<parameter>--enable-static[=PKGS]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: build static libraries [default=yes]
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-sysvsem">
<term>
<parameter>--enable-sysvsem</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Enable System V semaphore support.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-sysvshm">
<term>
<parameter>--enable-sysvshm</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Enable the System V shared memory support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-trans-sid">
<term>
<parameter>--enable-trans-sid</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Enable transparent session id propagation
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-cdb">
<term>
<parameter>--with-cdb[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include CDB support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-config-file-path">
<term>
<parameter>--with-config-file-path=PATH</parameter>
</term>
<listitem>
<para>
PHP 3: Sets the path in which to look for php3.ini. Defaults to
<filename>/usr/local/lib</filename>
</para>
<para>
PHP 4: Sets the path in which to look for <filename>php.ini</filename>.
Defaults to <filename>/usr/local/lib</filename>
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-cpdflib">
<term>
<parameter>--with-cpdflib[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Include ClibPDF support. DIR is the ClibPDF install directory,
defaults to /usr/local.
</para>
<para>
PHP 4: Include cpdflib support (requires cpdflib >= 2). DIR is the
cpdfllib install directory, defaults to /usr.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-esoob">
<term>
<parameter>--with-esoob[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include Easysoft OOB support. DIR is the OOB base install
directory, defaults to /usr/local/easysoft/oob/client.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-exec-dir">
<term>
<parameter>--with-exec-dir[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Only allow executables in DIR when in safe mode defaults
to /usr/local/php/bin
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-fdftk">
<term>
<parameter>--with-fdftk[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include fdftk support. DIR is the fdftk install directory,
defaults to /usr/local.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-gnu-ld">
<term>
<parameter>--with-gnu-ld</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: assume the C compiler uses GNU ld [default=no]
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-icap">
<term>
<parameter>--with-icap[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include ICAP support.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-imap">
<term>
<parameter>--with-imap[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include IMAP support. DIR is the IMAP include and
c-client.a directory.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-imsp">
<term>
<parameter>--with-imsp[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Include IMSP support (DIR is IMSP's include dir and libimsp.a
dir).
</para>
<para>
PHP 4: Option not available in PHP 4
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-java">
<term>
<parameter>--with-java[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include Java support. DIR is the base install directory for the
JDK. This extension can only be built as a shared dl.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-kerberos">
<term>
<parameter>--with-kerberos[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include Kerberos support in IMAP.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-mcal">
<term>
<parameter>--with-mcal[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include MCAL support.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-mcrypt">
<term>
<parameter>--with-mcrypt[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include mcrypt support. DIR is the mcrypt install
directory.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-mhash">
<term>
<parameter>--with-mhash[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include mhash support. DIR is the mhash install directory.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-mm">
<term>
<parameter>--with-mm[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include mm support for session storage
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-mod_charset">
<term>
<parameter>--with-mod_charset</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Enable transfer tables for mod_charset (Rus Apache).
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-pdflib">
<term>
<parameter>--with-pdflib[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Include pdflib support (tested with 0.6 and 2.0). DIR is
the pdflib install directory, which defaults to
<filename>/usr/local</filename>.
</para>
<para>
PHP 4: Include pdflib 3.x support. DIR is the pdflib install
directory, which defaults to <filename>/usr/local</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-shared-pdflib">
<term>
<parameter>--enable-shared-pdflib</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Activate pdflib as shared librairy.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-readline">
<term>
<parameter>--with-readline[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include readline support. DIR is the readline install directory.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-regex">
<term>
<parameter>--with-regex=TYPE</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: regex library type: system, apache, php
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-servlet">
<term>
<parameter>--with-servlet[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include servlet support. DIR is the base install
directory for the JSDK. This SAPI requires that the Java
extension be built as a shared dl.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-ming">
<term>
<parameter>--with-ming</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include Flash 4 support, with Ming
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-swf">
<term>
<parameter>--with-swf[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include swf support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-system-regex">
<term>
<parameter>--with-system-regex</parameter>
</term>
<listitem>
<para>
PHP 3: Do not use the bundled regex library
</para>
<para>
PHP 4: (deprecated) Use system regex library
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-tsrm-pth">
<term>
<parameter>--with-tsrm-pth[=pth-config]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Use GNU Pth.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-tsrm-pthreads">
<term>
<parameter>--with-tsrm-pthreads</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Use POSIX threads (default)
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-x">
<term>
<parameter>--with-x</parameter>
</term>
<listitem>
<para>
PHP 3: use the X Window System
</para>
<para>
PHP 4: Option not available in PHP 4
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-bzip2-dir">
<term>
<parameter>--with-bz2[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include support bzip2. DIR
is the bzip2 install dir.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-zlib-dir">
<term>
<parameter>--with-zlib-dir[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: zlib dir for pdflib 2.0 or include zlib support
</para>
<para>
PHP 4: zlib dir for pdflib 3.x or include zlib support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-zlib">
<term>
<parameter>--with-zlib[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include zlib support (requires zlib >= 1.0.9). DIR is
the zlib install directory, defaults to /usr.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.without-pcre-regex">
<term>
<parameter>--without-pcre-regex</parameter>
</term>
<listitem>
<para>
PHP 3: Don't include Perl Compatible Regular Expressions support
</para>
<para>
PHP 4: Do not include Perl Compatible Regular Expressions support. Use
--with-pcre-regex=DIR to specify DIR where PCRE's include and library
files are located, if not using bundled library.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.without-posix">
<term>
<parameter>--without-posix</parameter>
</term>
<listitem>
<para>
PHP 3: Don't include POSIX functions
</para>
<para>
PHP 4: Option not available in PHP 4; use <link
linkend="install.configure.disable-posix">--disable-posix</link>
instead.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="install.configure.networking">
<title>Networking</title>
<variablelist>
<varlistentry id="install.configure.with-curl">
<term>
<parameter>--with-curl[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include CURL support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-ftp">
<term>
<parameter>--enable-ftp</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available; use <link
linkend="install.configure.with-ftp">--with-ftp</link>
instead.
</para>
<para>
PHP 4: Enable FTP support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-ftp">
<term>
<parameter>--with-ftp</parameter>
</term>
<listitem>
<para>
PHP 3: Include FTP support.
</para>
<para>
PHP 4: Option not available; use <link
linkend="install.configure.enable-ftp">--enable-ftp</link>
instead
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.disable-url-fopen-wrapper">
<term>
<parameter>--disable-url-fopen-wrapper</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Disable the URL-aware fopen wrapper that allows accessing
files via http or ftp.
</para>
<warning>
<para>
This switch is only available for PHP versions up to 4.0.3, newer
versions provide an INI parameter called
<parameter>allow_url_fopen</parameter> instead of forcing you to
decide upon this feature at compile time.
</para>
</warning>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-mod-dav">
<term>
<parameter>--with-mod-dav=DIR</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include DAV support through Apache's mod_dav, DIR is
mod_dav's installation directory (Apache module version only!)
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-openssl">
<term>
<parameter>--with-openssl[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include OpenSSL support in SNMP.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-snmp">
<term>
<parameter>--with-snmp[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include SNMP support. DIR is the SNMP base install
directory, defaults to searching through a number of common locations
for the snmp install. Set DIR to shared to build as a dl, or shared,DIR
to build as a dl and still specify DIR.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-ucd-snmp-hack">
<term>
<parameter>--enable-ucd-snmp-hack</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Enable UCD SNMP hack
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-sockets">
<term>
<parameter>--enable-sockets</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Enable sockets support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-yaz">
<term>
<parameter>--with-yaz[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include YAZ support (ANSI/NISO Z39.50). DIR is the YAZ bin
install directory
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-yp">
<term>
<parameter>--enable-yp</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available; use <link
linkend="install.configure.with-yp">--with-yp</link>
instead.
</para>
<para>
PHP 4: Include YP support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-yp">
<term>
<parameter>--with-yp</parameter>
</term>
<listitem>
<para>
PHP 3: Include YP support
</para>
<para>
PHP 4: Option not available; use <link
linkend="install.configure.enable-yp">--enable-yp</link>
instead.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-mnogosearch">
<term>
<parameter>--with-mnogosearch</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include mnoGoSearch support.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="install.configure.php">
<title>PHP Behaviour</title>
<variablelist>
<varlistentry id="install.configure.enable-magic-quotes">
<term>
<parameter>--enable-magic-quotes</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Enable magic quotes by default.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.disable-short-tags">
<term>
<parameter>--disable-short-tags</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Disable the short-form <? start tag by default.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-track-vars">
<term>
<parameter>--enable-track-vars</parameter>
</term>
<listitem>
<para>
PHP 3: Enable GET/POST/Cookie track variables by default.
</para>
<para>
PHP 4: Option not available in PHP 4; as of PHP 4.0.2,
track_vars is always on.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="install.configure.servers">
<title>Server</title>
<variablelist>
<varlistentry id="install.configure.with-aolserver-src">
<term>
<parameter>--with-aolserver-src=DIR</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Specify path to the source distribution of AOLserver
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-aolserver">
<term>
<parameter>--with-aolserver=DIR</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Specify path to the installed AOLserver
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-apache">
<term>
<parameter>--with-apache[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Build Apache module. DIR is the top-level Apache build
directory, defaults to /usr/local/etc/httpd.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-apxs">
<term>
<parameter>--with-apxs[=FILE]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Build shared Apache module. FILE is the optional pathname
to the Apache apxs tool; defaults to apxs.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-versioning">
<term>
<parameter>--enable-versioning</parameter>
</term>
<listitem>
<para>
PHP 3: Take advantage of versioning and scoping Provided by Solaris 2.x
and Linux
</para>
<para>
PHP 4: Export only required symbols. See INSTALL for more information
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-caudium">
<term>
<parameter>--with-caudium[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Build PHP as a Pike module for use with the Caudium
webserver. DIR is the Caudium base directory. If no directory
is specified $prefix/caudium/server is used. The prefix is
controlled by the --prefix option and is /usr/local per
default.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-fhttpd">
<term>
<parameter>--with-fhttpd[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Build fhttpd module. DIR is the fhttpd sources directory,
defaults to /usr/local/src/fhttpd.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-nsapi">
<term>
<parameter>--with-nsapi=DIR</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Specify path to the installed Netscape
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-phttpd">
<term>
<parameter>--with-phttpd=DIR</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4:
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-pi3web">
<term>
<parameter>--with-pi3web=DIR</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Build PHP as a module for use with Pi3Web.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-roxen">
<term>
<parameter>--with-roxen=DIR</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Build PHP as a Pike module. DIR is the base Roxen directory,
normally /usr/local/roxen/server.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-roxen-zts">
<term>
<parameter>--enable-roxen-zts</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Build the Roxen module using Zend Thread Safety.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-thttpd">
<term>
<parameter>--with-thttpd=SRCDIR</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4:
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-zeus">
<term>
<parameter>--with-zeus=DIR</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Build PHP as an ISAPI module for use with Zeus.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="install.configure.text">
<title>Text and language</title>
<variablelist>
<varlistentry id="install.configure.with-aspell">
<term>
<parameter>--with-aspell[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include ASPELL support.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-gettext">
<term>
<parameter>--with-gettext[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4: Include GNU gettext support. DIR is the gettext install
directory, defaults to /usr/local
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-pspell">
<term>
<parameter>--with-pspell[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include PSPELL support.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-recode">
<term>
<parameter>--with-recode[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Include GNU recode support.
</para>
<para>
PHP 4: Include recode support. DIR is the recode install directory.
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-shmop">
<term>
<parameter>--enable-shmop</parameter>
</term>
<listitem>
<para>
PHP 3, PHP 4 : Activate shmop support.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="install.configure.xml">
<title>XML</title>
<variablelist>
<varlistentry id="install.configure.with-dom">
<term>
<parameter>--with-dom[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include DOM support (requires libxml >= 2.0). DIR is the
libxml install directory, defaults to <filename>/usr</filename>
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-sablot-errors-descriptive">
<term>
<parameter>--enable-sablot-errors-descriptive</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Enable Descriptive errors
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-sablot">
<term>
<parameter>--with-sablot[=DIR]</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Include Sablotron support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.enable-wddx">
<term>
<parameter>--enable-wddx</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3
</para>
<para>
PHP 4: Enable WDDX support
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.disable-xml">
<term>
<parameter>--disable-xml</parameter>
</term>
<listitem>
<para>
PHP 3: Option not available in PHP 3; XML functionality is
not built in by default. Use <link
linkend="install.configure.with-xml">--with-xml</link>
to turn it on.
</para>
<para>
PHP 4: Disable XML support using bundled expat lib
</para>
</listitem>
</varlistentry>
<varlistentry id="install.configure.with-xml">
<term>
<parameter>--with-xml</parameter>
</term>
<listitem>
<para>
PHP 3: Include XML support
</para>
<para>
PHP 4: Option not available; XML support is built in by
default. Use <link
linkend="install.configure.disable-xml">--disable-xml</link> to
turn it off.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
<sect1 id="install-windows">
<title>Installation on Windows 9x/Me/NT/2000 systems</title>
<para>
There are two main ways to install PHP for Windows: either
<link linkend="install.windows.manual">manually</link>
or by using the <link linkend="install.windows.installer">InstallShield</link>
installer.
</para>
<para>
If you have Microsoft Visual Studio, you can also
<link linkend="install.windows.build">build</link>
PHP from the original source code.
</para>
<para>
Once you have PHP installed on your Windows system, you may also
want to <link linkend="install.windows.extensions">load various extensions</link>
for added functionality.
</para>
<sect2 id="install.windows.installer">
<title>Windows InstallShield</title>
<para>
The Windows PHP installer available from the downloads page at
<ulink url="&url.php;">&url.php;</ulink>, this installs the CGI version
of PHP and, for IIS, PWS, and Xitami, configures the web server as
well.
</para>
<simpara>
Install your selected <acronym>HTTP</acronym> server on your system
and make sure that it works.
</simpara>
<simpara>
Run the executable installer and follow the instructions provided by
the installation wizard. Two types of installation are supported -
standard, which provides sensible defaults for all the settings it
can, and advanced, which asks questions as it goes along.
</simpara>
<simpara>
The installation wizard gathers enough information to set up the
<filename>php.ini</filename> file and configure the web server to
use PHP. For IIS and also PWS on NT Workstation, a list of all the
nodes on the server with script map settings is displayed, and you
can choose those nodes to which you wish to add the PHP script
mappings.
</simpara>
<simpara>
Once the installation has completed the installer will inform you
if you need to restart your system, restart the server, or just
start using PHP.
</simpara>
</sect2>
<sect2 id="install.windows.manual">
<title>General Installation Steps</title>
<simpara>
This install guide will help you manually install and configure
PHP on your Windows 9x/Me/NT/2000 webservers. This guide was compiled by
&link.bob;. The original version can be found at <ulink
url="&url.win32install;">&url.win32install;</ulink>.
</simpara>
<para>
This guide provides manual installation support for:
<itemizedlist>
<listitem>
<para>
Personal Web Server 3 and 4 or newer
</para>
</listitem>
<listitem>
<para>
Internet Information Server 3 and 4 or newer
</para>
</listitem>
<listitem>
<para>
Apache 1.3.x
</para>
</listitem>
<listitem>
<para>
OmniHTTPd 2.0b1 and up
</para>
</listitem>
<listitem>
<para>
Oreilly Website Pro
</para>
</listitem>
<listitem>
<para>
Xitami
</para>
</listitem>
</itemizedlist>
</para>
<para>
PHP 4 for Windows comes in two flavours - a CGI executable (php.exe),
and several SAPI modules (for exapmle php4isapi.dll). The latter form
is new to PHP 4, and provides significantly improved performance and
some new functionality. However, please note that the SAPI modules
are <emphasis>NOT</emphasis> yet considered to be production quality.
The reason for this is that the PHP SAPI modules are using the
thread-safe version of the PHP code, which is new to PHP 4, and has
not yet been tested and pounded enough to be considered completely
stable, and there are actually a few known bugs. On the other hand,
some people have reported very good results with the SAPI modules,
even though we're not aware of anyone actually running it on a
production site. In short - your mileage may vary; If you need
absolute stability, trade the performance of the SAPI modules
with the stability of the CGI executable.
</para>
<para>
If you choose one of the SAPI modules and use Windows 95, be sure
to download the DCOM update from the <ulink
url="http://download.microsoft.com/msdownload/dcom/95/x86/en/dcom95.exe">Microsoft
DCOM pages</ulink>. For the ISAPI module, an ISAPI 4.0 compliant Web server
is required (tested on IIS 4.0, PWS 4.0 and IIS 5.0). IIS 3.0 is
<emphasis>NOT</emphasis> supported; You should download and
install the Windows NT 4.0 Option Pack with IIS 4.0 if you
want native PHP support.
</para>
<para>
The following steps should be performed on all installations
before the server specific instructions.
<itemizedlist>
<listitem>
<para>
Extract the distribution file to a directory of your choice.
"C:\PHP\" is a good start.
</para>
</listitem>
<listitem>
<para>
Copy the file, 'php.ini-dist' to your
'%WINDOWS%' directory on Windows 95/98 or to your
'%SYSTEMROOT%' directory under Windows NT or Windows
2000 and rename it to 'php.ini'. Your
'%WINDOWS%' or '%SYSTEMROOT%' directory is
typically:
<simplelist>
<member>c:\windows for Windows 95/98</member>
<member>c:\winnt or c:\winnt40 for NT/2000 servers</member>
</simplelist>
</para>
</listitem>
<listitem>
<para>
Edit your 'php.ini' file:
<itemizedlist>
<listitem>
<simpara>
You will need to change the 'extension_dir' setting to
point to your php-install-dir, or where you have placed
your 'php_*.dll' files. ex: c:\php
</simpara>
</listitem>
<listitem>
<simpara>
If you are using OmniHTTPd, do not follow the next step.
Set the 'doc_root' to point to your webservers
document_root. ex: c:\apache\htdocs or c:\webroot
</simpara>
</listitem>
<listitem>
<simpara>
Choose which extensions you would like to load when PHP
starts. You can uncomment the: 'extension=php_*.dll' lines
in <filename>php.ini</filename> to load these extensions.
Some extensions 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 where to get supporting libraries. You
can also load a module dynamically in your script
using <function>dl</function>. See the section about
<link linkend="install.windows.extensions">Windows
extensions</link>.
</simpara>
</listitem>
<listitem>
<simpara>
On PWS and IIS, you can set the <filename>browscap.ini</filename>
to point to: 'c:\windows\system\inetsrv\browscap.ini' on
Windows 9x/Me and 'c:\winnt\system32\inetsrv\browscap.ini'
on NT/2000 Server. Additional information on using the
browscap 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>
</para>
</sect2>
<sect2 id="install.windows.build">
<title>Building from source</title>
<para>
Before getting started, it is worthwhile answering the question:
"Why is building on Windows so hard?" Two reasons come to mind:
</para>
<orderedlist>
<listitem><simpara>
Windows does not (yet) enjoy a large community of developers
who are willing to freely share their source. As a direct
result, the necessary investment in infrastructure required
to support such development hasn't been made. By and large,
what is available has been made possible by the porting of
necessary utilities from Unix. Don't be surprised if some of
this heritage shows through from time to time.
</simpara></listitem>
<listitem><simpara>
Pretty much all of the instructions that follow are of the
"set and forget" variety. So sit back and try follow the
instructions below as faithfully as you can.
</simpara></listitem>
</orderedlist>
<sect3 id="install.windows.build.prepare">
<title>Preparations</title>
<para>
Before you get started, you have a lot to download....
</para>
<itemizedlist>
<listitem><simpara>
For starters, get the Cygwin toolkit from the closest <ulink
url="http://sources.redhat.com/cygwin/download.html">cygwin</ulink>
mirror site. This will provide you most of the popular GNU
utilities used by the build process.
</simpara></listitem>
<listitem><simpara>
Download the rest of the build tools you will need from the PHP
site at <ulink url="http://www.php.net/extra/win32build.zip"
>http://www.php.net/extra/win32build.zip</ulink>.
</simpara></listitem>
<listitem><simpara>
Get the source code for the DNS name resolver used by PHP
at <ulink url="http://www.php.net/extra/bindlib_w32.zip"
>http://www.php.net/extra/bindlib_w32.zip</ulink>. This
is a replacement for the <filename>resolv.lib</filename>
library included in <filename>win32build.zip</filename>.
</simpara></listitem>
<listitem><simpara>
If you don't already have an unzip utility, you will
need one. A free version is available from <ulink
url="http://www.cdrom.com/pub/infozip/UnZip.html">InfoZip</ulink>.
</simpara></listitem>
</itemizedlist>
<simpara>
Finally, you are going to need the source to PHP 4 itself.
You can get the latest development version using <ulink
url="http://www.php.net/anoncvs.php">anonymous CVS</ulink>. If you get
a <ulink url="http://snaps.php.net/">snapshot</ulink> or a <ulink
url="http://www.php.net/downloads.php">source</ulink> tarball, you
not only will have to untar and ungzip it, but you will have to
convert the bare linefeeds to crlf's in the <filename>*.dsp</filename>
and <filename>*.dsw</filename> files before Microsoft Visual C++
will have anything to do with them.
</simpara>
<note>
<simpara>
Place the <filename>Zend</filename> and
<filename>TSRM</filename> directories inside the
<filename>php4</filename> directory in order for the projects
to be found during the build process.
</simpara>
</note>
</sect3>
<sect3 id="install.windows.build.install">
<title>Putting it all together</title>
<itemizedlist>
<listitem><simpara>
Follow the instructions for installing the unzip utility of
your choosing.
</simpara></listitem>
<listitem>
<simpara>
Execute <filename>setup.exe</filename> and follow the installation
instructions. If you choose to install to a path other than
<filename>c:\cygnus</filename>, let the build process know by setting
the Cygwin environment variable. On Windows 95/98 setting
an environment variable can be done by placing a line in
your autoexec.bat. On Windows NT, go to My Computer =>
Control Panel => System and select the environment tab.
</simpara>
<warning>
<simpara>
Make a temporary directory for Cygwin to use, otherwise many
commands (particularly bison) will fail. On Windows 95/98,
<userinput>mkdir C:\TMP</userinput>. For Windows NT,
<userinput>mkdir %SystemDrive%\tmp</userinput>.
</simpara>
</warning>
</listitem>
<listitem><simpara>
Make a directory and unzip <filename>win32build.zip</filename> into it.
</simpara></listitem>
<listitem>
<simpara>
Launch Microsoft Visual C++, and from the menu select
Tools => Options. In the dialog, select the
directories tab. Sequentially change the dropdown
to Executables, Includes, and Library files,
and ensure that <filename>cygwin\bin</filename>,
<filename>win32build\include</filename>, and
<filename>win32build\lib</filename> are in each list,
respectively. (To add an entry, select a blank line
at the end of the list and begin typing). Typical entries
will look like this:
</simpara>
<itemizedlist>
<listitem><simpara>
<filename>c:\cygnus\bin</filename>
</simpara></listitem>
<listitem><simpara>
<filename>c:\php-win32build\include</filename>
</simpara></listitem>
<listitem><simpara>
<filename>c:\php-win32build\lib</filename>
</simpara></listitem>
</itemizedlist>
<simpara>
Press OK, and exit out of Visual C++.
</simpara>
</listitem>
<listitem>
<simpara>
Make another directory and unzip <filename>bindlib_w32.zip</filename>
into it. Decide whether you want to have debug symbols available
(bindlib - Win32 Debug) or not (bindlib - Win32 Release).
Build the appropriate configuration:
</simpara>
<itemizedlist>
<listitem><simpara>
For GUI users, launch VC++, and then select File => Open
Workspace and select bindlib. Then select Build=>Set
Active Configuration and select the desired configuration.
Finally select Build=>Rebuild All.
</simpara></listitem>
<listitem>
<simpara>
For command line users, make sure that you either have
the C++ environment variables registered, or have run
<command>vcvars.bat</command>, and then execute one of the
following:
</simpara>
<itemizedlist>
<listitem>
<simpara>
<userinput>msdev bindlib.dsp /MAKE "bindlib - Win32 Debug"</userinput>
</simpara>
</listitem>
<listitem>
<simpara>
<userinput>msdev bindlib.dsp /MAKE "bindlib - Win32 Release"</userinput>
</simpara>
</listitem>
</itemizedlist>
</listitem>
<listitem><simpara>
At this point, you should have a usable
<filename>resolv.lib</filename> in either your
<filename>Debug</filename> or <filename>Release</filename>
subdirectories. Copy this file into your
<filename>win32build\lib</filename> directory over the
file by the same name found in there.
</simpara></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</sect3>
<sect3 id="install.windows.build.compile">
<title>Compiling</title>
<simpara>
The best way to get started is to build the standalone/CGI version.
</simpara>
<itemizedlist>
<listitem><simpara>
For GUI users, launch VC++, and then select File => Open
Workspace and select php4ts. Then select Build=>Set Active
Configuration and select the desired configuration. Finally
select Build=>Rebuild All.
</simpara></listitem>
<listitem>
<simpara>
For command line users, make sure that you either have
the C++ environment variables registered, or have run
<command>vcvars.bat</command>, and then execute one of the
following:
</simpara>
<itemizedlist>
<listitem><simpara>
<userinput>msdev php4ts.dsp /MAKE "php4ts - Win32 Debug_TS"</userinput>
</simpara></listitem>
<listitem><simpara>
<userinput>msdev php4ts.dsp /MAKE "php4ts - Win32 Release_TS"</userinput>
</simpara></listitem>
<listitem><simpara>
At this point, you should have a usable
<filename>php.exe</filename> in either
your <filename>Debug_TS</filename> or
<filename>Release_TS</filename> subdirectories.
</simpara></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<simpara>
Repeat the above steps with <filename>php4isapi.dsp</filename>
(which can be found in <filename>sapi\isapi</filename>) in
order to build the code necessary for integrating PHP with
Microsoft IIS.
</simpara>
</sect3>
</sect2>
<sect2 id="install.windows.extensions">
<title>Installation of Windows extensions</title>
<para>
After installing PHP and a webserver on Windows, you will
probably want to install some extensions for added functionality.
The following table describes some of the extensions available. As
described in the manual installation steps, you can choose which
extensions you would like to load when PHP starts by uncommenting the:
'extension=php_*.dll' lines in <filename>php.ini</filename>. Some
extensions 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
where to get supporting libraries. You can also load a module
dynamically in your script using <function>dl</function>.
</para>
<para>
The DLLs for PHP extensions are prefixed with 'php_'. This
prevents confusion between PHP extensions and their supporting
libraries.
</para>
<note>
<para>
In PHP 4.0.4pl1 MySQL, ODBC, FTP, Calendar, BCMath, COM, PCRE,
Session, WDDX and XML support is <emphasis>built-in</emphasis>.
You don't need to load any additional extensions in order to
use these functions. See your distributions
<filename>README.txt</filename> or <filename>install.txt</filename>
for a list of built in modules.
</para>
</note>
<para>
<table>
<title>PHP Extensions</title>
<tgroup cols="2">
<tbody>
<row>
<entry>php_calendar.dll</entry>
<entry>Calendar conversion functions</entry>
</row>
<row>
<entry>php_crypt.dll</entry>
<entry>Crypt functions</entry>
</row>
<row>
<entry>php_dbase.dll</entry>
<entry>dBase functions</entry>
</row>
<row>
<entry>php_dbm.dll</entry>
<entry>Berkeley DB2 library</entry>
</row>
<row>
<entry>php_filepro.dll</entry>
<entry>Read-only access to Filepro databases</entry>
</row>
<row>
<entry>php_gd.dll</entry>
<entry>GD library functions for GIF manipulation</entry>
</row>
<row>
<entry>php_hyperwave.dll</entry>
<entry>HyperWave functions</entry>
</row>
<row>
<entry>php_imap4r2.dll</entry>
<entry>IMAP 4 functions</entry>
</row>
<row>
<entry>php_ldap.dll</entry>
<entry>LDAP functions</entry>
</row>
<row>
<entry>php_msql1.dll</entry>
<entry>mSQL 1 client</entry>
</row>
<row>
<entry>php_msql2.dll</entry>
<entry>mSQL 2 client</entry>
</row>
<row>
<entry>php_mssql.dll</entry>
<entry>MSSQL client (requires MSSQL DB-Libraries</entry>
</row>
<row>
<entry>php3_mysql.dll (built into PHP 4)</entry>
<entry>MySQL functions</entry>
</row>
<row>
<entry>php_nsmail.dll</entry>
<entry>Netscape mail functions</entry>
</row>
<row>
<entry>php_oci73.dll</entry>
<entry>Oracle functions</entry>
</row>
<row>
<entry>php_snmp.dll</entry>
<entry>SNMP get and walk functions (NT only!)</entry>
</row>
<row>
<entry>php_zlib.dll</entry>
<entry>ZLib compression functions</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</sect2>
</sect1>
<sect1 id="install.apache">
<title>Servers-Apache</title>
<para>
This section contains notes and hints specific to Apache installs
of PHP, both for <link linkend="install.apache.unix">Unix</link> and
<link linkend="install.apache.windows">Windows</link> versions.
</para>
<sect2 id="install.apache.unix">
<title>Details of installing PHP with Apache on Unix.</title>
<para>
You can select arguments to add to the
<command>configure</command> on line 8 below from the <link
linkend="install.configure">Complete list of configure
options</link>.
</para>
<example id="install.apache.unix.longer">
<title>
Installation Instructions (Apache Module Version)
</title>
<programlisting>
1. gunzip apache_1.3.x.tar.gz
2. tar xvf apache_1.3.x.tar
3. gunzip php-x.x.x.tar.gz
4. tar xvf php-x.x.x.tar
5. cd apache_1.3.x
6. ./configure --prefix=/www
7. cd ../php-x.x.x
8. ./configure --with-mysql --with-apache=../apache_1.3.x --enable-track-vars
9. make
10. make install
11. cd ../apache_1.3.x
12. for PHP 3: ./configure --activate-module=src/modules/php3/libphp3.a
for PHP 4: ./configure --activate-module=src/modules/php4/libphp4.a
13. make
14. make install
Instead of this step you may prefer to simply copy the httpd binary
overtop of your existing binary. Make sure you shut down your
server first though.
15. cd ../php-x.x.x
16. for PHP 3: cp php3.ini-dist /usr/local/lib/php3.ini
for PHP 4: cp php.ini-dist /usr/local/lib/php.ini
You can edit your .ini file to set PHP options. If
you prefer this file in another location, use
--with-config-file-path=/path in step 8.
17. Edit your httpd.conf or srm.conf file and add:
For PHP 3: AddType application/x-httpd-php3 .php3
For PHP 4: AddType application/x-httpd-php .php
You can choose any extension you wish here. .php is simply the one
we suggest. You can even include .html .
18. Use your normal procedure for starting the Apache server. (You must
stop and restart the server, not just cause the server to reload by
use a HUP or USR1 signal.)
</programlisting>
</example>
<para>
Depending on your Apache install and Unix variant, there are many
possible ways to stop and restart the server. Below are some typical
lines used in restarting the server, for different apache/unix
installations. You should replace <literal>/path/to/</literal> with
the path to these applications on your systems.
<informalexample>
<programlisting>
1. Several Linux and SysV variants:
/etc/rc.d/init.d/httpd restart
2. Using apachectl scripts:
/path/to/apachectl stop
/path/to/apachectl start
3. httpdctl and httpsdctl (Using OpenSSL), similar to apachectl:
/path/to/httpsdctl stop
/path/to/httpsdctl start
4. Using mod_ssl, or another SSL server, you may want to manually
stop and start:
/path/to/apachectl stop
/path/to/apachectl startssl
</programlisting>
</informalexample>
The locations of the apachectl and http(s)dctl binaries often
vary. If your system has <literal>locate</literal> or
<literal>whereis</literal> or <literal>which</literal> commands,
these can assist you in finding your server contrl programs.
</para>
<para>
Different examples of compiling PHP for apache are as follows:
<informalexample>
<programlisting>
/configure --with-apxs --with-pgsql
</programlisting>
</informalexample>
</para>
<para>
This will create a <filename>libphp4.so</filename> shared
library that is loaded into Apache using a LoadModule line in
Apache's <filename>httpd.conf</filename> file. The PostgreSQL
support is embedded into this <filename>libphp4.so</filename>
library.
</para>
<para>
<informalexample>
<programlisting>
/configure --with-apxs --with-pgsql=shared
</programlisting>
</informalexample>
</para>
<para>
This will again create a <filename>libphp4.so</filename> shared
library for Apache, but it will also create a
<filename>pgsql.so</filename> shared library that is loaded into
PHP either by using the extension directive in
<filename>php.ini</filename> file or by loading it explicitly in
a script using the <function>dl</function> function.
</para>
<para>
<informalexample>
<programlisting>
/configure --with-apache=/path/to/apache_source --with-pgsql
</programlisting>
</informalexample>
</para>
<para>
This will create a <filename>libmodphp4.a</filename> library, a
<filename>mod_php4.c</filename> and some accompanying files and
copy this into the <literal>src/modules/php4</literal> directory
in the Apache source tree. Then you compile Apache using
<literal>--activate-module=src/modules/php4/libphp4.a</literal>
and the Apache build system will create
<filename>libphp4.a</filename> and link it statically into the
<filename>httpd</filename> binary. The PostgreSQL support is
included directly into this <filename>httpd</filename> binary,
so the final result here is a single <filename>httpd</filename>
binary that includes all of Apache and all of PHP.
</para>
<para>
<informalexample>
<programlisting>
/configure --with-apache=/path/to/apache_source --with-pgsql=shared
</programlisting>
</informalexample>
</para>
<para>
Same as before, except instead of including PostgreSQL support
directly into the final <filename>httpd</filename> you will get
a <filename>pgsql.so</filename> shared library that you can load
into PHP from either the <filename>php.ini</filename> file or
directly using <function>dl</function>.
</para>
<para>
When choosing to build PHP in different ways, you should consider
the advantages and drawbacks of each method. Building as a shared
object will mean that you can compile apache separately, and don't
have to recompile everything as you add to, or change, PHP.
Building PHP into apache (static method) means that PHP will
load and run faster. For more information, see the Apache
<ulink url="&url.apachedso;">webpage on DSO support</ulink>.
</para>
</sect2>
<sect2 id="install.apache.windows">
<title>Details of installing PHP on Windows with Apache 1.3.x</title>
<simpara>
There are two ways to set up PHP to work with Apache 1.3.x
on Windows. One is to use the CGI binary (php.exe),
the other is to use the Apache module dll. In either case
you need to stop the Apache server, and edit your
<literal>srm.conf</literal> or <literal>httpd.conf</literal>
to configure Apache to work with PHP.
</simpara>
<simpara>
Although there can be a few variations of configuring PHP
under Apache, these are simple enough to be used by the
newcomer. Please consult the Apache Docs for further
configuration directives.
</simpara>
<para>
If you unziped the PHP package to C:\PHP\ as desribed
in the <link linkend="install.windows.manual">General
Installation Steps</link> section, you need to insert
these lines to your Apache conf file to set up the
CGI binary:
<itemizedlist>
<listitem>
<simpara>
<literal>
ScriptAlias /php/ "c:/php/"
</literal>
</simpara>
</listitem>
<listitem>
<simpara>
<literal>
AddType application/x-httpd-php .php .phtml
</literal>
</simpara>
</listitem>
<listitem>
<simpara>
<literal>
Action application/x-httpd-php "/php/php.exe"
</literal>
</simpara>
</listitem>
</itemizedlist>
Remerber to restart the server, for example,
<literal>NET STOP APACHE</literal> followed by
<literal>NET START APACHE</literal>.
</para>
<para>
If you would like to use PHP as a module in Apache,
you should move <filename>php4ts.dll</filename> to
the windows/system (for Windows 9x/Me) or winnt/system32
(for Windows NT/2000) directory, overwriting any older file.
Then you should add the following two lines to you Apache
conf file:
<itemizedlist>
<listitem>
<simpara>
<literal>
LoadModule php4_module c:/php/sapi/php4apache.dll
</literal>
</simpara>
</listitem>
<listitem>
<simpara>
<literal>
AddType application/x-httpd-php .php .phtml
</literal>
</simpara>
</listitem>
</itemizedlist>
</para>
<simpara>
To use the source code highlighting feature, simply create a PHP
script file and stick this code in: <literal><?php show_source
("original_php_script.php"); ?></literal>. Substitute
<literal>original_php_script.php</literal> with the name of the
file you wish to show the source of. (This is the only way of
doing so).
</simpara>
<note>
<simpara>
On Win-Apache all backslashes in a path statement such
as: "c:\directory\file.ext", must be converted to
forward slashes.
</simpara>
</note>
</sect2>
</sect1>
<sect1 id="install.commandline">
<title>Servers-CGI/Commandline</title>
<para>
The default is to build PHP as a CGI program. This creates a
commandline interpreter, which can be used for CGI processing, or
for non-web-related PHP scripting. If you are running a web
server PHP has module support for, you should generally go for
that solution for performance reasons. However, 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.
</para>
<sect2 id="install.commandline.testing">
<title>Testing</title>
<simpara>
If you have built PHP as a CGI program, you may test your build
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.
</simpara>
</sect2>
<sect2 id="install.commandline.benchmarking">
<title>Benchmarking</title>
<simpara>
If you have built PHP 3 as a CGI program, you may benchmark your
build by typing <command>make bench</command>. Note that if safe
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>
configuration setting to control this time for your own
scripts. <command>make bench</command> ignores the <link
linkend="configuration.file">configuration file</link>.
</simpara>
<note>
<simpara>
<command>make bench</command> is only available for PHP 3.
</simpara>
</note>
</sect2>
</sect1>
<sect1 id="install.fhttpd">
<title>Servers-fhttpd</title>
<para>
To build PHP as an fhttpd module, answer "yes" to "Build as an
fhttpd module?" (the <option><link
linkend="install.configure.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
running fhttpd, building PHP as a module will give better
performance, more control and remote execution capability.
</para>
</sect1>
<sect1 id="install.caudium">
<title>Servers-Caudium</title>
<para>
PHP 4 can be build as a Pike module for the Caudium webserver. Note
that this is not supported with PHP 3. Follow the simple
instructions below to install PHP 4 for Caudium.
</para>
<example id="install.caudium.instructions">
<title>Caudium Installation Instructions</title>
<programlisting>
1. Make sure you have Caudium installed prior to attempting to
install PHP 4. For PHP 4 to work correctly, you will need Pike
7.0.268 or newer. For the sake of this example we assume that
Caudium is installed in /opt/caudium/server/.
2. Change directory to php-x.y.z (where x.y.z is the version number).
3. ./configure --with-caudium=/opt/caudium/server
4. make
5. make install
6. Restart Caudium if it's currently running.
7. Log into the graphical configuration interface and go to the
virtual server where you want to add PHP 4 support.
8. Click Add Module and locate and then add the PHP 4 Script Support module.
9. If the documentation says that the 'PHP 4 interpreter isn't
available', make sure that you restarted the server. If you did
check /opt/caudium/logs/debug/default.1 for any errors related to
<filename>PHP4.so</filename>. Also make sure that
<filename>caudium/server/lib/[pike-version]/PHP4.so</filename>
is present.
10. Configure the PHP Script Support module if needed.
</programlisting>
</example>
<para>
You can of course compile your Caudium module with support for the
various extensions available in PHP 4. See the
<link linkend="install.configure">complete list of configure
options</link> for an exhaustive rundown.
</para>
<note>
<para>
When compiling PHP 4 with MySQL support you must make sure that
the normal MySQL client code is used. Otherwise there might be
conflicts if your Pike already has MySQL support. You do this by
specifying a MySQL install directory <link
linkend="install.configure.with-mysql">the --with-mysql
option</link>.
</para>
</note>
</sect1>
<sect1 id="install.iis">
<title>Servers-IIS/PWS</title>
<para>
This section contains notes and hints specific to IIS (Microsoft
Internet Information Server) installing PHP for
<link linkend="install.iis.iis3">PWS/IIS 3</link>,
<link linkend="install.iis.pws4">PWS 4 or newer</link> and
<link linkend="install.iis.iis4">IIS 4 or newer</link> versions.
</para>
<sect2 id="install.iis.iis3">
<title>Windows and PWS/IIS 3</title>
<simpara>
The recommended method for configuring these servers is to use
the INF file included with the distribution
(php_iis_reg.inf). You may want to edit this file and make sure
the extensions and PHP install directories match your
configuration. Or you can follow the steps below to do it
manually.
</simpara>
<warning>
<para>
These steps involve working directly with the Windows
registry. One error here can leave your system in an unstable
state. We highly recommend that you back up your registry
first. The PHP Development team will not be held responsible if
you damage your registry.
</para>
</warning>
<para>
<itemizedlist>
<listitem>
<simpara>
Run Regedit.
</simpara>
</listitem>
<listitem>
<simpara>
Navigate to: <literal>HKEY_LOCAL_MACHINE /System
/CurrentControlSet /Services /W3Svc /Parameters
/ScriptMap</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
On the edit menu select: <literal>New->String Value</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
Type in the extension you wish to use for your php
scripts. ex: <literal>.php</literal>
</simpara>
</listitem>
<listitem>
<simpara>
Double click on the new string value and enter the path to
<literal>php.exe</literal> in the value data field. ex:
<literal>c:\php\php.exe %s %s</literal>. The '%s %s' is VERY
important, PHP will not work properly without it.
</simpara>
</listitem>
<listitem>
<simpara>
Repeat these steps for each extension you wish to associate
with PHP scripts.
</simpara>
</listitem>
<listitem>
<simpara>
Now navigate to: <literal>HKEY_CLASSES_ROOT</literal>
</simpara>
</listitem>
<listitem>
<simpara>
On the edit menu select: <literal>New->Key</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
Name the key to the extension you setup in the previous
section. ex: <literal>.php</literal>
</simpara>
</listitem>
<listitem>
<simpara>
Highlight the new key and in the right side pane, double click
the "default value" and enter <literal>phpfile</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
Repeat the last step for each extension you set up in the
previous section.
</simpara>
</listitem>
<listitem>
<simpara>
Now create another <literal>New->Key</literal> under
<literal>HKEY_CLASSES_ROOT</literal> and name it
<literal>phpfile</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
Highlight the new key <literal>phpfile</literal> and in the
right side pane, double click the "default value" and enter
<literal>PHP Script</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
Right click on the <literal>phpfile</literal> key and select
<literal>New->Key</literal>, name it <literal>Shell</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
Right click on the <literal>Shell</literal> key and select
<literal>New->Key</literal>, name it <literal>open</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
Right click on the <literal>open</literal> key and select
<literal>New->Key</literal>, name it
<literal>command</literal>.
</simpara>
</listitem>
<listitem>
<simpara>
Highlight the new key <literal>command</literal> and in the
right side pane, double click the "default value" and enter
the path to <literal>php.exe</literal>. ex:
<literal>c:\php\php.exe -q %1</literal>. (don't forget the
<literal>%1</literal>).
</simpara>
</listitem>
<listitem>
<simpara>
Exit Regedit.
</simpara>
</listitem>
<listitem>
<simpara>
If using PWS on Windows, reboot to reload the registry.
</simpara>
</listitem>
</itemizedlist>
</para>
<simpara>
PWS and IIS 3 users now have a fully operational system. IIS 3
users can use a nifty <ulink url="&url.iiscfg;">tool</ulink>
from Steven Genusa to configure their script maps.
</simpara>
</sect2>
<sect2 id="install.iis.pws4">
<title>Windows and PWS 4 or newer</title>
<simpara>
When installing PHP on Windows with PWS 4 or newer version,
you have two options. One to set up the PHP CGI binary,
the other is to use the ISAPI module dll.
</simpara>
<para>
If you choose the CGI binary, do the following:
<itemizedlist>
<listitem>
<simpara>
Edit the enclosed <filename>pws-php4cgi.reg</filename>
file (look into the sapi dir) to reflect the location of
your php.exe. Forward slashes should be escaped, for example:
<literal>[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parameters\Script
Map] ".php"="C:\\PHP\\php.exe"</literal>
</simpara>
</listitem>
<listitem>
<simpara>
In the PWS Manager, right click on a given directory you want
to add PHP support to, and select Properties. Check the 'Execute'
checkbox, and confirm.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
If you choose the ISAPI module, do the following:
<itemizedlist>
<listitem>
<simpara>
Edit the enclosed <filename>pws-php4isapi.reg</filename>
file (look into the sapi dir) to reflect the location of
your php4isapi.dll. Forward slashes should be escaped, for example:
<literal>[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parameters\Script
Map] ".php"="C:\\PHP\\sapi\\php4isapi.dll"</literal>
</simpara>
</listitem>
<listitem>
<simpara>
In the PWS Manager, right click on a given directory you want to
add PHP support to, and select Properties. Check the 'Execute'
checkbox, and confirm.
</simpara>
</listitem>
</itemizedlist>
</para>
</sect2>
<sect2 id="install.iis.iis4">
<title>Windows NT/2000 and IIS 4 or newer</title>
<simpara>
To install PHP on an NT/2000 Server running IIS 4 or newer,
follow these instructions. You have two options to set up
PHP, using the CGI binary (php.exe) or with the ISAPI module.
</simpara>
<simpara>
In either case, you need to start the Microsoft Management
Console (may appear as 'Internet Services Manager', either
in your Windows NT 4.0 Option Pack branch or the Control
Panel=>Administrative Tools under Windows 2000). Then
right click on your Web server node (this will most probably
appear as 'Default Web Server'), and select 'Properties'.
</simpara>
<para>
If you want to use the CGI binary, do the following:
<itemizedlist>
<listitem>
<simpara>
Under 'Home Directory', 'Virtual Directory', or
'Directory', click on the 'Configuration' button,
and then enter the App Mappings tab.
</simpara>
</listitem>
<listitem>
<simpara>
Click Add, and in the Executable box, type:
<literal>c:\php\php.exe %s %s</literal> (assuming
that you have unziped PHP in c:\php\). You MUST
have the %s %s on the end, PHP will not function
properly if you fail to do this.
</simpara>
</listitem>
<listitem>
<simpara>
In the Extension box, type the file name extension you want
associated with PHP scripts. Leave 'Method exclusions'
blank, and check the Script engine checkbox.
You must repeat step 3 and 4 for each extension you
want associated with PHP scripts.
(<literal>.php</literal> and <literal>.phtml</literal>
are common.)
</simpara>
</listitem>
<listitem>
<simpara>
Set up the appropriate security. (This is done in Internet
Service Manager), and if your NT Server uses NTFS file system,
add execute rights for I_USR_ to the directory that contains
<literal>php.exe</literal>.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
To use the ISAPI module, do the following:
<itemizedlist>
<listitem>
<simpara>
If you don't want to perform HTTP Authentication using PHP,
you can (and should) skip this step. Under ISAPI Filters,
add a new ISAPI filter. Use PHP as the filter name, and
supply a path to the php4isapi.dll.
</simpara>
</listitem>
<listitem>
<simpara>
Under 'Home Directory', click on the 'Configuration' button.
Add a new entry to the Application Mappings. Use the path
to the php4isapi.dll as the Executable, supply .php as the
extension, leave Method exclusions blank, and check the
Script engine checkbox.
</simpara>
</listitem>
<listitem>
<simpara>
Stop IIS completely
</simpara>
</listitem>
<listitem>
<simpara>
Start IIS again
</simpara>
</listitem>
</itemizedlist>
</para>
</sect2>
</sect1>
<sect1 id="install.netscape-enterprise">
<title>Servers-Netscape and iPlanet</title>
<para>
To build PHP with NES or iPlanet web servers, enter the proper
install directory for the
<option><link linkend="install.configure.with-nsapi">--with-nsapi</link> =
<replaceable>DIR</replaceable></option>
option. The default directory is usually
<filename class="directory">/opt/netscape/suitespot/</filename>.
Please also read
<filename>/php-xxx-version/sapi/nsapi/nsapi-readme.txt</filename>.
</para>
<para>
<example id="install.netscape-enterprise.solaris">
<title>
Installation Example for Netscape Enterprise on Solaris
</title>
<programlisting>
Instructions for Sun Solaris 2.6 with Netscape Enterprise Server 3.6
From: [EMAIL PROTECTED]
1. Install the following packages from www.sunfreeware.com or another
download site:
flex-2_5_4a-sol26-sparc-local
gcc-2_95_2-sol26-sparc-local
gzip-1.2.4-sol26-sparc-local
perl-5_005_03-sol26-sparc-local
bison-1_25-sol26-sparc-local
make-3_76_1-sol26-sparc-local
m4-1_4-sol26-sparc-local
autoconf-2.13
automake-1.4
mysql-3.23.24-beta (if you want mysql support)
tar-1.13 (GNU tar)
2. Make sure your path includes the proper directories
PATH=.:/usr/local/bin:/usr/sbin:/usr/bin:/usr/ccs/bin
export PATH
3. gunzip php-x.x.x.tar.gz (if you have a .gz dist, otherwise go to 4)
4. tar xvf php-x.x.x.tar
5. cd ../php-x.x.x
6. For the following step, make sure /opt/netscape/suitespot/ is where
your netscape server is installed. Otherwise, change to correct path:
/configure --with-mysql=/usr/local/mysql --with-nsapi=/opt/netscape/suitespot/
--enable-track-vars --enable-libgcc
7. make
8. make install
</programlisting>
</example>
After performing the base install and reading the appropriate
readme file, you may need to performs some additional
configuration steps.
</para>
<para>
Firstly you may need to add some paths to the LD_LIBRARY_PATH
environment for Netscape to find all the shared libs. This can
best done in the start script for your Netscape server.
Windows users can probably skip this step. The start
script is often located in:
<filename
class="directory">/path/to/server/https-servername/start</filename>
</para>
<para>
You may also need to edit the configuration files that are
located in:<filename
class="directory">/path/to/server/https-servername/config/</filename>.
</para>
<example id="install.netscape-enterprise.configure">
<title>
Configuration Example for Netscape Enterprise
</title>
<programlisting>
Configuration Instructions for Netscape Enterprise Server
From: [EMAIL PROTECTED]
1. Add the following line to mime.types:
type=magnus-internal/x-httpd-php exts=php
2. Add the following to obj.conf, shlib will vary depending on
your OS, for unix it will be something like
/opt/netscape/suitespot/bin/libphp4.so.
You should place the following lines after mime types init.
Init fn="load-modules" funcs="php4_init,php4_close,php4_execute,php4_auth_trans"
shlib="/php4/nsapiPHP4.dll"
Init fn=php4_init errorString="Failed to initialize PHP!"
<object name="default">
.
.
.
.#NOTE this next line should happen after all 'ObjectType' and before all 'AddLog'
lines
Service fn="php4_execute" type="magnus-internal/x-httpd-php"
.
.
</Object>
<Object name="x-httpd-php">
ObjectType fn="force-type" type="magnus-internal/x-httpd-php"
Service fn=php4_execute
</Object>
Authentication configuration
PHP authentication cannot be used with any other authentication. ALL
AUTHENTICATION IS
PASSED TO YOUR PHP SCRIPT. To configure PHP Authentication for the entire server,
add
the following line:
<Object name="default">
AuthTrans fn=php4_auth_trans
.
.
.
.
</Object>
To use PHP Authentication on a single directory, add the following:
<Object ppath="d:\path\to\authenticated\dir\*">
AuthTrans fn=php4_auth_trans
</Object>
</programlisting>
</example>
</sect1>
<sect1 id="install.omnihttpd">
<title>Servers-OmniHTTPd Server</title>
<para>
This section contains notes and hints specific to OmniHTTPd.
</para>
<sect2 id="install.omnihttpd.windows">
<title>OmniHTTPd 2.0b1 and up for Windows</title>
<simpara>
This has got to be the easiest config there is:
</simpara>
<para>
<itemizedlist>
<listitem>
<para>
Step 1: Install OmniHTTPd server.
</para>
</listitem>
<listitem>
<para>
Step 2: Right click on the blue OmniHTTPd icon in the system
tray and select <literal>Properties</literal>
</para>
</listitem>
<listitem>
<para>
Step 3: Click on <literal>Web Server Global Settings</literal>
</para>
</listitem>
<listitem>
<para>
Step 4: On the 'External' tab, enter: <literal>virtual = .php
| actual = c:\path-to-php-dir\php.exe</literal>, and use the Add
button.
</para>
</listitem>
<listitem>
<para>
Step 5: On the <literal>Mime</literal> tab, enter:
<literal>virtual = wwwserver/stdcgi | actual = .php</literal>,
and use the Add button.
</para>
</listitem>
<listitem>
<para>
Step 6: Click <literal>OK</literal>
</para>
</listitem>
</itemizedlist>
</para>
<simpara>
Repeat steps 2 - 6 for each extension you want to associate with PHP.
</simpara>
<note>
<para>
Some OmniHTTPd packages come with built in PHP support.
You can choose at setup time to do a custom setup, and
uncheck the PHP component. We recommend you to use the latest
PHP binaries. Some OmniHTTPd servers come with PHP 4 beta
distributions, so you should choose not to set up
the built in support, but install your own. If the server
is already on your machine, use the Replace button in Step
4 and 5 to set the new, correct information.
</para>
</note>
</sect2>
</sect1>
<sect1 id="install.oreilly">
<title>Servers-Oreilly Website Pro</title>
<para>
This section contains notes and hints specific to Oreilly
Website Pro.
</para>
<sect2 id="install.oreilly.windows">
<title>Oreilly Website Pro 2.5 and up for Windows</title>
<simpara>
This list describes how to set up the PHP CGI binary
or the ISAPI module to work with Oreilly Website Pro
on Windows.
</simpara>
<para>
<itemizedlist>
<listitem>
<para>
Edit the Server Properties and select the tab "Mapping".
</para>
</listitem>
<listitem>
<para>
From the List select "Associations" and enter the desired
extension (".php") and the path to the CGI exe
(ex. c:\php\php.exe) or the ISAPI dll file
(ex. c:\php\sapi\php4isapi.dll).
</para>
</listitem>
<listitem>
<para>
Select "Content Types" add the same extension ".php"
and enter the content type. If you choose the CGI exe
file, enter 'wwwserver/shellcgi', if you chosse the
ISAPI module, enter 'wwwserver/isapi' (both without
quotes).
</para>
</listitem>
</itemizedlist>
</para>
</sect2>
</sect1>
<sect1 id="install.xitami">
<title>Servers-Xitami</title>
<para>
This section contains notes and hints specific to Xitami.
</para>
<sect2 id="install.xitami.windows">
<title>Xitami for Windows</title>
<simpara>
This list describes how to set up the PHP CGI binary
to work with Xitami on Windows.
</simpara>
<para>
<itemizedlist>
<listitem>
<para>
Make sure the webserver is running, and point
your browser to xitamis admin console
(usually http://127.0.0.1/admin), and click on
Configuration.
</para>
</listitem>
<listitem>
<para>
Navigate to the Filters, and put the
extension which php should parse (i.e. .php)
into the field File extensions (.xxx).
</para>
</listitem>
<listitem>
<para>
In Filter command or script put the path and name
of your php executable i.e. c:\php\php.exe.
</para>
</listitem>
<listitem>
<para>
Press the 'Save' icon.
</para>
</listitem>
</itemizedlist>
</para>
</sect2>
</sect1>
<sect1 id="install.otherhttpd">
<title>Servers-Other web servers</title>
<para>
PHP can be built to support a large number of web servers. Please
see <link linkend="install.configure.servers">Server-related
options</link> for a full list of server-related configure
options. The PHP CGI binaries are compatible with almost all
webservers supporting the CGI interface.
</para>
</sect1>
<sect1 id="install-problems">
<title>Problems?</title>
<sect2>
<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>
</simpara>
</sect2>
<sect2 id="install.otherproblems">
<title>Other problems</title>
<simpara>
If you are still stuck, someone on the PHP installation mailing list may be
able to help you. You should check out the archive first, in 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 installation
mailing list, send an empty mail to <ulink
url="mailto:&email.php.install.subscribe;">&email.php.install.subscribe;</ulink>.
The mailing list address is
<literal>&email.php.install;</literal>.
</simpara>
<simpara>
If you want to get help on the mailing list, please try to be
precise and give the necessary details about your environment
(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.
</simpara>
</sect2>
<sect2 id="install.bugreports">
<title>Bug reports</title>
<simpara>
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>.
</simpara>
<simpara>
Read the <ulink
url="&url.php.bugdosdonts;">Bugs-Dos-And-Donts</ulink>
before submitting any bug reports!
</simpara>
</sect2>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
Index: phpdoc/hk/chapters/intro.xml
+++ phpdoc/hk/chapters/intro.xml
<chapter id="introduction">
<title>引言</title>
<sect1 id="intro-whatis">
<title>PHP 是什麼 ?</title>
<simpara>
PHP (官方名稱 "PHP: Hypertext Preprocessor") 是一種包含在 HTML
文件中在伺服上運行的解釋器語言。
</simpara>
<para>
這個答案高深莫測， 到底是什麼意思呢 ? 看下面的示範 :
</para>
<para>
<example>
<title>簡單例子</title>
<programlisting role="php">
<html>
<head>
<title>Example</title>
</head>
<body>
<?php
echo "Hi, I'm a PHP script!";
?>
</body>
</html>
</programlisting>
</example>
</para>
<para>
比較一下上面的例子和一般用 Perl、 C 等所 寫的 CGI 程式， 你會發現它異常的簡單。
那些用來輸出 HTML 文本的長篇大論的指令不見了， 取而代之的 是嵌入在 HTML
文件中的程式碼。這些程式碼會執行特定的工作，如上例便是打出一行文字。 PHP
的程式語句必須用指定的
開始/結束標籤
</para>
<para>
包起來以便和真的 HTML 內容分開。 支授 PHP 的伺服器會把 PHP
類文件送給解釋器，解釋器再依標籤過瀘出 PHP 文件中含程式指令的部分來執行。
最後伺服器把運算結果和本來的 HTML 部分一併送到客戶端去。 </para>
</sect1>
<sect1 id="intro-whatcando">
<title>PHP 可以做什麼 ?</title>
<para>
在最低的要求下， PHP 可以完成所有 CGI 程式的工作。 比如收取表單上的資料，
自動按情況產生 HTML 頁面或者收送 COOKIES。
</para>
<para>
不過 PHP 最吸引人的地方是它支授極多類型的資料庫軟件。
用它來寫作支授資料庫的網頁簡直比吃菜還容易。 PHP 目前支授的資料庫包括:
<blockquote>
<simplelist columns="3">
<member>Adabas D</member>
<member>dBase</member>
<member>Empress</member>
<member>FilePro (read-only)</member>
<member>Hyperwave</member>
<member>IBM DB2</member>
<member>Informix</member>
<member>Ingres</member>
<member>InterBase</member>
<member>FrontBase</member>
<member>mSQL</member>
<member>Direct MS-SQL</member>
<member>MySQL</member>
<member>ODBC</member>
<member>Oracle (OCI7 and OCI8)</member>
<member>Ovrimos</member>
<member>PostgreSQL</member>
<member>Solid</member>
<member>Sybase</member>
<member>Velocis</member>
<member>Unix dbm</member>
</simplelist>
</blockquote>
</para>
<para>
除此之外， PHP 也可通過 IMAP、 SNMP、 NNTP、 POP3 甚至 HTTP
等的通訊協定來和別的網上服務相連。 就算是連接到低層的網絡接口 SOCKET
等也有相應的通訊協定可用。 </para>
<!--
<figure>
<title>內部結構</title>
<graphic fileref="../images/php3_internal_structure.gif"/>
</figure>
<figure>
<title>建立連接的規則</title>
<graphic fileref="../images/php3_request_scheme.gif"/>
</figure>
-->
</sect1>
<sect1 id="intro-history">
<title>PHP 的故事</title>
<simpara>
PHP 的概念是 1994 秋天由 &link.rasmus; 想出來的。
PHP was conceived sometime in the fall of 1994 by &link.rasmus;.
Early non-released versions were used on his home page to keep
track of who was looking at his online resume. The first version
used by others was available sometime in early 1995 and was known
as the Personal Home Page Tools. It consisted of a very
simplistic parser engine that only understood a few special macros
and a number of utilities that were in common use on home pages
back then. A guestbook, a counter and some other stuff. The
parser was rewritten in mid-1995 and named PHP/FI Version 2. The
FI came from another package Rasmus had written which interpreted
html form data. He combined the Personal Home Page tools scripts
with the Form Interpreter and added mSQL support and PHP/FI was
born. PHP/FI grew at an amazing pace and people started
contributing code to it.
</simpara>
<simpara>
It is difficult to give any hard statistics, but it is estimated
that by late 1996 PHP/FI was in use on at least 15,000 web sites
around the world. By mid-1997 this number had grown to over
50,000. Mid-1997 also saw a change in the development of PHP. It
changed from being Rasmus' own pet project that a handful of
people had contributed to, to being a much more organized team
effort. The parser was rewritten from scratch by Zeev Suraski and
Andi Gutmans and this new parser formed the basis for PHP Version
3. A lot of the utility code from PHP/FI was ported over to PHP 3
and a lot of it was completely rewritten.
</simpara>
<simpara>
The latest version (PHP 4) uses the <ulink
url="&url.zend;">Zend</ulink> scripting engine to deliver higher
performance, supports an even wider array of third-party libraries
and extensions, and runs as a native server module with all of the
popular web servers.
</simpara>
<simpara>
Today (1/2001) PHP 3 or PHP 4 now ships with a number of
commercial products such as Red Hat's Stronghold web server.
A conservative estimate based on an extrapolation from
numbers provided by <ulink url="&url.netcraft;">Netcraft</ulink>
(see also <ulink url="&url.netcraft-survey;">Netcraft Web Server
Survey</ulink>) would be that PHP is in use on over 5,100,000
sites around the world. To put that in perspective, that is
slightly more sites than run Microsoft's IIS server on the Internet
(5.03 million).
</simpara>
<!--
<figure>
<title>NetCraft Webserver Survey</title>
<graphic fileref="&url.php.stats;"/>
</figure>
-->
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
Index: phpdoc/hk/chapters/security.xml
+++ phpdoc/hk/chapters/security.xml
<chapter id="security">
<title>Security</title>
<simpara>
PHP is a powerful language and the interpreter, whether included
in a web server as a module or executed as a separate
<acronym>CGI</acronym> binary, is able to access files, execute
commands and open network connections on the server. These
properties make anything run on a web server insecure by default.
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, and proper coding
practices, it can give you exactly the combination of freedom and
security you need.
</simpara>
<simpara>
As there are many different ways of utilizing PHP, there are many
configuration options controlling its behaviour. A large
selection of options guarantees you can use PHP for a lot of
purposes, but it also means there are combinations of these
options and server configurations that result in an insecure
setup.
</simpara>
<simpara>
The configuration flexibility of PHP is equally rivalled by the
code flexibility. PHP can be used to build complete server
applications, with all the power of a shell user, or it can be used
for simple server-side includes with little risk in a tightly
controlled environment. How you build that environment, and how
secure it is, is largely up to the PHP developer.
</simpara>
<simpara>
This chapter starts by explaining the different configuration
option combinations and the situations they can be safely used. It
then describes different considerations in coding for different
levels of security, and ends with some general security advice.
</simpara>
<sect1 id="security.cgi">
<title>Installed as CGI binary</title>
<sect2 id="security.cgi.attacks">
<title>Possible attacks</title>
<simpara>
Using PHP as a <acronym>CGI</acronym> binary is an option for
setups that for some reason do not wish to integrate PHP as a
module into server software (like Apache), or will use PHP with
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="&url.cert;">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:
</simpara>
<itemizedlist>
<listitem>
<simpara>
Accessing system files: <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.
</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>
</simpara>
<simpara>
The path information part of the url after the PHP binary 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.php</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.php</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.php</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="install.configure.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>
</sect2>
<sect2 id="security.cgi.default">
<title>Case 1: only public files served</title>
<simpara>
If your server does not have any content that is not restricted
by password or ip based access control, there is no need for
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="install.configure.enable-force-cgi-redirect">--enable-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.php</filename>
nor by redirection <filename
role="php">http://my.host/dir/script.php</filename>.
</simpara>
<simpara>
Redirection can be configured in Apache by 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.php</filename>.
Instead, PHP will only parse in this mode if it has gone through
a web server redirect rule.
</simpara>
<simpara>
Usually the redirection in the Apache configuration is done with
the following directives:
</simpara>
<programlisting role="apache-conf">
Action php-script /cgi-bin/php
AddHandler php-script .php
</programlisting>
<simpara>
This option has only been tested with the Apache web server, and
relies on Apache to set the non-standard CGI environment variable
<envar>REDIRECT_STATUS</envar> on redirected requests. 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.
</simpara>
</sect2>
<sect2 id="security.cgi.doc-root">
<title>Case 3: setting doc_root or user_dir</title>
<simpara>
To include active content, like scripts and executables, in the
web server document directories is sometimes consider an insecure
practice. If, because of some configuration mistake, the scripts
are not executed but displayed as regular HTML documents, this
may result in leakage of intellectual property or security
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.
</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.
</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 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).
</simpara>
<simpara>
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.php</filename> does not
result in opening a file under users home directory, but a file
called <filename role="uri">~user/doc.php</filename> under
doc_root (yes, a directory name starting with a tilde
[<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.php</filename> will open a
file called <filename>doc.php</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.php</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.
</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
downside to this option is that you will now have to put a line
similar to:
<informalexample>
<programlisting>
#!/usr/local/bin/php
</programlisting>
</informalexample>
as the first line of any file containing PHP tags. You will also
need to make the file executable. That is, treat it 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.
</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="install.configure.enable-discard-path">--enable-discard-path</link>
configure option.
</para>
</sect2>
</sect1>
<sect1 id="security.apache">
<title>Installed as an Apache module</title>
<simpara>
When PHP is used as an Apache module it inherits Apache's user
permissions (typically those of the "nobody" user). This has several
impacts on security and authorization. For example, if you are using
PHP to access a database, unless that database has built-in access
control, you will have to make the database accessable to the
"nobody" user. This means a malicious script could access and modify
the databse, even without a username and password. It's entirely
possible that a web spider could stumble across a database
adminisitror's web page, and drop all of your databases. You can
protect against this with Apache authorization, or you can design
your own access model using LDAP, .htaccess files, etc. and include
that code as part of your PHP scripts.
</simpara>
<simpara>
Often, once security is established to the point where the PHP user
(in this case, the apache user) has very little risk, it is
discovered that PHP now has been prevented from writing virus files
to user directories. Or perhaps it has been prevented from accessing
or changing a non-public database. It has equally been secured from
writing files that it should, or entering database transactions.
</simpara>
<simpara>
A frequent security mistake made at this point is to allow apache
root permissions.
</simpara>
<simpara>
Escalating the Apache user's permissions to root is extremely
dangerous and may compromise the entire system, so sudo'ing,
chroot'ing ,or otherwise running as root should not be considered by
those who are not security professionals.
</simpara>
</sect1>
<sect1 id="security.filesystem">
<title>Filesystem Security</title>
<simpara>
PHP is subject to the security built into most server systems with
respect to permissions on a file and directory basis. This allows
you to control which files in the filesystem may be read. Care
should be taken with any files which are world readable to ensure
that they are safe for reading by all users who have access to that
filesystem.
</simpara>
<simpara>
Since PHP was designed to allow user level access to the filesystem,
it's entirely possible to write a PHP script that will allow you
to read system files such as /etc/password, modify your ethernet
connections, send massive printer jobs out, etc. This has some
obvious implications, in that you need to ensure that the files
that you read from and write to are the appropriate ones.
</simpara>
<simpara>
Consider the following script, where a user indicates that they'd
like to delete a file in their home directory. This assumes a
situation where a PHP web interface is regularly used for file
management, so the Apache user is allowed to delete files in
the user home directories.
</simpara>
<para>
<example>
<title>Poor variable checking leads to....</title>
<programlisting role="php">
<?php
// remove a file from the user's home directory
$username = $user_submitted_name;
$homedir = "/home/$username";
$file_to_delete = "$userfile";
unlink ($homedir/$userfile);
echo "$file_to_delete has been deleted!";
?>
</programlisting>
</example>
Since the username is postable from a user form, they can submit
a username and file belonging to someone else, and delete files.
In this case, you'd want to use some other form of authentication.
Consider what could happen if the variables submitted were
"../etc/" and "passwd". The code would then effectively read:
<example>
<title>... A filesystem attack</title>
<programlisting role="php">
<?php
// removes a file from anywhere on the hard drive that
// the PHP user has access to. If PHP has root access:
$username = "../etc/";
$homedir = "/home/../etc/";
$file_to_delete = "passwd";
unlink ("/home/../etc/passwd");
echo "/home/../etc/passwd has been deleted!";
?>
</programlisting>
</example>
There are two important measures you should take to prevent these
issues.
<itemizedlist>
<listitem>
<simpara>
Only allow limited permissions to the PHP web user binary.
</simpara>
</listitem>
<listitem>
<simpara>
Check all variables which are submitted.
</simpara>
</listitem>
</itemizedlist>
Here is an improved script:
<example>
<title>More secure file name checking</title>
<programlisting role="php">
<?php
// removes a file from the hard drive that
// the PHP user has access to.
$username = $HTTP_REMOTE_USER; // use an authentication mechanisim
$homedir = "/home/$username";
$file_to_delete = basename("$userfile"); // strip paths
unlink ($homedir/$file_to_delete);
$fp = fopen("/home/logging/filedelete.log","+a"); //log the deletion
$logstring = "$HTTP_REMOTE_USER $homedir $file_to_delete";
fputs ($fp, $logstring);
fclose($fp);
echo "$file_to_delete has been deleted!";
?>
</programlisting>
</example>
Alternately, you may prefer to write a more customized check:
<example>
<title>More secure file name checking</title>
<programlisting role="php">
<?php
$username = getenv("REMOTE_USER");
$homedir = "/home/$username";
if (!ereg('^[^./][^/]*$', $userfile))
die('bad filename'); //die, do not process
//etc...
?>
</programlisting>
</example>
Depending on your operating system, there are a wide variety of files
which you should be concerned about, including device entries (/dev/
or COM1), configuration files (/etc/ files and the .ini files),
well known file storage areas (/home/, My Documents), etc. For this
reason, it's usually easier to create a policy where you forbid
everything except for what you explicitly allow.
</para>
</sect1>
<sect1 id="security.errors">
<title>Error Reporting</title>
<simpara>
A standard attack tactic involves profiling a system by feeding
it improper data, and checking for the kinds, and contexts, of the
errors which are returned. This allows the system cracker to probe
for information about the server, to determine possible weaknesses.
</simpara>
<simpara>
The PHP errors which are normally returned can be quite helpful to a
developer who is trying to debug a script, indicating such things
as the function or file that failed, the PHP file it failed in,
and the line number which the failure occured in. This is all
information that can be exploited. It is not uncommon for a php
developer to use <function>show_source</function>,
<function>highlight_string</function>, or
<function>highlight_file</function> as a debugging measure, but in
a live site, this can expose hidden variables, unchecked syntax,
and other dangerous information.
</simpara>
<simpara>
For example, the very style of a generic error indicates a system
is running PHP. If the attacker was looking at an .html page, and
wanted to probe for the back-end (to look for known weaknesses in
the system), by feeding it the wrong data they may be able to
determine that a system was built with PHP.
</simpara>
<simpara>
A function error can indicate whether a system may be running a
specific database engine, or give clues as to how a web page or
programmed or designed. This allows for deeper investigation into
open database ports, or to look for specific bugs or weaknesses
in a web page. By feeding different pieces of bad data, for example,
an attacker can determine the order of authentication in a script,
(from the line number errors) as well as probe for exploits that
may be exploited in different locations in the script.
</simpara>
<simpara>
A filesystem or general PHP error can indicate what permissions
the webserver has, as well as the structure and organization of
files on the web server. Developer written error code can aggravate
this problem, leading to easy exploitation of formerly "hidden"
information.
</simpara>
<simpara>
There are three major solutions to this issue. The first is to
scrutinize all functions, and attempt to compensate for the bulk
of the errors. The second is to disable error reporting entirely
on the running code. The third is to use PHP's custom error
handling functions to create your own error handler. Depending
on your security policy, you may find all three to be applicable
to your situation.
</simpara>
</sect1>
<sect1 id="security.variables">
<title>User Submitted Data</title>
<para>
The greatest weakness in many PHP programs is not inherent in the
language itself, but merely an issue of code not being written with
security in mind. For this reason, you should always take the time
to consider the implications of a given piece of code, to ascertain
the possible damage if an unexpected variable is submitted to it.
<example>
<title>Dangerous Variable Usage</title>
<programlisting role="php">
<?php
// remove a file from the user's home directory... or maybe
// somebody else's?
unlink ($evil_var);
// Write logging of their access... or maybe not?
fputs ($fp, $evil_var);
// Execute something trivial.. or rm -rf *?
system ($evil_var);
exec ($evil_var);
?>
</programlisting>
</example>
You should always carefully examine your code to make sure that any
variables being submitted from a web browser are being properly
checked, and ask yourself the following questions:
<itemizedlist>
<listitem>
<simpara>
Will this script only affect the intended files?
</simpara>
</listitem>
<listitem>
<simpara>
Can unusual or undesirable data be acted upon?
</simpara>
</listitem>
<listitem>
<simpara>
Can this script be used in unintended ways?
</simpara>
</listitem>
<listitem>
<simpara>
Can this be used in conjunction with other scripts in a negative
manner?
</simpara>
</listitem>
<listitem>
<simpara>
Will any transactions be adequately logged?
</simpara>
</listitem>
</itemizedlist>
By adequately asking these questions while writing the script,
rather than later, you prevent an unfortunate re-write when you
need to increase your security. By starting out with this mindset,
you won't guarantee the security of your system, but you can help
improve it.
</para>
<para>
You may also want to consider turning off register_globals,
magic_quotes, or other convenience settings which may confuse
you as to the validity, source, or value of a given variable.
Working with PHP in error_reporting(E_ALL) mode can also help warn
you about variables being used before they are checked or
initialized (so you can prevent unusual data from being
operated upon).
</para>
</sect1>
<sect1 id="security.general">
<title>General considerations</title>
<simpara>
A completely secure system is a virtual impossibility, so an
approach often used in the security profession is one of balancing
risk and usability. If every variable submitted by a user required
two forms of biometric validation (such as a retinal scan and a
fingerprint), you would have an extremely high level of
accountability. It would also take half an hour to fill out a fairly
complex form, which would tend to encourage users to find ways of
bypassing the security.
</simpara>
<simpara>
The best security is often inobtrusive enough to suit the
requirements without the user being prevented from accomplishing
their work, or over-burdening the code author with excessive
complexity. Indeed, some security attacks are merely exploits of
this kind of overly built security, which tends to erode over time.
</simpara>
<simpara>
A phrase worth remembering: A system is only as good as the weakest
link in a chain. If all transactions are heavily logged based on
time, location, transaction type, etc. but the user is only
verified based on a single cookie, the validity of tying the users
to the transaction log is severely weakened.
</simpara>
<simpara>
When testing, keep in mind that you will not be able to test all
possibilities for even the simplest of pages. The input you
may expect will be completely unrelated to the input given by
a disgruntled employee, a cracker with months of time on their
hands, or a housecat walking across the keyboard. This is why it's
best to look at the code from a logical perspective, to discern
where unexpected data can be introduced, and then follow how it is
modified, reduced, or amplified.
</simpara>
<simpara>
The Internet is filled with people trying to make a name for
themselves by breaking your code, crashing your site, posting
inappropriate content, and otherwise making your day interesting.
It doesn't matter if you have a small or large site, you are
a target by simply being online, by having a server that can be
connected to. Many cracking programs do not discern by size, they
simply trawl massive IP blocks looking for victims. Try not to
become one.
</simpara>
</sect1>
<sect1 id="security.current">
<title>Keeping Current</title>
<simpara>
PHP, like any other large system, is under constant scrutiny and
improvement. Each new version will often include both major and
minor changes to enhance and repair security flaws, configuration
mishaps, and other issues that will affect the overall security
and stability of your system.
</simpara>
<simpara>
Like other system-level scripting languages and programs, the best
approach is to update often, and maintain awareness of the latest
versions and their changes.
</simpara>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
Index: phpdoc/hk/features/connection-handling.xml
+++ phpdoc/hk/features/connection-handling.xml
<chapter id="features.connection-handling">
<title>Connection handling</title>
<note>
<para>The following applies to 3.0.7 and later.</para>
</note>
<para>
Internally in PHP a connection status is maintained. There are 3
possible states:
<itemizedlist>
<listitem><simpara>0 - NORMAL</simpara></listitem>
<listitem><simpara>1 - ABORTED</simpara></listitem>
<listitem><simpara>2 - TIMEOUT</simpara></listitem>
</itemizedlist>
</para>
<simpara>
When a PHP script is running normally the NORMAL state, is active.
If the remote client disconnects the ABORTED state flag is
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.</simpara>
<simpara>
You can decide whether or not you want a client disconnect to cause
your script to be aborted. Sometimes it is handy to always have your
scripts run to completion even if there is no remote browser receiving
the output. The default behaviour is however for your script to be
aborted when the remote client disconnects. This behaviour can be
set via the ignore_user_abort php3.ini directive as well as through
the corresponding php3_ignore_user_abort Apache .conf directive or
with the <function>ignore_user_abort</function> function. If you do
not tell PHP to ignore a user abort and the user aborts, your script
will terminate. The one exception is if you have registered a shutdown
function using <function>register_shutdown_function</function>. With a
shutdown function, when the remote user hits his STOP button, the
next time your script tries to output something PHP will detect that
the connection has been aborted and the shutdown function is called.
This shutdown function will also get called at the end of your script
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.</simpara>
<simpara>
Your script can also be terminated by the built-in script timer.
The default timeout is 30 seconds. It can be changed using
the max_execution_time php3.ini directive or the corresponding
php3_max_execution_time Apache .conf directive as well as with
the <function>set_time_limit</function> function. When the timer
expires the script will be aborted and as with the above client
disconnect case, if a shutdown function has been registered it will
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.</simpara>
<simpara>
One thing to note is that both the ABORTED and the TIMEOUT states
can be active at the same time. This is possible if you tell
PHP to ignore user aborts. PHP will still note the fact that
a user may have broken the connection, but the script will keep
running. If it then hits the time limit it will be aborted and
your shutdown function, if any, will be called. At this point
you will find that <function>connection_timeout</function>
and <function>connection_aborted</function> return true.
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.</simpara>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
Index: phpdoc/hk/features/cookies.xml
+++ phpdoc/hk/features/cookies.xml
<chapter id="features.cookies">
<title>Cookies</title>
<para>
PHP transparently supports HTTP cookies. 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 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.</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.</para>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
Index: phpdoc/hk/features/error-handling.xml
+++ phpdoc/hk/features/error-handling.xml
<chapter id="features.error-handling">
<title>Error Handling</title>
<para>
There are several types of errors and warnings in PHP. They are:
<table>
<title>PHP error types</title>
<tgroup cols="4">
<thead>
<row>
<entry>Value</entry>
<entry>Constant</entry>
<entry>Description</entry>
<entry>Note</entry>
</row>
</thead>
<tbody>
<row>
<entry>1</entry>
<entry>E_ERROR</entry>
<entry>fatal run-time errors</entry>
<entry></entry>
</row>
<row>
<entry>2</entry>
<entry>E_WARNING</entry>
<entry>run-time warnings (non fatal errors)</entry>
<entry></entry>
</row>
<row>
<entry>4</entry>
<entry>E_PARSE</entry>
<entry>compile-time parse errors</entry>
<entry></entry>
</row>
<row>
<entry>8</entry>
<entry>E_NOTICE </entry>
<entry>
run-time notices (less serious than warnings)
</entry>
<entry></entry>
</row>
<row>
<entry>16</entry>
<entry>E_CORE_ERROR</entry>
<entry>fatal errors that occur during PHP's initial startup</entry>
<entry>PHP 4 only</entry>
</row>
<row>
<entry>32</entry>
<entry>E_CORE_WARNING</entry>
<entry>
warnings (non fatal errors) that occur during PHP's initial
startup
</entry>
<entry>PHP 4 only</entry>
</row>
<row>
<entry>64</entry>
<entry>E_COMPILE_ERROR</entry>
<entry>fatal compile-time errors</entry>
<entry>PHP 4 only</entry>
</row>
<row>
<entry>128</entry>
<entry>E_COMPILE_WARNING</entry>
<entry>compile-time warnings (non fatal errors)</entry>
<entry>PHP 4 only</entry>
</row>
<row>
<entry>256</entry>
<entry>E_USER_ERROR</entry>
<entry>user-generated error message</entry>
<entry>PHP 4 only</entry>
</row>
<row>
<entry>512</entry>
<entry>E_USER_WARNING</entry>
<entry>user-generated warning message</entry>
<entry>PHP 4 only</entry>
</row>
<row>
<entry>1024</entry>
<entry>E_USER_NOTICE </entry>
<entry>user-generated notice message</entry>
<entry>PHP 4 only</entry>
</row>
<row>
<entry></entry>
<entry>E_ALL</entry>
<entry>all of the above, as supported</entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
The above values (either numerical or symbolic) are used to build
up a bitmask that specifies which errors to report. You can use the
<link linkend="language.operators.bitwise">bitwise operators</link>
to combine these values or mask out certain types of errors. Note
that only '|', '~', '!', and '&' will be understood within
<filename>php.ini</filename>, however, and that no bitwise
operators will be understood within <filename>php3.ini</filename>.
</para>
<para>
In PHP 4, the default <link
linkend="ini.error-reporting">error_reporting</link> setting is
<literal>E_ALL & ~E_NOTICE</literal>, meaning to display all errors
and warnings which are not E_NOTICE-level. In PHP 3, the default
setting is <literal>(E_ERROR | E_WARNING | E_PARSE)</literal>,
meaning the same thing. Note, however, that since constants are not
supported in PHP 3's <filename>php3.ini</filename>, the <link
linkend="ini.error-reporting">error_reporting</link> setting there
must be numeric; hence, it is <literal>7</literal>.
</para>
<para>
The initial setting can be changed in the ini file with the <link
linkend="ini.error-reporting">error_reporting</link> directive, in
your Apache <filename>httpd.conf</filename> file with the
php_error_reporting (php3_error_reporting for PHP 3) directive, and
lastly it may be set at runtime within a script by using the
<function>error_reporting</function> function.
</para>
<warning>
<para>
When upgrading code or servers from PHP 3 to PHP 4 you should
check these settings and calls to
<function>error_reporting</function> or you might disable
reporting the new error types, especially E_COMPILE_ERROR. This
may lead to empty documents without any feedback of what happened
or where to look for the problem.
</para>
</warning>
<para>
All <link linkend="language.expressions">PHP expressions</link> can
also be called with the "@" prefix, which turns off error reporting
for that particular 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
<literal>$php_errormsg</literal>.
</para>
<note>
<para>
The <link linkend="language.operators.errorcontrol">@
error-control operator</link> prefix will not disable messages
that are the result of parse errors.
</para>
</note>
<warning>
<para>
Currently the <link linkend="language.operators.errorcontrol">@
error-control operator</link> prefix will even disable error
reporting for critical errors that will terminate script
execution. Among other things, this means that if you use <link
linkend="language.operators.errorcontrol">@</link> to suppress
errors from a certain function and either it isn't available or
has been mistyped, the script will die right there with no
indication as to why.
</para>
</warning>
<para>
Below we can see an example of using the error handling capabilities in
PHP. We define a error handling function which logs the information into
a file (using an XML format), and e-mails the developer in case a critical
error in the logic happens.
<example>
<title>Using error handling in a script</title>
<programlisting role="php">
<?php
// we will do our own error handling
error_reporting(0);
// user defined error handling function
function userErrorHandler ($errno, $errmsg, $filename, $linenum, $vars) {
// timestamp for the error entry
$dt = date("Y-m-d H:i:s (T)");
// define an assoc array of error string
// in reality the only entries we should
// consider are 2,8,256,512 and 1024
$errortype = array (
1 => "Error",
2 => "Warning",
4 => "Parsing Error",
8 => "Notice",
16 => "Core Error",
32 => "Core Warning",
64 => "Compile Error",
128 => "Compile Warning",
256 => "User Error",
512 => "User Warning",
1024=> "User Notice"
);
// set of errors for which a var trace will be saved
$user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE);
$err = "<errorentry>\n";
$err .= "\t<datetime>".$dt."</datetime>\n";
$err .= "\t<errornum>".$errno."</errnumber>\n";
$err .=
"\t<errortype>".$errortype[$errno]."</errortype>\n";
$err .= "\t<errormsg>".$errmsg."</errormsg>\n";
$err .=
"\t<scriptname>".$filename."</scriptname>\n";
$err .=
"\t<scriptlinenum>".$linenum."</scriptlinenum>\n";
if (in_array($errno, $user_errors))
$err .=
"\t<vartrace>".wddx_serialize_value($vars,"Variables")."</vartrace>\n";
$err .= "</errorentry>\n\n";
// for testing
// echo $err;
// save to the error log, and e-mail me if there is a critical user error
error_log($err, 3, "/usr/local/php4/error.log");
if ($errno == E_USER_ERROR)
mail("[EMAIL PROTECTED]","Critical User Error",$err);
}
function distance ($vect1, $vect2) {
if (!is_array($vect1) || !is_array($vect2)) {
trigger_error("Incorrect parameters, arrays expected", E_USER_ERROR);
return NULL;
}
if (count($vect1) != count($vect2)) {
trigger_error("Vectors need to be of the same size", E_USER_ERROR);
return NULL;
}
for ($i=0; $i<count($vect1); $i++) {
$c1 = $vect1[$i]; $c2 = $vect2[$i];
$d = 0.0;
if (!is_numeric($c1)) {
trigger_error("Coordinate $i in vector 1 is not a number, using
zero",
E_USER_WARNING);
$c1 = 0.0;
}
if (!is_numeric($c2)) {
trigger_error("Coordinate $i in vector 2 is not a number, using
zero",
E_USER_WARNING);
$c2 = 0.0;
}
$d += $c2*$c2 - $c1*$c1;
}
return sqrt($d);
}
$old_error_handler = set_error_handler("userErrorHandler");
// undefined constant, generates a warning
$t = I_AM_NOT_DEFINED;
// define some "vectors"
$a = array(2,3,"foo");
$b = array(5.5, 4.3, -1.6);
$c = array (1,-3);
// generate a user error
$t1 = distance($c,$b)."\n";
// generate another user error
$t2 = distance($b,"i am not an array")."\n";
// generate a warning
$t3 = distance($a,$b)."\n";
?>
</programlisting>
</example>
This is just a simple example showing how to use the
<link linkend="ref.errorfunc">Error Handling and Logging
functions</link>.
</para>
<para>
See also <function>error_reporting</function>,
<function>error_log</function>,
<function>set_error_handler</function>,
<function>restore_error_handler</function>,
<function>trigger_error</function>,
<function>user_error</function>
</para>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
Index: phpdoc/hk/features/file-upload.xml
+++ phpdoc/hk/features/file-upload.xml
<chapter id="features.file-upload">
<title>Handling file uploads</title>
<sect1 id="features.file-upload.post-method">
<title>POST method uploads</title>
<simpara>
PHP is capable of receiving file uploads from any RFC-1867
compliant browser (which includes Netscape Navigator 3 or later,
Microsoft Internet Explorer 3 with a patch from Microsoft, or
later without a patch). This feature lets people upload both text
and binary files. With PHP's authentication and file manipulation
functions, you have full control over who is allowed to upload and
what is to be done with the file once it has been uploaded.
</simpara>
<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.
</para>
<para>
A file upload screen can be built by creating a special form which
looks something like this:
<example>
<title>File Upload Form</title>
<programlisting>
<FORM ENCTYPE="multipart/form-data" ACTION="_URL_"
METHOD=POST>
<INPUT TYPE="hidden" name="MAX_FILE_SIZE"
value="1000">
Send this file: <INPUT NAME="userfile" TYPE="file">
<INPUT TYPE="submit" VALUE="Send File">
</FORM>
</programlisting>
</example>
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.
</para>
<para>
In PHP 3, the following variables will be defined within the
destination script upon a successful upload, assuming that <link
linkend="ini.register-globals">register_globals</link> is turned
on in <filename>php3.ini</filename>. If <link
linkend="ini.track-vars">track_vars</link> is turned on, they will
also be available in PHP 3 within the global array
<varname>$HTTP_POST_VARS</varname>. Note that the following
variable names assume the use of the file upload name 'userfile',
as used in the example above:
<itemizedlist>
<listitem>
<simpara>
<varname>$userfile</varname> - The temporary filename in which
the uploaded file was stored on the server machine.
</simpara>
</listitem>
<listitem>
<simpara>
<varname>$userfile_name</varname> - The original name or path
of the file on the sender's system.
</simpara>
</listitem>
<listitem>
<simpara>
<varname>$userfile_size</varname> - The size of the uploaded
file in bytes.
</simpara>
</listitem>
<listitem>
<simpara>
<varname>$userfile_type</varname> - The mime type of the file
if the browser provided this information. An example would be
"image/gif".
</simpara>
</listitem>
</itemizedlist>
Note that the "$userfile" 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
"userfile"
</para>
<para>
In PHP 4, the behaviour is slightly different, in that the new
global array <varname>$HTTP_POST_FILES</varname> is provided to
contain the uploaded file information. This is still only
available if <link linkend="ini.track-vars">track_vars</link> is
turned on, but <link linkend="ini.track-vars">track_vars</link> is
always turned on in versions of PHP after PHP 4.0.2.
</para>
<para>
The contents of <varname>$HTTP_POST_FILES</varname> are as
follows. Note that this assumes the use of the file upload name
'userfile', as used in the example above:
<variablelist>
<varlistentry>
<term><varname>$HTTP_POST_FILES['userfile']['name']</varname></term>
<listitem>
<para>
The original name of the file on the client machine.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>$HTTP_POST_FILES['userfile']['type']</varname></term>
<listitem>
<para>
The mime type of the file, if the browser provided this
information. An example would be
<literal>"image/gif"</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>$HTTP_POST_FILES['userfile']['size']</varname></term>
<listitem>
<para>
The size, in bytes, of the uploaded file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>$HTTP_POST_FILES['userfile']['tmp_name']</varname></term>
<listitem>
<para>
The temporary filename of the file in which the uploaded file
was stored on the server.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Files will by default be stored in the server's default temporary
directory, unless another location has been given with the <link
linkend="ini.upload-tmp-dir">upload_tmp_dir</link> directive in
<filename>php.ini</filename>. The server's default directory 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. This environment variable can also be used
to make sure that other operations are working on uploaded files,
as well.
<example>
<title>Validating file uploads</title>
<para>
The following examples are for versions of PHP 3 greater than
3.0.16, and versions of PHP 4 greater than 4.0.2. See the
function entries for <function>is_uploaded_file</function> and
<function>move_uploaded_file</function>.
</para>
<programlisting role="php">
<?php
if (is_uploaded_file($userfile)) {
copy($userfile, "/place/to/put/uploaded/file");
} else {
echo "Possible file upload attack: filename '$userfile'.";
}
/* ...or... */
move_uploaded_file($userfile, "/place/to/put/uploaded/file");
?>
</programlisting>
<para>
For earlier versions of PHP, you'll need to do something like
the following.
<note>
<para>
This will <emphasis>not</emphasis> work in versions of PHP 4
after 4.0.2. It depends on internal functionality of PHP which
changed after that version.
</para>
</note>
</para>
<programlisting role="php">
<?php
/* Userland test for uploaded file. */
function is_uploaded_file($filename) {
if (!$tmp_file = get_cfg_var('upload_tmp_dir')) {
$tmp_file = dirname(tempnam('', ''));
}
$tmp_file .= '/' . basename($filename);
/* User might have trailing slash in php.ini... */
return (ereg_replace('/+', '/', $tmp_file) == $filename);
}
if (is_uploaded_file($userfile)) {
copy($userfile, "/place/to/put/uploaded/file");
} else {
echo "Possible file upload attack: filename '$userfile'.";
}
?>
</programlisting>
</example>
</para>
<simpara>
The PHP script which receives the uploaded file should implement
whatever logic is necessary for determining what should be done
with the uploaded file. You can for example use the
<varname>$file_size</varname> variable to throw away any files
that are either too small or too big. You could use the
<varname>$file_type</varname> 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.
</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.
</simpara>
</sect1>
<sect1 id="features.file-upload.common-pitfalls">
<title>Common Pitfalls</title>
<simpara>
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 PHP 3.ini file
or the corresponding php3_upload_max_filesize Apache .conf directive.
The default is 2 Megabytes.
</simpara>
<simpara>
Not validating which file you operate on may mean that users can access
sensitive information in other directories.
</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.
</simpara>
</sect1>
<sect1 id="feature-fileupload.multiple">
<title>Uploading multiple files</title>
<simpara>
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:
</simpara>
<note>
<para>
Support for multiple file uploads was added in version 3.0.10.
</para>
</note>
<para>
<example>
<title>Uploading multiple files</title>
<programlisting>
<form action="file-upload.php" method="post"
enctype="multipart/form-data">
Send these files:<br>
<input name="userfile[]" type="file"><br>
<input name="userfile[]" type="file"><br>
<input type="submit" value="Send files">
</form>
</programlisting>
</example>
</para>
<simpara>
When the above form is submitted, the arrays
<computeroutput>$userfile</computeroutput>,
<computeroutput>$userfile_name</computeroutput>, and
<computeroutput>$userfile_size</computeroutput> will be formed in
the global scope (as well as in $HTTP_POST_FILES ($HTTP_POST_VARS
in PHP 3)). Each of these will be a numerically indexed array of
the appropriate values for the submitted files.
</simpara>
<simpara>
For instance, assume that the filenames
<filename>/home/test/review.html</filename> and
<filename>/home/test/xwp.out</filename> are submitted. In this
case, <computeroutput>$userfile_name[0]</computeroutput> would
contain the value <computeroutput>review.html</computeroutput>,
and <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.
</simpara>
<simpara>
<computeroutput>$userfile['name'][0]</computeroutput>,
<computeroutput>$userfile['tmp_name'][0]</computeroutput>,
<computeroutput>$userfile['size'][0]</computeroutput>, and
<computeroutput>$userfile['type'][0]</computeroutput> are also set.
</simpara>
</sect1>
<sect1 id="features.file-upload.put-method">
<title>PUT method support</title>
<para>
PHP provides support for the HTTP PUT method used by clients such
as Netscape Composer and W3C Amaya. PUT requests are much simpler
than a file upload and they look something like this:
<informalexample>
<programlisting>
PUT /path/filename.html HTTP/1.1
</programlisting>
</informalexample>
</para>
<para>
This would normally mean that the remote client would like to save
the content that follows as: /path/filename.html in your web tree.
It is obviously not a good idea for Apache or PHP to automatically
let everybody overwrite any files in your web tree. So, to handle
such a request you have to first tell your web server that you
want a certain PHP script to handle the request. In Apache you do
this with the <emphasis>Script</emphasis> directive. It can be
placed almost anywhere in your Apache configuration file. A
common place is inside a <Directory> block or perhaps inside
a <Virtualhost> block. A line like this would do the trick:
<informalexample>
<programlisting>
Script PUT /put.php3
</programlisting>
</informalexample>
</para>
<simpara>
This tells Apache to send all PUT requests for URIs that match the
context in which you put this line to the put.php3 script. This
assumes, of course, that you have PHP enabled for the .php3
extension and PHP is active.
</simpara>
<simpara>
Inside your put.php3 file you would then do something like this:
</simpara>
<para>
<informalexample><programlisting>
<?php copy($PHP_UPLOADED_FILE_NAME,$DOCUMENT_ROOT.$REQUEST_URI); ?>
</programlisting></informalexample>
</para>
<simpara>
This would copy the file to the location requested by the remote
client. You would probably want to perform some checks and/or
authenticate the user before performing this file copy. The only
trick here is that when PHP sees a PUT-method request it stores
the uploaded file in a temporary file just like those handled but
the <link
linkend="features.file-upload.post-method">POST-method</link>.
When the request ends, this temporary file is deleted. So, your
PUT handling PHP script has to copy that file somewhere. The
filename of this temporary file is in the $PHP_PUT_FILENAME
variable, and you can see the suggested destination filename in
the $REQUEST_URI (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.
</simpara>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
Index: phpdoc/hk/features/http-auth.xml
+++ phpdoc/hk/features/http-auth.xml
<chapter id="features.http-auth">
<title>HTTP authentication with PHP</title>
<simpara>
The HTTP Authentication hooks in PHP are only available when it is
running as an Apache module and is hence not available in the CGI version.
In an Apache module PHP script, it is possible to use the
<function>Header</function> function to send an "Authentication Required"
message to the client browser causing it to pop up a Username/Password
input window. Once the user has filled in a username and a password,
the URL containing the PHP script will be called again with the variables,
$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.</simpara>
<para>
An example script fragment which would force client authentication
on a page would be the following:
<example>
<title>HTTP Authentication example</title>
<programlisting role="php">
<?php
if(!isset($PHP_AUTH_USER)) {
Header("WWW-Authenticate: Basic realm=\"My Realm\"");
Header("HTTP/1.0 401 Unauthorized");
echo "Text to send if user hits Cancel button\n";
exit;
} else {
echo "Hello $PHP_AUTH_USER.<P>";
echo "You entered $PHP_AUTH_PW as your password.<P>";
}
?>
</programlisting>
</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.</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.</para>
<simpara>
In order to prevent someone from writing a script which reveals
the password for a page that was authenticated through a
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.</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.</simpara>
<simpara>
Both Netscape Navigator 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>
<simpara></simpara>
<example>
<title>HTTP Authentication example forcing a new name/password</title>
<programlisting role="php">
<?php
function authenticate() {
Header( "WWW-authenticate: basic realm=\"Test Authentication
System\"");
Header( "HTTP/1.0 401 Unauthorized");
echo "You must enter a valid login ID and password to access
this resource\n";
exit;
}
if(!isset($PHP_AUTH_USER) || ($SeenBefore == 1 && !strcmp($OldAuth,
$PHP_AUTH_USER)) ) {
authenticate();
}
else {
echo "Welcome: $PHP_AUTH_USER<BR>";
echo "Old: $OldAuth";
echo "<FORM ACTION=\"$PHP_SELF\" METHOD=POST>\n";
echo "<INPUT TYPE=HIDDEN NAME=\"SeenBefore\"
VALUE=\"1\">\n";
echo "<INPUT TYPE=HIDDEN NAME=\"OldAuth\"
VALUE=\"$PHP_AUTH_USER\">\n";
echo "<INPUT TYPE=Submit VALUE=\"Re
Authenticate\">\n";
echo "</FORM>\n";
}
?>
</programlisting>
</example>
<simpara>
This behavior is not required by the HTTP Basic authentication
standard, so you should never depend on this. Testing with Lynx
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. The user can press the
'_' key to clear their authentication information, however.
</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.
</simpara>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
Index: phpdoc/hk/features/images.xml
+++ phpdoc/hk/features/images.xml
<chapter id="features.images">
<title>Creating and manipulating images</title>
<simpara>
PHP is not limited to creating just HTML output. It can also be
used to create and manipulate image files in a variety of different
image formats, including gif, png, jpg, wbmp, and xpm. Even more
convenient, php can output image streams directly to a browser. You
will need to compile PHP with the GD library of image functions for
this to work. GD and PHP may also require other libraries, depending
on which image formats you want to work with. GD stopped supporting
Gif images in version 1.6.
</simpara>
<para>
<example>
<title>PNG creation with PHP</title>
<programlisting role="php">
<?php
Header("Content-type: image/png");
$string=implode($argv," ");
$im = imageCreateFromPng("images/button1.png");
$orange = ImageColorAllocate($im, 220, 210, 60);
$px = (imagesx($im)-7.5*strlen($string))/2;
ImageString($im,3,$px,9,$string,$orange);
ImagePng($im);
ImageDestroy($im);
?>
</programlisting>
</example>
This example would be called from a page with a tag like: <img
src="button.php?text"> The above button.php script
then takes this "text" string an overlays it on top of a
base image which in this case is "images/button1.png"
and outputs the resulting image. This is a very convenient way to
avoid having to draw new button images every time you want to
change the text of a button. With this method they are
dynamically generated.
</para>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
Index: phpdoc/hk/features/persistent-connections.xml
+++ phpdoc/hk/features/persistent-connections.xml
<chapter id="features.persistent-connections">
<title>Persistent Database Connections</title>
<simpara>
Persistent connections are SQL links that do not close when the
execution of your script ends. When a persistent connection is
requested, PHP checks if there's already an identical persistent
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).
</simpara>
<simpara>
People who aren't thoroughly familiar with the way web servers work
and distribute the load may mistake persistent connects for what
they're not. In particular, they do <emphasis>not</emphasis> give
you an ability to open 'user sessions' on the same SQL link, they
do <emphasis>not</emphasis> give you an ability to build up a
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.
</simpara>
<simpara>
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.
</simpara>
<simpara>
The first method is to use PHP as a CGI "wrapper". When run this
way, an instance of the PHP interpreter is created and destroyed
for every page request (for a PHP page) to your web server.
Because it 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.
</simpara>
<simpara>
The second, and most popular, method is to run PHP as a module in a
multiprocess web server, which currently only includes Apache. A
multiprocess server typically has one process (the parent) which
coordinates a set of processes (its children) who actually do the
work of serving up web pages. When each request comes in from a
client, it is handed off to one of the children that is not already
serving another client. This means that when the same client makes
a second request to the server, it may be serviced by a different
child process than the first time. What a persistent connection
does for you in 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.
</simpara>
<simpara>
The last method is to use PHP as a plug-in for a multithreaded web
server. Currently PHP 4 has support for ISAPI, WSAPI, and NSAPI (on
Windows), which 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. The behavior is essentially
the same as for the multiprocess model described before. Note that
SAPI support is not available in PHP 3.
</simpara>
<simpara>
If persistent connections don't have any added functionality, what
are they good for?
</simpara>
<simpara>
The answer here is extremely simple -- efficiency. Persistent
connections are good if the overhead to create a link to your SQL
server is high. Whether or not this overhead is really high depends
on many factors. Like, what kind of database it is, whether or not
it sits on the same computer on which your web server sits, how
loaded the machine the SQL server sits on is and so forth. The
bottom line is that if that connection overhead is high, persistent
connections help you considerably. They cause the child process to
simply connect only once for its entire lifespan, instead of every
time it processes a page that requires connecting to the SQL
server. This means that for every child that opened a persistent
connection will have its own 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.
</simpara>
<simpara>
Note, however, that this can have some drawbacks if you are using a
database with connection limits that are exceeded by persistant
child connections. If your database has a limit of 16 simultaneous
connections, and in the course of a busy server session, 17 child
threads attempt to connect, one will not be able to. If there are
bugs in your scripts which do not allow the connections to shut
down (such as infinite loops), a database with only 32 connections
may be rapidly swamped. Check your database documentation for
information on handling abandoned or idle connections.
</simpara>
<simpara>
An important summary. Persistent connections were designed to have
one-to-one mapping to regular connections. That means that you
should <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!
</simpara>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
Index: phpdoc/hk/features/remote-files.xml
+++ phpdoc/hk/features/remote-files.xml
<chapter id="features.remote-files">
<title>Using remote files</title>
<para>
As long as support for the "URL fopen wrapper" is enabled when
you configure PHP (which it is unless you explicitly pass the
<option>--disable-url-fopen-wrapper</option> flag to configure (for versions
up to 4.0.3) or set <parameter>allow_url_fopen</parameter> to off in php.ini
(for newer versions),
you can use HTTP and FTP URLs with most functions that take a
filename as a parameter, including the <function>require</function>
and <function>include</function> statements.
</para>
<para>
<note>
<para>
You can't use remote files in <function>include</function> and
<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.
</para>
<para>
<example>
<title>Getting the title of a remote page</title>
<programlisting role="php">
<![CDATA[
<?php
$file = fopen ("http://www.php.net/", "r");
if (!$file) {
echo "<p>Unable to open remote file.\n";
exit;
}
while (!feof ($file)) {
$line = fgets ($file, 1024);
/* This only works if the title and its tags are on one line */
if (eregi ("<title>(.*)</title>", $line, $out)) {
$title = $out[1];
break;
}
}
fclose($file);
?>
]]>
</programlisting>
</example>
</para>
<para>
You can also write to files on an FTP as long you connect as a user
with the correct access rights, and the file doesn't exist already.
To connect as a user other than 'anonymous', you need to specify
the username (and possibly password) within the URL, such as
'ftp://user:[EMAIL PROTECTED]/path/to/file'. (You can use the
same sort of syntax to access files via HTTP when they require Basic
authentication.)
</para>
<para>
<example>
<title>Storing data on a remote server</title>
<programlisting role="php">
<![CDATA[
<?php
$file = fopen ("ftp://ftp.php.net/incoming/outputfile", "w");
if (!$file) {
echo "<p>Unable to open remote file for writing.\n";
exit;
}
/* Write the data here. */
fputs ($file, "$HTTP_USER_AGENT\n");
fclose ($file);
?>
]]>
</programlisting>
</example>
</para>
<para>
<note>
<para>
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>.
</para>
</note>
</para>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
