diff options
Diffstat (limited to 'Zend/OBJECTS2_HOWTO')
| -rw-r--r-- | Zend/OBJECTS2_HOWTO | 195 |
1 files changed, 0 insertions, 195 deletions
diff --git a/Zend/OBJECTS2_HOWTO b/Zend/OBJECTS2_HOWTO deleted file mode 100644 index aef370330d..0000000000 --- a/Zend/OBJECTS2_HOWTO +++ /dev/null @@ -1,195 +0,0 @@ -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 modifyable 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 |