Nearly all operations on objects in PHP go through object handlers and every magic method or magic interface is implemented with an object or class handler internally. Furthermore there are quite a few handlers which are not exposed to userland PHP. For example internal classes can have custom comparison and cast behavior.
Here are all the object handlers with their signature and a small description.
zval *read_property(zend_object *object, zend_string *member, int type, void **cache_slot, zval *rv)¶
zval *write_property(zend_object *object, zend_string *member, zval *value, void **cache_slot)¶
int has_property(zend_object *zobj, zend_string *name, int has_set_exists, void **cache_slot)¶
void unset_property(zend_object *zobj, zend_string *name, void **cache_slot)¶
zval *get_property_ptr_ptr(zend_object *zobj, zend_string *name, int type, void **cache_slot)¶
These handlers correspond to the
get_property_ptr_ptris the internal equivalent of
__getreturning by reference.
cache_slotis used to store the property offset and
read_propertymay directly return a zval owned by the object, in which case its reference count should not be modified by
read_property, and the caller should not release it. Alternatively, it may return
rvfor temporary zvals (e.g. result of call to
__get), in which case the refcount should be incremented, and the caller is responsible for releasing the value.
zval *read_dimension(zend_object *object, zval *offset, int type, zval *rv)¶
void write_dimension(zend_object *object, zval *offset, zval *value)¶
int has_dimension(zend_object *object, zval *offset, int check_empty)¶
void unset_dimension(zend_object *object, zval *offset)¶
This set of handlers is the internal representation of the
read_dimensionis used for temporary values returned from
HashTable *get_properties(zend_object *zobj)¶
HashTable *get_debug_info(zend_object *object, int *is_temp)¶
Used to get the object properties as a hashtable. The former is more general purpose, for example it is also used for the
get_object_varsfunction. The latter on the other hand is used exclusively to display properties in debugging functions like
var_dump. So even if your object does not provide any formal properties you can still have a meaningful debug output.
zend_function *get_method(zend_object **obj_ptr, zend_string *method_name, const zval *key)¶
get_methodhandler fetches the
zend_functionused to call a certain method. Optionally
keycan be passed as an optimization to avoid lowercasing
method_namein case it is already present.
zend_function *get_constructor(zend_object *zobj)¶
get_method, but getting the constructor function. The most common reason to override this handler is to disallow manual construction by throwing an error in the handler.
zend_result count_elements(zend_object *object, zend_long *count)¶
This is just the internal way of implementing the
Countable::countmethod. The function returns a
zend_resultand assigns the value to the
int compare(zval *o1, zval *o2)¶
comparehandler is a required handler that computes equality of the given object and another value. Note that the other value isn’t necessarily an object of the same class, or even an object at all. The handler should return negative numbers if the lhs is smaller, 0 if they are equal, or a positive number is the lhs is larger. If the values are uncomparable
ZEND_UNCOMPARABLEshould be returned.
zend_result cast_object(zend_object *readobj, zval *writeobj, int type)¶
Internal classes have the ability to implement a custom compare behavior and override casting behavior for all types. Userland classes on the other hand only have the ability to override object to string casting through
zend_result get_closure(zend_object *obj, zend_class_entry **ce_ptr, zend_function **fptr_ptr, zend_object **obj_ptr, bool check_only)¶
This handler is invoked when the object is used as a function, i.e. it is the internal version of
__invoke. The name derives from the fact that its main use is for the implementation of closures (the
zend_string *get_class_name(const zend_object *zobj)¶
This handler is used to get the class name from an object for debugging contexts. There should be little reason to overwrite it.
zend_object *clone_obj(zend_object *old_object)¶
clone_objhandler is called when executing
clone $old_object. By default PHP performs a shallow clone on objects, which means properties containing objects are not be cloned but both the old and new object will point to the same object. The
clone_objallows for this behavior to be customized. It’s also used to inhibit
HashTable *get_gc(zend_object *zobj, zval **table, int *n)¶
get_gchandler should return all variables that are held by the object, so cyclic dependencies can be properly collected. If the object doesn’t maintain a property hashmap (because it doesn’t store any dynamic properties) it can use
tableto store a pointer directly into the list of zvals, along with a count of properties.
void dtor_obj(zend_object *object)¶
void free_obj(zend_object *object)¶
dtor_objis called before
free_obj. The object must remain in a valid state after dtor_obj finishes running. Unlike
free_obj, it is run prior to deactivation of the executor during shutdown, which allows user code to run. This handler is not guaranteed to be called (e.g. on fatal error), and as such should not be used to release resources or deallocate memory. Furthermore, releasing resources in this handler can break detection of memory leaks, as cycles may be broken early.
dtor_objshould be used only to call user destruction hooks, such as
free_objshould release any resources the object holds, without freeing the object structure itself. The object does not need to be in a valid state after
free_objwill always be invoked, even if the object leaks or a fatal error occurs. However, during shutdown it may be called once the executor is no longer active, in which case execution of user code may be skipped.
zend_result do_operation(zend_uchar opcode, zval *result, zval *op1, zval *op2)¶
do_operationis an optional handler that will be invoked for various arithmetic and binary operations on instances of the given class. This allows for operator overloading semantics to be implemented for custom classes. Examples for overloadable operators are
zend_array *get_properties_for(zend_object *object, zend_prop_purpose purpose)¶
get_properties_forcan be used to customize the list of object properties returned for various purposes. The purposes are defined in
zend_prop_purpose, which currently entails