SAPIs

SAPIs provide the glue for interfacing PHP into an application. They define the ways in which data is passed between an application and PHP.

The following sections provide an in-depth look at a moderately simple SAPI, the PHP CGI SAPI, and the embed SAPI, for embedding PHP into an application with minimal custom needs.

The CGI SAPI

The CGI SAPI provides a good introduction to how SAPIs are implemented. It is simple, in that it does not have to link against complicated external entities as mod_php does. Despite this relative simplicity, it supports reading in complex environment information, including POST, GET, and cookie data. This import of environmental information is one of the major duties of any SAPI implementation, so it is important to understand it.

The defining structure in a SAPI is sapi_module_struct, which defines all the ways that the SAPI can bridge PHP and the environment so that it can set environment and query variables. sapi_module_struct is a collection of details and function pointers that tell the SAPI how to hand data to and from PHP. It is defined as follows:

Notice that the last 14 fields of the struct have been replaced with the macro STANDARD_SAPI_PROPERTIES. This common technique used by SAPI authors takes advantage of the C language semantic of defining omitted struct elements in a declaration as NULL.

The first two fields in the struct are the name of the SAPI. These are what is returned when you call phpinfo() or php_sapi_name() from a script.

The third field is the function pointer sapi_module_struct.startup. When an application implementing a PHP SAPI is started, this function is called. An important task for this function is to bootstrap the rest of the loading by calling php_module_startup() on its module details. In the CGI module, only the bootstrapping procedure is performed, as shown here:

The fourth element, sapi_module_struct.shutdown, is the corresponding function called when the SAPI is shut down (usually when the application is terminating). The CGI SAPI (like most of the SAPIs that ship with PHP) calls php_module_shutdown_wrapper as its shutdown function. This simply calls php_module_shutdown, as shown here:

As described in Chapter 20, "PHP and Zend Engine Internals," on every request, the SAPI performs startup and shutdown calls to clean up its running environment and to reset any resources it may require. These are the fifth and sixth sapi_module_struct elements. The CGI SAPI does not define sapi_module_struct.activate, meaning that it registers no generic request-startup code, but it does register sapi_module_struct.deactivate. In deactivate, the CGI SAPI flushes its output file streams to guarantee that the end user gets all the data before the SAPI closes its end of the socket. The following are the deactivation code and the flush helper function:

Note that stdout is explicitly flushed; this is because the CGI SAPI is hard-coded to send output to stdout.

