Extend your PHP with C/C++ to add functionality to your php_PHP Tutorial

English version download: PHP 5 Power Programming http://www.jb51.net/books/61020.html

One of the main reasons for PHP's success is that she has a large number of available extensions. No matter what needs web developers have, they are most likely to be found in PHP distribution packages. The PHP distribution package includes many extensions that support various databases, graphics file formats, compression, and XML technology extensions.
The introduction of extension API has made great progress in PHP3. The extension API mechanism allows the PHP development community to easily develop dozens of extensions. Now, two versions later, the API is still very similar to PHP3. The main idea of ​​extensions is to hide the internal mechanisms of PHP and the scripting engine itself from extension writers as much as possible, and only require developers to be familiar with the API.

There are two reasons to write your own PHP extension. The first reason is: PHP needs to support a technology that it does not yet support. This usually involves wrapping some off-the-shelf C library to provide a PHP interface. For example, if a database called FooBase is launched on the market, you need to create a PHP extension to help you call FooBase's C function library from PHP. This work might be done by just one person and then shared by the entire PHP community (if you will). The second, less common reason is that you need to write some business logic for performance or functionality reasons.

If the above two reasons have nothing to do with you and you feel that you have no adventurous spirit, then you can skip this chapter.

This chapter teaches you how to write a relatively simple PHP extension, using some extension API functions. It contains enough information for most developers considering developing custom PHP extensions. One of the best ways to learn a programming course is to work on some extremely simple examples, which are the clues in this chapter. Once you understand the basics, you can enrich yourself on the Internet by reading documentation, source code, or participating in mailing list newsgroup discussions. Therefore, this chapter focuses on getting you started. Under UNIX a script called ext_skel is used to create the extension's skeleton. The skeleton information is obtained from a definition file that describes the extension's interface. So you need to use UNIX to build a skeleton. Windows developers can use Windows ext_skel_win32.php instead of ext_skel.

However, the instructions in this chapter for compiling PHP with the extensions you develop only refer to UNIX build systems. All explanations of the API in this chapter relate to extensions developed for UNIX and Windows.

When you finish reading this chapter, you will learn how to

• Build a simple business logic extension.
•Suggest a package extension for the C function library, especially some standard C file operation functions such as fopen()
Quick start
This section does not introduce some knowledge about the basic structure of the script engine, but goes directly to The extension's coding is being explained, so don't worry that you won't immediately get a feel for the extension as a whole. Suppose you are developing a website and need a function that repeats a string n times. The following is an example written in PHP:

Suppose that for some strange reasons, you need to call this function from time to time, and you also need to pass a long string and a large value n to the function. This means that there is a considerable amount of string concatenation and memory reallocation in the script, which can significantly slow down script execution. If there was a function that could faster allocate a large and sufficient memory to store the result string, and then repeat $string n times, there would be no need to allocate memory on each loop iteration.

The first step in creating a function for an extension is to write a function definition file, which defines the function prototype provided by the extension. In this example, there is only one line of function prototype self_concat() to define the function:



The general format of a function definition file is one function per line. You can define optional parameters and use a large number of PHP types, including: bool, float, int, array, etc.

Save it as myfunctions.def file in the PHP original code directory tree.

It’s time to run the function definition file by extending the skeleton constructor. The constructor script is called ext_skel and is placed in the ext/ directory of the PHP original code directory tree (README.EXT_SKEL in the PHP original code main directory provides more information). Assuming you save your function definitions in a file called myfunctions.def, and you want to name the extension myfunctions, run the following command to create the extension skeleton



This command creates a myfunctions/ directory under the ext/ directory. The first thing you might want to do is compile the skeleton so that you can write and test actual C code. There are two ways to compile extensions:

• As a loadable module or DSO (Dynamic Shared Object)
• Static compilation to PHP

PHP extension development map

