Running PHP-FPM in CLI

The standard for running an NGINX webserver for PHP is with PHP-FPM — PHP FastCGI Process Manager(see nginx docs, digitalocean docs). I experienced some major performance enhancements when switching from standard PHP on Apache HTTPD webserver to NGINX with PHP-FPM in my websites.

PHP-FPM started as an independent project (many stackoverflow answers hold broken links to its old standalone documentation) that offered an alternative to PHP FastCGI (which in turn is a take on FastCGI), but eventually embraced by the official PHP group (see php.net).

The problem with using PHP-FPM is that it is customized for webservers (the whole purpose of FastCGI is an interface between applications and webservers), whereas as engineers, we often need to execute PHP scripts in command-line (CLI). i.e. for cronjobs, bash scripts, batch operations done without the intervention of a web-browser and so on. Some of these can be resolved with a mere curl, but it’s not always convenient enough.

Solution

Recommendations vote for php-cli, so one can use that.
My “yet another” solution was to create php-fpm-cli (forked from Mathias Leppich’s gist), which adds to that gist support for loading the PHP script from a file, using query-string parameters and verification of the http-status-code if exists. In this article I’ll explain a bit on the behind the scenes.

Setup and how does it work

Basically to run PHP with PHP-FPM, we use the FastCGI socket/host (explained in detail in Oracle’s CGI FastCGI manual or Ubuntu’s, and it’s the same for PHP-FPM). Since PHP-FPM v7 it is located in:

/run/php-fpm/www.sock

(prior PHP-FPM versions had it in /var/run/php5-fpm.sock for example — it is noted in the listenfield of /etc/php-fpm.d/www.conf,or use something like find / -type f -iname "php*.sock" 2>/dev/null to locate it)
(Also note that in Nginx it is configured with unix:prefix, not relevant to this flow)

To be able to do that, we need the cgi-fcgi command, which is available when installing either of these, depending on your OS:

#RHEL / CentOS
yum --enablerepo=epel install fcgi

#Ubuntu / Debian
apt-get install libfcgi0ldbl

We also need to allow PHP-FPM access to the executed file, so we configure the “listen.acl_users” field in its .conf file to allow access to the PHP scripts’ owners (those set by chown). This will prevent errors like “Could not connect to /run/php-fpm/www.sock”. Run this (might require sudo):

vi /etc/php-fpm.d/www.conf
#or /etc/php5/fpm/pool.d/www.conf in older versions

and change the following line to something similar:

listen.acl_users = apache,nginx,myuser

Then restart the php-fpm service:

systemctl restart php-fpm
#or sudo systemctl restart php7.0-fpm

I would note that PHP-FPM v5 and earlier did not support “listen.acl_users” and so we’ll need to change listen.owner and listen.group — but I don’t recommend that for newer versions where acl_users is supported. It is very limiting and can introduce issues with your webserver (Nginx).

All set. you can run your PHP script in CLI:

./php-fqm-cli -f <path_to_php_file> -q "<query_params>"

# Example:
./php-fqm-cli -f myscript.php -q "param1=val1&param2=val2"

If you want to configure the php-fpm-cli script, to support more FastCGI parameters other than SCRIPT_FILENAME, QUERY_STRING, REQUEST_METHOD, you can use the following for reference (and also CGI FastCGI manuals I mentioned above):

/etc/nginx/fastcgi_params

References

1. https://maxchadwick.xyz/blog/getting-the-php-fpm-status-from-the-command-line
2. https://www.thatsgeeky.com/2012/02/directly-connecting-to-php-fpm/
3. http://www.inanzzz.com/index.php/post/653v/testing-php-fpm-without-having-a-web-server