A SAPI that implements more complex activate and deactivate functions is the Apache module mod_php. Its activate function registers memory cleanup functions in case Apache terminates the script prematurely (for instance, if the client clicks the Stop button in the browser or the script exceeds Apache's timeout setting).

The seventh element, sapi_module_struct.ub_write, provides a callback for how PHP should write data to the user when output buffering is not on. This is the function that will actually send the data when you use print or echo on something in a PHP script. As mentioned earlier, the CGI SAPI writes directly to stdout. Here is its implementation, which writes data in 16KB chunks:

This method writes each individual character separately, which is inefficient but very cross-platform portable. On systems that support POSIX input/output, you could as easily consolidate this function into the following:

The eighth element is sapi_module_struct.flush, which gives PHP a way to flush its stream buffers (for example, when you call flush() within a PHP script). This uses the function sapi_cgibin_flush, which you saw called earlier from within the deactivate function.

The ninth element is sapi_module_struct.get_stat. This provides a callback to override the default stat() of the file performed to ensure that the script can be run in safe mode. The CGI SAPI does not implement this hook.

The tenth element is sapi_module_struct.getenv.getenv provides an interface to look up environment variables by name. Because the CGI SAPI runs akin to a regular user shell script, its sapi_cgibin_getenv() function is just a simple gateway to the C function getenv(), as shown here:

In more complex applications, such as mod_php, the SAPI should implement sapi_module_struct.getenv on top of the application's internal environment facilities.

The eleventh element is the callback sapi_module_struct.sapi_error. This sets the function to be called whenever a userspace error or an internal call to zend_error() occurs. Most SAPIs set this to php_error, which is the built-in PHP error handler.

The twelfth element is sapi_module_struct.header_handler. This function is called anytime you call header() inside code or when PHP sets its own internal headers. The CGI SAPI does not set its own header_handler, which means that it falls back on the default SAPI behavior, which is to append it to an internal list that PHP manages. This callback is mainly used in Web server SAPIs such as mod_php, where the Web server wants to maintain the headers itself instead of having PHP do so.

The thirteenth element is sapi_module_struct.send_headers. This is called when it is time to send all the headers that have been set in PHP (that is, immediately before the first content is sent). This callback can choose to send all the headers itself, in which case it returns SAPI_HEADER_SENT_SUCCESSFULLY, or it can delegate the task of sending individual headers to the fourteenth sapi_module_struct element, send_header, in which case it should return SAPI_HEADER_DO_SEND. The CGI SAPI chooses the first methodology and writes all its headers in a send_headers function, defined as follows:

PHPWRITE_H is a macro wrapper that handles output buffering, which might potentially be on.

The fifteenth element is sapi_module_struct.read_post, which specifies how POST data should be read. The function is passed a buffer and a buffer size, and it is expected to fill out the buffer and return the length of the data within. Here is the CGI SAPI's implementation, which simply reads up to the specified buffer size of data from stdin (file descriptor 0):

Note that no parsing is done here: read_post only provides the facility to read in raw post data. If you want to modify the way PHP parses POST data, you can do so in sapi_module_struct.default_post_reader, which is covered later in this chapter, in the section "SAPI Input Filters."

The sixteenth element is sapi_module_struct.read_cookies. This performs the same function as read_post, except on cookie data. In the CGI specification, cookie data is passed in as an environment variable, so the CGI SAPI cookie reader just uses the getenv callback to extract it, as shown here:

Next comes sapi_module_struct.register_server_variables. As the name implies, this function is passed in what will become the $_SERVER autoglobal array, and the SAPI has the option of adding elements to the array. The following is the top-level register_server_variables callback for the CGI SAPI:

This calls php_import_environment_variables(), which loops through all the shell environment variables and creates entries for them in $_SERVER. Then it sets $_SERVER['PHP_SELF'] to be the requested script.

The last declared element in the CGI module is sapi_module_struct.log_message. This is a fallback function when no other error logging facility is specified. If error_log is not set in the php.ini file, then this is the function that will be called to print out any errors you receive. The CGI module implements this by printing to stderr, as follows:

We've now covered the standard sapi_module_struct elements. The filtering callbacks default_post_reader, treat_data, and input_filter are covered later in this chapter, in the section "SAPI Input Filters." The others are special-purpose elements that are not covered here.

The CGI SAPI Application

You need to incorporate the CGI SAPI into an application that can actually run it. The actual CGI main() routine is very long, as it supports a wide variety of options and flags. Instead of covering that (which could easily take an entire chapter), this section provides a very stripped-down version of the main() routine that implements no optional flags. Here is the stripped-down version of the CGI main() routine:

The following is the helper function init_request_info(), which sets the SAPI globals for script locations and query string parameters from the environment as per the CGI specification:

Call sapi_startup(&cgi_sapi_module). This sets up all the default SAPI structures.
Call php_module_startup(&cgi_sapi_module, NULL, 0). This actually loads, initializes, and registers this SAPI.
Call init_request_info(). This function sets the necessary SAPI global's request_info values from the environment. This is how the CGI SAPI knows what file you want to execute and what parameters are being passed to it. Every SAPI implements this differently. For example, mod_php extracts all this information from the Apache request_rec data structure.
Initialize zend_file_handle with the location of the script to execute.
Call php_request_startup(). This function does a large amount of work: It initializes the output buffering system for the request, creates all autoglobal variables, calls the RINIT hooks of all registered extensions, and calls the activate callback for the SAPI.
Open and execute the script with php_fopen_primary_script(&file_handle TSRMLS_CC) and php_execute_script(&file_handle TSRMLS_CC). Technically, it is not necessary to open the script, but doing so allows an easy way to check whether the script actually exists. When php_execute_script() returns, the script has completed.
Call php_request_shutdown((void *) 0) to complete the request. This calls the RSHUTDOWN hooks for modules, calls the deactivate callback registered by the SAPI, and ends output buffering and sends all data to the client.
Call php_module_shutdown. This shuts down the SAPI permanently because the CGI SAPI serves only a single request per invocation.
Call sapi_shutdown(). This performs final cleanup of the SAPI environment.

This is the complete process of embedding the PHP interpreter into an application, using the SAPI interface.

The Embed SAPI

The CGI SAPI seems like quite a bit of work, but the majority of it involves handling automatic importing of data from the caller's environment. PHP goes to great trouble to allow transparent access to user environment data, and much of that work has to be done in the SAPI implementation.

If your goals are less ambitious than full custom PHP integration and you only want to execute PHP code as part of an application, the embed SAPI may be the right solution for you. The embed SAPI exposes PHP as a shared library that you can link against and run code.

To build the embed library, you need to compile PHP with the following configuration line:

Inside the block defined by those macros is a running PHP environment where you can execute scripts with this:

As an example of just how simple this is, here is a working PHP shell that interactively executes anything you pass to it:

Note that the embed SAPI sets the $argc and $argv autoglobals from what is passed to PHP_EMBED_START_BLOCK(). Check out the following psh session:

This is a toy example in that psh is pretty featureless, but it demonstrates how you can leverage all of PHP in under 15 lines of C. Later in this chapter you will use the embed SAPI to build a more significant application: the opcode dumper described in Chapter 20.

SAPI Input Filters

In Chapter 13, "User Authentication and Session Security," you learned a bit about cross-site scripting and SQL injection attacks. Although they manifest differently, both attacks involve getting a Web application to accidentally execute (or in the case of cross-site scripting, getting a third-party user to execute) malicious code in your application's space.

The solution to all attacks of this sort is simple: You must be fanatical about validating and sanitizing any input a user gives you. The responsibility for this sanitization process lies with the developer, but leaving it at that can be unsatisfactory for two reasons:

To help address this issue, the SAPI interface provides a set of three callbacks that can be used to automatically sanitize data on every incoming request: input_filter, treat_data, and default_post_reader. Because they are registered at the SAPI level, they are invisible to the developer and are executed automatically. This makes it impossible to forget to apply them on a page. Further, because they are implemented in C and occur before data is inserted into the autoglobal arrays, the implementations can be much faster than anything written in PHP.

The most useful of the filter callbacks is sapi_module_struct.input_filter. A registered input_filter callback is called on the input to be populated into the auto-globals $_POST, $_GET, and $_COOKIE before the input data is actually inserted into the arrays. An input_filter callback provides a blanket mechanism for sanitizing all user-submitted data before it is available to userspace code.

This section describes an input_filter that removes all HTML from POST, GET, and COOKIE data using the C code from the strip_tags() PHP function. This is a variation of the input_filter example in the PHP distribution, with a few extra bells and whistles. A new set of autoglobal arrays$_RAW_POST, $_RAW_GET, and $_RAW_COOOKIEis created, and the original contents of each variable are placed in that new array, with the cleaned data going into the standard arrays. That way, if a developer needs access to the original source, he or she can still have access to it, but the standard arrays will be free of HTML.

Input filters of all kinds can be registered post-SAPI startup, and this one is implemented as an extension. This is nice because it means you do not have to actually modify the code of the SAPI you use.

First is the standard module header. You add a global zval * for each of the new autoglobal arrays you are creating. Here is the code for this:

This is largely a standard module. There are two new things to notice, though. The first is that you call this in the MINIT phase to register the new $_RAW arrays as autoglobals:

The second is that you register raw_filter as a SAPI input filter in MINIT via the following call:

When raw_filter is called, it looks to see whether the appropriate $_RAW array exists, and if it does not, it creates it. It then assigns a copy of the original value of *val into that array. Next, it removes all the HTML tags from *val by using php_strip_tags() (the C underpinning of the PHP function strip_tags()) and sets the new (possibly shortened) length of *val.

Although the input_filter callback allows you to modify incoming variables, it does not give you complete control of the variable import process. For example, it does not allow you to avoid inserting certain variables or to change the way they are parsed from their raw form.

If you need more control, you can use two other hooks that the SAPI interface provides:

sapi_module_struct.treat_data is called by the engine when it parses the raw POST, COOKIE, and GET query string data. The default implementation breaks the raw data into key/value pairs, sanitizes the values with any registered input_filter callbacks, and inserts the values into the appropriate symbol tables.

sapi_module_struct.default_post_reader is called to parse any POST data that does not have a content type handler already associated with it. The default action is to simply swallow the entire POST contents into $HTTP_RAW_POST_DATA. If, for instance, you need to ban certain file types from ever being uploaded under any circumstances, defining a custom sapi_module_struct.default_post_reader callback might make sense.

Like input_filter, both of these callbacks can be registered at runtime in extensions by using the sapi_register_treat_data() and sapi_register_default_post_reader() functions. In general, though, these are both very special-purpose functions. In most cases, an input_filter callback can meet your needs.