Getting Started

Boost.PHP Basics

A typical Boost.PHP extension consists of the following source files:

• The main C++ source file.
• Optional source files.

Since the magic has to happen within a single compilation unit, everything related to the extension itself must go to the main source file. Other thingie can be in different units.

The main C++ source file consists of the following portions:

• The module class definition.
• Bootstrap macros.

Every Boost.PHP-powered extension must contain a module class. A module class is a singleton which gets initialized right after the module is loaded. You can modify the contents of zend_module_entry within the module class’s constructor.

The module class must contain a typedef or an inner class definition for a handler. A handler is a class that has 4 methods that handles the lifecycle callbacks from the PHP runtime

• handler::__initialize() – called when the module is being initialized
• handler::__activate() – called when the runtime is about to handle a new request
• handler::__deactivate() – called when the runtime is completing the request
• handler::__finalize() – called when the module is being cleaned up

The handler and the empty definitions of those methods are defined as boost::php::module::handle, so you don’t bother to write them if the module class is derived from it.

Bootstrap macros are necessary to define several functions and global variables required by PHP. There are only 4 macros that need to be defined:

• BOOST_PHP_MODULE_NAME – the name of the extension
• BOOST_PHP_MODULE_CAPITALIZED_NAME – the all-capitalized name of the extension
• BOOST_PHP_MODULE_VERSION – the version of the extension as a string literal
• BOOST_PHP_MODULE_CLASS_NAME – the name of the module class

And finally, you have to include

#include "boost/php/module_def.hpp"</pre> to do the trick.
Your first Boost.PHP extension

#include "boost/php/module.hpp"

using namespace boost;

// (1) Module class definition
class m001_module
    : public php::module {
public:
    // Handler class
    class handler
        : public php::module::handler {
    public:
        handler(m001_module* mod)
            :php::module::handler(mod) {}
    };
public:
    m001_module(zend_module_entry* entry)
        : php::module(entry) {
    }
};

// (2) Bootstrap macros
#define BOOST_PHP_MODULE_NAME m001
#define BOOST_PHP_MODULE_CAPITALIZED_NAME M001
#define BOOST_PHP_MODULE_VERSION "0.1"
#define BOOST_PHP_MODULE_CLASS_NAME m001_module

#include "boost/php/module_def.hpp"