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