Before We Begin

Before we begin, I should note that the focus of this article will be on the UNIX side of the PHP world. I'll mention a few pointers for Windows development, but since I do most of my coding on UNIX systems, I'll be sticking to what I know for the most part.

I should also mention that these instructions should work with PHP 4.2.x and 4.3.x.

Now, here's a few conventions I'll use throughout this article...

1. $PHP_HOME will refer to the path to your PHP source code, i.e. where you unpacked your PHP source. On my system, it's /home/jay/setup/php/php-x.x.x.

    

2. The example module we'll be creating will be called cppext.

   The Setup

   Before you get to coding your extension for PHP in C++, you'll need to get yourself a basic extension skeleton. In the UNIX world, you'll want to run a shell script found in $PHP_HOME/ext called ext_skel. Switch over to the $PHP_HOME/ext directory and fire up the shell script. Use the --extname argument to give your extension a name.

   jay@monty ~ $ cd setup/php/php-4.3.1/ext jay@month ext $ ./ext_skel --extname cppext

   On Windows systems, there's PHP script in $PHP_HOME/ext called ext_skel_win32.php in the current PHP CVS HEAD. It'll probably become a part of PHP 5 and may be included in future versions of the PHP 4.x branch. I have no idea if it works, but the daring may try it out...

   You should now have a basic PHP extension ready to go in $PHP_HOME/ext/cppext. The only problem is, it's all done in C and not in C++.

   Setting Up The config.m4 File

   Now would be a good time to open up your extension's config.m4 file and get it ready for some C++ action. This section is geared towards PHP 4.2.x, but it should still work in PHP 4.3.x.

   There isn't much you have to change here. Basically, you want to tell PHP's build system that it should be prepared to use C++ and link with the standard C++ library. Here's a sample file for our little cppext extension, minus all of the auto-generated comments:

   PHP_ARG_ENABLE(cppext, for cppext support, [ --enable-cppext Enable cppext support] ) if test "$PHP_CPPEXT" != "no" ; then PHP_ADD_LIBRARY(stdc++, 1, CPPEXT_SHARED_LIBADD) PHP_EXTENSION(cppext, $ext_shared) PHP_REQUIRE_CXX() fi

   In PHP 4.3.x, the config.m4 file can be set up a little differently, but the above should still work fine.

   Setting Up The Makefile.in File

   Now you'll need to set up the Makefile.in file. In PHP 4.3.x, this file won't exist, so you'll have to create it. The build system in PHP 4.3.0 got rid of this file, but it will still work.

   In this file, you want to tell the build system which files it should compile using your C++ compiler. There's not much difference as compared to the stock Makefile.in that ext_skel creates in PHP 4.2.x...

   LTLIBRARY_NAME = libcppext.la LTLIBRARY_SOURCES_CPP = cppext.cpp LTLIBRARY_SHARED_NAME = cppext.la LTLIBRARY_OBJECTS_X = cppext.lo include $(top_srcdir)/build/dynlib.mk

   Setting Up The Source

   With config.m4 and Makefile.in in place, you can start setting up your code. Rename cppext.c to a more Cish name. Following our example Makefile.in, rename it to cppext.cpp.

   Now you can start editing the file. If you were to try and build the extension in it's current state, odds are it would compile without any errors as a shared object, but it probably would not work with PHP. If you compiled it statically into PHP itself, you'd probably get some linker errors. This is due to various differences in C (which is what PHP is written in, for the most part) and C (which is what your extension will be written in). Think name mangling and that sort of thing.

   To remedy this, you'll need to tell your extension to treat a few PHP API functions as if they were written in C (which they are) rather than in C (which they aren't).

   You'll need to wrap a few lines with BEGIN/END_EXTERN_C(). Specifically, you'll want your cppext.cpp to look like this:

   extern "C" { #include "php.h" #include "php_ini.h" #include "ext/standard/info.h" } . . . #ifdef COMPILE_DL_CPPEXT BEGIN_EXTERN_C() ZEND_GET_MODULE(cppext) END_EXTERN_C() #endif

   Normally, we'd want to wrap the header files above in BEGIN/END_EXTERN_C() as we did for ZEND_GET_MODULE(cppext), but since BEGIN/END_EXTERN_C() are defined in zend.h, extern "C" will have to do.

   In Windows, you may find that Visual C complains about linking your extension. You may need to put something like this near the top of your extension:

   #ifdef PHP_WIN32 #include <iostream> #include <math.h> #endif

   That seems to help. You should obviously put that in there anyway to try and keep things cross-platform.

   Compiling the Extension

   Now you're ready to compile your extension. If you want to compile the extension statically (compile into PHP as a part of PHP itself), go down to the PHP root directory at $PHP_HOME, move the configure file out of the way and run buildconf.

   Next, run configure with your normal set of configuration options and add --enable-cppext. Run make clean, make, make install and all that other jazz, like recompiling Apache and all that.

   If you want to compile the extension as a loadable object, head to your extension's directory and run the phpize command. (This assumes that you have PEAR installed on your system.) phpize will create a configure script just for your little extension. Run configure, make and make install. If you want the extension to load automatically, you'll have to modify your php.ini file to load the proper file. Adding a line like extension=cppext.so should do the trick.

   Your extension should now be compiled and ready to use by PHP. Try running the auto-generated cppext.php file found in your extension's source directory to see if everything is kosher.

   Mapping C++ Classes To PHP

   There are a ton of ways you can go about doing this, but here's a few tips to get you started.

   • Start of by making a global zend_class_entry for each class. You also need to have a list entry to handle the destructors for your actual C++ objects, which we'll actually be treating as PHP resources. (See Note 1 in the exmaple code.)

      

   • Put all of your methods into your function_entry array. For each class, make another function_entry for the methods you want to map. (See Note 2 in example code.)

      

   • Your MINIT function should initialize the class entries, list entries, etc. (See Note 3.)

      

   • In your PHP class constructor, you need to register a resource within the PHP class. This resource (handle in the example code) is used to reference the actual C++ object in method calls. (See Note 4.)

      

   • Map your PHP methods onto the C++ class methods. (See Note 5.)

      

   That's pretty much it. Of course, there are a ton of ways to get the same effect, but this one's pretty simple and should be a decent guide to get you going.

   Example Code

   Here's some example code to get you going. This is pretty simple stuff -- we have a single C++ class that we map to PHP. The C++ class is simple and doesn't do much, but you should be able to figure out the harder stuff if you can understand this...

   config.m4

   dnl config.m4 for extension cppext PHP_ARG_ENABLE(cppext, whether to enable cppext support, [ --enable-cppext Enable cppext support]) if test "$PHP_CPPEXT" != "no"; then PHP_ADD_LIBRARY(stdc++, 1, CPPEXT_SHARED_LIBADD) PHP_NEW_EXTENSION(cppext, cppext.cpp class.cpp, $ext_shared) PHP_REQUIRE_CXX() fi

   Makefile.in

   LTLIBRARY_NAME = libcppext.la LTLIBRARY_SOURCES_CPP = cppext.cpp LTLIBRARY_SHARED_NAME = cppext.la LTLIBRARY_SHARED_LIBADD = $(CPPEXT_SHARED_LIBADD) LTLIBRARY_OBJECTS_X = cppext.lo class.lo include $(top_srcdir)/build/dynlib.mk

   class.h -- this is for our actual C++ class...

   #ifndef __CLASS_H__ #define __CLASS_H__ #include <string> using namespace std; class MyPHPClass { private: string itsString; public: MyPHPClass(string s = "default"); void setString(const string s); string getString() const; }; #endif

   class.cpp -- the MyPHPClass implementation...

   #include "class.h" MyPHPClass::MyPHPClass(string s) { itsString = s; } void MyPHPClass::setString(const string s) { itsString = s; } string MyPHPClass::getString() const { return itsString; }

   php_cppext.h -- our PHP wrapper header. Be careful with putting actual C++ code in here, as the C compiler used to build PHP may choke on it during static builds.

   #ifndef PHP_CPPEXT_H #define PHP_CPPEXT_H extern zend_module_entry cppext_module_entry; #define phpext_cppext_ptr &cppext_module_entry #ifdef PHP_WIN32 #define PHP_CPPEXT_API __declspec(dllexport) #else #define PHP_CPPEXT_API #endif #ifdef ZTS #include "TSRM.h" #endif PHP_MINIT_FUNCTION(cppext); PHP_FUNCTION(myphpclass); PHP_FUNCTION(myphpclass_getstring); PHP_FUNCTION(myphpclass_setstring); static void destroy_myphpclass(zend_rsrc_list_entry *rsrc TSRMLS_DC); #ifdef ZTS #define CPPEXT_G(v) TSRMG(cppext_globals_id, zend_cppext_globals *, v) #else #define CPPEXT_G(v) (cppext_globals.v) #endif #endif /* PHP_CPPEXT_H */

   cppext.cpp

   #ifdef HAVE_CONFIG_H #include "config.h" #endif #ifdef PHP_WIN32 #include <iostream> #include <math.h> #endif extern "C" { #include "php.h" #include "php_ini.h" #include "ext/standard/info.h" } #include "php_cppext.h" #include "class.h" /* Note 1 -- here's the zend_class_entry. You'll also need a list entry for the resources used to store the actual C++ objects... */ static zend_class_entry myphpclass_entry; static int le_myphpclass; /* Note 2 -- all of the methods go into this function_entry. Below are the actual methods that map onto MyPHPClass. */ function_entry cppext_functions[] = { PHP_FE(myphpclass, NULL) PHP_FE(myphpclass_getstring, NULL) PHP_FE(myphpclass_setstring, NULL) {NULL, NULL, NULL} }; static function_entry myphpclass_methods[] = { {"getstring", PHP_FN(myphpclass_getstring), NULL}, {"setstring", PHP_FN(myphpclass_setstring), NULL}, {NULL, NULL, NULL} }; /* {{{ cppext_module_entry */ zend_module_entry cppext_module_entry = { #if ZEND_MODULE_API_NO >= 20010901 STANDARD_MODULE_HEADER, #endif "cppext", cppext_functions, PHP_MINIT(cppext), NULL, NULL, NULL, NULL, #if ZEND_MODULE_API_NO >= 20010901 "0.1", #endif STANDARD_MODULE_PROPERTIES }; /* }}} */ #ifdef COMPILE_DL_CPPEXT BEGIN_EXTERN_C() ZEND_GET_MODULE(cppext) END_EXTERN_C() #endif /* {{{ PHP_MINIT_FUNCTION */ PHP_MINIT_FUNCTION(cppext) { /* Note 3 -- here we register the destructor for the myphpclass PHP objects, which deletes the actual C++ objects. Below that, we initialize the class entry for myphpclass. */ le_myphpclass = zend_register_list_destructors_ex(destroy_myphpclass, NULL, "myphpclass-obj", module_number); INIT_CLASS_ENTRY(myphpclass_entry, "myphpclass", myphpclass_methods); zend_register_internal_class(&myphpclass_entry TSRMLS_CC); return SUCCESS; } /* }}} */ /* {{{ proto myphpclass object myphpclass() Returns a new myphpclass object. This is basically the constructor. */ PHP_FUNCTION(myphpclass) { /* Note 4 -- here's the constructor. First, initalize return_value as an object, then make a handle to the C++ object. Register the handle as a resource and store the resource within the PHP object so we can get to it in the method calls. */ MyPHPClass *obj; zval *handle; if (ZEND_NUM_ARGS() != 0) { WRONG_PARAM_COUNT; } obj = new MyPHPClass; object_init_ex(return_value, &myphpclass_entry); MAKE_STD_ZVAL(handle); ZEND_REGISTER_RESOURCE(handle, obj, le_myphpclass); zend_hash_update(Z_OBJPROP_P(return_value), "handle", sizeof("handle"), &handle, sizeof(zval *), NULL); } /* }}} */ /* Note 5 -- this macro gets the resource handle for the C++ object so we can use the C++ object in our methods mappings below. */ #define CPP_GET_THIS() / id = getThis(); / if (!id) { / php_error(E_ERROR, "this isn't an object?! %s()", get_active_function_name(TSRMLS_C)); / } / if (zend_hash_find(Z_OBJPROP_P(id), "handle", sizeof("handle"), (void **) &handle) == FAILURE) { / php_error(E_ERROR, "underlying object missing, can't find 'this' in %s()", get_active_function_name(TSRMLS_C)); / } / obj = (MyPHPClass *) zend_list_find(Z_LVAL_PP(handle), &type); / if (!obj || type != le_myphpclass) { / php_error(E_ERROR, "underlying object is of wrong type in %s()", get_active_function_name(TSRMLS_C)); / } /* {{{ proto string myphpclass->getstring() Passthru to MyPHPClass::getString(). */ PHP_FUNCTION(myphpclass_getstring) { MyPHPClass *obj; zval *id, **handle; int type; CPP_GET_THIS(); RETURN_STRINGL((char*) obj->getString().c_str(), obj->getString().length(), 1); } /* }}} */ /* {{{ proto bool myphpclass->setstring(string) Passthru to MyPHPClass::setString(string). */ PHP_FUNCTION(myphpclass_setstring) { MyPHPClass *obj; zval *id, **handle; int type, len; char *str; if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s", &str, &len) == FAILURE) { RETURN_FALSE; } else { CPP_GET_THIS(); obj->setString(str); RETURN_TRUE; } } /* }}} */ /* {{{ destructor for myphpclass objects */ static void destroy_myphpclass(zend_rsrc_list_entry *rsrc TSRMLS_DC) { delete (MyPHPClass*) rsrc->ptr; } /* }}} */