This section contains notes and hints specific to Apache HTTP Server
2.x installs of PHP on Linux and Unix-like systems.
Warning
Use PHP-FPM Instead
Do not use mod_php for new
installations. 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.
For all modern deployments, use
PHP-FPM (FastCGI Process Manager)
with Apache httpd's mod_proxy_fcgi module. PHP-FPM
provides better resource management, process isolation, independent
restart of PHP without restarting Apache httpd, and compatibility with
Apache httpd's event MPM (the default since Apache httpd 2.4).
Major Linux distributions ship this as the default configuration.
The mod_php approach embeds PHP directly into every
Apache httpd worker process. Unless PHP is compiled with thread safety
(--enable-zts), mod_php requires
the prefork MPM, which significantly limits
concurrency. If you proceed with mod_php, you
should fully understand the performance and security implications.
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.
-
Obtain Apache httpd from the location listed above,
and unpack it:
-
Likewise, obtain and unpack the PHP source:
-
Build and install Apache httpd. Consult the Apache httpd install documentation for
more details on building Apache httpd. Note that mod_php
requires the prefork MPM unless PHP was compiled
with thread safety (--enable-zts). If you intend
to use PHP-FPM instead (recommended), you can use the default
event MPM and skip to the
PHP-FPM installation instructions.
-
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 httpd server, e.g.:
and stop the server to continue with the configuration for PHP:
-
Now, configure and build PHP. This is where you customize PHP
with various options, like which extensions will be enabled. Run
./configure --help for a list of available options. In our example
we'll do a simple configure with Apache httpd and MySQL support.
If you built Apache httpd from source, as described above, the below example will
match your path for apxs, but if you installed Apache httpd some other way, you'll
need to adjust the path to apxs accordingly. Note that some distributions may rename
apxs to apxs2.
If you decide to change your configure options after installation,
you'll need to re-run the configure, make,
and make install steps.
You only need to restart apache for the new module to take effect.
A recompile of Apache httpd is not needed.
Note that unless told otherwise, make install will also install
» PEAR,
various PHP tools such as phpize,
install the PHP CLI, and more.
-
Setup your php.ini.
You may edit your .ini file to set PHP options. If you prefer having
php.ini in another location,
use --with-config-file-path=/some/path in step 5.
If you instead choose php.ini-production, be certain to read the list
of changes within, as they affect how PHP behaves.
-
Edit your httpd.conf to load the PHP module. The path on the right hand
side of the LoadModule statement must point to the path of the PHP
module on your system. The make install from above may have already
added this for you, but be sure to check.
-
Tell Apache httpd to parse certain extensions as PHP. For example, let's have
Apache httpd parse .php files as PHP. Instead of only using the AddType
directive, we want to avoid potentially dangerous uploads and created
files such as exploit.php.jpg from being executed as PHP. Using this
example, you could have any extension(s) parse as PHP by simply adding
them. We'll add .php to demonstrate.
Or, if we wanted to allow .php, .php2,
.php3, .php4, .php5,
.php6, and .phtml files to be
executed as PHP, but nothing else, we'd use this:
And to allow .phps files to be handled by the php source filter, and
displayed as syntax-highlighted source code, use this:
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 FallbackResource directive may be used.
Because the SetHandler directive is applied whether the file exists or not, and the
FallbackResource is only applied if a handler has not already been set,
you may need to use the If directive to ensure that the handler is only
applied if the file exists.
This allows the FallbackResource to handle paths which end in .php
but do not exist, which may be useful for error handling and routing.
mod_rewrite may be used to allow any arbitrary .php file to be displayed
as syntax-highlighted source code, without having to rename or copy it
to a .phps file:
The php source filter should not be enabled on production systems, where
it may expose confidential or otherwise sensitive information embedded in
source code.
-
Use your normal procedure for starting Apache httpd, e.g.:
OR
Following the steps above you will have a running Apache httpd web server with
support for PHP as a SAPI module. There are
many more configuration options available for Apache httpd and PHP. For more
information type ./configure --help in the corresponding
source tree.
Note:
MPM Compatibility
Unless PHP was compiled with Zend Thread Safety
(--enable-zts), mod_php requires
the prefork MPM.
For information on why, read the related FAQ entry on using
Apache httpd with a threaded
MPM.
Most distribution packages of
mod_php are not built with ZTS, so
prefork is typically required. If you need a
threaded MPM (recommended for better performance under load), use
PHP-FPM with
mod_proxy_fcgi instead.
