Type Alias ZendObject 

pub type ZendObject = zend_object;

A PHP object.

This type does not maintain any information about its type, for example, classes with have associated Rust structs cannot be accessed through this type. ZendClassObject is used for this purpose, and you can convert between the two.

Aliased Type

#[repr(C)]
pub struct ZendObject {
    pub gc: _zend_refcounted_h,
    pub handle: u32,
    pub extra_flags: u32,
    pub ce: *mut _zend_class_entry,
    pub handlers: *const _zend_object_handlers,
    pub properties: *mut _zend_array,
    pub properties_table: [_zval_struct; 1],
}

Fields

gc: _zend_refcounted_h

handle: u32

extra_flags: u32

ce: *mut _zend_class_entry

handlers: *const _zend_object_handlers

properties: *mut _zend_array

properties_table: [_zval_struct; 1]

Implementations

impl ZendObject

pub fn new(ce: &ClassEntry) -> ZBox<Self>

Creates a new ZendObject, returned inside an ZBox<ZendObject> wrapper.

Parameters

• ce - The type of class the new object should be an instance of.

Panics

Panics when allocating memory for the new object fails.

pub fn new_stdclass() -> ZBox<Self>

Creates a new stdClass instance, returned inside an ZBox<ZendObject> wrapper.

Panics

Panics if allocating memory for the object fails, or if the stdClass class entry has not been registered with PHP yet.

Example

use ext_php_rs::types::ZendObject;

let mut obj = ZendObject::new_stdclass();

obj.set_property("hello", "world");

pub fn ref_count(&self) -> u32

Returns the number of references to the object.

use ext_php_rs::types::ZendObject;

fn count(obj: &ZendObject) -> u32 {
    obj.ref_count()
}

No public method changes the reference count:

use ext_php_rs::types::ZendObject;

fn release(obj: &mut ZendObject) {
    obj.del_ref();
}

pub fn from_class_object<T: RegisteredClass>( obj: ZBox<ZendClassObject<T>>, ) -> ZBox<Self>

Converts a class object into an owned ZendObject. This removes any possibility of accessing the underlying attached Rust struct.

pub fn get_class_entry(&self) -> &'static ClassEntry

Returns the ClassEntry associated with this object.

The class entry is valid only until the module shuts down. Do not keep the reference across a module restart.

Panics

Panics if the class entry is invalid.

pub fn get_class_name(&self) -> Result<String>

Attempts to retrieve the class name of the object.

Errors

• Error::InvalidScope - If the object handlers or the class name cannot be retrieved.

pub fn instance_of(&self, ce: &ClassEntry) -> bool

Returns whether this object is an instance of the given ClassEntry.

This method checks the class and interface inheritance chain.

Panics

Panics if the class entry is invalid.

pub fn is_instance<T: RegisteredClass>(&self) -> bool

Checks if the given object is an instance of a registered class with Rust type T.

This method doesn’t check the class and interface inheritance chain.

pub fn is_traversable(&self) -> bool

Returns whether this object is an instance of \Traversable

Panics

Panics if the class entry is invalid.

pub fn try_call_method( &self, name: &str, params: Vec<&dyn IntoZvalDyn>, ) -> Result<Zval>

Tries to call a method on the object.

Returns

Returns the return value of the method, or an error if the method could not be found or called.

Errors

• Error::Callable - If the method could not be found.
• If a parameter could not be converted to a zval.
• If the parameter count is bigger than u32::MAX.

pub fn get_property<'a, T>(&'a self, name: &str) -> Result<T>

where T: FromZval<'a>,

Attempts to read a property from the Object. Returns a result containing the value of the property if it exists and can be read, and an Error otherwise.

Parameters

• name - The name of the property.
• query - The type of query to use when attempting to get a property.

Errors

• Error::InvalidScope - If the object handlers or the properties cannot be retrieved.

pub fn set_property(&mut self, name: &str, value: impl IntoZval) -> Result<()>

Attempts to set a property on the object.

