1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146
//! Types and functions used for throwing exceptions from Rust to PHP.
use std::ffi::CString;
use crate::{
class::RegisteredClass,
error::{Error, Result},
ffi::zend_throw_exception_ex,
flags::ClassFlags,
zend::{ce, ClassEntry},
};
/// Result type with the error variant as a [`PhpException`].
pub type PhpResult<T = ()> = std::result::Result<T, PhpException>;
/// Represents a PHP exception which can be thrown using the `throw()` function.
/// Primarily used to return from a [`Result<T, PhpException>`] which can
/// immediately be thrown by the `ext-php-rs` macro API.
///
/// There are default [`From`] implementations for any type that implements
/// [`ToString`], so these can also be returned from these functions. You can
/// also implement [`From<T>`] for your custom error type.
#[derive(Debug)]
pub struct PhpException {
message: String,
code: i32,
ex: &'static ClassEntry,
}
impl PhpException {
/// Creates a new exception instance.
///
/// # Parameters
///
/// * `message` - Message to contain in the exception.
/// * `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 }
}
/// Creates a new default exception instance, using the default PHP
/// `Exception` type as the exception type, with an integer code of
/// zero.
///
/// # Parameters
///
/// * `message` - Message to contain in the exception.
pub fn default(message: String) -> Self {
Self::new(message, 0, ce::exception())
}
/// Creates an instance of an exception from a PHP class type and a message.
///
/// # Parameters
///
/// * `message` - Message to contain in the exception.
pub fn from_class<T: RegisteredClass>(message: String) -> Self {
Self::new(message, 0, T::get_metadata().ce())
}
/// 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)
}
}
impl From<String> for PhpException {
fn from(str: String) -> Self {
Self::default(str)
}
}
impl From<&str> for PhpException {
fn from(str: &str) -> Self {
Self::default(str.into())
}
}
#[cfg(feature = "anyhow")]
impl From<anyhow::Error> for PhpException {
fn from(err: anyhow::Error) -> Self {
Self::new(format!("{:#}", err), 0, crate::zend::ce::exception())
}
}
/// Throws an exception with a given message. See [`ClassEntry`] for some
/// built-in exception types.
///
/// Returns a result containing nothing if the exception was successfully thown.
///
/// # Parameters
///
/// * `ex` - The exception type to throw.
/// * `message` - The message to display when throwing the exception.
///
/// # Examples
///
/// ```no_run
/// use ext_php_rs::{zend::{ce, ClassEntry}, exception::throw};
///
/// throw(ce::compile_error(), "This is a CompileError.");
/// ```
pub fn throw(ex: &ClassEntry, message: &str) -> Result<()> {
throw_with_code(ex, 0, message)
}
/// Throws an exception with a given message and status code. See [`ClassEntry`]
/// for some built-in exception types.
///
/// Returns a result containing nothing if the exception was successfully thown.
///
/// # Parameters
///
/// * `ex` - The exception type to throw.
/// * `code` - The status code to use when throwing the exception.
/// * `message` - The message to display when throwing the exception.
///
/// # Examples
///
/// ```no_run
/// use ext_php_rs::{zend::{ce, ClassEntry}, exception::throw_with_code};
///
/// throw_with_code(ce::compile_error(), 123, "This is a CompileError.");
/// ```
pub fn throw_with_code(ex: &ClassEntry, code: i32, message: &str) -> Result<()> {
let flags = ex.flags();
// Can't throw an interface or abstract class.
if flags.contains(ClassFlags::Interface) || flags.contains(ClassFlags::Abstract) {
return Err(Error::InvalidException(flags));
}
// SAFETY: We are given a reference to a `ClassEntry` therefore when we cast it
// to a pointer it will be valid.
unsafe {
zend_throw_exception_ex(
(ex as *const _) as *mut _,
code as _,
CString::new("%s")?.as_ptr(),
CString::new(message)?.as_ptr(),
)
};
Ok(())
}