Because the second method is easier to use, this chapter uses static compilation. If you are interested in compiling loadable extension modules, you can read the README.SELF-CONTAINED_EXTENSIONS file in the root directory of the PHP source code. In order for the extension to be compiled, the config.m4 file in the extension directory ext/myfunctions/ needs to be modified. The extension does not wrap any external C library, you need to add support for the --enable-myfunctions configuration switch to the PHP build system (the --with-extension switch is used for extensions that require the user to specify the path to the relevant C library). You can enable this configuration by removing the automatically generated comments on the following two lines.



The only thing left now is to create the root of the PHP original code tree Run ./buildconf in the directory. This command will generate a new configuration script. You can check whether the new configuration options are included in the configuration file by viewing the ./configure –help output. Now, turn on your preferred configuration options. Reconfigure PHP with --enable-myfunctions. Last but not least, recompile PHP with make.

ext_skel should add two PHP functions to your extension skeleton: intended to be implemented. The self_concat() function and the confirm_myfunctions_compiled() function used to detect whether myfunctions are compiled into PHP can be removed after completing the PHP extension development.


Run this The script will produce output similar to the following:

In addition, the ext_skel script generates a script called myfunctions.php, which you can also use to verify whether the extension is successfully compiled. to PHP. It will list all the functions supported by the extension.
Now that you know how to compile the extension, it's time to actually study the self_concat() function.
Here is the skeleton structure generated by the ext_skel script. :


There are some comments around the automatically generated PHP functions, which are used to automatically generate code documentation and code folding in editors such as vi and Emacs. The function itself is defined using the macro PHP_FUNCTION(), which can generate a function prototype suitable for the Zend engine. The logic itself is divided into semantic parts, taking the parameters of the calling function and the logic itself.

In order to obtain the parameters passed by the function, you can use the zend_parse_parameters() API function. The following is the prototype of the function:

第一个参数是传递给函数的参数个数。通常的做法是传给它ZEND_NUM_ARGS()。这是一个表示传递给函数参数总个数的宏。第二个参数是为了线程安全，总是传递TSRMLS_CC宏，后面会讲到。第三个参数是一个字符串，指定了函数期望的参数类型，后面紧跟着需要随参数值更新的变量列表。因为PHP采用松散的变量定义和动态的类型判断，这样做就使得把不同类型的参数转化为期望的类型成为可能。例如，如果用户传递一个整数变量，可函数需要一个浮点数，那么zend_parse_parameters()就会自动地把整数转换为相应的浮点数。如果实际值无法转换成期望类型（比如整形到数组形），会触发一个警告。

下表列出了可能指定的类型。我们从完整性考虑也列出了一些没有讨论到的类型。

类型指定符	对应的C类型	描述
l	long	符号整数
d	double	浮点数
s	char *, int	二进制字符串，长度
b	zend_bool	逻辑型（1或0）
r	zval *	资源（文件指针，数据库连接等）
a	zval *	联合数组
o	zval *	任何类型的对象
O	zval *	指定类型的对象。需要提供目标对象的类类型
z	zval *	无任何操作的zval

To easily understand the meaning of the last few options, you need to know that zval is the Zend engine's value container[1]. Regardless of whether the variable is a boolean, string, or any other type, its information is always contained in a zval union. In this chapter we do not access zval directly, but operate it through some additional macros. Below is zval more or less in C so that we can better understand the code that follows.



In our example, we call zend_parse_parameters() with basic types to get the values ​​of function parameters in native C types instead of using zval containers.

In order for zend_parse_parameters() to change the value of the parameters passed to it and return the changed value, a reference needs to be passed. Take a closer look at self_concat():



