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}
76
77impl Display for Error {
78    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
79        match self {
80            Error::IncorrectArguments(n, expected) => write!(
81                f,
82                "Expected at least {expected} arguments, got {n} arguments."
83            ),
84            Error::ZvalConversion(ty) => write!(
85                f,
86                "Could not convert Zval from type {ty} into primitive type."
87            ),
88            Error::UnknownDatatype(dt) => write!(f, "Unknown datatype {dt}."),
89            Error::InvalidTypeToDatatype(dt) => {
90                write!(f, "Type flags did not contain a datatype: {dt:?}")
91            }
92            Error::InvalidScope => write!(f, "Invalid scope."),
93            Error::InvalidPointer => write!(f, "Invalid pointer."),
94            Error::InvalidProperty => write!(f, "Property does not exist on object."),
95            Error::InvalidCString => write!(
96                f,
97                "String given contains NUL-bytes which cannot be present in a C string."
98            ),
99            Error::InvalidUtf8 => write!(f, "Invalid Utf8 byte sequence."),
100            Error::Callable => write!(f, "Could not call given function."),
101            Error::Object => write!(f, "An object was expected."),
102            Error::InvalidException(flags) => {
103                write!(f, "Invalid exception type was thrown: {flags:?}")
104            }
105            Error::IntegerOverflow => {
106                write!(f, "Converting integer arguments resulted in an overflow.")
107            }
108            Error::Exception(e) => write!(f, "Exception was thrown: {e:?}"),
109            Error::StreamWrapperRegistrationFailure => {
110                write!(f, "A failure occurred while registering the stream wrapper")
111            }
112            Error::StreamWrapperUnregistrationFailure => {
113                write!(
114                    f,
115                    "A failure occurred while unregistering the stream wrapper"
116                )
117            }
118            Error::SapiWriteUnavailable => {
119                write!(f, "The SAPI write function is not available")
120            }
121        }
122    }
123}
124
125impl ErrorTrait for Error {}
126
127impl From<NulError> for Error {
128    fn from(_: NulError) -> Self {
129        Self::InvalidCString
130    }
131}
132
133impl From<TryFromIntError> for Error {
134    fn from(_value: TryFromIntError) -> Self {
135        Self::IntegerOverflow
136    }
137}
138
139impl From<Error> for PhpException {
140    fn from(err: Error) -> Self {
141        Self::default(err.to_string())
142    }
143}
144
145/// Trigger an error that is reported in PHP the same way `trigger_error()` is.
146///
147/// See specific error type descriptions at <https://www.php.net/manual/en/errorfunc.constants.php>.
148///
149/// # Panics
150///
151/// * If the error type bits exceed `i32::MAX`.
152pub fn php_error(type_: &ErrorType, message: &str) {
153    let Ok(c_string) = CString::new(message) else {
154        return;
155    };
156
157    unsafe {
158        php_error_docref(
159            std::ptr::null(),
160            type_.bits().try_into().expect("Error type flags overflown"),
161            c_string.as_ptr(),
162        );
163    }
164}
ext_php_rs/error.rs

ext_php_rs/
error.rs
