Creating an object-oriented PHP extension

Hi Boris,

Hi there,

I'm trying to create an object-oriented PHP 5 extension. As I don't know
any step-by-step tutorial which would explain everything in detail I'm
trying to understand various sources and documents I happen to run into.
I'd appreciate if anyone could comment on what I currently think the
typical steps look like (the more comments the better as it's a rather
random learning process):

Well there's Sara's book (SBN-10: 067232704X or ISBN-13: 978-0672327049)
and there are Marcus "Code Camp" slides (while slides without the talk
don't work the same) which show all the things step by step.

• Before a class can be used it must be registered with
  zend_register_internal_class(). The returned pointer is typically saved in
  a global zend_class_entry* (why I don't know - do you need the pointer
  somewhere later?).

Yes, you need the ce everywhere, where you want to reference that class
(checking whether an object passed to to you is of the correct type,
checking properties, etc.)

• As you need to register a class before you can use it you must call the
  code somewhere - a good place is the module startup function.

It is the best place.

• In order to call zend_register_internal_class() you need another another
  zend_class_entry first. It can be initialized with INIT_CLASS_ENTRY which
  sets the class name and assigns the function table (which contains member
  functions declared with PHP_ME).

Right, first setup everything on your ce then give it to the engine
which makes a copy for further use.

• Classes are instantiated by calling the function assigned to
  zend_class_entry::create_object. Thus apart from the initializiation with
  INIT_CLASS_ENTRY zend_class_entry::create_object must be set in the module
  startup function.

An class might work without your own create_object handler, but usually
you want to store additional data (like pointers to some complex data
structure) inside your object so you have to allocate and initilise
that.

• In the create_object function a zend_object is created and initialized
  (with zend_object_std_init). Furthermore the default_properties of the
  class are copied to the properties of the zend_object (with
  zend_hash_copy). Default properties need to be added to zend_class_entry*
  after the class is registered in the module startup function (with one of
  the many add_property_... functions).

yes

• As the create_object function does not return the newly created
  zend_object directly it must be stored in a zend_object_handle together
  with function pointers to a destructor, free storage function and storage
  clone function (is this a copy constructor if you use C++ terminology?).
  The function zend_objects_store_put() can be used to do all of this.

Objects are registered in the object storage, where they live and are
referenced by zvals (php variables)

• The zend_object_handle returned by the create_object function needs also
  a pointer to zend_object_handlers. This is a hash table which contains
  various object handlers - among others functions to read/write properties.
  The object handlers object is typically created and initialized in the
  module startup function (as it is the same for all objects of the same
  class). Is there any overview what these object handlers are used for and
  when exactly you should define your own? I especially wonder what the
  read/write property handlers are good for as you define properties in the
  class? They don't seem to be unimportant though as I've seen dozens of
  them in the DOM extension for example.

There's a file Zend/OBJECTS2_HOWTO or similar which should list all
handlers. read/write property handlers act similar to __get/__set in
userland, you can overwrite them if you don't want to use "regular"
properties but directly modify stuff in your internal structures or
offer read-only properties.

johannes