Skip to content

Modernize mod_php/Apache httpd installation guide #5743

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rbowen wants to merge 3 commits into
base: master
Choose a base branch
from
+101 −108
Open

Modernize mod_php/Apache httpd installation guide #5743

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
36b760c
Modernize mod_php installation guide
rbowen Aug 7, 2026
97403f9
Remove orphaned language snippet and link to threaded FAQ.
rbowen Aug 7, 2026
ab449be
Attempt to make doclint happy
rbowen Aug 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
204 changes: 101 additions & 103 deletions install/unix/apache2.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,49 +1,71 @@
<?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;
Comment thread
rbowen marked this conversation as resolved.

<para>
<title>Apache httpd 2.x on Unix systems</title>

<simpara>
This section contains notes and hints specific to Apache HTTP Server
2.x installs of PHP on Linux and Unix-like systems.
</simpara>

<warning>
<title>Use PHP-FPM Instead</title>
<simpara>
<emphasis role="strong">Do not use <literal>mod_php</literal> for new
installations.</emphasis> The instructions on this page are retained
for historical reference and for the rare cases where embedding PHP
directly in the Apache httpd process is specifically required.
</simpara>
<simpara>
For all modern deployments, use
<link linkend="install.fpm">PHP-FPM</link> (FastCGI Process Manager)
with Apache httpd's <literal>mod_proxy_fcgi</literal> module. PHP-FPM
provides better resource management, process isolation, independent
restart of PHP without restarting Apache httpd, and compatibility with
Apache httpd's <literal>event</literal> MPM (the default since Apache httpd 2.4).
Major Linux distributions ship this as the default configuration.
</simpara>
<simpara>
The <literal>mod_php</literal> approach embeds PHP directly into every
Apache httpd worker process. Unless PHP is compiled with thread safety
(<literal>--enable-zts</literal>), <literal>mod_php</literal> requires
the <literal>prefork</literal> MPM, which significantly limits
concurrency. If you proceed with <literal>mod_php</literal>, you
should fully understand the performance and security implications.
</simpara>
</warning>

<simpara>
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
is the most authoritative source of information on the Apache httpd 2.x server.
More information about installation options for Apache httpd may be found
there.
</para>
</simpara>

<para>
The most recent version of Apache HTTP Server may be obtained from
<simpara>
The most recent version of Apache httpd 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
This quick guide covers only the basics to get started with Apache httpd 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>
replaced with the specific version of Apache httpd being used.
</simpara>

<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>
<simpara>
These instructions apply to Apache httpd 2.4, which is the only supported
release branch of Apache httpd. Earlier versions (2.2 and below) are
end of life and should not be used.
</simpara>

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

<informalexample>
<screen>
Expand All @@ -55,9 +77,9 @@
</listitem>

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

<informalexample>
<screen>
Expand All @@ -67,18 +89,23 @@
</screen>
</informalexample>
</listitem>

<listitem>
<para>

Check failure on line 94 in install/unix/apache2.xml

View workflow job for this annotation

GitHub Actions / DocBook Style Check (en) 

apache2.xml: <para> contains only inline content and should be <simpara>.
Build and install Apache. Consult the Apache install documentation for
more details on building Apache.
Build and install Apache httpd. Consult the Apache httpd install documentation for
more details on building Apache httpd. Note that <literal>mod_php</literal>
requires the <literal>prefork</literal> MPM unless PHP was compiled
with thread safety (<literal>--enable-zts</literal>). If you intend
to use PHP-FPM instead (recommended), you can use the default
<literal>event</literal> MPM and skip to the
<link linkend="install.fpm">PHP-FPM installation instructions</link>.
</para>

<informalexample>
<screen>
<![CDATA[
cd httpd-2_x_NN
./configure --enable-so
./configure --enable-so --with-mpm=prefork
make
make install
]]>
Expand All @@ -88,10 +115,10 @@

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

<informalexample>
<screen>
Expand All @@ -101,7 +128,7 @@
</screen>
</informalexample>

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

<informalexample>
<screen>
Expand All @@ -114,17 +141,17 @@
</listitem>

<listitem>
<para>

Check failure on line 144 in install/unix/apache2.xml

View workflow job for this annotation

GitHub Actions / DocBook Style Check (en) 

apache2.xml: <para> contains only inline content and should be <simpara>.
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.
we'll do a simple configure with Apache httpd and MySQL support.
</para>

<para>

Check failure on line 151 in install/unix/apache2.xml

View workflow job for this annotation

GitHub Actions / DocBook Style Check (en) 

apache2.xml: <para> contains only inline content and should be <simpara>.
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
If you built Apache httpd from source, as described above, the below example will
match your path for <command>apxs</command>, but if you installed Apache httpd some other way, you'll
need to adjust the path to <command>apxs</command> accordingly. Note that some distributions may rename
<command>apxs</command> to <command>apxs2</command>.
</para>

