[Translation] [php extension development and embedded] Chapter 19 - Setting up the hosting environment

Set up the hosting environment

Now you have an understanding of the world of PHPAPI and can use zval as well The language's internal extension mechanism performs a lot of work, and it's time to shift gears and use it to do what it does best: interpret script code.

Embedded SAPI

In the review introduction, PHP has built a hierarchical system. The top layer provides all extensions of user space functions and class libraries. At the same time, below it is the service API (SAPI) layer, which plays the role of The interface of webserver (such as apache, iis and command line interface cli).

Among these many sapi implementations, there is a special sapi which is the embedded sapi. When this sapi implementation is built , will create a library object that contains all the PHP and Zend API functions and variables you know. This library object also contains some additional helper functions and macros to simplify calling external programs.

Generating libraries and header files for embedded APIs performs the same actions as compiling other sapis. Just pass --enable-embed to the ./configure command. As before, use --enable- debug is helpful for error reporting and tracking.

You may also need to turn on --enable-maintainer-zts, of course, for reasons you are already familiar with, it will help you notice the code Error, however, there are other reasons here. Assume that at a certain moment, you have multiple applications using the PHP embedded library to perform script tasks; one of the applications is a simple short-life cycle, and it does not use threads, so for efficiency you You may want to turn off ZTS.

Now assume that the second application uses threads, such as a webserver, and each thread needs to track its own request context. If ZTS is turned off, only the first Two applications can use this library; however, if ZTS is turned on, both applications can use the same shared object in their own process space.

Of course, you can also build both at the same time versions, and giving them different names, but this is more of a problem than the small efficiency hit of including ZTS when it is not needed.

By default , the embedded library will be built as a libphp5.so shared object, or a dynamic link library under Windows, however, it may also be built as a static library using the optional static keyword (--enable-embed=static).

Building as a static library avoids ZTS/non-ZTS issues and potentially having multiple php versions on a system. The risk is that this means your As a result, the application binary will become significantly larger, and it will host the entire ZendEngine and PHP frameworks. Therefore, when choosing, you need to carefully consider whether you need a relatively smaller library.

No matter which build method you choose, once you execute make install, libphp5 will be copied to the lib/ directory under the PREFIX directory specified by your ./configure. In addition, it will also be in PREFIX/include/php/sapi/embed Put the header file named php_embed.h in the directory, as well as several other important header files you need when using the php embedded library to compile the program.

Build And compile a host application

#At its core, a library is just a collection of code without a purpose. In order for it to work, you need an application that embeds PHP. First , let’s encapsulate a very simple application, which starts the Zend engine and initializes PHP to process a request, and then goes back to clean up resources.

#include <sapi/embed/php_embed.h>

int main(int argc, char *argv[])
{
    PHP_EMBED_START_BLOCK(argc,argv)
    PHP_EMBED_END_BLOCK()

    return 0;
}

Since this involves a lot of header files, the build actually takes longer than it normally would for such a small snippet. It takes time. If you use PREFIX different from the default path (/usr/local), please make sure to specify the path in the following way:

gcc -I /usr/local/php-dev/include/php/ \
	-I /usr/local/php-dev/include/php/main/ \
	-I /usr/local/php-dev/include/php/Zend/ \
	-I /usr/local/php-dev/include/php/TSRM/ \
	-lphp5 \
	-o embed1 
	embed1.c

Since this command will be entered every time It's very troublesome, you may prefer to use a simple Makefile instead:

CC = gcc 
CFLAGS = -c \
    -I /usr/local/php-dev/include/php/ \
    -I /usr/local/php-dev/include/php/main/ \
    -I /usr/local/php-dev/include/php/Zend/ \
    -I /usr/local/php-dev/include/php/TSRM/ \
    -Wall -g
LDFLAGS = -lphp5

all: embed1.c
    $(CC) -o embed1.o embed1.c $(CFLAGS)
    $(CC) -o embed1 embed1.o $(LDFLAGS)

