ext_php_rs/
error.rs

1//! Error and result types returned from the library functions.
2
3use std::{
4    error::Error as ErrorTrait,
5    ffi::{CString, NulError},
6    fmt::Display,
7    num::TryFromIntError,
8};
9
10use crate::{
11    boxed::ZBox,
12    exception::PhpException,
13    ffi::php_error_docref,
14    flags::{ClassFlags, DataType, ErrorType, ZvalTypeFlags},
15    types::ZendObject,
16};
17
18/// The main result type which is passed by the library.
19pub type Result<T, E = Error> = std::result::Result<T, E>;
20
21/// The main error type which is passed by the library inside the custom
22/// [`Result`] type.
23#[derive(Debug)]
24#[non_exhaustive]
25pub enum Error {
26    /// An incorrect number of arguments was given to a PHP function.
27    ///
28    /// The enum carries two integers - the first representing the minimum
29    /// number of arguments expected, and the second representing the number of
30    /// arguments that were received.
31    IncorrectArguments(usize, usize),
32    /// There was an error converting a Zval into a primitive type.
33    ///
34    /// The enum carries the data type of the Zval.
35    ZvalConversion(DataType),
36    /// The type of the Zval is unknown.
37    ///
38    /// The enum carries the integer representation of the type of Zval.
39    UnknownDatatype(u32),
40    /// Attempted to convert a [`ZvalTypeFlags`] struct to a [`DataType`].
41    /// The flags did not contain a datatype.
42    ///
43    /// The enum carries the flags that were attempted to be converted to a
44    /// [`DataType`].
45    InvalidTypeToDatatype(ZvalTypeFlags),
46    /// The function called was called in an invalid scope (calling
47    /// class-related functions inside of a non-class bound function).
48    InvalidScope,
49    /// The pointer inside a given type was invalid, either null or pointing to
50    /// garbage.
51    InvalidPointer,
52    /// The given property name does not exist.
53    InvalidProperty,
54    /// The string could not be converted into a C-string due to the presence of
55    /// a NUL character.
56    InvalidCString,
57    /// The string could not be converted into a valid Utf8 string
58    InvalidUtf8,
59    /// Could not call the given function.
60    Callable,
61    /// An object was expected.
62    Object,
63    /// An invalid exception type was thrown.
64    InvalidException(ClassFlags),
65    /// Converting integer arguments resulted in an overflow.
66    IntegerOverflow,
67    /// An exception was thrown in a function.
68    Exception(ZBox<ZendObject>),
69    /// A failure occurred while registering the stream wrapper
70    StreamWrapperRegistrationFailure,
71    /// A failure occurred while unregistering the stream wrapper
72    StreamWrapperUnregistrationFailure,
73    /// The SAPI write function is not available
74    SapiWriteUnavailable,
75    /// Failed to make an object lazy (PHP 8.4+)
76    LazyObjectFailed,
77}
78
79impl Display for Error {
80    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
81        match self {
82            Error::IncorrectArguments(n, expected) => write!(
83                f,
84                "Expected at least {expected} arguments, got {n} arguments."
85            ),
86            Error::ZvalConversion(ty) => write!(
87                f,
88                "Could not convert Zval from type {ty} into primitive type."
89            ),
90            Error::UnknownDatatype(dt) => write!(f, "Unknown datatype {dt}."),
91            Error::InvalidTypeToDatatype(dt) => {
92                write!(f, "Type flags did not contain a datatype: {dt:?}")
93            }
94            Error::InvalidScope => write!(f, "Invalid scope."),
95            Error::InvalidPointer => write!(f, "Invalid pointer."),
96            Error::InvalidProperty => write!(f, "Property does not exist on object."),
97            Error::InvalidCString => write!(
98                f,
99                "String given contains NUL-bytes which cannot be present in a C string."
100            ),
101            Error::InvalidUtf8 => write!(f, "Invalid Utf8 byte sequence."),
102            Error::Callable => write!(f, "Could not call given function."),
103            Error::Object => write!(f, "An object was expected."),
104            Error::InvalidException(flags) => {
105                write!(f, "Invalid exception type was thrown: {flags:?}")
106            }
107            Error::IntegerOverflow => {
108                write!(f, "Converting integer arguments resulted in an overflow.")
109            }
110            Error::Exception(e) => write!(f, "Exception was thrown: {e:?}"),
111            Error::StreamWrapperRegistrationFailure => {
112                write!(f, "A failure occurred while registering the stream wrapper")
113            }
114            Error::StreamWrapperUnregistrationFailure => {
115                write!(
116                    f,
117                    "A failure occurred while unregistering the stream wrapper"
118                )
119            }
120            Error::SapiWriteUnavailable => {
121                write!(f, "The SAPI write function is not available")
122            }
123            Error::LazyObjectFailed => {
124                write!(f, "Failed to make the object lazy")
125            }
126        }
127    }
128}
129
130impl ErrorTrait for Error {}
131
132impl From<NulError> for Error {
133    fn from(_: NulError) -> Self {
134        Self::InvalidCString
135    }
136}
137
138impl From<TryFromIntError> for Error {
139    fn from(_value: TryFromIntError) -> Self {
140        Self::IntegerOverflow
141    }
142}
143
144impl From<Error> for PhpException {
145    fn from(err: Error) -> Self {
146        Self::default(err.to_string())
147    }
148}
149
150/// Trigger an error that is reported in PHP the same way `trigger_error()` is.
151///
152/// See specific error type descriptions at <https://www.php.net/manual/en/errorfunc.constants.php>.
153///
154/// # Panics
155///
156/// * If the error type bits exceed `i32::MAX`.
157pub fn php_error(type_: &ErrorType, message: &str) {
158    let Ok(c_string) = CString::new(message) else {
159        return;
160    };
161
162    unsafe {
163        php_error_docref(
164            std::ptr::null(),
165            type_.bits().try_into().expect("Error type flags overflown"),
166            c_string.as_ptr(),
167        );
168    }
169}
ext_php_rs/error.rs

ext_php_rs/
error.rs
