jan Wed Jun 16 07:11:20 2004 EDT
Modified files:
/phpdoc/en language-snippets.ent
/phpdoc/en/install/unix apache2.xml
Log:
- reorder language snippets
- add Rasmus' explaination about PHP and Apache2
#make test went through fine, it would be neat, though,
#if someone could have a second look at it. Thanks.
http://cvs.php.net/diff.php/phpdoc/en/language-snippets.ent?r1=1.96&r2=1.97&ty=u
Index: phpdoc/en/language-snippets.ent
diff -u phpdoc/en/language-snippets.ent:1.96 phpdoc/en/language-snippets.ent:1.97
--- phpdoc/en/language-snippets.ent:1.96 Fri Jun 11 04:25:38 2004
+++ phpdoc/en/language-snippets.ent Wed Jun 16 07:11:19 2004
@@ -1,4 +1,96 @@
-<!-- $Revision: 1.96 $ -->
+<!-- $Revision: 1.97 $ -->
+<!-- Keep 'em sorted -->
+
+
+<!-- Notes -->
+
+<!ENTITY note.bin-safe '<note><simpara>This function is
+binary-safe.</simpara></note>'>
+
+<!ENTITY note.clearstatcache '<note><simpara>The results of this
+function are cached. See <function>clearstatcache</function> for
+more details.</simpara></note>'>
+
+<!ENTITY note.context-support '<note><simpara>Context support was added
+with <literal>PHP 5.0.0</literal>.</simpara></note>'>
+
+<!ENTITY note.exec-bg '<note><para>If you start a program using this function
+and want to leave it running in the background, you have to make sure that the
+output of that program is redirected to a file or some other output stream or
+else PHP will hang until the execution of the program ends.</para></note>'>
+
+<!ENTITY note.func-callback '<note><simpara>Instead of a function name, an
+array containing an object reference and a method name can also be
+supplied.</simpara></note>'>
+
+<!ENTITY note.line-endings '<note><simpara>If you are having problems
+with <literal>PHP</literal> not recognizing the line endings when
+reading files either on or created by a Macintosh computer, you
+might want to enable the <link linkend="ini.auto-detect-line-endings"
+>auto_detect_line_endings</link> run-time configuration option.</simpara>
+</note>'>
+
+<!ENTITY note.no-remote '<note><simpara>This function will not work on
+<link linkend="features.remote-files">remote files</link> as the file to
+be examined must be accessible via the servers filesystem.</simpara></note>'>
+
+<!ENTITY note.not-bin-safe '<warning><simpara>This function
+is not (yet) binary safe!</simpara></warning>'>
+
+<!ENTITY note.no-windows '<note><simpara>This function is not
+implemented on Windows platforms.</simpara></note>'>
+
+<!ENTITY note.no-windows.extension '<note><simpara>This extension is not
+available on Windows platforms.</simpara></note>'>
+
+<!ENTITY note.randomseed '<note><simpara>As of PHP 4.2.0, there is no need
+to seed the random number generator with <function>srand</function> or
+<function>mt_srand</function> as this is now done automatically.
+</simpara></note>'>
+
+<!ENTITY note.registerglobals '<note><title>register_globals: important
+note</title><para>Since PHP 4.2.0, the default value for the PHP directive
+<link linkend="ini.register-globals">register_globals</link> is <emphasis>
+off</emphasis>. The PHP community encourages all to not rely on this
+directive but instead use other means, such as the &link.superglobals;.
+</para></note>'>
+
+<!ENTITY note.superglobals '<note><title>Superglobals: availability note
+</title><para>Since PHP 4.1.0, superglobal arrays such as <varname>$_GET
+</varname>, <varname>$_POST</varname>, and <varname>$_SERVER</varname>,
+etc. have been available. For more information, read the manual section
+on &link.superglobals;</para></note>'>
+
+
+<!-- Tips -->
+
+<!ENTITY tip.fopen-wrapper '<tip><simpara>You can use a URL as a
+filename with this function if the <link linkend="ini.allow-url-fopen"
+>fopen wrappers</link> have been enabled.
+See <function>fopen</function> for more details on how to specify
+the filename and <xref linkend="wrappers"/> for a list of supported
+URL protocols.</simpara></tip>'>
+
+<!ENTITY tip.fopen-wrapper.stat '<tip><simpara>As of
+<literal>PHP 5.0.0</literal> this function can also be used with
+<emphasis>some</emphasis> URL wrappers. Refer to
+<xref linkend="wrappers"/> for a listing of which wrappers support
+<function>stat</function> family of functionality.</simpara></tip>'>
+
+<!ENTITY tip.ob-capture '<tip><simpara>As with anything that outputs
+its result directly to the browser, you can use the <link
+linkend="ref.outcontrol">output-control functions</link> to capture
+the output of this function, and save it in a
+<type>string</type> (for example).</simpara></tip>'>
+
+
+<!-- Warnings -->
+
+<!ENTITY warn.escapeshell '<warning><para>If you are going to allow data coming
+from user input to be passed to this function, then you should be using
+<function>escapeshellarg</function> or <function>escapeshellcmd</function>
+to make sure that users cannot trick the system into executing arbitrary
+commands.</para></warning>'>
<!ENTITY warn.experimental '<warning><simpara>This extension is
<emphasis>EXPERIMENTAL</emphasis>. The behaviour of this extension --
@@ -12,9 +104,17 @@
function may change without notice in a future release of PHP.
Use this function at your own risk.</simpara></warning>'>
-<!ENTITY warn.undocumented.func '<warning><simpara>This function is
-currently not documented; only the argument list is
-available.</simpara></warning>'>
+<!ENTITY warn.imaprecodeyaz '<warning><simpara>The <link
+linkend="ref.imap">IMAP</link> extension cannot be used in conjuction with
+the <link linkend="ref.recode">recode</link> or <link
+linkend="ref.yaz">YAZ</link> extensions. This is due to the fact that they
+both share the same internal symbol.</simpara></warning>'>
+
+<!ENTITY note.magicquotes.gpc '<note><title>directive note: magic_quotes_gpc
+</title><para>The PHP directive <link linkend="ini.magic-quotes-gpc">
+magic_quotes_gpc</link> defaults to <literal>on</literal>. It essentially
+runs <function>addslashes</function> on all your GET, POST, and COOKIE data.
+You may use <function>stripslashes</function> to strip them.</para></note>'>
<!ENTITY warn.no-win32-fopen-wrapper '<warning><para>Windows
versions of <literal>PHP</literal> prior to PHP 4.3.0 do not
@@ -33,41 +133,18 @@
you are responsible for detecting and suppressing the warning yourself.
</para></warning>'>
-<!ENTITY note.no-remote '<note><simpara>This function will not work on
-<link linkend="features.remote-files">remote files</link> as the file to
-be examined must be accessible via the servers filesystem.</simpara></note>'>
-
-<!ENTITY tip.ob-capture '<tip><simpara>As with anything that outputs
-its result directly to the browser, you can use the <link
-linkend="ref.outcontrol">output-control functions</link> to capture
-the output of this function, and save it in a
-<type>string</type> (for example).</simpara></tip>'>
+<!ENTITY warn.undocumented.func '<warning><simpara>This function is
+currently not documented; only the argument list is
+available.</simpara></warning>'>
-<!ENTITY tip.fopen-wrapper '<tip><simpara>You can use a URL as a
-filename with this function if the <link linkend="ini.allow-url-fopen"
->fopen wrappers</link> have been enabled.
-See <function>fopen</function> for more details on how to specify
-the filename and <xref linkend="wrappers"/> for a list of supported
-URL protocols.</simpara></tip>'>
-<!ENTITY tip.fopen-wrapper.stat '<tip><simpara>As of
-<literal>PHP 5.0.0</literal> this function can also be used with
-<emphasis>some</emphasis> URL wrappers. Refer to
-<xref linkend="wrappers"/> for a listing of which wrappers support
-<function>stat</function> family of functionality.</simpara></tip>'>
-
-<!ENTITY note.context-support '<note><simpara>Context support was added
-with <literal>PHP 5.0.0</literal>.</simpara></note>'>
-
-<!ENTITY return.success 'Returns &true; on success or &false; on failure.'>
+<!-- Misc -->
<!ENTITY array.resetspointer '<note><simpara>This function will
<function>reset</function> the <type>array</type> pointer after
use.</simpara></note>'>
-<!ENTITY note.clearstatcache '<note><simpara>The results of this
-function are cached. See <function>clearstatcache</function> for
-more details.</simpara></note>'>
+<!ENTITY return.success 'Returns &true; on success or &false; on failure.'>
<!ENTITY return.falseproblem '<warning><simpara>This function may
return Boolean &false;, but may also return a non-Boolean value which
@@ -78,36 +155,12 @@
operator</link> for testing the return value of this
function.</simpara></warning>'>
-<!ENTITY warn.imaprecodeyaz '<warning><simpara>The <link
-linkend="ref.imap">IMAP</link> extension cannot be used in conjuction with
-the <link linkend="ref.recode">recode</link> or <link
-linkend="ref.yaz">YAZ</link> extensions. This is due to the fact that they
-both share the same internal symbol.</simpara></warning>'>
-
-<!ENTITY note.registerglobals '<note><title>register_globals: important
-note</title><para>Since PHP 4.2.0, the default value for the PHP directive
-<link linkend="ini.register-globals">register_globals</link> is <emphasis>
-off</emphasis>. The PHP community encourages all to not rely on this
-directive but instead use other means, such as the &link.superglobals;.
-</para></note>'>
-
-<!ENTITY note.superglobals '<note><title>Superglobals: availability note
-</title><para>Since PHP 4.1.0, superglobal arrays such as <varname>$_GET
-</varname>, <varname>$_POST</varname>, and <varname>$_SERVER</varname>,
-etc. have been available. For more information, read the manual section
-on &link.superglobals;</para></note>'>
-
<!ENTITY avail.register-long-arrays 'As of PHP 5.0.0, the long PHP
<link linkend="language.variables.predefined">predefined variable</link>
arrays may be disabled with the
<link linkend="ini.register-long-arrays">register_long_arrays</link>
directive.'>
-<!ENTITY note.magicquotes.gpc '<note><title>directive note: magic_quotes_gpc
-</title><para>The PHP directive <link linkend="ini.magic-quotes-gpc">
-magic_quotes_gpc</link> defaults to <literal>on</literal>. It essentially
-runs <function>addslashes</function> on all your GET, POST, and COOKIE data.
-You may use <function>stripslashes</function> to strip them.</para></note>'>
<!-- Image (GD) Notes -->
<!ENTITY note.config.t1lib '<note><simpara>This function is only available
@@ -119,15 +172,18 @@
<!ENTITY note.gd.2 '<note><simpara>This function requires GD 2.0.1 or
later.</simpara></note>'>
+
<!-- DomXml Notes -->
<!ENTITY node.inserted 'This node will not show up in the document unless it
is inserted with e.g. <function>domnode_append_child</function>.'>
+
<!-- Dom Notes -->
<!ENTITY dom.node.inserted 'This node will not show up in the document unless
it is inserted with e.g. <link
linkend="function.dom-domnode-appendchild">DOMNode->appendChild()</link>.'>
+
<!-- FileSystem entities -->
<!ENTITY fs.validfp.all '<para>The file pointer must be valid, and must point to
a file successfully opened by <function>fopen</function> or
@@ -139,51 +195,12 @@
<parameter>status</parameter> is the status parameter supplied to a successfull
call to <function>pcntl_waitpid</function>.</para>'>
+
<!-- XSLT Notes -->
<!ENTITY note.xslt.windows '<note><para>Please note that <emphasis>file://</emphasis>
is needed in front of path if you use Windows.</para></note>'>
-<!-- Various notes -->
-<!ENTITY note.randomseed '<note><simpara>As of PHP 4.2.0, there is no need
-to seed the random number generator with <function>srand</function> or
-<function>mt_srand</function> as this is now done automatically.
-</simpara></note>'>
-
-<!ENTITY note.not-bin-safe '<warning><simpara>This function
-is not (yet) binary safe!</simpara></warning>'>
-
-<!ENTITY note.bin-safe '<note><simpara>This function is
-binary-safe.</simpara></note>'>
-
-<!ENTITY note.line-endings '<note><simpara>If you are having problems
-with <literal>PHP</literal> not recognizing the line endings when
-reading files either on or created by a Macintosh computer, you
-might want to enable the <link linkend="ini.auto-detect-line-endings"
->auto_detect_line_endings</link> run-time configuration option.</simpara>
-</note>'>
-
-<!ENTITY note.no-windows '<note><simpara>This function is not
-implemented on Windows platforms.</simpara></note>'>
-
-<!ENTITY note.no-windows.extension '<note><simpara>This extension is not
-available on Windows platforms.</simpara></note>'>
-
-<!ENTITY note.func-callback '<note><simpara>Instead of a function name, an
-array containing an object reference and a method name can also be
-supplied.</simpara></note>'>
-
-<!ENTITY warn.escapeshell '<warning><para>If you are going to allow data coming
-from user input to be passed to this function, then you should be using
-<function>escapeshellarg</function> or <function>escapeshellcmd</function>
-to make sure that users cannot trick the system into executing arbitrary
-commands.</para></warning>'>
-
-<!ENTITY note.exec-bg '<note><para>If you start a program using this function
-and want to leave it running in the background, you have to make sure that the
-output of that program is redirected to a file or some other output stream or
-else PHP will hang until the execution of the program ends.</para></note>'>
-
<!-- Notes for safe-mode limited functions: -->
<!ENTITY note.sm.disabled '<note><simpara>&sm.disabled;</simpara></note>'>
@@ -339,7 +356,7 @@
<!ENTITY warn.apache2.compat '<warning><para>Do not use Apache 2.0.x
and <literal>PHP</literal> in a production environment neither
on Unix nor on Windows.</para></warning>'>
-
+
<!ENTITY note.apache.slashes '<note><simpara>Remember that when adding
path values in the Apache configuration files on Windows, all backslashes
such as <filename>c:\directory\file.ext</filename> must be converted to
http://cvs.php.net/diff.php/phpdoc/en/install/unix/apache2.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/install/unix/apache2.xml
diff -u phpdoc/en/install/unix/apache2.xml:1.1 phpdoc/en/install/unix/apache2.xml:1.2
--- phpdoc/en/install/unix/apache2.xml:1.1 Tue Jun 8 17:47:58 2004
+++ phpdoc/en/install/unix/apache2.xml Wed Jun 16 07:11:20 2004
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<sect1 id="install.unix.apache2">
<title>Apache 2.0 on Unix systems</title>
<para>
@@ -7,8 +7,90 @@
of PHP on Unix systems.
</para>
- &warn.apache2.compat;
-
+ <warning>
+ <para>
+ Do not use Apache 2.0.x and <literal>PHP</literal> in a production
+ environment neither on Unix nor on Windows. The reasoning behing
+ that is explained thoroughly in this modified excerpt of a mail
+ by Rasmus Lerdorf.
+ </para>
+
+ <para>
+ Apache2 is a complete rewrite and a complete architecture change from
+ Apache1. It is not like going from <literal>PHP3</literal> to
+ <literal>PHP4</literal> or from <literal>PHP4</literal> to PHP5.
+ There is a lot of code that is common, and certainly the base architecture
+ of PHP has not changed for years. So comparing Apache1 vs. Apache2 to
+ <literal>PHP4</literal> vs. <literal>PHP5</literal> makes no sense.
+ The architecture has been proven over the years and the code, while
+ somewhat unwieldy in places, is a known entity. PHP from the very
+ early days was designed against this basic Apache1 architecture and
+ works extremely well running under it.
+ </para>
+
+ <para>
+ The major feature that draws people to Apache2 is threading. On Windows
+ where most basic libraries are, and must be, threadsafe, Apache2 does
+ actually make sense and it would be good to work out the kinks on that
+ platform. However, on UNIX there are a lot of basic libraries where
+ thread safety is an unknown. And this is not about <literal>PHP</literal>
+ extensions, it is about 3rd-party libraries underneath
<literal>PHP's</literal>
+ hundreds of extensions. Whether any one 3rd-party library is threadsafe is
+ really hard to determine. There are a lot of variables involved, including
which
+ OS, which version of the OS, which libc, which version of that libc and on
+ some platforms even the compiler flags used to compile these things. And
+ to make it even more fun, tracking down a thread safety problem is damn
+ well near impossible. Hundreds of people may well state that
+ Apache+<literal>PHP</literal>+ext/foo works perfectly for them, but maybe
+ they are only getting about a million hits a day. Then another user comes
+ along who gets 100 million hits a day and uses a fast dual-cpu machine and
+ everything blows up because now suddenly the window for some tiny race
+ condition has been made much larger due to the faster cpu speeds, the
+ second cpu and the higher frequency of requests. And the bug report we
+ get from this user will be something along the lines of:
+ </para>
+
+ <para>
+ <note>
+ It don't work sometimes. Most of the times it works fine, but then
+ every now and then it just don't. The error is different each time
+ and I have no idea how to reproduce it, but fix it right away!!!
+ </note>
+ </para>
+
+ <para>What can we do about these?</para>
+
+ <para>
+ There are a number of (fixable) technical reasons Rasmus does not think
+ Apache2+<literal>PHP</literal> is a good idea in a production environment,
+ but setting those aside it really boils down to one simple concept:
+ </para>
+
+ <para>
+ <literal>PHP</literal> is glue. It is the glue used to build cool web
+ applications by sticking dozens of 3rd-party libraries together and making
+ it all appear as one coherent entity through an intuitive and easy to learn
+ language interface. The flexibility and power of <literal>PHP</literal>
relies
+ on the stability and robustness of the underlying platform. It needs a
working
+ OS, a working web server and working 3rd-party libraries to glue together.
+ When any of these stop working <literal>PHP</literal> needs ways to identify
+ the problems and fix them quickly. By making the underlying framework more
+ complex by not having completely separate execution threads, completely
+ separate memory segments and a strong sandbox for each request to play
+ in, a feet of clay is introduced into <literal>PHP's</literal> system.
+ </para>
+
+ <para>
+ Using the prefork mpm with Apache2 to avoid the
+ threading is possible, and yes using a standalone fastcgi mechanism to avoid
+ the threading, too, but then defining characteristic of the web server of
+ choice are avoided. At this point in its development, Rasmus still maintains
+ that one is better off simply sticking with Apache1 for serving up
+ <literal>PHP</literal> pages with the one caveat that Apache1 sucks pretty
badly
+ on Windows.
+ </para>
+ </warning>
+
<para>
You are highly encouraged to take a look at the
<ulink url="&url.apache2.docs;">Apache Documentation</ulink> to get
