Add support for throwing Exception objects

Currently we only support throwing exception class entries, i.e. stateless exceptions. Ideally we also want to support throwing a ZVal which has a ClassEntry that extends the Exception PHP class. This can be used to throw stateful exceptions which is not uncommon.

This PR is missing one piece: `throw_object` will currently `drop` the Zval when the function is completed, causing reference / null pointer errors. It seems `ZVal::Drop` doesn't actually free the zval currently, it just sets the type to NULL (which also breaks things.) Discussed briefly in https://discord.com/channels/115233111977099271/1025314959179120714 on how best to solve this, but I'm not totally clear still! Ideally I think we want `throw_object` to own the `zval` but not free it once the function returns.

Author: joehoyle

allowed_bindings.rs

@@ -81,6 +81,7 @@ bind! {
     zend_string,
     zend_string_init_interned,
     zend_throw_exception_ex,
+    zend_throw_exception_object,
     zend_type,
     zend_value,
     zend_wrong_parameters_count_error,

src/exception.rs

@@ -6,8 +6,9 @@ use crate::{
     class::RegisteredClass,
     error::{Error, Result},
     ffi::zend_throw_exception_ex,
+    ffi::zend_throw_exception_object,
     flags::ClassFlags,
-    zend::{ce, ClassEntry},
+    zend::{ce, ClassEntry}, types::Zval,
 };
 
 /// Result type with the error variant as a [`PhpException`].
@@ -25,6 +26,7 @@ pub struct PhpException {
     message: String,
     code: i32,
     ex: &'static ClassEntry,
+    object: Option<Zval>,
 }
 
 impl PhpException {
@@ -36,7 +38,7 @@ impl PhpException {
     /// * `code` - Integer code to go inside the exception.
     /// * `ex` - Exception type to throw.
     pub fn new(message: String, code: i32, ex: &'static ClassEntry) -> Self {
-        Self { message, code, ex }
+        Self { message, code, ex, object: None, }
     }
 
     /// Creates a new default exception instance, using the default PHP
@@ -59,10 +61,27 @@ impl PhpException {
         Self::new(message, 0, T::get_metadata().ce())
     }
 
+    /// Set the Zval object for the exception.
+    ///
+    /// Exceptions can be based of instantiated Zval objects when you are throwing a custom exception with
+    /// stateful properties.
+    ///
+    /// # Parameters
+    ///
+    /// * `object` - The Zval object.
+    pub fn set_object(&mut self, object: Option<Zval>) {
+        self.object = object;
+    }
+
     /// Throws the exception, returning nothing inside a result if successful
     /// and an error otherwise.
     pub fn throw(self) -> Result<()> {
-        throw_with_code(self.ex, self.code, &self.message)
+        match self.object {
+            Some(object) => {
+                throw_object(object)
+            },
+            None => throw_with_code(self.ex, self.code, &self.message),
+        }
     }
 }
 
@@ -146,3 +165,38 @@ pub fn throw_with_code(ex: &ClassEntry, code: i32, message: &str) -> Result<()>
     };
     Ok(())
 }
+
+
+/// Throws an exception object.
+///
+/// Returns a result containing nothing if the exception was successfully
+/// thrown.
+///
+/// # Parameters
+///
+/// * `object` - The zval of type object
+///
+/// # Examples
+///
+/// ```no_run
+/// use ext_php_rs::{zend::{ce, ClassEntry}, exception::throw_with_code};
+///
+/// #[php_class]
+/// #[extends(ext_php_rs::zend::ce::exception())]
+/// pub struct JsException {
+///     #[prop(flags = ext_php_rs::flags::PropertyFlags::Public)]
+///     message: String,
+///     #[prop(flags = ext_php_rs::flags::PropertyFlags::Public)]
+///     code: i32,
+///     #[prop(flags = ext_php_rs::flags::PropertyFlags::Public)]
+///     file: String,
+/// }
+/// let error = JsException { message: "A JS error occurred.", code: 100, file: "index.js" };
+/// throw_object( error.into_val(true) );
+/// ```
+pub fn throw_object(zval: Zval) -> Result<()> {
+    unsafe {
+        zend_throw_exception_object((&zval as *const _) as *mut _);
+    };
+    Ok(())
+}