Annotation of embedaddon/php/Zend/OBJECTS2_HOWTO, revision 1.1
1.1 ! misho 1: Creating an object
! 2: ------------------
! 3:
! 4: Object can be created in the following ways:
! 5:
! 6: 1. As a result of a function call. E.g.:
! 7:
! 8: $foo = create_new_foo("parameter");
! 9: $foo->run();
! 10:
! 11: The function should create a new zval, create new object and get the
! 12: handle for it, set handle and handler table as needed. Note that the
! 13: handle is the only ID of the object, so it should be enough to
! 14: identify it.
! 15:
! 16: 2. Overriding create_object handler for class. E.g.:
! 17:
! 18: $foo = new Java("some.Class.here", "parameter");
! 19: $foo->run();
! 20:
! 21: The create_object handler function should create a new zval, create
! 22: new object and get the handle for it, set handle and handler table as
! 23: needed, and also provide constructor method that would handle
! 24: constructor call. The get_constructor handler table entry should be
! 25: used for that. Do not rely class entry's constructor, unless you refer
! 26: to it from get_constructor handler.
! 27:
! 28: Object maintenance
! 29: ------------------
! 30:
! 31: The handlers add_ref and del_ref are called when a new zval referring
! 32: to the object is created. This does not create a new object - both
! 33: zvals still refer to the same object.
! 34:
! 35: clone_obj handler should create a new object, identical to an old one,
! 36: but being a separate entity.
! 37:
! 38: delete_obj should destroy an object, all references to it become
! 39: invalid.
! 40:
! 41: Object access - read
! 42: --------------------
! 43:
! 44: read_property is used to read object's property. This value is not
! 45: meant to be changed. The handler returns zval * with the value.
! 46:
! 47: Object access - write
! 48: ---------------------
! 49:
! 50: write_property is used to directly write object's property by
! 51: name. This handler is used to assign property variables or to change them
! 52: in operations like += or ++ (unless get_property_zval_ptr is also set).
! 53:
! 54: get_property_zval_ptr is used to obtain pointer to modifiable zval for
! 55: operations like += or ++. This should be used only if your object model
! 56: stores properties as real zval's that can be modified from outside.
! 57: Otherwise this handler should be NULL and the engine will use
! 58: read_property and write_property instead.
! 59:
! 60: get_property_ptr is used to obtain zval ** for future writing to
! 61: it. If your object properties are stored as zval*, return real place
! 62: where the property is stored. If the aren't, the best way is to create
! 63: proxy object and handle it via get and set methods (see below).
! 64: This method is meant to be used for send-by-reference and assign-by-reference
! 65: use of object properties. If you don;t want to implement property
! 66: referencing for your objects, you can set this handler to NULL.
! 67:
! 68: get and set handlers are used when engine needs to access the object
! 69: as a value. E.g., in the following situation:
! 70:
! 71: $foo =& $obj->bar;
! 72: $foo = 1;
! 73:
! 74: if $foo is an object (e.g., proxy object from get_property_ptr) it
! 75: would be accessed using write handler.
! 76:
! 77: Object access - method call
! 78: ---------------------------
! 79:
! 80: get_method handler is used to find method description by name. It
! 81: should set right type, function name and parameter mask for the
! 82: method. If the type is ZEND_OVERLOADED_FUNCTION, the method would be
! 83: called via call_method handler, otherwise it would be called with
! 84: standard Zend means.
! 85:
! 86: get_constructor performs the same function as get_method, but for the
! 87: object constructor.
! 88:
! 89: call_method handler is used to perform method call. Parameters are
! 90: passed like to any other Zend internal function.
! 91:
! 92: Object - comparison
! 93: -------------------
! 94:
! 95: Objects can be compared via compare_objects handler. This is used with
! 96: == operation, === compares objects by handles, i.e., return true if
! 97: and only if it's really the same object. Note that objects from
! 98: different object types (i.e., having different handlers) can not be
! 99: compared.
! 100:
! 101: Objects - reflection
! 102: --------------------
! 103:
! 104: get_class_name is used to retrieve class name of the object.
! 105: get_class_entry returns class entry (zend_class_entry) for the object,
! 106: in case there exists PHP class for it.
! 107: No other reflection functions are currently implemented.
! 108:
! 109: Objects - data structures and handlers
! 110: ---------------------------------------
! 111:
! 112: The object is represented by the following structure:
! 113:
! 114: struct _zend_object_value {
! 115: zend_object_handle handle;
! 116: zend_object_handlers *handlers;
! 117: };
! 118:
! 119: handle is an ID of the object among the objects of the same type (not
! 120: class!). The type of the object and how it behaves is determined by
! 121: the handler table.
! 122:
! 123: typedef struct _zend_object_handlers {
! 124: zend_object_add_ref_t add_ref;
! 125: zend_object_del_ref_t del_ref;
! 126: zend_object_delete_obj_t delete_obj;
! 127: zend_object_clone_obj_t clone_obj;
! 128: zend_object_read_property_t read_property;
! 129: zend_object_write_property_t write_property;
! 130: zend_object_get_property_ptr_t get_property_ptr;
! 131: zend_object_get_property_zval_ptr_t get_property_zval_ptr;
! 132: zend_object_get_t get;
! 133: zend_object_set_t set;
! 134: zend_object_has_property_t has_property;
! 135: zend_object_unset_property_t unset_property;
! 136: zend_object_get_properties_t get_properties;
! 137: zend_object_get_method_t get_method;
! 138: zend_object_call_method_t call_method;
! 139: zend_object_get_constructor_t get_constructor;
! 140: zend_object_get_class_entry_t get_class_entry;
! 141: zend_object_get_class_name_t get_class_name;
! 142: zend_object_compare_t compare_objects;
! 143: } zend_object_handlers;
! 144:
! 145: See zend_object_handlers.h for prototypes. All objects are passed as zval's.
! 146:
! 147: Handlers explained:
! 148:
! 149: add_ref - called when a copy of the object handle is created.
! 150:
! 151: del_ref - called when a copy of the object handle is destroyed.
! 152:
! 153: delete_obj - called when an object needs to be destroyed.
! 154:
! 155: clone_obj - called when a new object identical to an old one should be
! 156: created (unlike Zend Engine 1, this never happens unless explicitly
! 157: asked for).
! 158:
! 159: read_property - returns zval *, containing the value of the
! 160: property. Is used when value of the property should be retrieved for
! 161: reading.
! 162:
! 163: write_property - assigns value to certain property of the object.
! 164:
! 165: get_property_zval_ptr - retrieves zval** for being directly modified by
! 166: the engine. If your properties are not zval's, don't define it.
! 167:
! 168: get_property_ptr - retrieves zval** for the property of the value, to
! 169: be used for read and write. If object properties are not zval's
! 170: natively, this method should create and return proxy object for use
! 171: with get and set methods.
! 172:
! 173: get - retrieves zval* for object contents. To be used mainly with
! 174: proxy objects from get_property_ptr, but also may be used for
! 175: convert_to_* functions.
! 176:
! 177: set - sets value for object contents. To be used mainly with
! 178: proxy objects from get_property_ptr.
! 179:
! 180: has_property - checks if the object has certain property set.
! 181:
! 182: unset_property - removes value for the property of the object
! 183:
! 184: get_method - retrieves description of the method
! 185:
! 186: call_method - calls the method (parameters should be put on stack like
! 187: for any other PHP internal function).
! 188:
! 189: get_constructor - get description for the object constructor method
! 190:
! 191: get_class_entry - should return the class entry for the object
! 192:
! 193: get_class_name - get the name of the class the object belongs to
! 194:
! 195: compare_objects - compares if two objects are equal
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to OBJECTS2_HOWTO CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php / Zend