Expand All @@ -139,14 +166,14 @@
</screen>
</informalexample>

<para>

Check failure on line 169 in install/unix/apache2.xml

View workflow job for this annotation

GitHub Actions / DocBook Style Check (en) 

apache2.xml: <para> contains only inline content and should be <simpara>.
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.
A recompile of Apache httpd 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>,
Expand All @@ -159,7 +186,7 @@
<para>
Setup your <filename>php.ini</filename>.
</para>

<informalexample>
<screen>
<![CDATA[
Expand All @@ -173,7 +200,7 @@
<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.
Expand All @@ -189,34 +216,18 @@
</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>

Check failure on line 228 in install/unix/apache2.xml

View workflow job for this annotation

GitHub Actions / DocBook Style Check (en) 

apache2.xml: <para> contains only inline content and should be <simpara>.
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>
Tell Apache httpd to parse certain extensions as PHP. For example, let's have
Apache httpd parse <literal>.php</literal> files as PHP. Instead of only using the <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
Expand All @@ -243,7 +254,7 @@
<informalexample>
<programlisting role="apache-conf">
<![CDATA[
<FilesMatch "\.ph(p[2-6]?|tml)$">
<FilesMatch "\.(php[2-6]?|phtml)$">
SetHandler application/x-httpd-php
</FilesMatch>
]]>
Expand All @@ -268,7 +279,6 @@
<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>
Expand Down Expand Up @@ -316,10 +326,10 @@
</listitem>

<listitem>
<para>

Check failure on line 329 in install/unix/apache2.xml

View workflow job for this annotation

GitHub Actions / DocBook Style Check (en) 

apache2.xml: <para> contains only inline content and should be <simpara>.
Use your normal procedure for starting the Apache server, e.g.:
Use your normal procedure for starting Apache httpd, e.g.:
</para>

<informalexample>
<screen>
<![CDATA[
Expand All @@ -340,52 +350,39 @@
</listitem>
</orderedlist>

<para>

Check failure on line 353 in install/unix/apache2.xml

View workflow job for this annotation

GitHub Actions / DocBook Style Check (en) 

apache2.xml: <para> contains only inline content and should be <simpara>.
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
Following the steps above you will have a running Apache httpd web server with
support for PHP as a <literal>SAPI</literal> module. There are
many more configuration options available for Apache httpd 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>
<title>MPM Compatibility</title>
<para>

Check failure on line 363 in install/unix/apache2.xml

View workflow job for this annotation

GitHub Actions / DocBook Style Check (en) 

apache2.xml: <para> contains only inline content and should be <simpara>.
The <link linkend="faq.installation.apache.multiviews">Apache MultiViews
FAQ</link> discusses using multiviews with PHP.
Unless PHP was compiled with Zend Thread Safety
(<literal>--enable-zts</literal>), <literal>mod_php</literal> requires
the <literal>prefork</literal> MPM.
For information on why, read the related FAQ entry on using
<link linkend="faq.installation.apache2">Apache httpd with a threaded
MPM</link>.
</para>

<para>

Check failure on line 372 in install/unix/apache2.xml

View workflow job for this annotation

GitHub Actions / DocBook Style Check (en) 

apache2.xml: <para> contains only inline content and should be <simpara>.
Most distribution packages of
<literal>mod_php</literal> are not built with ZTS, so
<literal>prefork</literal> is typically required. If you need a
threaded MPM (recommended for better performance under load), use
<link linkend="install.fpm">PHP-FPM</link> with
<literal>mod_proxy_fcgi</literal> instead.
</para>
</note>

<note>
<para>

Check failure on line 383 in install/unix/apache2.xml

View workflow job for this annotation

GitHub Actions / DocBook Style Check (en) 

apache2.xml: <para> contains only inline content and should be <simpara>.
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.
The <link linkend="faq.installation.apache.multiviews">Apache MultiViews
FAQ</link> discusses using multiviews with PHP.
</para>
</note>
</sect1>
Expand All @@ -410,3 +407,4 @@
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

5 changes: 0 additions & 5 deletions language-snippets.ent
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2266,11 +2266,6 @@ brackets—for example, <literal>tcp://[fe80::1]:80</literal>.</simpara></note>'
<!ENTITY tidy.object 'The <classname xmlns="http://docbook.org/ns/docbook">Tidy</classname> object.'>

<!-- Snippets for the installation section -->
<!ENTITY warn.apache2.compat '<warning xmlns="http://docbook.org/ns/docbook"><simpara>We do not recommend using a
threaded MPM in production with Apache 2. Use the prefork MPM, which is
the default MPM with Apache 2.0 and 2.2.
For information on why, read the related FAQ entry on using
<link linkend="faq.installation.apache2">Apache2 with a threaded MPM</link></simpara></warning>'>
<!ENTITY warn.install.third-party-support '<warning xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<simpara>
Builds from third-parties are considered unofficial and not directly
Expand Down
Loading