[Translation] [php extension development and embedded] Chapter 18 - Automatic generation of php extensions

Extension generation

As you have undoubtedly noticed, every php extension contains some Very common and very monotonous structures and files. When starting the development of a new extension, it makes sense to only think about filling in the functional code if these common structures already exist. For this purpose, a Simple but very useful shell script.

ext_skel

Switch to your php source code tree ext/ In the directory, execute the following command:

jdoe@devbox:/home/jdoe/cvs/php-src/ext/$ ./ext_skel extname=sample7

Wait a moment and output some text. You will see the following output:

To use your new extension, you will have to execute the following steps:

1.  $ cd ..
2.  $ vi ext/sample7/config.m4
3.  $ ./buildconf
4.  $ ./configure [with|enable]-sample7
5.  $ make
6.  $ ./php -f ext/sample7/sample7.php
7.  $ vi ext/sample7/sample7.c
8.  $ make

Repeat steps 3-6 until you are satisfied with ext/sample7/config.m4 and
step 6 confirms that your module is compiled into PHP. Then, start writing
code and repeat the last two steps as often as necessary.

Now look in the ext/sample7 directory, you will see the extension skeleton code you wrote in Chapter 5 "Your First Extension" Annotated version of . It's just that you can't compile it yet; but you only need to make a small modification to config.m4 to make it work, so you can avoid most of the work you did in Chapter 5.

Generate function prototype

#If you want to write a wrapper extension for a third-party library, then you already have a function Description (header file) of the machine-scale version of the prototype and basic behavior. By passing an extra argument to ./ext_skel, it will automatically scan your header file and create a simple PHP_FUCNTION() block corresponding to the interface. Here is how to use it The ./ext_skel directive parses the zlib header:

jdoe@devbox:/home/jdoe/cvs/php-src/ext/$ ./ext_skel extname=sample8 \
proto=/usr/local/include/zlib/zlib.h

Now in ext/sample8/sample8.c, you can see many PHP_FUNCTION() definitions, one for each zlib function. Be aware that the skeleton generator will generate warning messages for some unknown resource types. You will need to pay special attention to these functions, and in order to associate these internal complex structures with user-space accessible variables, you may need to use the What you learned in Chapter 9 "Resource Data Types".

PECL_Gen

