CHAPTER 15 – An Introduction to Writing PHP Extensions – QUICKSTART

Instead of slowly explaining some of the building blocks of the scripting engine, this section dives into coding an extension, so do not worry if you don't see the whole picture right away. Imagine you are writing a web site but need a function, which will repeat a string n times. Writing this in PHP is simple: function self_concat($string, $n) { $result = ""; for ($i = 0; $i < $n; $i++) { $result .= $string; } return $result; } self_concat("One", 3) returns "OneOneOne". self_concat("One", 1) returns "One". Imagine that for some odd reason, you need to call this function often, with very long strings and large values of n. This means that you'd have a huge amount of concatenation and memory reallocation going on in your script, which could significantly slow things down. It would be much faster to have a function that allocates a large enough string to hold the resulting string and then repeat $string n times, not needing to reallocate memory every loop iteration.

The first step in creating an extension for your function is to write the function definition file for the functions you want your extension to have. In this case, the file will have only one line with the prototype of the function self_concat(): string self_concat(string str, int n) The general format of the function definition file is one function per line. You can specify optional parameters and a wide variety of PHP types, includ- ing bool, float, int, array, and others. Save the file as myfunctions.def in the ext/ directory under the PHP's source tree. Now it's time to run it through the extension skeleton creator. The script is called ext_skel and sits in the ext/ directory of the PHP source tree (more information can be found in the README.EXT_SKEL file under the main PHP source directory). Assuming you saved your function definitions in a file called myfunctions.def and you would like the extension to be called myfunctions, you would use the following line to create your skeleton extension: ./ext_skel --extname=myfunctions --proto=myfunctions.def This creates a directory myfunctions/ under the ext/ directory. First thing you'd probably want to do is get the skeleton to compile so that you're ready for actually writing and testing your C code. There are two ways to compile the extension: As a loadable module or DSO (dynamically shared object) Build it statically into PHP This chapter uses the second method because it's slightly easier to begin with. If you're interested in building your extension as a loadable module, you should read the README.SELF-CONTAINED_EXTENSIONS file in the PHP source tree's root directory. To get the extension to compile, you need to edit its config.m4 file, which can be found in ext/myfunctions/. As your extension does not wrap any external C libraries, you will want to add support of the --enable-myfunc- tions configure switch to PHP's build system (the ­with-extension switch is used for extensions that need to allow the user to specify a path to the relevant C library). You can enable the switch by uncommenting the following two auto-generated lines: PHP_ARG_ENABLE(myfunctions, whether to enable myfunctions support, [ --enable-myfunctions Include myfunctions support])

Now all that's left to do is to run ./buildconf in the root of the PHP source tree, which will create a new configure script. You can check that your new configure option made it into configure by finding it in the output of ./ configure --help. Now, reconfigure PHP with all of your favorite switches and include the --enable-myfunctions switch. Last but not least, rebuild PHP by running make. ext_skel should have added two PHP functions to your skeleton exten- sion: self_concat() which is the function you want to implement, and confirm_myfunctions_compiled(), which can be called to check that you properly enabled the myfunctions extension in your build of PHP. After you finish devel- oping your PHP extension, remove the latter function. <?php print confirm_myfunctions_compiled("myextension"); ?> Running this script would result in something similar to the following being printed: "Congratulations! You have successfully modified ext/myfunctions config.m4. Module myfunctions is now compiled into PHP." In addition, the ext_skel script creates a myfunctions.php script that you can also run to verify that your extension was successfully built into PHP. It shows you a list of functions that your extension supports. Now that you've managed to build PHP with your extension, it's time to actually start hacking at the self_concat() function. The following is the skeleton that the ext_skel script created: /* {{{ proto string self_concat(string str, int n) */ PHP_FUNCTION(self_concat) } char *str = NULL; int argc = ZEND_NUM_ARGS(); int str_len; long n; if (zend_parse_parameters(argc TSRMLS_CC, "sl", &str, &str_len, &n) == FAILURE) return; php_error(E_WARNING, "self_concat: not yet implemented"); } /* }}} */

