A Use for the SAPI in PHP

Every PHP program uses a specific ‘Server API’, or SAPI for short. The SAPI indicates the interface that PHP uses to communicate with its environment, e.g. if PHP is running via a web-server or something else. In this brief article I will explain a little about it and how it can be useful.

Types of SAPIs

The function php_sapi_name() returns a string indicating the SAPI that PHP is using. Here are some examples of the SAPI names it returns:

There’s more than that. But thankfully there is no reason to memorize them. All we need to remember is that php_sapi_name() will tell us the environment PHP is interacting with. So if we are running a PHP program via the Apache web-server then the function will return apache.

(Note: We may get a different value depending on the version and configuration of Apache.)

Instead of calling the php_sapi_name() function you can use the PHP_SAPI constant, which may be equal to any of the values in the list above, as well as the values I did not mention. I prefer to use the PHP_SAPI constant because it reflects the fact that the SAPI cannot change during the execution of a program.

But how is discriminating against the SAPI useful?

Command-Line Programs

I know some readers are thinking, “Why in the Hell would you ever write a command-line application in PHP?” There are valid reasons.

I only want that program to run from the command-line. Or to put it another way, I do not want my web-server to execute the script. I can test the value of the SAPI to determine whether or not the user invoked the script from the command-line. For example, I can put this test in my code:

if (PHP_SAPI !== "cli")
{
        exit(1);
}

Now the program will exit if not invoked from the command-line. Note that simply writing exit() would represent successful execution; to indicate an error requires using a non-zero exit value.

However, this test is not foolproof. It is possible for a web server to run a PHP program in such a way that the SAPI is cli. In that situation the web server will fill the $_SERVER global with various values. A useful one to test is SERVER_NAME. For example I can rewrite the test above like this:

if (PHP_SAPI !== "cli" && $_SERVER["SERVER_NAME"] !== NULL)
{
        exit(1);
}

A web-server which claims to use the cli SAPI will have a non-null value for SERVER_NAME. A PHP program that I run directly from the command-line will have a null server name. That provides an extra level of assurance that the program is running via the command-line as expected.

Conclusion

So is it useful to examine the SAPI for PHP programs? Often it’s not. But if we want to restrict a script to a specific interface then checking the value of the SAPI is a simple and effective approach.

We will rarely need to perform these tests, but when we do it’s easy.

Advertisements

Add Your Thoughts

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s