OBJECTS2_HOWTO

Creating an object
------------------

Object can be created in the following ways:

1. As a result of a function call. E.g.:

$foo = create_new_foo("parameter");
$foo->run();

The function should create a new zval, create new object and get the
handle for it, set handle and handler table as needed. Note that the
handle is the only ID of the object, so it should be enough to
identify it.

2. Overriding create_object handler for class. E.g.:

$foo = new Java("some.Class.here", "parameter");
$foo->run();

The  create_object handler function should create a new zval, create
new object and get the handle for it, set handle and handler table as
needed, and also provide constructor method that would handle
constructor call. The get_constructor handler table entry should be
used for that. Do not rely class entry's constructor, unless you refer
to it from get_constructor handler.

Object maintenance
------------------

The handlers add_ref and del_ref are called when a new zval referring
to the object is created. This does not create a new object - both
zvals still refer to the same object.

clone_obj handler should create a new object, identical to an old one, 
but being a separate entity.

delete_obj should destroy an object, all references to it become
invalid.

Object access - read
--------------------

read_property is used to read object's property. This value is not
meant to be changed. The handler returns zval * with the value.

Object access - write
---------------------

write_property is used to directly write object's property by
name.  This handler is used to assign property variables or to change them 
in operations like += or ++ (unless get_property_zval_ptr is also set).

get_property_zval_ptr is used to obtain pointer to modifiable zval for 
operations like += or ++. This should be used only if your object model 
stores properties as real zval's that can be modified from outside. 
Otherwise this handler should be NULL and the engine will use 
read_property and write_property instead.

get_property_ptr is used to obtain zval ** for future writing to
it. If your object properties are stored as zval*, return real place
where the property is stored. If the aren't, the best way is to create 
proxy object and handle it via get and set methods (see below). 
This method is meant to be used for send-by-reference and assign-by-reference
use of object properties. If you don;t want to implement property
referencing for your objects, you can set this handler to NULL. 

get and set handlers are used when engine needs to access the object
as a value. E.g., in the following situation:

$foo =& $obj->bar;
$foo = 1;

if $foo is an object (e.g., proxy object from get_property_ptr) it
would be accessed using write handler.

Object access - method call
---------------------------

get_method handler is used to find method description by name. It
should set right type, function name and parameter mask for the
method. If the type is ZEND_OVERLOADED_FUNCTION, the method would be
called via call_method handler, otherwise it would be called with
standard Zend means.

get_constructor performs the same function as get_method, but for the
object constructor. 

call_method handler is used to perform method call. Parameters are
passed like to any other Zend internal function. 

Object - comparison
-------------------

Objects can be compared via compare_objects handler. This is used with 
== operation, === compares objects by handles, i.e., return true if
and only if it's really the same object. Note that objects from
different object types (i.e., having different handlers) can not be
compared. 

Objects - reflection
--------------------

get_class_name is used to retrieve class name of the object. 
get_class_entry returns class entry (zend_class_entry) for the object,
in case there exists PHP class for it.
No other reflection functions are currently implemented.

Objects - data structures and handlers
---------------------------------------

The object is represented by the following structure:

struct _zend_object_value {
	zend_object_handle handle;
	zend_object_handlers *handlers;
};

handle is an ID of the object among the objects of the same type (not
class!). The type of the object and how it behaves is determined by
the handler table.

typedef struct _zend_object_handlers {
	zend_object_add_ref_t                    add_ref;
	zend_object_del_ref_t                    del_ref;
	zend_object_delete_obj_t                 delete_obj;
	zend_object_clone_obj_t                  clone_obj;	
	zend_object_read_property_t              read_property;
	zend_object_write_property_t             write_property;
	zend_object_get_property_ptr_t           get_property_ptr;
	zend_object_get_property_zval_ptr_t      get_property_zval_ptr;
	zend_object_get_t                        get;
	zend_object_set_t                        set;
	zend_object_has_property_t               has_property;
	zend_object_unset_property_t             unset_property;
	zend_object_get_properties_t             get_properties;
	zend_object_get_method_t                 get_method;
	zend_object_call_method_t                call_method;
	zend_object_get_constructor_t            get_constructor;
	zend_object_get_class_entry_t            get_class_entry;
	zend_object_get_class_name_t             get_class_name;
	zend_object_compare_t                    compare_objects;
} zend_object_handlers;

See zend_object_handlers.h for prototypes. All objects are passed as zval's.

Handlers explained:

add_ref - called when a copy of the object handle is created.

del_ref - called when a copy of the object handle is destroyed.

delete_obj - called when an object needs to be destroyed.

clone_obj - called when a new object identical to an old one should be 
created (unlike Zend Engine 1, this never happens unless explicitly
asked for).

read_property - returns zval *, containing the value of the
property. Is used when value of the property should be retrieved for
reading.

write_property - assigns value to certain property of the object. 

get_property_zval_ptr - retrieves zval** for being directly modified by 
the engine. If your properties are not zval's, don't define it.

get_property_ptr - retrieves zval** for the property of the value, to
be used for read and write. If object properties are not zval's
natively, this method should create and return proxy object for use
with get and set methods.

get - retrieves zval* for object contents. To be used mainly with
proxy objects from get_property_ptr, but also may be used for
convert_to_* functions.

set - sets value for object contents. To be used mainly with
proxy objects from get_property_ptr.

has_property - checks if the object has certain property set.

unset_property - removes value for the property of the object

get_method - retrieves description of the method

call_method - calls the method (parameters should be put on stack like 
for any other PHP internal function).

get_constructor - get description for the object constructor method

get_class_entry - should return the class entry for the object

get_class_name - get the name of the class the object belongs to

compare_objects - compares if two objects are equal