This file describe how to write in C++ a PHP4/PHP5 extension module dynamically
linked to libcarob. Using static linking instead of dynamic should be even
easier.

First you must be familiar with how to write in C a simple PHP module.
References:
  http://www.zend.com/php/internals/
  http://www.php.net/manual/en/zend.php

More advanced tutorial (and helpers) from Marcus Boerger (zend conf 2005)
http://somabo.de/talks/

The only two additional issues described are:
- your PHP module (a library) must be linked to libcarob (another library)
- your PHP module has to be written in C++, but export C symbols to
  the PHP engine.

Building the example
====================
Quick:
  1) > phpize sample_carob_request.cpp
     edit ./configure, replace "link_cmd='$(CC)" by "link_cmd='$(CXX)"
  2) > ./configure
  3) > export CAROB_INSTALL_DIR=<where_lib_carob_so_is>
     > make EXTRA_LDFLAGS="-L${CAROB_INSTALL_DIR} -lcarob -Wl,--rpath, -Wl,${CAROB_INSTALL_DIR}"

Deeper:
1) First there is a small bug in the phpize script, so you must
slighty patch the "./configure" file generated. The .configure file
correctly calls the C++ compiler to compile "your_php_module.cpp", but
unfortunately still calls the C compiler to link it. Search for the
"link_cmd=" definition inside "./configure" and just replace "$(CC)"
by "$(CXX)". In case you use them, replace as well "$(EXTRA_CFLAGS)"
by "$(EXTRA_CXXFLAGS)" etc.


2) Since the PHP engine is written in C, you must take care that:
- all symbols of your C++ module are exported in a way compatible with C
- all PHP symbols imported by your C++ module are known as coming from C

In order to do this you have to include all the declarations of those
symbols inside an "extern C" scope. Your headers files must look like this:

  #include "php.h" // no need to worry since this is .h is 
                   // fortunately already C/C++ compatible.

  #ifdef __cplusplus
  extern "C" {
  #endif

  PHP_FUNCTION(hello_world);
  PHP_FUNCTION(hello_greetme);

  extern zend_module_entry hello_module_entry;

  #ifdef __cplusplus
  } // extern "C"
  #endif

This trick is only needed at declaration time. Once the compiler knows
this is a C-compatible symbol you can then use it just like a regular
C++ symbol.  This is a very well-known C/C++ linking issue and you'll
easily find plenty of literature about it.

Additional issue with PHP4:
With PHP4, you also have to enclose the ZEND_GET_MODULE(module_name) call
inside your .cpp file like this:

 extern "C" {
 #ifdef COMPILE_DL_HELLO
 ZEND_GET_MODULE(hello)
 #endif
 }
(thanks to Sara Goleman for the tip)


3) Finally the libcarob library must be found by your module: - at
  compile+link time; - again at run-time.

To achieve this simply just add the following EXTRA_LDFLAGS when
compiling your C++ PHP module:

export CAROB_INSTALL_DIR=/usr/local/lib/my_carob_install
make EXTRA_LDFLAGS="-L${CAROB_INSTALL_DIR} -lcarob -Wl,--rpath, -Wl,${CAROB_INSTALL_DIR}"