This Makefile There are some important differences from the previously provided commands. First, it turns on compile-time warnings with the -Wall switch, and turns on debugging information with -g. In addition, it divides the compilation and linking phases into two independent phases. , so that it is relatively easy to add more source files later. Please reorganize this Makefile yourself, but the alignment used here is Tab (horizontal tab character) instead of spaces.

Now, after you modify the embed1.c source file, you only need to execute a make command to build a new embed1 executable program.

Recreate cli by embedding wrapper

Now that PHP is accessible in your application, it’s time to make it do some stuff. The rest of this chapter is the core It revolves around re-creating the cli sapi in this test application framework.

It's very simple. The most basic function of the cli binary program is to specify the name of a script on the command line, which is processed by php Its interpretation and execution. Replace the content of your embed1.c with the following code to implement cli in your application.

#include <stdio.h>
#include <sapi/embed/php_embed.h>

int main(int argc, char *argv[]) {
    zend_file_handle    script;

    /* 基本的参数检查 */
    if ( argc <= 1 ) {
        fprintf(stderr, "Usage: %s <filename.php> <arguments>\n", argv[0]);
        return -1;
    }
    
    /* 设置一个文件处理结构 */
    script.type             = ZEND_HANDLE_FP;
    script.filename         = argv[1];
    script.opened_path      = NULL;
    script.free_filename    = 0;
    if ( !(script.handle.fp = fopen(script.filename, "rb")) ) {
        fprintf(stderr, "Unable to open: %s\n", argv[1]);
        return -1;
    }
    
    /* 在将命令行参数注册给php时(php中的$argv/$argc), 忽略第一个命令行参数, 因为它对php脚本无意义 */
    argc --;
    argv ++;
    
    PHP_EMBED_START_BLOCK(argc, argv)
        php_execute_script(&script TSRMLS_CC);
    PHP_EMBED_END_BLOCK()
    
    return 0;
}

Translation Note: The code in the original work cannot be run directly in the translator's environment. The above code has been modified.

Of course, You need a file to test it, create a small php script, name it test.php, and execute it from the command line using your embed program:

$ ./embed1 test.php

If you passed other arguments to the command line, you can see them in your php script using $_SERVER['argc']/$_SERVER['argv'].

You may have noticed that the code between PHP_EMBED_START_BLOCK() and PHP_EMBED_END_BLOCK() is indented. This detail is because these two macros actually form a Code block scope in C language. That is to say, PHP_EMBED_START_BLOCK() contains an opening curly brace "{", and there is a corresponding closing curly brace "}" in PHP_EMBED_END_BLOCK(). A very important issue in doing so is They cannot be put into separate start/stop functions. You will see the solution to this problem in the next chapter.

##After PHP_EMBED_START_BLOCK() is called, your application is at the beginning of a PHP request cycle, which is equivalent to after the RINIT callback function is completed. At this point you can execute the same as before The php_execute_script() command, or any other valid, php/Zend API directive that can appear within a PHP_FUNCTION() or RINIT() block.

第2章"变量的里里外外"中介绍了操纵符号表的概念, 第5至18章则介绍了怎样通过用户空间脚本调用内部函数使用这些技术. 到这里这些处理也并没有发生变化, 虽然这里并没有激活的用户空间脚本, 但是你的包装应用仍然可以操纵符号表. 将你的PHP_EMBED_START_BLOCK()/PHP_EMBED_END_BLOCK()代码块替换为下面的代码:

    PHP_EMBED_START_BLOCK(argc, argv)
        zval    *type;

        ALLOC_INIT_ZVAL(type);
        ZVAL_STRING(type, "Embedded", 1);
        ZEND_SET_SYMBOL(&EG(symbol_table), "type", type);
        
        php_execute_script(&script TSRMLS_CC);
    PHP_EMBED_END_BLOCK()

现在使用make重新构建embed1, 并用下面的测试脚本进行测试:

<?php
	var_dump($type);
?>

