PHP core - SAPI interface

SAPI: Server Application Programming Interface server-side application programming port. Students who have studied PHP architecture should know the importance of this stuff. It provides an interface that allows PHP to interact with other applications. This article will not introduce each PHP SAPI in detail, but will only explain the mechanism of SAPI for the simplest CGI SAPI.

Let’s take a look at the architecture diagram of PHP first:

SAPI refers to the programming interface for specific PHP applications. Just like a PC, no matter which operating system is installed, as long as it meets the PC interface specifications, it can be used on the PC To run properly, PHP scripts can be executed in many ways, through a web server, directly from the command line, or embedded in other programs.

Usually, we use web servers such as Apache or Nginx to test PHP scripts, or execute them through a PHP interpreter program on the command line. After the script is executed, the web server responds and the browser displays the response information or displays the content on the standard output of the command line.

We rarely care where the PHP interpreter is. Although executing scripts through a web server and a command-line program looks very different, the workflow is actually the same. The command line parameters are passed to the script to be executed by the PHP interpreter, which is equivalent to requesting a PHP page through the URL. After the script is executed, the response result is returned, but the response result of the command line is displayed on the terminal.

The script execution starts with the implementation of the SAPI interface. It's just that different SAPI interface implementations will complete their specific work. For example, Apache's mod_php SAPI implementation needs to initialize some information obtained from Apache, and return the content to Apache when outputting content. Other SAPI implementations are similar.

SAPI provides an interface for external communication. For PHP5.2, many kinds of SAPI are provided by default. The common ones are mod_php5 for Apache, CGI, ISAPI for IIS, and Shell CLI. This article will start with CGI SAPI. , introduce the mechanism of SAPI. Although CGI is simple, don't worry, it contains most of the content, enough to give you a deep understanding of how SAPI works.

To define a SAPI, first define a sapi_module_struct, check PHP-SRC/sapi/cgi/cgi_main.c:

*/
static sapi_module_struct cgi_sapi_module = {
#if PHP_FASTCGI
    "cgi-fcgi",                     /* name */
    "CGI/FastCGI",                  /* pretty name */
#else
    "cgi",                          /* name */
    "CGI",                          /* pretty name */
#endif
    php_cgi_startup,                /* startup */
    php_module_shutdown_wrapper,    /* shutdown */
    NULL,                           /* activate */
    sapi_cgi_deactivate,            /* deactivate */
    sapi_cgibin_ub_write,           /* unbuffered write */
    sapi_cgibin_flush,              /* flush */
    NULL,                           /* get uid */
    sapi_cgibin_getenv,             /* getenv */
    php_error,                      /* error handler */
    NULL,                           /* header handler */
    sapi_cgi_send_headers,          /* send headers handler */
    NULL,                           /* send header handler */
    sapi_cgi_read_post,             /* read POST data */
    sapi_cgi_read_cookies,          /* read Cookies */
    sapi_cgi_register_variables,    /* register server variables */
    sapi_cgi_log_message,           /* Log message */
    NULL,                           /* Get request time */
    STANDARD_SAPI_MODULE_PROPERTIES
};

This structure contains some constants, such as name, which will be used when we call php_info() used. Some initialization, closing functions, and some function pointers are used to tell Zend how to obtain and output data.

1. php_cgi_startup, when an application calls PHP, this function will be called. For CGI, it simply calls PHP’s initialization function:

static int php_cgi_startup(sapi_module_struct *sapi_module)
{
    if (php_module_startup(sapi_module, NULL, 0) == FAILURE) {
        return FAILURE;
    }
    return SUCCESS;
}

2. php_module_shutdown_wrapper, a shutdown function for PHP Simple packaging. Just simply call php_module_shutdown;

3. PHP will handle some initialization and resource allocation transactions at each request. This part is what the activate field is to be defined. From the above structure, we can see that for CGI, it does not provide an initialization handle. For mod_php5, it is different. He needs to register the resource destructor in the apache pool, apply for space, initialize environment variables, etc.

4. sapi_cgi_deactivate, this is the function corresponding to activate. As the name suggests, it will provide a handler to handle the finishing work. For CGI, it simply refreshes the buffer to ensure that the user gets the data before Zend is closed. All output data:

