apache2.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<sect1 xml:id="install.unix.apache2" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Apache 2.x on Unix systems</title>

 <para>
  This section contains notes and hints specific to Apache 2.x installs
  of PHP on Unix systems.
 </para>
   
 &warn.apache2.compat;
    
 <para>
  The <link xlink:href="&url.apache2.docs;">Apache Documentation</link>
  is the most authoritative source of information on the Apache 2.x server.
  More information about installation options for Apache may be found
  there.
 </para>

 <para>
  The most recent version of Apache HTTP Server may be obtained from
  <link xlink:href="&url.apache;">Apache download site</link>,
  and a fitting PHP version from the above mentioned places.
  This quick guide covers only the basics to get started with Apache 2.x
  and PHP. For more information read the
  <link xlink:href="&url.apache2.docs;">Apache Documentation</link>.
  The version numbers have been omitted here, to ensure the
  instructions are not incorrect. In the examples below, 'NN' should be
  replaced with the specific version of Apache being used.
 </para>

 <para>
  There are currently two versions of Apache 2.x - there's 2.4 and 2.2.
  While there are various reasons for choosing each, 2.4 is the current
  latest version, and the one that is recommended, if that option is
  available to you. However, the instructions here will work for either
  2.4 or 2.2. Note that Apache httpd 2.2 is officially End Of Life,
  and no new development or patches are being issued for it.
 </para>

 <orderedlist>
  <listitem>
   <para>
    Obtain the Apache HTTP server from the location listed above,
    and unpack it:
   </para>

   <informalexample>
    <screen>
<![CDATA[
tar -xzf httpd-2.x.NN.tar.gz
]]>
    </screen>
   </informalexample>
  </listitem>

  <listitem>
   <para>
    Likewise, obtain and unpack the PHP source:
   </para>

   <informalexample>
    <screen>
<![CDATA[
tar -xzf php-NN.tar.gz
]]>
    </screen>
   </informalexample>
  </listitem>
   
  <listitem>
   <para>
    Build and install Apache. Consult the Apache install documentation for
    more details on building Apache.
   </para>

   <informalexample>
    <screen>
<![CDATA[
cd httpd-2_x_NN
./configure --enable-so
make
make install
]]>
    </screen>
   </informalexample>
  </listitem>

  <listitem>
   <para>
    Now you have Apache 2.x.NN available under /usr/local/apache2,
    configured with loadable module support and the standard MPM prefork.
    To test the installation use your normal procedure for starting
    the Apache server, e.g.:

    <informalexample>
     <screen>
<![CDATA[
/usr/local/apache2/bin/apachectl start
]]>
     </screen>
    </informalexample>

    and stop the server to go on with the configuration for PHP:

    <informalexample>
     <screen>
<![CDATA[
/usr/local/apache2/bin/apachectl stop
]]>
     </screen>
    </informalexample>
   </para>
  </listitem>

  <listitem>
   <para>
    Now, configure and build PHP. This is where you customize PHP
    with various options, like which extensions will be enabled. Run
    <command>./configure --help</command> for a list of available options. In our example
    we'll do a simple configure with Apache 2 and MySQL support.
   </para>

   <para>
    If you built Apache from source, as described above, the below example will
    match your path for <command>apxs</command>, but if you installed Apache some other way, you'll
    need to adjust the path to <command>apxs</command> accordingly. Note that some distros may rename
    <command>apxs</command> to <command>apxs2</command>.
   </para>

   <informalexample>
    <screen>
<![CDATA[
cd ../php-NN
./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-pdo-mysql
make
make install
]]>
    </screen>
   </informalexample>

   <para>
    If you decide to change your configure options after installation,
    you'll need to re-run the <command>configure</command>, <command>make</command>,
    and <command>make install</command> steps.
    You only need to restart apache for the new module to take effect.
    A recompile of Apache is not needed.
   </para>
         
   <para>
    Note that unless told otherwise, <command>make install</command> will also install
    <link xlink:href="&url.php.pear;">PEAR</link>,
    various PHP tools such as <link linkend="install.pecl.phpize">phpize</link>,
    install the PHP CLI, and more.
   </para>
  </listitem>

  <listitem>
   <para>
    Setup your <filename>php.ini</filename>.
   </para>
    
   <informalexample>
    <screen>
<![CDATA[
cp php.ini-development /usr/local/lib/php.ini
]]>
    </screen>
   </informalexample>

   <para>
    You may edit your <literal>.ini</literal> file to set PHP options. If you prefer having
    <filename>php.ini</filename> in another location,
    use <literal>--with-config-file-path=/some/path</literal> in step 5.
   </para>
   
   <para>
    If you instead choose <filename>php.ini-production</filename>, be certain to read the list
    of changes within, as they affect how PHP behaves.
   </para>
  </listitem>

  <listitem>
   <para>
    Edit your <filename>httpd.conf</filename> to load the PHP module. The path on the right hand
    side of the <literal>LoadModule</literal> statement must point to the path of the PHP
    module on your system. The <command>make install</command> from above may have already
    added this for you, but be sure to check.
   </para>

   <informalexample>
    <para>
     For PHP 8:
    </para>

    <programlisting role="apache-conf">
<![CDATA[
LoadModule php_module modules/libphp.so
]]>
    </programlisting>
   </informalexample>

   <informalexample>
    <para>
     For PHP 7:
    </para>

    <programlisting role="apache-conf">
