From 6608f07322789bd0896b265c29e13c0c9f5d5898 Mon Sep 17 00:00:00 2001 From: Stanislav Malyshev Date: Thu, 7 Feb 2002 14:08:43 +0000 Subject: Mega-commit: Enter the new object model Note: only standard Zend objects are working now. This is definitely going to break custom objects like COM, Java, etc. - this will be fixed later. Also, this may break other things that access objects' internals directly. --- Zend/OBJECTS2_HOWTO | 177 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 Zend/OBJECTS2_HOWTO (limited to 'Zend/OBJECTS2_HOWTO') diff --git a/Zend/OBJECTS2_HOWTO b/Zend/OBJECTS2_HOWTO new file mode 100644 index 0000000000..9a0222e313 --- /dev/null +++ b/Zend/OBJECTS2_HOWTO @@ -0,0 +1,177 @@ +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 +-------------------- + +get_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 not oftenly used by the engine itself, but may +be used by some internal functions. + +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). + +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. 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_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_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_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_name - get the name of the class the object belongs to + +compare_objects - compares if two objects are equal -- cgit v1.2.1