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 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269
//! Builder and objects relating to function and method arguments.
use std::{ffi::CString, ptr};
use crate::{
convert::{FromZvalMut, IntoZvalDyn},
error::{Error, Result},
ffi::{
_zend_expected_type, _zend_expected_type_Z_EXPECTED_ARRAY,
_zend_expected_type_Z_EXPECTED_BOOL, _zend_expected_type_Z_EXPECTED_DOUBLE,
_zend_expected_type_Z_EXPECTED_LONG, _zend_expected_type_Z_EXPECTED_OBJECT,
_zend_expected_type_Z_EXPECTED_RESOURCE, _zend_expected_type_Z_EXPECTED_STRING,
zend_internal_arg_info, zend_wrong_parameters_count_error,
},
flags::DataType,
types::Zval,
zend::ZendType,
};
/// Represents an argument to a function.
#[derive(Debug)]
pub struct Arg<'a> {
name: String,
_type: DataType,
as_ref: bool,
allow_null: bool,
variadic: bool,
default_value: Option<String>,
zval: Option<&'a mut Zval>,
variadic_zvals: Vec<Option<&'a mut Zval>>,
}
impl<'a> Arg<'a> {
/// Creates a new argument.
///
/// # Parameters
///
/// * `name` - The name of the parameter.
/// * `_type` - The type of the parameter.
pub fn new<T: Into<String>>(name: T, _type: DataType) -> Self {
Arg {
name: name.into(),
_type,
as_ref: false,
allow_null: false,
variadic: false,
default_value: None,
zval: None,
variadic_zvals: vec![],
}
}
/// Sets the argument as a reference.
#[allow(clippy::wrong_self_convention)]
pub fn as_ref(mut self) -> Self {
self.as_ref = true;
self
}
/// Sets the argument as variadic.
pub fn is_variadic(mut self) -> Self {
self.variadic = true;
self
}
/// Sets the argument as nullable.
pub fn allow_null(mut self) -> Self {
self.allow_null = true;
self
}
/// Sets the default value for the argument.
pub fn default<T: Into<String>>(mut self, default: T) -> Self {
self.default_value = Some(default.into());
self
}
/// Attempts to consume the argument, converting the inner type into `T`.
/// Upon success, the result is returned in a [`Result`].
///
/// If the conversion fails (or the argument contains no value), the
/// argument is returned in an [`Err`] variant.
///
/// As this function consumes, it cannot return a reference to the
/// underlying zval.
pub fn consume<T>(mut self) -> Result<T, Self>
where
for<'b> T: FromZvalMut<'b>,
{
self.zval
.as_mut()
.and_then(|zv| T::from_zval_mut(zv.dereference_mut()))
.ok_or(self)
}
/// Attempts to retrieve the value of the argument.
/// This will be None until the ArgParser is used to parse
/// the arguments.
pub fn val<T>(&'a mut self) -> Option<T>
where
T: FromZvalMut<'a>,
{
self.zval
.as_mut()
.and_then(|zv| T::from_zval_mut(zv.dereference_mut()))
}
/// Retrice all the variadic values for this Rust argument.
pub fn variadic_vals<T>(&'a mut self) -> Vec<T>
where
T: FromZvalMut<'a>,
{
self.variadic_zvals
.iter_mut()
.filter_map(|zv| zv.as_mut())
.filter_map(|zv| T::from_zval_mut(zv.dereference_mut()))
.collect()
}
/// Attempts to return a reference to the arguments internal Zval.
///
/// # Returns
///
/// * `Some(&Zval)` - The internal zval.
/// * `None` - The argument was empty.
pub fn zval(&mut self) -> Option<&mut &'a mut Zval> {
self.zval.as_mut()
}
/// Attempts to call the argument as a callable with a list of arguments to
/// pass to the function. Note that a thrown exception inside the
/// callable is not detectable, therefore you should check if the return
/// value is valid rather than unwrapping. Returns a result containing the
/// return value of the function, or an error.
///
/// You should not call this function directly, rather through the
/// [`call_user_func`](crate::call_user_func) macro.
///
/// # Parameters
///
/// * `params` - A list of parameters to call the function with.
#[inline(always)]
pub fn try_call(&self, params: Vec<&dyn IntoZvalDyn>) -> Result<Zval> {
self.zval.as_ref().ok_or(Error::Callable)?.try_call(params)
}
/// Returns the internal PHP argument info.
pub(crate) fn as_arg_info(&self) -> Result<ArgInfo> {
Ok(ArgInfo {
name: CString::new(self.name.as_str())?.into_raw(),
type_: ZendType::empty_from_type(
self._type,
self.as_ref,
self.variadic,
self.allow_null,
)
.ok_or(Error::InvalidCString)?,
default_value: match &self.default_value {
Some(val) => CString::new(val.as_str())?.into_raw(),
None => ptr::null(),
},
})
}
}
impl From<Arg<'_>> for _zend_expected_type {
fn from(arg: Arg) -> Self {
let err = match arg._type {
DataType::False | DataType::True => _zend_expected_type_Z_EXPECTED_BOOL,
DataType::Long => _zend_expected_type_Z_EXPECTED_LONG,
DataType::Double => _zend_expected_type_Z_EXPECTED_DOUBLE,
DataType::String => _zend_expected_type_Z_EXPECTED_STRING,
DataType::Array => _zend_expected_type_Z_EXPECTED_ARRAY,
DataType::Object(_) => _zend_expected_type_Z_EXPECTED_OBJECT,
DataType::Resource => _zend_expected_type_Z_EXPECTED_RESOURCE,
_ => unreachable!(),
};
if arg.allow_null {
err + 1
} else {
err
}
}
}
/// Internal argument information used by Zend.
pub type ArgInfo = zend_internal_arg_info;
/// Parses the arguments of a function.
pub struct ArgParser<'a, 'b> {
args: Vec<&'b mut Arg<'a>>,
min_num_args: Option<usize>,
arg_zvals: Vec<Option<&'a mut Zval>>,
}
impl<'a, 'b> ArgParser<'a, 'b> {
/// Builds a new function argument parser.
pub fn new(arg_zvals: Vec<Option<&'a mut Zval>>) -> Self {
ArgParser {
args: vec![],
min_num_args: None,
arg_zvals,
}
}
/// Adds a new argument to the parser.
///
/// # Parameters
///
/// * `arg` - The argument to add to the parser.
pub fn arg(mut self, arg: &'b mut Arg<'a>) -> Self {
self.args.push(arg);
self
}
/// Sets the next arguments to be added as not required.
pub fn not_required(mut self) -> Self {
self.min_num_args = Some(self.args.len());
self
}
/// Uses the argument parser to parse the arguments contained in the given
/// `ExecuteData` object. Returns successfully if the arguments were
/// parsed.
///
/// This function can only be safely called from within an exported PHP
/// function.
///
/// # Parameters
///
/// * `execute_data` - The execution data from the function.
///
/// # Errors
///
/// Returns an [`Error`] type if there were too many or too little arguments
/// passed to the function. The user has already been notified so you
/// should break execution after seeing an error type.
pub fn parse(mut self) -> Result<()> {
let max_num_args = self.args.len();
let min_num_args = self.min_num_args.unwrap_or(max_num_args);
let num_args = self.arg_zvals.len();
let has_variadic = self.args.last().map_or(false, |arg| arg.variadic);
if num_args < min_num_args || (!has_variadic && num_args > max_num_args) {
// SAFETY: Exported C function is safe, return value is unused and parameters
// are copied.
unsafe { zend_wrong_parameters_count_error(min_num_args as _, max_num_args as _) };
return Err(Error::IncorrectArguments(num_args, min_num_args));
}
for (i, arg_zval) in self.arg_zvals.into_iter().enumerate() {
let arg = match self.args.get_mut(i) {
Some(arg) => Some(arg),
// Only select the last item if it's variadic
None => self.args.last_mut().filter(|arg| arg.variadic),
};
if let Some(arg) = arg {
if arg.variadic {
arg.variadic_zvals.push(arg_zval);
} else {
arg.zval = arg_zval;
}
}
}
Ok(())
}
}