Parameters

• name - The name of the property.
• value - The value to set the property to.

Errors

• Error::InvalidScope - If the object handlers or the properties cannot be retrieved.

pub fn has_property(&self, name: &str, query: PropertyQuery) -> Result<bool>

Checks if a property exists on an object. Takes a property name and query parameter, which defines what classifies if a property exists or not. See PropertyQuery for more information.

Parameters

• name - The name of the property.
• query - The ‘query’ to classify if a property exists.

Errors

• Error::InvalidScope - If the object handlers or the properties cannot be retrieved.

pub fn get_properties(&self) -> Result<&HashTable>

Attempts to retrieve the properties of the object. Returned inside a Zend Hashtable.

Errors

• Error::InvalidScope - If the object handlers or the properties cannot be retrieved.

pub fn extract<'a, T>(&'a self) -> Result<T>

where T: FromZendObject<'a>,

Extracts some type from a Zend object.

This is a wrapper function around FromZendObject::extract().

Errors

Returns an error if the conversion fails.

pub fn get_id(&self) -> u32

Returns an unique identifier for the object.

The id is guaranteed to be unique for the lifetime of the object. Once the object is destroyed, it may be reused for other objects. This is equivalent to calling the spl_object_id PHP function.

pub fn hash(&self) -> String

Computes an unique hash for the object.

The hash is guaranteed to be unique for the lifetime of the object. Once the object is destroyed, it may be reused for other objects. This is equivalent to calling the spl_object_hash PHP function.

pub fn is_lazy(&self) -> bool

Available on php84 only.

Returns whether this object is a lazy object (ghost or proxy).

Lazy objects are objects whose initialization is deferred until one of their properties is accessed.

This is a PHP 8.4+ feature.

pub fn is_lazy_proxy(&self) -> bool

Available on php84 only.

Returns whether this object is a lazy proxy.

Lazy proxies wrap a real instance that is created when the proxy is first accessed. The proxy and real instance have different identities.

This is a PHP 8.4+ feature.

pub fn is_lazy_ghost(&self) -> bool

Available on php84 only.

Returns whether this object is a lazy ghost.

Lazy ghosts are indistinguishable from non-lazy objects once initialized. The ghost object itself becomes the real instance.

This is a PHP 8.4+ feature.

pub fn is_lazy_initialized(&self) -> bool

Available on php84 only.

Returns whether this lazy object has been initialized.

Returns false for non-lazy objects.

This is a PHP 8.4+ feature.

pub fn lazy_init(&mut self) -> Option<&mut Self>

Available on php84 only.

Triggers initialization of a lazy object.

If the object is a lazy ghost, this populates the object in place. If the object is a lazy proxy, this creates the real instance.

Returns None if the object is not lazy or initialization fails.

This is a PHP 8.4+ feature.

pub fn mark_lazy_initialized(&mut self) -> Option<&mut Self>

Available on php84 only.

Marks a lazy object as initialized without calling the initializer.

This can be used to manually initialize a lazy object’s properties and then mark it as initialized.

Returns None if the object is not lazy.

This is a PHP 8.4+ feature.

pub fn lazy_get_instance(&mut self) -> Option<&mut Self>

Available on php84 only.

For lazy proxies, returns the real instance after initialization.

Returns None if this is not a lazy proxy or if not initialized.

This is a PHP 8.4+ feature.

pub fn make_lazy_ghost<F>(&mut self, initializer: F) -> Result<()>

where F: Fn() + 'static,

Available on php84 and crate feature closure only.

Converts this object into a lazy ghost with the given initializer.

The initializer closure will be called when the object’s properties are first accessed. The closure should perform initialization logic.

Parameters

• initializer - A closure that performs initialization. The closure returns (). Any state needed for initialization should be captured in the closure.

Returns

Returns Ok(()) if the object was successfully made lazy, or an error if the operation failed.

Example

use ext_php_rs::types::ZendObject;

