How To Install and Configure PHP-FPM and Apache 2.4 on FreeBSD

Are you looking for instructions about how to install PHP-FPM on FreeBSD or how to configure Apache 2.4 and PHP-FPM? Keep on reading. This is how I did it on my FreeBSD laptop.

NOTE: I’m assuming you are in a hurry and want to get to the point ASAP. While I’m using FreeBSD at the time of this writing, the principles should apply to any *nix. It would be a matter of adjusting paths and, of course, using the correct package manager and package names. Hence, this is not a full fledged tutorial, but a series of pointers in the right direction. I’ll also point to official sources of documentation so you can know here this information comes from.

1. INSTALLING APACHE 2.4

Use the package manager in order to look for (and install) the apache string. Lots of results will be returned, so you can filter using the grep command.

$ pkg search apache | grep -i web
apache24-2.4.54 Version 2.4.x of Apache web server
...
$ sudo pkg install apache24-2.4.54

NOTE: following hier(7), new directories were created under /usr/local, for example /usr/local/www/apache24/, /usr/local/etc/apache24/, etc.

You’ll be asked to include apache24_enable="YES"in your /etc/rc.conf file if you want Apache to start at system boot.

2. INSTALLING PHP

Use the package manager in order to look for (and install) the “php” string. You’ll see results for different version of PHP and, as a bonus point, you’ll also see the package name for the PHP module used by Apache (mod_php74-7.4.30_1).

$ pkg search php | grep -i scripting
...
mod_php74-7.4.30_1 PHP Scripting Language
mod_php80-8.0.20_1 PHP Scripting Language
mod_php81-8.1.8_1 PHP Scripting Language (8.1.X branch)
mod_php82-8.2.0.a3_1 PHP Scripting Language (8.2.X branch)
php74-7.4.30 PHP Scripting Language
php80-8.0.20 PHP Scripting Language
php81-8.1.8 PHP Scripting Language (8.1.X branch)
php82-8.2.0.a3 PHP Scripting Language (8.2.X branch)
...
$ sudo pkg install php74-7.4.30 mod_php74-7.4.30_1

NOTE: following hier(7), new directories were created under /usr/local, for example /usr/local/etc/php (your .ini files are located here), /usr/local/etc/php-fpm.d (PHP-FPM workers configuration files are here), etc.

You’ll be asked to include php_fpm_enable="YES"in your /etc/rc.conf file if you want PHP-FPM to start at system boot.

The package information displayed at installation time also includes a message telling us to add the following snippet somewhere in the Apache configuration file (/usr/local/etc/apache24/httpd.conf):

<FilesMatch "\.php$">
    SetHandler application/x-httpd-php
</FilesMatch>
<FilesMatch "\.phps$">
    SetHandler application/x-httpd-php-source
</FilesMatch>

But If you take a look at the bottom of /usr/local/etc/apache24/httpd.conf file, you’ll see the following statement:

Include /usr/local/etc/apache24/Includes/*.conf

This means that Apache will try to include any .conf file located inside /usr/local/etc/apache24/Includes/. So, instead of copying the provided snippet directly into httpd.conf, create a new file under the Includes directory, and put the snippet there.

E.g. you can create a new /usr/local/etc/apache24/Includes/php7.4.conf (the file name doesn’t matter).

TIP: a “handler” is an internal Apache representation of the action to be performed when a file is called. Generally, files have implicit handlers, based on the file type. Normally, all files are simply served by the server, but certain file types are “handled” separately.

So, you are basically telling Apache what to do when .php(s) files are requested.

Take into consideration that we’ll be performing a slight change to those settings in a few minutes, as we want Apache to use the “FPM/FastCGI API“, instead of the traditional “Apache 2.0 Handler“, which is what we just configured.

3. CONFIGURING APACHE 2.4 + PHP-FPM

Now that we have PHP + Apache installed:

1. Get sure that your workers configuration is correct: /usr/local/etc/php-fpm.d/www.conf.
2. In your /usr/local/etc/apache24/httpd.conf file, uncomment the following lines:

LoadModule php7_module libexec/apache24/libphp7.so
...
LoadModule proxy_module libexec/apache24/mod_proxy.so
...
LoadModule proxy_fcgi_module libexec/apache24/mod_proxy_fcgi.so

According to Apache docs, mod_proxy.so and mod_proxy_fcgi.so are required in order to support FastCGI. Remember that this is what FPM is about: FastCGI Process Manager (FPM).

If you look a the examples provided in the Apache documentation, you’ll notice that they look very similar to the snippet we created in the previous section where we added a new handler. The only difference is that in these examples, handlers are based on the configuration of PHP-FPM workers.

In my case, this is how the PHP-FPM handler looks like:

<FilesMatch "\.php$">
    SetHandler  "proxy:fcgi://localhost:9000"
</FilesMatch>

This is what Apache documentation says about it:

…The example configuration below will pass all requests for PHP scripts to the specified FastCGI server using reverse proxy. This feature is available in Apache HTTP Server 2.4.10 and later. For performance reasons, you will want to define a worker representing the same fcgi:// backend. The benefit of this form is that it allows the normal mapping of URI to filename to occur in the server, and the local filesystem result is passed to the backend. When FastCGI is configured this way, theserver can calculate the most accurate PATH_INFO.

So, now you have at least 2 options:

1. You replace the handler we created in the previous section with a new handler using the settings of your PHP-FPM workers.
2. You place the new snippet inside any VirtualHost block where you want it to apply.

I took the second approach and included it only in the VirtualHost block where I want it to apply. It looks as follows:

<VirtualHost *:80>
    ServerAdmin foo@example.com
    DocumentRoot "/usr/local/www/apache24/SymfonyProjects/current/public"

    <Directory "/usr/local/www/apache24/SymfonyProjects/current">
        Require all granted
    </Directory>

    <FilesMatch "\.php$">
       SetHandler  "proxy:fcgi://localhost:9000"
    </FilesMatch>

    ServerName symfony-projects.local
    ServerAlias aspirebsd-local.com
    ErrorLog "/var/log/symfony-projects.local-error_log"
    CustomLog "/var/log/symfony-projects.local-access_log" common
</VirtualHost>

Whatever route you take, remember to restart the Apache service afterwards.

$ sudo service apache24 restart

4. TESTING YOUR CONFIGURATION

Create a PHP file calling the phpinfo()function. If everything worked as expected, the “Server API” row at the beginning of the page should indicate we are using “FPM/FastCGI API“, instead of the traditional “Apache 2.0 Handler“.

CONCLUSION

Attaboy! You should be running Apache 2.4 with PHP-FPM enabled by now, or at least have a better idea what path to follow. As I mentioned earlier, the principles should apply to any *nix platform you are using.

Tagged apache 2.4, apache virtualhost, configuring php-fpm, FastCGI, FreeBSD, how to configure Apache 2.4 and PHP-FPM, how to install PHP-FPM on FreeBSD, mod_proxy_fcgi.so, mod_proxy.so, php-fpm