release/src/router/php/Zend/OBJECTS2_HOWTO

   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