fn make_lazy_example(obj: &mut ZendObject) -> ext_php_rs::error::Result<()> {
    let init_value = "initialized".to_string();
    obj.make_lazy_ghost(Box::new(move || {
        // Use captured state for initialization
        println!("Initializing with: {}", init_value);
    }) as Box<dyn Fn()>)?;
    Ok(())
}

Errors

Returns an error if the initializer closure cannot be converted to a PHP callable or if the object cannot be made lazy.

Safety

This is a PHP 8.4+ feature. The closure must be 'static as it may be called at any time during the object’s lifetime.

Note: PHP 8.4 lazy objects only work with user-defined PHP classes, not internal classes. Rust-defined classes cannot be made lazy.

pub fn make_lazy_proxy<F>(&mut self, initializer: F) -> Result<()>

where F: Fn() -> Option<ZBox<ZendObject>> + 'static,

Available on php84 and crate feature closure only.

Converts this object into a lazy proxy with the given initializer.

The initializer closure will be called when the object’s properties are first accessed. The closure should return the real instance that the proxy will forward to.

Parameters

• initializer - A closure that returns Option<ZBox<ZendObject>>, the real instance. Any state needed should be captured in the closure.

Returns

Returns Ok(()) if the object was successfully made lazy, or an error if the operation failed.

Example

use ext_php_rs::types::ZendObject;
use ext_php_rs::boxed::ZBox;

fn make_proxy_example(obj: &mut ZendObject) -> ext_php_rs::error::Result<()> {
    obj.make_lazy_proxy(Box::new(|| {
        // Create and return the real instance
        Some(ZendObject::new_stdclass())
    }) as Box<dyn Fn() -> Option<ZBox<ZendObject>>>)?;
    Ok(())
}

Errors

Returns an error if the initializer closure cannot be converted to a PHP callable or if the object cannot be made lazy.

Safety

This is a PHP 8.4+ feature. The closure must be 'static as it may be called at any time during the object’s lifetime.

Note: PHP 8.4 lazy objects only work with user-defined PHP classes, not internal classes. Rust-defined classes cannot be made lazy.

Trait Implementations

impl Debug for ZendObject

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> FromZval<'a> for &'a ZendObject

const TYPE: DataType = DataType::ANY_OBJECT

The corresponding type of the implemented value in PHP.

fn from_zval(zval: &'a Zval) -> Option<Self>

Attempts to retrieve an instance of Self from a reference to a Zval.

const NULLABLE: bool = false

Whether a PHP argument of this type accepts null and may be omitted.

fn from_missing() -> Option<Self>

The value to use when a PHP argument of this type was omitted by the caller. None means the argument is required.

impl<'a> FromZvalMut<'a> for &'a mut ZendObject

const TYPE: DataType = DataType::ANY_OBJECT

The corresponding type of the implemented value in PHP.

fn from_zval_mut(zval: &'a mut Zval) -> Option<Self>

Attempts to retrieve an instance of Self from a mutable reference to a Zval.

const NULLABLE: bool = false

Whether a PHP argument of this type accepts null and may be omitted.

const BY_REF: bool = false

Whether a PHP argument of this type is declared pass-by-reference (&$arg). Set it for types that mutate a PHP value in place, so the engine separates the value before the call.

fn from_missing() -> Option<Self>

The value to use when a PHP argument of this type was omitted by the caller. None means the argument is required.

impl IntoZval for &mut ZendObject

const TYPE: DataType = DataType::ANY_OBJECT

The corresponding type of the implemented value in PHP.

const NULLABLE: bool = false

Whether converting into a Zval may result in null.

fn set_zval(self, zv: &mut Zval, _: bool) -> Result<()>

Sets the content of a pre-existing zval. Returns a result containing nothing if setting the content was successful.

fn into_zval(self, persistent: bool) -> Result<Zval>

Converts a Rust primitive type into a Zval. Returns a result containing the Zval if successful.

impl ZBoxable for ZendObject

fn free(&mut self)

Frees the memory pointed to by self, calling any destructors required in the process.