Return to OBJECTS2_HOWTO CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php / Zend

php

    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