当然, 这个简单的概念可以很容易的扩展为填充这个类型信息到$_SERVER超级全局变量数组中.

    PHP_EMBED_START_BLOCK(argc, argv)
        zval    **SERVER_PP, *type;

        /* 注册$_SERVER超级全局变量 */
        zend_is_auto_global_quick("_SERVER", sizeof("_SERVER") - 1, 0 TSRMLS_CC);
        /* 查找$_SERVER超级全局变量 */
        zend_hash_find(&EG(symbol_table), "_SERVER", sizeof("_SERVER"), (void **)&SERVER_PP) ;

        /* $_SERVER['SAPI_TYPE'] = "Embedded"; */
        ALLOC_INIT_ZVAL(type);
        ZVAL_STRING(type, "Embedded", 1);
        ZEND_SET_SYMBOL(Z_ARRVAL_PP(SERVER_PP), "SAPI_TYPE", type);

        php_execute_script(&script TSRMLS_CC);
    PHP_EMBED_END_BLOCK()

译注: 译者的环境中代码运行到zend_hash_find()处$_SERVER尚未注册, 经过跟踪, 发现它是直到编译用户空间代码的时候, 发现用户空间使用了$_SERVER变量才进行的注册. 因此, 上面的代码中增加了zend_is_auto_global_quick()的调用, 通过这个调用将完成对$_SERVER的注册.

覆写INI选项

在第13章"INI设置"中, 有一部分是讲INI修改处理器的, 在那里看到的是INI阶段的处理. PHP_EMBED_START_BLOCK()宏则将这些代码放到了运行时阶段. 也就是说这个时候修改某些设置(比如register_globals/magic_quotes_gpc)已经有点迟了.

不过在内部访问也没有什么不好. 所谓的"管理设置"比如safe_mode在这个略迟的阶段可以使用下面的zend_alter_ini_entry()命令打开或关闭:

int zend_alter_ini_entry(char *name, uint name_length,
                         char *new_value, uint new_value_length,
                         int modify_type, int stage);

name, new_value以及它们对应的长度参数的含义正如你所预期的: 修改名为name的INI设置的值为new_value. 要注意name_length包含了末尾的NULL字节, 然而new_value_length则不包含; 然而, 无论如何, 两个字符串都必须是NULL终止的.

modify_type则提供简化的访问控制检查. 回顾每个INI设置都有一个modifiable属性, 它是PHP_INI_SYSTEM, PHP_INI_PERDIR, PHP_INI_USER等常量的组合值. 当使用zend_alter_ini_entry()修改INI设置时, modify_type参数必须包含至少一个INI设置的modifiable属性值.

用户空间的ini_set()函数通过传递PHP_INI_USER利用了这个特性, 也就是说只有modifiable属性包含PHP_INI_USER标记的INI设置才能使用这个函数修改. 当在你的嵌入式应用中使用这个API调用时, 你可以通过传递PHP_INI_ALL标记短路这个访问控制系统, 它将包含所有的INI访问级别.

stage必须对应于Zend Engine的当前状态; 对于这些简单的嵌入式示例, 总是PHP_INI_STAGE_RUNTIME. 如果这是一个扩展或更高端的嵌入式应用, 你可能就需要将这个值设置为PHP_INI_STAGE_STARTUP或PHP_INI_STAGE_ACTIVE.

下面是扩展embed1.c源文件, 让它在执行脚本文件之前强制开启safe_mode.

    PHP_EMBED_START_BLOCK(argc, argv)
        zval    **SERVER_PP, *type;

        /* 不论php.ini中如何设置都强制开启safe_mode */
        zend_alter_ini_entry("safe_mode", sizeof("safe_mode"), "1", sizeof("1") - 1, PHP_INI_ALL, PHP_INI_STAGE_RUNTIME);
        
        /* 注册$_SERVER超级全局变量 */
        zend_is_auto_global_quick("_SERVER", sizeof("_SERVER") - 1, 0 TSRMLS_CC);
        /* 查找$_SERVER超级全局变量 */
        zend_hash_find(&EG(symbol_table), "_SERVER", sizeof("_SERVER"), (void **)&SERVER_PP) ;
        
        /* $_SERVER['SAPI_TYPE'] = "Embedded"; */
        ALLOC_INIT_ZVAL(type);
        ZVAL_STRING(type, "Embedded", 1);
        ZEND_SET_SYMBOL(Z_ARRVAL_PP(SERVER_PP), "SAPI_TYPE", type);
        
        php_execute_script(&script TSRMLS_CC);
    PHP_EMBED_END_BLOCK()