static int sapi_cgi_deactivate(TSRMLS_D)
{
    /* flush only when SAPI was started. The reasons are:
        1. SAPI Deactivate is called from two places: module init and request shutdown
        2. When the first call occurs and the request is not set up, flush fails on
            FastCGI.
    */
    if (SG(sapi_started)) {
        sapi_cgibin_flush(SG(server_context));
    }
    return SUCCESS;
}

5. sapi_cgibin_ub_write, this handler tells Zend how to output data. For mod_php5, this function provides an interface for writing response data, while for CGI, it simply writes stdout:

static inline size_t sapi_cgibin_single_write(const char *str, uint str_length TSRMLS_DC)
{
#ifdef PHP_WRITE_STDOUT
    long ret;
#else
    size_t ret;
#endif
#if PHP_FASTCGI
    if (fcgi_is_fastcgi()) {
        fcgi_request *request = (fcgi_request*) SG(server_context);
        long ret = fcgi_write(request, FCGI_STDOUT, str, str_length);
        if (ret <= 0) {
            return 0;
        }
        return ret;
    }
#endif
#ifdef PHP_WRITE_STDOUT
    ret = write(STDOUT_FILENO, str, str_length);
    if (ret <= 0) return 0;
    return ret;
#else
    ret = fwrite(str, 1, MIN(str_length, 16384), stdout);
    return ret;
#endif
}
static int sapi_cgibin_ub_write(const char *str, uint str_length TSRMLS_DC)
{
    const char *ptr = str;
    uint remaining = str_length;
    size_t ret;
    while (remaining > 0) {
        ret = sapi_cgibin_single_write(ptr, remaining TSRMLS_CC);
        if (!ret) {
            php_handle_aborted_connection();
            return str_length - remaining;
        }
        ptr += ret;
        remaining -= ret;
    }
    return str_length;
}

The real writing logic is stripped out in order to simply implement a fastcgi-compatible writing method.

6. sapi_cgibin_flush, this is the function handle provided to zend to refresh the cache. For CGI, it is just a simple call to fflush provided by the system;

7.NULL, this part is used to allow Zend to verify a script to be executed. The state of the file, so as to determine whether the file has execution permissions, etc., is not provided by CGI.

8. sapi_cgibin_getenv provides Zend with an interface to find environment variables based on name. For mod_php5, when we call getenv in the script, this handle will be called indirectly. For CGI, because its operating mechanism is very similar to CLI, the direct call parent is Shell, so it simply calls the genenv provided by the system:

static char *sapi_cgibin_getenv(char *name, size_t name_len TSRMLS_DC)
{
#if PHP_FASTCGI
    /* when php is started by mod_fastcgi, no regular environment
       is provided to PHP.  It is always sent to PHP at the start
       of a request.  So we have to do our own lookup to get env
       vars.  This could probably be faster somehow.  */
    if (fcgi_is_fastcgi()) {
        fcgi_request *request = (fcgi_request*) SG(server_context);
        return fcgi_getenv(request, name, name_len);
    }
#endif
    /*  if cgi, or fastcgi and not found in fcgi env
        check the regular environment */
    return getenv(name);
}

9. php_error, error handling function, here, say A few digressions, last time I saw the PHP maillist mentioned that PHP's error handling mechanism is completely OO, that is, rewriting this function handle so that whenever an error occurs, an exception will be thrown. CGI simply calls the error handling function provided by PHP.

10. This function will be called when we call PHP's header() function, which is not provided for CGI.

11. sapi_cgi_send_headers, this function will be called when the header is actually sent, generally speaking, before any output is to be sent:

static int sapi_cgi_send_headers(sapi_headers_struct *sapi_headers TSRMLS_DC)
{
    char buf[SAPI_CGI_MAX_HEADER_LENGTH];
    sapi_header_struct *h;
    zend_llist_position pos;
    if (SG(request_info).no_headers == 1) {
        return  SAPI_HEADER_SENT_SUCCESSFULLY;
    }
    if (cgi_nph || SG(sapi_headers).http_response_code != 200)
    {
        int len;
        if (rfc2616_headers && SG(sapi_headers).http_status_line) {
            len = snprintf(buf, SAPI_CGI_MAX_HEADER_LENGTH,
                           "%s\r\n", SG(sapi_headers).http_status_line);
            if (len > SAPI_CGI_MAX_HEADER_LENGTH) {
                len = SAPI_CGI_MAX_HEADER_LENGTH;
            }
        } else {
            len = sprintf(buf, "Status: %d\r\n", SG(sapi_headers).http_response_code);
        }
        PHPWRITE_H(buf, len);
    }
    h = (sapi_header_struct*)zend_llist_get_first_ex(&sapi_headers->headers, &pos);
    while (h) {
        /* prevent CRLFCRLF */
        if (h->header_len) {
            PHPWRITE_H(h->header, h->header_len);
            PHPWRITE_H("\r\n", 2);
        }
        h = (sapi_header_struct*)zend_llist_get_next_ex(&sapi_headers->headers, &pos);
    }
    PHPWRITE_H("\r\n", 2);
    return SAPI_HEADER_SENT_SUCCESSFULLY;
   }

12. NULL, this is used to send each header individually, CGI Not provided

13. sapi_cgi_read_post, 这个句柄指明了如何获取POST的数据，如果做过CGI编程的话，我们就知道CGI是从stdin中读取POST DATA的：

static int sapi_cgi_read_post(char *buffer, uint count_bytes TSRMLS_DC)
{
    uint read_bytes=0, tmp_read_bytes;
#if PHP_FASTCGI
    char *pos = buffer;
#endif
    count_bytes = MIN(count_bytes, (uint) SG(request_info).content_length - SG(read_post_bytes));
    while (read_bytes < count_bytes) {
#if PHP_FASTCGI
        if (fcgi_is_fastcgi()) {
            fcgi_request *request = (fcgi_request*) SG(server_context);
            tmp_read_bytes = fcgi_read(request, pos, count_bytes - read_bytes);
            pos += tmp_read_bytes;
        } else {
            tmp_read_bytes = read(0, buffer + read_bytes, count_bytes - read_bytes);
        }
#else
        tmp_read_bytes = read(0, buffer + read_bytes, count_bytes - read_bytes);
#endif
        if (tmp_read_bytes <= 0) {
            break;
        }
        read_bytes += tmp_read_bytes;
    }
    return read_bytes;
}

14. sapi_cgi_read_cookies, 这个和上面的函数一样，只不过是去获取cookie值：

static char *sapi_cgi_read_cookies(TSRMLS_D)
{
   return sapi_cgibin_getenv((char *) "HTTP_COOKIE", sizeof("HTTP_COOKIE")-1 TSRMLS_CC);
}
15. sapi_cgi_register_variables, 这个函数给了一个接口，用以给$_SERVER变量中添加变量，对于CGI来说，注册了一个PHP_SELF,这样我们就可以在脚本中访问$_SERVER['PHP_SELF']来获取本次的request_uri：
static void sapi_cgi_register_variables(zval *track_vars_array TSRMLS_DC)
{
   /* In CGI mode, we consider the environment to be a part of the server
    * variables
    */
   php_import_environment_variables(track_vars_array TSRMLS_CC);
   /* Build the special-case PHP_SELF variable for the CGI version */
   php_register_variable("PHP_SELF", (SG(request_info).request_uri ? SG(request_info).request_uri : ""), track_vars_array TSRMLS_CC);
}
16. sapi_cgi_log_message ，用来输出错误信息，对于CGI来说，只是简单的输出到stderr：
static void sapi_cgi_log_message(char *message)
{
#if PHP_FASTCGI
   if (fcgi_is_fastcgi() && fcgi_logging) {
       fcgi_request *request;
       TSRMLS_FETCH();

       request = (fcgi_request*) SG(server_context);
       if (request) {
           int len = strlen(message);
           char *buf = malloc(len+2);

           memcpy(buf, message, len);
           memcpy(buf + len, "\n", sizeof("\n"));
           fcgi_write(request, FCGI_STDERR, buf, len+1);
           free(buf);
       } else {
           fprintf(stderr, "%s\n", message);
       }
       /* ignore return code */
   } else
#endif /* PHP_FASTCGI */
   fprintf(stderr, "%s\n", message);
}

经过分析，我们已经了解了一个SAPI是如何实现的了， 分析过CGI以后，我们也就可以想象mod_php5, embed等SAPI的实现机制。