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

ext_php_rs/
error.rs
