[Webapps-common-discuss] webapps-common/doc PHP-Policy-Manual-DRAFT.sgml, 1.1, 1.2

[seanius at haydn.debian.org]

Update of /cvsroot/webapps-common/webapps-common/doc
In directory haydn:/org/alioth.debian.org/chroot/home/users/seanius/tmp/cvs-serv24160

Modified Files:
	PHP-Policy-Manual-DRAFT.sgml 
Log Message:
included a first attempt at info about the interpreters.


Index: PHP-Policy-Manual-DRAFT.sgml
===================================================================
RCS file: /cvsroot/webapps-common/webapps-common/doc/PHP-Policy-Manual-DRAFT.sgml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- PHP-Policy-Manual-DRAFT.sgml	25 Jul 2005 21:52:37 -0000	1.1
+++ PHP-Policy-Manual-DRAFT.sgml	4 Aug 2005 01:59:37 -0000	1.2
@@ -91,12 +91,94 @@
 					<tag><item>do we need any?
 				</taglist>
 
-	<chapt id="php-int">PHP Interpreters
+	<chapt id="php-int">PHP Interpreters and Engines
 		<sect id="php-interpreter-naming">Packages and naming scheme
+		<p>
+			The PHP engine is provided in one of three
+			types of packages, each providing a different
+			environment for execution.  
+		<p>
+			The first and most commonly used  type of package
+			is the "server-side" family of libraries/plugins
+			(such as <package>libapache2-mod-php4</package>)
+			for interpreting PHP pages by web servers.
+			There also exists a "cli" and "cgi" version of the
+			interpreter, as well as a prebuilt set of bundled
+			modules provided along with the PHP source code.
+		<p>
+			For each version of PHP, the following naming conventions
+			are followed:
+		<taglist>
+		<tag>php<var>PHPVERSION</var>
+			<item>A meta-package depending on one of any of the "server-side"
+			      modules, such as <package>libapache2-mod-php4</package>.  This
+					is the most common package to have installed for using PHP
+					with web pages.
+		<tag>php<var>PHPVERSION</var>-cli
+			<item>Provides the command-line PHP interpreter for use in
+			      scripting.
+		<tag>php<var>PHPVERSION</var>-cgi
+			<item>Provides the command-line CGI interpreter for use with
+			      webservers that provide CGI functionality but do not have
+					built-in support for PHP.
+		<tag>php<var>PHPVERSION</var>-<var>PHPMODULENAME</var>
+			<item>One of a small collection of prebuilt php modules such
+			      as <package>php4-mysql</package>, which are included
+					with PHP by the upstream authors.
+		</taglist>
+			
 		<sect id="php-interpreter-fs">File and directory layout
 			<sect1 id="php-interpreter-fs-bins">PHP executable binaries
+			<p>
+				The "cli" packages provide the interpreter binary provided in
+				<file>/usr/bin</file> as php<var>PHPVERSION</var>.  For example,
+				<file>/usr/bin/php4</file>.
+			<p>
+				The "cgi" packages similarly provide the binaries as
+				php<var>PHPVERSION</var>-cgi.
+			<p>
+				In both cases, PHP interpreters will
+				use the debian alternatives system for determining what
+				binary will provide
+				<file>/usr/bin/php</file> and <file>/usr/bin/php-cgi</file>
 			<sect1 id="php-interpreter-fs-include">Default include path
+			<p>
+				The standard PHP include path is:
+				<tt>
+.:/etc/php:/usr/local/share/php/5.0:/usr/share/php5:/usr/share/php/5.0:/usr/share/php:/usr/local/share/php 
+				</tt>
+			<p>
+				XXX: this still needs to be solidified.
+			<p>
+				<file>/etc/php</file> is for
+				use by the local administrator.
+				<file>/usr/local/share/php</file>
+				and similar directories are also for
+				local use, but also serve as the root
+				repository for packages locally installed
+				via <prgn>pear</prgn>.
+			<p>
+				<file>/usr/share/php</file> is for all PHP libraries
+				packaged as part of Debian.
+			<p>
+				<file>/usr/share/php<var>PHPVERSION</var></file>
+				and
+				<file>/usr/share/php/<var>PHPVERSION</var></file>
+				are used for PHP libraries installed via the debian
+				package management system that are dependant on a
+				particular version of PHP.
+
 			<sect1 id="php-interpreter-fs-conf">Configuration files
+			<p>
+				Each PHP engine has a seperate configuration file located
+				at <file>/etc/php<var>PHPVERSION</var>/<var>PHPSAPI</var>/php.ini</file>
+			<p>
+				Additionally, each engine
+				provides a directory at
+				<file>/etc/php<var>PHPVERSION</var>/<var>PHPSAPI</var>/conf.d</file>
+				where 3rd party PHP libraries and modules can provide additional
+				configuration information.
+			<p>XXX this second part is not yet true.
 
 	<chapt id="php-apps">PHP applications
 		<sect id="php-apps-naming">Packages and naming scheme