定义附加的超级全局变量

在第12章"启动, 终止, 以及其中的一些点"中, 你知道了用户空间全局变量以及超级全局变量可以在启动(MINIT)阶段定义. 同样, 本章介绍的嵌入式直接跳过了启动阶段, 处于运行时状态. 和覆写INI一样, 这并不会显得太迟.

超级全局变量的定义实际上只需要在脚本编译之前定义即可, 并且在php的进程生命周期中它只应该出现一次. 在扩展中的正常情况下, MINIT是唯一可以保证这些条件的地方.

由于你的包装应用现在是在控制中的, 因此可以保证定义用户空间自动全局变量的这些点位于真正编译脚本源文件的php_execute_script()命令之前. 我们定义一个$_EMBED超级全局变量并给它设置一个初始值来进行测试:

    PHP_EMBED_START_BLOCK(argc, argv)
        zval    **SERVER_PP, *type, *EMBED, *foo;

        /* 在全局作用域创建$_EMBED数组 */
        ALLOC_INIT_ZVAL(EMBED);
        array_init(EMBED);
        ZEND_SET_SYMBOL(&EG(symbol_table), "_EMBED", EMBED);

        /* $_EMBED['foo'] = 'Bar'; */
        ALLOC_INIT_ZVAL(foo);
        ZVAL_STRING(foo, "Bar", 1); 
        add_assoc_zval_ex(EMBED, "foo", sizeof("foo"), foo);

        /* 注册超级全局变量$_EMBED */
        zend_register_auto_global("_EMBED", sizeof("_EMBED")
#ifdef ZEND_ENGINE_2
            , 1, NULL TSRMLS_CC);
#else
            , 1 TSRMLS_CC);
#endif

        /* 不论php.ini中如何设置都强制开启safe_mode */
        zend_alter_ini_entry("safe_mode", sizeof("safe_mode"), "1", sizeof("1") - 1, PHP_INI_ALL, PHP_INI_STAGE_RUNTIME);

        /* 注册$_SERVER超级全局变量 */
        zend_is_auto_global_quick("_SERVER", sizeof("_SERVER") - 1, 0 TSRMLS_CC);
        /* 查找$_SERVER超级全局变量 */
        zend_hash_find(&EG(symbol_table), "_SERVER", sizeof("_SERVER"), (void **)&SERVER_PP) ;

        /* $_SERVER['SAPI_TYPE'] = "Embedded"; */
        ALLOC_INIT_ZVAL(type);
        ZVAL_STRING(type, "Embedded", 1); 
        ZEND_SET_SYMBOL(Z_ARRVAL_PP(SERVER_PP), "SAPI_TYPE", type);

        php_execute_script(&script TSRMLS_CC);
    PHP_EMBED_END_BLOCK()

要记住, Zend Engine 2(php 5.0或更高)使用了不同的zend_register_auto_global()元婴, 因此你需要用前面讲php 4兼容时候讲过的#ifdef. 如果你不关心旧版本php的兼容性, 则可以丢弃这些指令让代码变得更加整洁.

小结

如你所见, 将完整的Zend Engine和PHP语言嵌入到你的应用中相比如扩展新功能来说工作量要少. 由于它们共享相同的基础API, 我们可以学习尝试让其他实例可访问.

通过本章的学习, 你了解了最简单的嵌入式脚本代码格式, 同时还有all-in-one的宏PHP_EBED_START_BLOCK()和PHP_EMBED_END_BLOCK(). 下一章你将回到这些宏的层的使用, 利用它们将php和你的宿主系统结合起来.

以上就是[翻译][php扩展开发和嵌入式]第19章-设置宿主环境的内容，更多相关内容请关注PHP中文网（www.php.cn）！