Note that the automatically generated code will detect the function's return value FAILUER (success is SUCCESS) to determine whether it is successful. If it is not successful, it returns immediately, and zend_parse_parameters() is responsible for triggering a warning message. Because the function is intended to receive a string l and an integer n, "sl" is specified as its type indicator. s requires two parameters, so we pass the reference char * and int (str and str_len) to the zend_parse_parameters() function. Whenever possible, remember to always use the string length str_len in your code to ensure that the function works in a binary-safe environment. Don't use strlen() and strcpy() unless you don't mind the function not working with binary strings. A binary string is a string containing nulls. Binary formats include image files, compressed files, executable files and many more. "l" only takes one argument, so we pass it a reference to n. Although for the sake of clarity, the C variable names generated by the skeleton script are the same as the parameter names in the function prototype definition file; this is not required, although in practice it is encouraged.

Back to the conversion rules. The following three calls to the self_concat() function cause str, str_len and n to get the same value:



When we write code to implement the connection character Before returning a string to a PHP function, we need to talk about two important topics: memory management and the API used to return function values ​​from within PHP.

Memory Management

The PHP API for allocating memory from the heap is almost the same as the standard C API. When writing extensions, use the following API functions that correspond to C (so no need to explain):

在这一点上，任何一位有经验的C程序员应该象这样思考一下：“什么？标准C没有strndup()？”是的，这是正确的，因为GNU扩展通常在Linux下可用。estrndup()只是PHP下的一个特殊函数。它的行为与estrdup()相似，但是可以指定字符串重复的次数（不需要结束空字符），同时是二进制安全的。这是推荐使用estrndup()而不是estrdup()的原因。

在几乎所有的情况下，你应该使用这些内存分配函数。有一些情况，即扩展需要分配在请求中永久存在的内存，从而不得不使用malloc()，但是除非你知道你在做什么，你应该始终使用以上的函数。如果没有使用这些内存函数，而相反使用标准C函数分配的内存返回给脚本引擎，那么PHP会崩溃。

这些函数的优点是：任何分配的内存在偶然情况下如果没有被释放，则会在页面请求的最后被释放。因此，真正的内存泄漏不会产生。然而，不要依赖这一机制，从调试和性能两个原因来考虑，应当确保释放应该释放的内存。剩下的优点是在多线程环境下性能的提高，调试模式下检测内存错误等。

还有一个重要的原因，你不需要检查这些内存分配函数的返回值是否为null。当内存分配失败，它们会发出E_ERROR错误，从而决不会返回到扩展。

从PHP函数中返回值

扩展API包含丰富的用于从函数中返回值的宏。这些宏有两种主要风格：第一种是RETVAL_type()形式，它设置了返回值但C代码继续执行。这通常使用在把控制交给脚本引擎前还希望做的一些清理工作的时候使用，然后再使用C的返回声明 ”return” 返回到PHP；后一个宏更加普遍，其形式是RETURN_type()，他设置了返回类型，同时返回控制到PHP。下表解释了大多数存在的宏。

设置返回值并且结束函数	设置返回值	宏返回类型和参数
RETURN_LONG(l)	RETVAL_LONG(l)	整数
RETURN_BOOL(b)	RETVAL_BOOL(b)	布尔数(1或0)
RETURN_NULL()	RETVAL_NULL()	NULL
RETURN_DOUBLE(d)	RETVAL_DOUBLE(d)	浮点数
RETURN_STRING(s, dup)	RETVAL_STRING(s, dup)	字符串。如果dup为1，引擎会调用estrdup()重复s，使用拷贝。如果dup为0，就使用s
RETURN_STRINGL(s, l, dup)	RETVAL_STRINGL(s, l, dup)	长度为l的字符串值。与上一个宏一样，但因为s的长度被指定，所以速度更快。
RETURN_TRUE	RETVAL_TRUE	返回布尔值true。注意到这个宏没有括号。
RETURN_FALSE	RETVAL_FALSE	返回布尔值false。注意到这个宏没有括号。
RETURN_RESOURCE(r)	RETVAL_RESOURCE(r)	资源句柄。

Complete self_concat()

Now that you have learned how to allocate memory and return function values ​​from PHP extension functions, we can complete the coding of self_concat():