14.3.1. Command-Line PHP

% cd php4
% ./configure --with-mysql=/usr --with-pgsql --with-zlib --with-config-file=/etc   
% make
# make install

This will put a php binary in your /usr/local/bin directory. The configure line above adds MySQL, PostgreSQL, and zlib support. While you don't need them to develop your extension, they won't get in the way, and it is a good idea to have a php binary that can run complex web applications directly from the command line.

Just to make sure it worked, test it:

% /usr/local/bin/php -v
4.2.0-dev

14.3.2. Planning Your Extension

<?php
 echo rot13($string);
?>

From this we see that we need to implement a single function, which takes a string as an argument and returns a string. Don't let the simplicity of the example fool you—the approach we'll take holds for extensions of any complexity.

14.3.3. Creating a Skeleton Extension

string rot13(string arg) Returns the rot13 version of arg

This defines a function that returns a string and takes a string argument. Anything after the close parenthesis is a one-line description of the function.

The other types valid in a .def file are:

void

For functions that return nothing or take no arguments

bool

Boolean

int

Integer/long

long

Same as int

array

An array

float

Floating point

double

Same as float

object

An object

resource

A PHP resource

mixed

Any of the above

Let's look at the basic structure of a PHP extension. Create one for yourself and follow along:

% cd php4/ext
% ./ext_skel --extname=rot13 --proto=rot13.def
% cd rot13

Running ext_skel like this creates the following files:

config.m4

The configuration rules

CREDITS

Put your extension name and your name here

EXPERIMENTAL

Indicates the extension is still experimental

rot13.c

The actual C code for the extension

rot13.php

The test script

Makefile.in

The makefile template for autoconf/automake

php_rot13.h

The C header file for the extension

tests/

The directory for regression tests

14.3.4. Fleshing Out the Skeleton

/* {{{ rot13_functions[]
 *
 * every user-visible function must have an entry in rot13_functions[]
 */
function_entry rot13_functions[] = {
    PHP_FE(confirm_rot13_compiled,  NULL)  /* for testing; remove later */
    PHP_FE(rot13,   NULL)
    {NULL, NULL, NULL}  /* must be the last line in rot13_functions[] */
};
/* }}} */

zend_module_entry rot13_module_entry = {
  STANDARD_MODULE_HEADER,
  "rot13",
  rot13_functions,
  PHP_MINIT(rot13),
  PHP_MSHUTDOWN(rot13),
  PHP_RINIT(rot13), /* replace with NULL if no request init code */
  PHP_RSHUTDOWN(rot13), /* replace with NULL if no request shutdown code */
  PHP_MINFO(rot13),
  "0.1", /* replace with version number for your extension */
  STANDARD_MODULE_PROPERTIES
};

This defines the functions to be called for the various stages of startup and shutdown. Like most extensions, rot13 doesn't need per-request startup and shutdown functions, so follow the instructions in the comments and replace PHP_RINIT(rot13) and PHP_RSHUTDOWN(rot13) with NULL. The resulting zend_module_entry struct looks like this:

zend_module_entry rot13_module_entry = {
  STANDARD_MODULE_HEADER,
  "rot13",
  rot13_functions,
  PHP_MINIT(rot13),
  PHP_MSHUTDOWN(rot13),
  NULL,
  NULL,
  PHP_MINFO(rot13),
  "0.1", /* replace with version number for your extension */
  STANDARD_MODULE_PROPERTIES
};

The extension API changed between PHP 4.0.x and PHP 4.1.x. To make your extension be source-compatible with PHP 4.0.x, you need to make some of the elements of the structure conditional, as follows:

zend_module_entry rot13_module_entry = {
#if ZEND_MODULE_API >= 20010901
    STANDARD_MODULE_HEADER,
#endif
    "rot13",
    rot13_functions,
    PHP_MINIT(rot13),
    PHP_MSHUTDOWN(rot13),
    NULL,
    NULL,
    PHP_MINFO(rot13),
#if ZEND_MODULE_API >= 20010901
    "0.1",
#endif
    STANDARD_MODULE_PROPERTIES
};

14.3.5. Compiling Your Extension

PHP_ARG_ENABLE(rot13, whether to enable rot13 support,
[  --enable-rot13           Enable rot13 support])

There are two main choices for building your extension. You can make a completely standalone source tree and build your extension as a shared module, or you can work within the framework of the PHP source tree. Shared modules are quicker to compile, but a line in the program source or php.ini file is required to load them. Compiling your extension into PHP takes time, but it means that the extension's functions are always visible to scripts.

14.3.6. Testing Your Extension

<?php
 if(!extenson_loaded('rot13')) {
         dl('rot13.so');
 }
 $module = 'rot13';
 $functions = get_extension_funcs($module);
 echo "Functions available in the test extension:<br>\n";
 foreach($functions as $func) {
         echo $func."<br>\n";
 }
 echo "<br>\n";
 $function = 'confirm_' . $module . '_compiled';
 if (extension_loaded($module)) {
         $str = $function($module);
 } else {
         $str = "Module $module is not compiled into PHP";
 }
 echo "$str\n";
?>

This code checks to see an if the extension is loaded, lists the functions provided by the extension, and then calls the confirmation function if the extension was loaded. This is good, but it doesn't test whether the rot13( ) function works.

Modify the test script to look like this:

<?php
 if(!extension_loaded('rot13')) {
         dl('rot13.so');
 }
 $encrypted = rot13('Rasmus');
 $again = rot13($encrypted);
 echo "$encrypted $again\n";
?>

Run the test with:

% ~/php4/ext/rot13> php -q rot13.php
Enfzhf Rasmus

The test program encrypts "Rasmus", then uses rot13( ) on the string again to decrypt it. The -q option tells the command-line version of PHP to not display any HTTP headers.