ext_php_rs/
macros.rs

1//! Macros for interacting with PHP, mainly when the function takes variadic
2//! arguments. Unfortunately, this is the best way to handle these.
3//! Note that most of these will introduce unsafe into your code base.
4
5/// Starts the PHP extension information table displayed when running
6/// `phpinfo();` Must be run *before* rows are inserted into the table.
7#[macro_export]
8macro_rules! info_table_start {
9    () => {
10        unsafe { $crate::ffi::php_info_print_table_start() };
11    };
12}
13
14/// Ends the PHP extension information table. Must be run *after* all rows have
15/// been inserted into the table.
16#[macro_export]
17macro_rules! info_table_end {
18    () => {
19        unsafe { $crate::ffi::php_info_print_table_end() }
20    };
21}
22
23/// Sets the header for the PHP extension information table. Takes as many
24/// string arguments as required.
25#[macro_export]
26macro_rules! info_table_header {
27    ($($element:expr),*) => {$crate::_info_table_row!(php_info_print_table_header, $($element),*)};
28}
29
30/// Adds a row to the PHP extension information table. Takes as many string
31/// arguments as required.
32#[macro_export]
33macro_rules! info_table_row {
34    ($($element:expr),*) => {$crate::_info_table_row!(php_info_print_table_row, $($element),*)};
35}
36
37/// INTERNAL: Calls a variadic C function with the number of parameters, then
38/// following with the parameters.
39#[doc(hidden)]
40#[macro_export]
41macro_rules! _info_table_row {
42    ($fn: ident, $($element: expr),*) => {
43        unsafe {
44            $crate::ffi::$fn($crate::_info_table_row!(@COUNT; $($element),*) as i32, $(::std::ffi::CString::new($element).unwrap().as_ptr()),*);
45        }
46    };
47
48    (@COUNT; $($element: expr),*) => {
49        <[()]>::len(&[$($crate::_info_table_row![@SUBST; $element]),*])
50    };
51    (@SUBST; $_: expr) => { () };
52}
53
54/// Attempts to call a given PHP callable.
55///
56/// # Parameters
57///
58/// * `$fn` - The 'function' to call. Can be an [`Arg`] or a [`Zval`].
59/// * ...`$param` - The parameters to pass to the function. Must be able to be
60///   converted into a [`Zval`].
61///
62/// [`Arg`]: crate::args::Arg
63/// [`Zval`]: crate::types::Zval
64#[macro_export]
65macro_rules! call_user_func {
66    ($fn: expr) => {
67        $fn.try_call(vec![])
68    };
69
70    ($fn: expr, $($param: expr),*) => {
71        $fn.try_call(vec![$(&$param),*])
72    };
73}
74
75/// Parses a given list of arguments using the [`ArgParser`] class.
76///
77/// # Examples
78///
79/// This example parses all of the arguments. If one is invalid, execution of
80/// the function will stop at the `parse_args!` macro invocation. The user is
81/// notified via PHP's argument parsing system.
82///
83/// In this case, all of the arguments are required.
84///
85/// ```
86/// # #[macro_use] extern crate ext_php_rs;
87/// use ext_php_rs::{
88///     parse_args,
89///     args::Arg,
90///     flags::DataType,
91///     zend::ExecuteData,
92///     types::Zval,
93/// };
94///
95/// pub extern "C" fn example_fn(execute_data: &mut ExecuteData, _: &mut Zval) {
96///     let mut x = Arg::new("x", DataType::Long);
97///     let mut y = Arg::new("y", DataType::Long);
98///     let mut z = Arg::new("z", DataType::Long);
99///
100///     parse_args!(execute_data, x, y, z);
101/// }
102/// ```
103///
104/// This example is similar to the one above, apart from the fact that the `z`
105/// argument is not required. Note the semicolon separating the first two
106/// arguments from the second.
107///
108/// ```
109/// use ext_php_rs::{
110///     parse_args,
111///     args::Arg,
112///     flags::DataType,
113///     zend::ExecuteData,
114///     types::Zval,
115/// };
116///
117/// pub extern "C" fn example_fn(execute_data: &mut ExecuteData, _: &mut Zval) {
118///     let mut x = Arg::new("x", DataType::Long);
119///     let mut y = Arg::new("y", DataType::Long);
120///     let mut z = Arg::new("z", DataType::Long);
121///
122///     parse_args!(execute_data, x, y; z);
123/// }
124/// ```
125///
126/// [`ArgParser`]: crate::args::ArgParser
127#[macro_export]
128macro_rules! parse_args {
129    ($ed: expr, $($arg: expr),*) => {{
130        let parser = $ed.parser()
131            $(.arg(&mut $arg))*
132            .parse();
133        if parser.is_err() {
134            return;
135        }
136    }};
137
138    ($ed: expr, $($arg: expr),* ; $($opt: expr),*) => {{
139        let parser = $ed.parser()
140            $(.arg(&mut $arg))*
141            .not_required()
142            $(.arg(&mut $opt))*
143            .parse();
144        if parser.is_err() {
145            return;
146        }
147    }};
148}
149
150/// Throws an exception and returns from the current function.
151///
152/// Wraps the [`throw`] function by inserting a `return` statement after
153/// throwing the exception.
154///
155/// [`throw`]: crate::exception::throw
156///
157/// # Examples
158///
159/// ```
160/// use ext_php_rs::{
161///     throw,
162///     zend::{ce, ClassEntry, ExecuteData},
163///     types::Zval,
164/// };
165///
166/// pub extern "C" fn example_fn(execute_data: &mut ExecuteData, _: &mut Zval) {
167///     let something_wrong = true;
168///     if something_wrong {
169///         throw!(ce::exception(), "Something is wrong!");
170///     }
171///
172///     assert!(false); // This will not run.
173/// }
174/// ```
175#[macro_export]
176macro_rules! throw {
177    ($ex: expr, $reason: expr) => {
178        $crate::exception::throw($ex, $reason);
179        return;
180    };
181}
182
183/// Implements a set of traits required to convert types that implement
184/// [`RegisteredClass`] to and from [`ZendObject`]s and [`Zval`]s. Generally,
185/// this macro should not be called directly, as it is called on any type that
186/// uses the [`php_class`] macro.
187///
188/// The following traits are implemented:
189///
190/// * `FromZendObject for &'a T`
191/// * `FromZendObjectMut for &'a mut T`
192/// * `FromZval for &'a T`
193/// * `FromZvalMut for &'a mut T`
194/// * `IntoZendObject for T`
195/// * `IntoZval for T`
196///
197/// These implementations are required while we wait on the stabilisation of
198/// specialisation.
199///
200/// # Examples
201///
202/// ```
203/// # use ext_php_rs::{convert::{IntoZval, FromZval}, types::{Zval, ZendObject}, class::{RegisteredClass}};
204/// use ext_php_rs::class_derives;
205///
206/// struct Test {
207///     a: i32,
208///     b: i64
209/// }
210///
211/// impl RegisteredClass for Test {
212///     const CLASS_NAME: &'static str = "Test";
213///
214///     const CONSTRUCTOR: Option<ext_php_rs::class::ConstructorMeta<Self>> = None;
215///
216///     fn get_metadata() -> &'static ext_php_rs::class::ClassMetadata<Self> {
217///         todo!()
218///     }
219///
220///     fn get_properties<'a>(
221///     ) -> std::collections::HashMap<&'static str, ext_php_rs::props::Property<'a, Self>>
222///     {
223///         todo!()
224///     }
225/// }
226///
227/// class_derives!(Test);
228///
229/// fn into_zval_test() -> Zval {
230///     let x = Test { a: 5, b: 10 };
231///     x.into_zval(false).unwrap()
232/// }
233///
234/// fn from_zval_test<'a>(zv: &'a Zval) -> &'a Test {
235///     <&Test>::from_zval(zv).unwrap()
236/// }
237/// ```
238///
239/// [`RegisteredClass`]: crate::class::RegisteredClass
240/// [`ZendObject`]: crate::types::ZendObject
241/// [`Zval`]: crate::types::Zval
242/// [`php_class`]: crate::php_class
243#[macro_export]
244macro_rules! class_derives {
245    ($type: ty) => {
246        impl<'a> $crate::convert::FromZendObject<'a> for &'a $type {
247            #[inline]
248            fn from_zend_object(obj: &'a $crate::types::ZendObject) -> $crate::error::Result<Self> {
249                let obj = $crate::types::ZendClassObject::<$type>::from_zend_obj(obj)
250                    .ok_or($crate::error::Error::InvalidScope)?;
251                Ok(&**obj)
252            }
253        }
254
255        impl<'a> $crate::convert::FromZendObjectMut<'a> for &'a mut $type {
256            #[inline]
257            fn from_zend_object_mut(
258                obj: &'a mut $crate::types::ZendObject,
259            ) -> $crate::error::Result<Self> {
260                let obj = $crate::types::ZendClassObject::<$type>::from_zend_obj_mut(obj)
261                    .ok_or($crate::error::Error::InvalidScope)?;
262                Ok(&mut **obj)
263            }
264        }
265
266        impl<'a> $crate::convert::FromZval<'a> for &'a $type {
267            const TYPE: $crate::flags::DataType = $crate::flags::DataType::Object(Some(
268                <$type as $crate::class::RegisteredClass>::CLASS_NAME,
269            ));
270
271            #[inline]
272            fn from_zval(zval: &'a $crate::types::Zval) -> ::std::option::Option<Self> {
273                <Self as $crate::convert::FromZendObject>::from_zend_object(zval.object()?).ok()
274            }
275        }
276
277        impl<'a> $crate::convert::FromZvalMut<'a> for &'a mut $type {
278            const TYPE: $crate::flags::DataType = $crate::flags::DataType::Object(Some(
279                <$type as $crate::class::RegisteredClass>::CLASS_NAME,
280            ));
281
282            #[inline]
283            fn from_zval_mut(zval: &'a mut $crate::types::Zval) -> ::std::option::Option<Self> {
284                <Self as $crate::convert::FromZendObjectMut>::from_zend_object_mut(
285                    zval.object_mut()?,
286                )
287                .ok()
288            }
289        }
290
291        impl $crate::convert::IntoZendObject for $type {
292            #[inline]
293            fn into_zend_object(
294                self,
295            ) -> $crate::error::Result<$crate::boxed::ZBox<$crate::types::ZendObject>> {
296                Ok($crate::types::ZendClassObject::new(self).into())
297            }
298        }
299
300        impl $crate::convert::IntoZval for $type {
301            const TYPE: $crate::flags::DataType = $crate::flags::DataType::Object(Some(
302                <$type as $crate::class::RegisteredClass>::CLASS_NAME,
303            ));
304
305            #[inline]
306            fn set_zval(
307                self,
308                zv: &mut $crate::types::Zval,
309                persistent: bool,
310            ) -> $crate::error::Result<()> {
311                use $crate::convert::IntoZendObject;
312
313                self.into_zend_object()?.set_zval(zv, persistent)
314            }
315        }
316    };
317}
318
319/// Derives `From<T> for Zval` and `IntoZval` for a given type.
320macro_rules! into_zval {
321    ($type: ty, $fn: ident, $dt: ident) => {
322        impl From<$type> for $crate::types::Zval {
323            fn from(val: $type) -> Self {
324                let mut zv = Self::new();
325                zv.$fn(val);
326                zv
327            }
328        }
329
330        impl $crate::convert::IntoZval for $type {
331            const TYPE: $crate::flags::DataType = $crate::flags::DataType::$dt;
332
333            fn set_zval(self, zv: &mut $crate::types::Zval, _: bool) -> $crate::error::Result<()> {
334                zv.$fn(self);
335                Ok(())
336            }
337        }
338    };
339}
340
341/// Derives `TryFrom<Zval> for T` and `FromZval for T` on a given type.
342macro_rules! try_from_zval {
343    ($type: ty, $fn: ident, $dt: ident) => {
344        impl $crate::convert::FromZval<'_> for $type {
345            const TYPE: $crate::flags::DataType = $crate::flags::DataType::$dt;
346
347            fn from_zval(zval: &$crate::types::Zval) -> ::std::option::Option<Self> {
348                use ::std::convert::TryInto;
349
350                zval.$fn().and_then(|val| val.try_into().ok())
351            }
352        }
353
354        impl ::std::convert::TryFrom<$crate::types::Zval> for $type {
355            type Error = $crate::error::Error;
356
357            fn try_from(value: $crate::types::Zval) -> $crate::error::Result<Self> {
358                <Self as $crate::convert::FromZval>::from_zval(&value)
359                    .ok_or($crate::error::Error::ZvalConversion(value.get_type()))
360            }
361        }
362    };
363}
364
365/// Prints to the PHP standard output, without a newline.
366///
367/// Acts exactly the same as the built-in [`print`] macro.
368///
369/// # Panics
370///
371/// Panics if the generated string could not be converted to a `CString` due to
372/// `NUL` characters.
373#[macro_export]
374macro_rules! php_print {
375    ($arg: tt) => {{
376        $crate::zend::printf($arg).expect("Failed to print to PHP stdout");
377    }};
378
379    ($($arg: tt) *) => {{
380        let args = format!($($arg)*);
381        $crate::zend::printf(args.as_str()).expect("Failed to print to PHP stdout");
382    }};
383}
384
385/// Prints to the PHP standard output, with a newline.
386///
387/// The newline is only a newline character regardless of platform (no carriage
388/// return).
389///
390/// Acts exactly the same as the built-in [`println`] macro.
391///
392/// # Panics
393///
394/// Panics if the generated string could not be converted to a `CString` due to
395/// `NUL` characters.
396#[macro_export]
397macro_rules! php_println {
398    () => {
399        $crate::php_print!("\n");
400    };
401
402    ($fmt: tt) => {
403        $crate::php_print!(concat!($fmt, "\n"));
404    };
405
406    ($fmt: tt, $($arg: tt) *) => {
407        $crate::php_print!(concat!($fmt, "\n"), $($arg)*);
408    };
409}
410
411pub(crate) use into_zval;
412pub(crate) use try_from_zval;
ext_php_rs/macros.rs

ext_php_rs/
macros.rs