<![CDATA[
LoadModule php7_module modules/libphp7.so
]]>
    </programlisting>
   </informalexample>
  </listitem>

  <listitem>
   <para>
    Tell Apache to parse certain extensions as PHP. For example, let's have
    Apache parse <literal>.php</literal> files as PHP. Instead of only using the Apache <literal>AddType</literal>
    directive, we want to avoid potentially dangerous uploads and created
    files such as <filename>exploit.php.jpg</filename> from being executed as PHP. Using this
    example, you could have any extension(s) parse as PHP by simply adding
    them. We'll add <literal>.php</literal> to demonstrate.
   </para>

   <informalexample>
    <programlisting role="apache-conf">
<![CDATA[
<FilesMatch \.php$>
    SetHandler application/x-httpd-php
</FilesMatch>
]]>
    </programlisting>
   </informalexample>

   <para>
    Or, if we wanted to allow <literal>.php</literal>, <literal>.php2</literal>,
    <literal>.php3</literal>, <literal>.php4</literal>, <literal>.php5</literal>,
    <literal>.php6</literal>, and <literal>.phtml</literal> files to be
    executed as PHP, but nothing else, we'd use this:
   </para>

   <informalexample>
    <programlisting role="apache-conf">
<![CDATA[
<FilesMatch "\.ph(p[2-6]?|tml)$">
    SetHandler application/x-httpd-php
</FilesMatch>
]]>
    </programlisting>
   </informalexample>

   <para>
    And to allow <literal>.phps</literal> files to be handled by the php source filter, and
    displayed as syntax-highlighted source code, use this:
   </para>

   <informalexample>
    <programlisting role="apache-conf">
<![CDATA[
<FilesMatch "\.phps$">
    SetHandler application/x-httpd-php-source
</FilesMatch>
]]>
    </programlisting>
   </informalexample>

   <simpara>
    To allow use of a PHP file as the default handler if no other handler is found,
    for example when using a routing engine, the <literal>FallbackResource</literal> directive may be used.
    This is available in Apache 2.4.4 and later.
   </simpara>

   <simpara>
    Because the <literal>SetHandler</literal> directive is applied whether the file exists or not, and the
    <literal>FallbackResource</literal> is only applied if a handler has not already been set,
    you may need to use the <literal>If</literal> directive to ensure that the handler is only
    applied if the file exists.
    This allows the <literal>FallbackResource</literal> to handle paths which end in <literal>.php</literal>
    but do not exist, which may be useful for error handling and routing.
   </simpara>

   <informalexample>
    <programlisting role="apache-conf">
<![CDATA[
<FilesMatch "\.php$">
    <If "-f %{REQUEST_FILENAME}">
        SetHandler application/x-httpd-php
    </If>
</FilesMatch>
FallbackResource /index.php
]]>
    </programlisting>
   </informalexample>

   <para>
    <literal>mod_rewrite</literal> may be used to allow any arbitrary <literal>.php</literal> file to be displayed
    as syntax-highlighted source code, without having to rename or copy it
    to a <literal>.phps</literal> file:
   </para>

   <informalexample>
    <programlisting role="apache-conf">
<![CDATA[
RewriteEngine On
RewriteRule (.*\.php)s$ $1 [H=application/x-httpd-php-source]
]]>
    </programlisting>
   </informalexample>

   <para>
    The php source filter should not be enabled on production systems, where
    it may expose confidential or otherwise sensitive information embedded in
    source code.
   </para>
  </listitem>

  <listitem>
   <para>
    Use your normal procedure for starting the Apache server, e.g.:
   </para>
  
   <informalexample>
    <screen>
<![CDATA[
/usr/local/apache2/bin/apachectl start
]]>
    </screen>
   </informalexample>

   <para>OR</para>

   <informalexample>
    <screen>
<![CDATA[
service httpd restart
]]>
    </screen>
   </informalexample>
  </listitem>
 </orderedlist>

 <para>
  Following the steps above you will have a running Apache2 web server with
  support for PHP as a <literal>SAPI</literal> module. Of course, there are
  many more configuration options available for Apache and PHP. For more
  information type <command>./configure --help</command> in the corresponding
  source tree.
 </para>

 <para>
  Apache may be built multithreaded by selecting the
  <filename>worker</filename> MPM, rather than the standard
  <filename>prefork</filename> MPM, when Apache is built. This is done by
  adding the following option to the argument passed to <command>./configure</command>, in
  step 3 above:
 </para>

 <informalexample>
  <screen>
<![CDATA[
--with-mpm=worker
]]>
  </screen>
 </informalexample>

 <para>
  This should not be undertaken without being aware of the consequences of
  this decision, and having at least a fair understanding of
  the implications. The Apache documentation
  regarding <link xlink:href="&url.apache2.mpm;">MPM-Modules</link>
  discusses MPMs in a great deal more detail.
 </para>

 <note>
  <para>
   The <link linkend="faq.installation.apache.multiviews">Apache MultiViews
   FAQ</link> discusses using multiviews with PHP.
  </para>
 </note>

 <note>
  <para>
   To build a multithreaded version of Apache, the target system must support threads.
   In this case, PHP should also be built with
   Zend Thread Safety (ZTS). Under this configuration, not all extensions will be available.
   The recommended setup is to build Apache with the default
   <filename>prefork</filename> MPM-Module.
  </para>
 </note>
</sect1>

<!-- 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
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->