The auto-generated PHP function includes comments around the func- tion declaration which are used for self-documentation and code-folding in edi- tors such as vi and Emacs. The function itself is defined by using the PHP_FUNCTION() macro, which creates a function prototype suitable for the Zend Engine. The logic itself is divided into semantic parts, the first where you retrieve your function arguments and the latter the logic itself. To retrieve the parameters passed to your function, you'll want to use the zend_parse_parameters() API function which has the following prototype: zend_parse_parameters(int num_args TSRMLS_DC, char *type_spec, ...); The first argument is the number of arguments that were passed to your function. You will usually pass it ZEND_NUM_ARGS(), which is a macro that equals the amount of parameters passed to your PHP function. The second argument is for thread-safety purposes, and you should always pass it the TSRMLS_CC macro, which is explained later. The third argument is a string specifying what types of parameters you are expecting, followed by a list of variables that should be updated with the parameters' values. Because of PHP's loose and dynamic typing, when it makes sense, the parameters will convert to the requested types if they are different. For example, if the user sends an integer and you request a floating-point number, zend_parse_parameters() automati- cally converts the integer to the corresponding floating-point number. If the actual value cannot be converted to the expected type (for example, integer to array), a warning is triggered. Table 15.1 lists types you can specify. For completeness, some types that we haven't discussed yet are included. Table 15.1 Type Specifiers Type Specifier Corresponding C Type Description l long Signed integer. d double Floating-point number. s char *, int Binary string including length. b zend_bool Boolean value (1 or 0). r zval * Resource (file pointer, database connection, and so on). a zval * Associative array. o zval * Object of any type. O zval * Object of a specific type. This requires you to also pass the class type you want to retrieve. z zval * The zval without any manipulation.

To understand the last few options, you need to know that a zval is the Zend Engine's value container. Whether the value is a Boolean, a string, or any other type, its information is contained in the zval union. We will not access zval's directly in this chapter, except through some accessor macros, but the following is more or less what a zval value looks like in C, so that you can get a better idea of what's going on: typedef union _zval { long lval; double dval; struct { char *val; int len; } str; HashTable *ht; zend_object_value obj; } zval; In our examples, we use zend_parse_parameters() with basic types, receiv- ing their values as native C types and not as zval containers. For zend_parse_parameters() to be able to change the arguments that are supposed to return the function parameters, you need to send them by refer- ence. Take a closer look at self_concat(): if (zend_parse_parameters(argc TSRMLS_CC, "sl", &str, &str_len, &n) == FAILURE) return; Notice that the generated code checks for the return value FAILURE (SUC- CESS in case of success) to see if the function has succeeded. If not, it just returns because, as previously mentioned, zend_parse_parameters() takes care of triggering warnings. Because your function wants to retrieve a string str and an integer n, it specifies "sl" as its type specifier string. s requires two arguments, so we send references to both a char * and an int (str and str_len) to the zend_parse_parameters() function. Whenever possible, always use the string's length str_len in your source code to make sure your functions are binary safe. Don't use functions such as strlen() and strcpy() unless you don't mind if your functions don't work for binary string. Binary strings are strings that can contain nulls. Binary formats include image files, compressed files, executable files, and more. "l" just requires one argument, so we pass it the ref- erence of n. Although for clarity's sake, the skeleton script creates C variable names that are identical to the argument names in your specified function pro- totype; there's no need to do so, although it is recommended practice. Back to conversion rules. All the three following calls to self_concat() result in the same values being stored in str, str_len, and n: self_concat("321", 5); self_concat(321, "5"); self_concat("321", "5"); str points to the string "321", str_len equals 3, and n equals 5. Before we write the code that creates the concatenated string and returns it to PHP, we need to cover two important issues: memory manage- ment and the API for returning values from internal PHP functions.