There is a more complete but There is also a more complex code generator: PECL_Gen, which can be found in PECL (http://www.php.cn/) and can be installed using the pear install PECL_Gen command.

Translator's Note: PECL_Gen has been migrated to CodeGen_PECL (http://www.php.cn/). This chapter involves code testing using CodeGen_PECL. The version information is: "php 1.1.3, Copyright (c) 2003-2006 Hartmut Holzgraefe", if you have problems using the environment, please refer to the translator's environment configuration in the translation sequence.

Once the installation is complete, it can run like ext_skel, accept The same input parameters, produce roughly the same output, or if a complete xml definition file is provided, produce a more robust and fully compilable version of the extension. PECL_Gen does not save you time writing extensions to the core functionality; rather Provides an optional way to efficiently generate extended skeleton code.

specfile.xml

The following is the most Simple extension definition file:

<?xml version="1.0" encoding="utf-8" ?>
<extension name="sample9">
 <functions>
  <function name="sample9_hello_world" role="public">
   <code>
<![CDATA[

    php_printf("Hello World!");
]]>
   </code>
  </function>
 </functions>
</extension>

译注: 请注意, 译者使用的原著中第一行少了后面的问号, 导致不能使用, 加上就OK.

通过PECL_Gen命令运行这个文件:

jdoe@devbox:/home/jdoe/cvs/php-src/ext/$ pecl-gen specfile.xml

则会产生一个名为sample9的扩展, 并暴露一个用户空间函数sample9_hello_world().

关于扩展

除了你已经熟悉的功能文件, PECL_Gen还会产生一个package.xml文件 它可以用于pear安装. 如果你计划发布包到PECL库, 或者哪怕你只是想要使用pear包系统交付内容, 有这个文件都会很有用.

总之, 你可以在PECL_Gen的specfile.xml中指定多数package.xml文件的元素.

<?xml version="1.0" encoding="UTF-8" ?>
<extension name="sample9">
    <summary>Extension 9 generated by PECL_Gen</summary>
    <description>Another sample of PHP Extension Writing</description>
    <maintainers>
        <maintainer>
            <name>John D. Bookreader</name>
            <email>jdb@example.com</email>
            <role>lead</role>
        </maintainer>
    </maintainers>
    <release>
        <version>0.1</version>
        <date>2006-01-01</date>
        <state>beta</state>
        <notes>Initial Release</notes>
    </release>
    ...
</extension>

当PECL_Gen创建扩展时, 这些信息将被翻译到最终的package.xml文件中.

依赖

如你在第17章"配置和链接"中所见, 依赖可以扫描出来用于config.m4和config.w32文件. PECL_Gen可以使用定义各种类型的依赖完成扫描工作. 默认情况下, 列在标签下的依赖会同时应用到Unix和win32构建中, 除非显式的是否用platform属性指定某个目标

<?xml version="1.0" encoding="UTF-8" ?>
<extension name="sample9">
    ...
    <deps platform="unix">
        <! UNIX specific dependencies >
    </deps>
    <deps platform="win32">
        <! Win32 specific dependencies >
    </deps>
    <deps platform="all">
        <! Dependencies that apply to all platforms >
    </deps>
    ...
</extension>

with

通常, 扩展在配置时使用--enable-extname样式的配置选项. 通过增加一个或多个标签到块中, 则不仅配置选项被修改为--with-extname, 而且同时需要扫描头文件:

deps platform="unix">
    <with defaults="/usr:/usr/local:/opt"
        testfile="include/zlib/zlib.h">zlib headers</with>
</deps>

库

必须的库也列在下, 使用标签.

<deps platform="all">
    <lib name="ssleay" platform="win32"/>
    <lib name="crypto" platform="unix"/>
    <lib name="z" platform="unix" function="inflate"/>
</deps>

在前面两个例子中, 只是检查了库是否存在; 第三个例子中, 库将被真实的加载并扫描以确认inflate()函数是否定义.

尽管标签实际已经命名了目标平台, 但标签也有一个platform属性可以覆盖标签的platform设置. 当它们混合使用的时候要格外小心.

<deps>
    <header name="sys/types.h" platform="unix" prepend="yes"/>
    <header name="zlib/zlib.h"/>
</deps>

    <constants>
        <constant name="SAMPLE9_APINO" type="int" value="20060101"/>
        <constant name="SAMPLE9_VERSION" type="float" value="1.0"/>
        <constant name="SAMPLE9_AUTHOR" type="string" value="John Doe"/>
    </constants>

    <globals>
        <global name="greeting" type="char *"/>
        <global name="greeting_was_issued" type="zend_bool" value="1"/>
    </globals>

    <globals>
        <phpini name="mysetting" type="int" value="42" onupdate="OnUpdateLong" access="all"/>
    </globals>

    <functions>
        <function role="public" name="sample9_greet_me">
            <summary>Greet a person by name</summary>
            <description>Accept a name parameter as a string and say hello to that person. Returns TRUE.</description>
            <proto>bool sample9_greet_me(string name)</proto>
            <code>
            <![CDATA[
            char *name;
            int name_len;

            if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s",
                        &name, &name_len) == FAILURE) {
                return;
            }

            php_printf("Hello ");
            PHPWRITE(name, name_len);
            php_printf("!\n");
            RETURN_TRUE;
            ]]>
            </code>
        </function>
    </functions>

    <functions>
        <function role="internal" name="MINFO">
            <code>
            <![CDATA[
            php_info_print_table_start();
            php_info_print_table_header(2, "Column1", "Column2");
            php_info_print_table_end();
            ]]>
            </code>
        </function>
    </functions>

    <code role="header" position="bottom">
    <![CDATA[
    typedef struct _php_sample9_data {
        long val;
    } php_sample9_data;
    ]]>
    </code>
    <code role="code" position="top">
    <![CDATA[
    static php_sample9_data *php_sample9_data_ctor(long value)
    {
        php_sample9_data *ret;
        ret = emalloc(sizeof(php_sample9_data));
        ret->val = value;
        return ret;
    }
    ]]>
    </code>