SAPI Explained: How PHP Talks to the Web Server

In short: SAPI stands for Server Application Programming Interface, the interface through which PHP talks to its environment. Typical SAPIs are fpm-fcgi (PHP-FPM), apache2handler (mod_php), cgi-fcgi (php-cgi), litespeed and cli for the command line. The SAPI determines how requests arrive, which php.ini applies and which processes must restart after an update. With PHP2Shell, even the risk rating depends on it.

What is a SAPI?

PHP itself is a program that executes code. To be able to serve web pages, it needs a connection to a web server, to the command line or to another application. This connection is the SAPI. It receives request data, passes it to the Zend Engine and returns the output.

You can think of the SAPI as a plug: the engine stays the same, but depending on the plug it fits Apache, Nginx via FastCGI, LiteSpeed or the terminal. Each variant has its own strengths, its own configuration paths and its own pitfalls.

The SAPI mainly decides three things that matter in everyday operation:

1. Process model: Does PHP run inside the web server, as its own service with permanent workers, or as a short-lived process per call?
2. Configuration: Which php.ini is read, and where may additional settings be placed, for example in .htaccess, in a .user.ini or in the FPM pool?
3. Permissions and separation: Under which user does the code run, and can several websites be separated from one another?

In hosting panels, SAPIs appear under other names. Plesk, for example, speaks of PHP handlers such as "FPM application", "FastCGI application" or "Apache module". The same operating modes described on this page are meant. If in doubt, the test file further below helps, as it shows the actual SAPI name.

Which PHP SAPIs exist?

For php_sapi_name(), the PHP manual lists these return values, among others: apache, apache2handler, cgi (until PHP 5.3), cgi-fcgi, cli, cli-server, embed, fpm-fcgi, litespeed and phpdbg. The list is explicitly not exhaustive.

FrankenPHP is a modern application server that embeds PHP directly. It is also affected by PHP2Shell and has its own update paths; details under Securing FrankenPHP.

How to check your server's SAPI

You can learn the SAPI of a website only through the web server, not through the command line. A small test file is enough:

<?php
// sapi-check.php: delete again immediately after calling it
header('Content-Type: text/plain');
echo PHP_SAPI, "\n", PHP_VERSION, "\n", php_ini_loaded_file(), "\n";

On the command line, the installed variants and services can be recorded read-only:

php -r 'echo PHP_SAPI, PHP_EOL;'          # always "cli"
ls /usr/sbin/php-fpm* 2>/dev/null           # installed FPM versions
systemctl list-units --type=service | grep -i -E "php|lsws|apache2|httpd"
apachectl -M 2>/dev/null | grep -i php     # mod_php loaded?

Why every SAPI can have its own php.ini

According to the PHP manual, PHP first looks for a file php-SAPI.ini, for example php-cli.ini, and only then for php.ini. Distributions such as Debian and Ubuntu go further and create separate folders per SAPI, for example /etc/php/8.3/fpm/ and /etc/php/8.3/cli/.

The timing differs as well: with server modules, according to the manual, PHP reads the configuration only once when the web server starts; with CGI and CLI, on every call. Anyone changing a setting must therefore know which SAPI is affected. More on this under The php.ini explained.

SAPI and security: what PHP2Shell has shown

According to the reports, PHP-FPM, Apache with mod_php, php-cgi, FrankenPHP and LiteSpeed are affected by PHP2Shell. The PHP team rates the risk highest for mod_php because an exploit was demonstrated there before application code runs. The reasons are given under Why mod_php carries the highest risk.

For operations, the SAPI above all means one thing: it determines what has to restart after the update.

1. PHP-FPM: all pools and workers of every installed version
2. mod_php: the entire Apache service, not just a reload
3. php-cgi and FastCGI setups: all remaining PHP processes
4. LiteSpeed: the web server's PHP processes according to the vendor's instructions
5. CLI: no permanent processes, but update the package as well so that checks are correct

In the medium term, moving away from mod_php is worthwhile. For new Apache installations, the PHP manual recommends PHP-FPM with mod_proxy_fcgi. The basics are described in PHP-FPM explained.

How does PHP SOS help?

• Record SAPIs: For each server we determine which operating modes and PHP versions are actually active.
• Restart correctly: Through the PHP patch service we update every SAPI and verify the restart of all processes.
• Map the configuration: We show which php.ini and which pool settings apply to your website.
• Plan the switch: Where mod_php or php-cgi is running, we plan and test the move to PHP-FPM.

Frequently asked questions

Sources

• PHP Manual: php_sapi_name()
• PHP Manual: The Configuration File
• PHP Manual: Apache 2.x on Unix Systems
• php.net: Security Announcements