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/// Attempts to call a given PHP callable with named arguments.
76///
77/// This macro supports PHP 8.0+ named arguments, allowing you to pass
78/// arguments by name rather than position.
79///
80/// # Syntax
81///
82/// ```ignore
83/// // Named arguments only
84/// call_user_func_named!(callable, name1: value1, name2: value2)
85///
86/// // Positional arguments followed by named arguments
87/// call_user_func_named!(callable, [pos1, pos2], name1: value1, name2: value2)
88/// ```
89///
90/// # Parameters
91///
92/// * `$fn` - The 'function' to call. Can be an [`Arg`] or a [`Zval`].
93/// * `$name: $value` - Named parameters as `name: value` pairs.
94/// * `[$($pos),*]` - Optional positional parameters in square brackets.
95///
96/// # Examples
97///
98/// ```ignore
99/// use ext_php_rs::{call_user_func_named, types::ZendCallable};
100///
101/// let str_replace = ZendCallable::try_from_name("str_replace").unwrap();
102///
103/// // Using named arguments only
104/// let result = call_user_func_named!(str_replace,
105///     search: "world",
106///     replace: "PHP",
107///     subject: "Hello world"
108/// ).unwrap();
109///
110/// // Mixing positional and named arguments
111/// let result = call_user_func_named!(str_replace, ["world", "PHP"],
112///     subject: "Hello world"
113/// ).unwrap();
114/// ```
115///
116/// [`Arg`]: crate::args::Arg
117/// [`Zval`]: crate::types::Zval
118/// Note: Parameter names must be valid Rust identifiers.
119/// For other names, use `try_call_named` directly.
120#[macro_export]
121macro_rules! call_user_func_named {
122    // Named arguments only
123    ($fn: expr, $($name: ident : $value: expr),+ $(,)?) => {
124        $fn.try_call_named(&[$((stringify!($name), &$value as &dyn $crate::convert::IntoZvalDyn)),+])
125    };
126
127    // Positional arguments followed by named arguments
128    ($fn: expr, [$($pos: expr),* $(,)?], $($name: ident : $value: expr),+ $(,)?) => {
129        $fn.try_call_with_named(
130            &[$(&$pos as &dyn $crate::convert::IntoZvalDyn),*],
131            &[$((stringify!($name), &$value as &dyn $crate::convert::IntoZvalDyn)),+]
132        )
133    };
134
135}
136
137/// Parses a given list of arguments using the [`ArgParser`] class.
138///
139/// # Examples
140///
141/// This example parses all of the arguments. If one is invalid, execution of
142/// the function will stop at the `parse_args!` macro invocation. The user is
143/// notified via PHP's argument parsing system.
144///
145/// In this case, all of the arguments are required.
146///
147/// ```
148/// # #[macro_use] extern crate ext_php_rs;
149/// use ext_php_rs::{
150///     parse_args,
151///     args::Arg,
152///     flags::DataType,
153///     zend::ExecuteData,
154///     types::Zval,
155/// };
156///
157/// pub extern "C" fn example_fn(execute_data: &mut ExecuteData, _: &mut Zval) {
158///     let mut x = Arg::new("x", DataType::Long);
159///     let mut y = Arg::new("y", DataType::Long);
160///     let mut z = Arg::new("z", DataType::Long);
161///
162///     parse_args!(execute_data, x, y, z);
163/// }
164/// ```
165///
166/// This example is similar to the one above, apart from the fact that the `z`
167/// argument is not required. Note the semicolon separating the first two
168/// arguments from the second.
169///
170/// ```
171/// use ext_php_rs::{
172///     parse_args,
173///     args::Arg,
174///     flags::DataType,
175///     zend::ExecuteData,
176///     types::Zval,
177/// };
178///
179/// pub extern "C" fn example_fn(execute_data: &mut ExecuteData, _: &mut Zval) {
180///     let mut x = Arg::new("x", DataType::Long);
181///     let mut y = Arg::new("y", DataType::Long);
182///     let mut z = Arg::new("z", DataType::Long);
183///
184///     parse_args!(execute_data, x, y; z);
185/// }
186/// ```
187///
188/// [`ArgParser`]: crate::args::ArgParser
189#[macro_export]
190macro_rules! parse_args {
191    ($ed: expr, $($arg: expr),*) => {{
192        let parser = $ed.parser()
193            $(.arg(&mut $arg))*
194            .parse();
195        if parser.is_err() {
196            return;
197        }
198    }};
199
200    ($ed: expr, $($arg: expr),* ; $($opt: expr),*) => {{
201        let parser = $ed.parser()
202            $(.arg(&mut $arg))*
203            .not_required()
204            $(.arg(&mut $opt))*
205            .parse();
206        if parser.is_err() {
207            return;
208        }
209    }};
210}
211
212/// Throws an exception and returns from the current function.
213///
214/// Wraps the [`throw`] function by inserting a `return` statement after
215/// throwing the exception.
216///
217/// [`throw`]: crate::exception::throw
218///
219/// # Examples
220///
221/// ```
222/// use ext_php_rs::{
223///     throw,
224///     zend::{ce, ClassEntry, ExecuteData},
225///     types::Zval,
226/// };
227///
228/// pub extern "C" fn example_fn(execute_data: &mut ExecuteData, _: &mut Zval) {
229///     let something_wrong = true;
230///     if something_wrong {
231///         throw!(ce::exception(), "Something is wrong!");
232///     }
233///
234///     assert!(false); // This will not run.
235/// }
236/// ```
237#[macro_export]
238macro_rules! throw {
239    ($ex: expr, $reason: expr) => {
240        $crate::exception::throw($ex, $reason);
241        return;
242    };
243}
244
245/// Implements a set of traits required to convert types that implement
246/// [`RegisteredClass`] to and from [`ZendObject`]s and [`Zval`]s. Generally,
247/// this macro should not be called directly, as it is called on any type that
248/// uses the [`php_class`] macro.
249///
250/// The following traits are implemented:
251///
252/// * `FromZendObject for &'a T`
253/// * `FromZendObjectMut for &'a mut T`
254/// * `FromZval for &'a T`
255/// * `FromZvalMut for &'a mut T`
256/// * `IntoZendObject for T`
257/// * `IntoZval for T`
258///
259/// These implementations are required while we wait on the stabilisation of
260/// specialisation.
261///
262/// # Examples
263///
264/// ```
265/// # use ext_php_rs::{convert::{IntoZval, FromZval, IntoZvalDyn}, types::{Zval, ZendObject}, class::{RegisteredClass, ConstructorMeta, ClassEntryInfo}, builders::{ClassBuilder, FunctionBuilder}, zend::ClassEntry, flags::{ClassFlags, MethodFlags}, describe::DocComments};
266/// use ext_php_rs::class_derives;
267///
268/// struct Test {
269///     a: i32,
270///     b: i64
271/// }
272///
273/// impl RegisteredClass for Test {
274///     const CLASS_NAME: &'static str = "Test";
275///
276///     const BUILDER_MODIFIER: Option<fn(ClassBuilder) -> ClassBuilder> = None;
277///     const EXTENDS: Option<ClassEntryInfo> = None;
278///     const IMPLEMENTS: &'static [ClassEntryInfo] =  &[];
279///     const FLAGS: ClassFlags = ClassFlags::empty();
280///     const DOC_COMMENTS: DocComments = &[];
281///
282///     fn get_metadata() -> &'static ext_php_rs::class::ClassMetadata<Self> {
283///         todo!()
284///     }
285///
286///     fn method_builders() -> Vec<(FunctionBuilder<'static>, MethodFlags)> {
287///         todo!()
288///     }
289///
290///     fn constructor() -> Option<ConstructorMeta<Self>> {
291///         todo!()
292///     }
293///
294///     fn constants() -> &'static [(&'static str, &'static dyn IntoZvalDyn, DocComments)] {
295///         todo!()
296///     }
297/// }
298///
299/// class_derives!(Test);
300///
301/// fn into_zval_test() -> Zval {
302///     let x = Test { a: 5, b: 10 };
303///     x.into_zval(false).unwrap()
304/// }
305///
306/// fn from_zval_test<'a>(zv: &'a Zval) -> &'a Test {
307///     <&Test>::from_zval(zv).unwrap()
308/// }
309/// ```
310///
311/// [`RegisteredClass`]: crate::class::RegisteredClass
312/// [`ZendObject`]: crate::types::ZendObject
313/// [`Zval`]: crate::types::Zval
314/// [`php_class`]: crate::php_class
315#[macro_export]
316macro_rules! class_derives {
317    ($type: ty) => {
318        impl<'a> $crate::convert::FromZendObject<'a> for &'a $type {
319            #[inline]
320            fn from_zend_object(obj: &'a $crate::types::ZendObject) -> $crate::error::Result<Self> {
321                let obj = $crate::types::ZendClassObject::<$type>::from_zend_obj(obj)
322                    .ok_or($crate::error::Error::InvalidScope)?;
323                Ok(&**obj)
324            }
325        }
326
327        impl<'a> $crate::convert::FromZendObjectMut<'a> for &'a mut $type {
328            #[inline]
329            fn from_zend_object_mut(
330                obj: &'a mut $crate::types::ZendObject,
331            ) -> $crate::error::Result<Self> {
332                let obj = $crate::types::ZendClassObject::<$type>::from_zend_obj_mut(obj)
333                    .ok_or($crate::error::Error::InvalidScope)?;
334                Ok(&mut **obj)
335            }
336        }
337
338        impl<'a> $crate::convert::FromZval<'a> for &'a $type {
339            const TYPE: $crate::flags::DataType = $crate::flags::DataType::Object(Some(
340                <$type as $crate::class::RegisteredClass>::CLASS_NAME,
341            ));
342
343            #[inline]
344            fn from_zval(zval: &'a $crate::types::Zval) -> ::std::option::Option<Self> {
345                <Self as $crate::convert::FromZendObject>::from_zend_object(zval.object()?).ok()
346            }
347        }
348
349        impl<'a> $crate::convert::FromZvalMut<'a> for &'a mut $type {
350            const TYPE: $crate::flags::DataType = $crate::flags::DataType::Object(Some(
351                <$type as $crate::class::RegisteredClass>::CLASS_NAME,
352            ));
353
354            #[inline]
355            fn from_zval_mut(zval: &'a mut $crate::types::Zval) -> ::std::option::Option<Self> {
356                <Self as $crate::convert::FromZendObjectMut>::from_zend_object_mut(
357                    zval.object_mut()?,
358                )
359                .ok()
360            }
361        }
362
363        impl $crate::convert::IntoZendObject for $type {
364            #[inline]
365            fn into_zend_object(
366                self,
367            ) -> $crate::error::Result<$crate::boxed::ZBox<$crate::types::ZendObject>> {
368                Ok($crate::types::ZendClassObject::new(self).into())
369            }
370        }
371
372        impl $crate::convert::IntoZval for $type {
373            const TYPE: $crate::flags::DataType = $crate::flags::DataType::Object(Some(
374                <$type as $crate::class::RegisteredClass>::CLASS_NAME,
375            ));
376            const NULLABLE: bool = false;
377
378            #[inline]
379            fn set_zval(
380                self,
381                zv: &mut $crate::types::Zval,
382                persistent: bool,
383            ) -> $crate::error::Result<()> {
384                use $crate::convert::IntoZendObject;
385
386                self.into_zend_object()?.set_zval(zv, persistent)
387            }
388        }
389    };
390}
391
392/// Derives `From<T> for Zval` and `IntoZval` for a given type.
393macro_rules! into_zval {
394    ($type: ty, $fn: ident, $dt: ident) => {
395        impl From<$type> for $crate::types::Zval {
396            fn from(val: $type) -> Self {
397                let mut zv = Self::new();
398                zv.$fn(val);
399                zv
400            }
401        }
402
403        impl $crate::convert::IntoZval for $type {
404            const TYPE: $crate::flags::DataType = $crate::flags::DataType::$dt;
405            const NULLABLE: bool = false;
406
407            fn set_zval(self, zv: &mut $crate::types::Zval, _: bool) -> $crate::error::Result<()> {
408                zv.$fn(self);
409                Ok(())
410            }
411        }
412    };
413}
414
415/// Derives `TryFrom<Zval> for T` and `FromZval for T` on a given type.
416macro_rules! try_from_zval {
417    ($type: ty, $fn: ident, $dt: ident) => {
418        impl $crate::convert::FromZval<'_> for $type {
419            const TYPE: $crate::flags::DataType = $crate::flags::DataType::$dt;
420
421            fn from_zval(zval: &$crate::types::Zval) -> ::std::option::Option<Self> {
422                use ::std::convert::TryInto;
423
424                zval.$fn().and_then(|val| val.try_into().ok())
425            }
426        }
427
428        impl ::std::convert::TryFrom<$crate::types::Zval> for $type {
429            type Error = $crate::error::Error;
430
431            fn try_from(value: $crate::types::Zval) -> $crate::error::Result<Self> {
432                <Self as $crate::convert::FromZval>::from_zval(&value)
433                    .ok_or($crate::error::Error::ZvalConversion(value.get_type()))
434            }
435        }
436    };
437}
438
439/// Prints to the PHP standard output, without a newline.
440///
441/// Acts exactly the same as the built-in [`print`] macro.
442///
443/// # Panics
444///
445/// Panics if the generated string could not be converted to a `CString` due to
446/// `NUL` characters.
447#[macro_export]
448macro_rules! php_print {
449    ($arg: tt) => {{
450        $crate::zend::printf($arg).expect("Failed to print to PHP stdout");
451    }};
452
453    ($($arg: tt) *) => {{
454        let args = format!($($arg)*);
455        $crate::zend::printf(args.as_str()).expect("Failed to print to PHP stdout");
456    }};
457}
458
459/// Prints to the PHP standard output, with a newline.
460///
461/// The newline is only a newline character regardless of platform (no carriage
462/// return).
463///
464/// Acts exactly the same as the built-in [`println`] macro.
465///
466/// # Panics
467///
468/// Panics if the generated string could not be converted to a `CString` due to
469/// `NUL` characters.
470#[macro_export]
471macro_rules! php_println {
472    () => {
473        $crate::php_print!("\n");
474    };
475
476    ($fmt: tt) => {
477        $crate::php_print!(concat!($fmt, "\n"));
478    };
479
480    ($fmt: tt, $($arg: tt) *) => {
481        $crate::php_print!(concat!($fmt, "\n"), $($arg)*);
482    };
483}
484
485/// Writes binary data to the PHP standard output.
486///
487/// Unlike [`php_print!`], this macro is binary-safe and can handle data
488/// containing `NUL` bytes. It uses the SAPI module's `ub_write` function.
489///
490/// # Arguments
491///
492/// * `$data` - A byte slice (`&[u8]`) or byte literal (`b"..."`) to write.
493///
494/// # Returns
495///
496/// A `Result<usize>` containing the number of bytes written.
497///
498/// # Errors
499///
500/// Returns [`Error::SapiWriteUnavailable`] if the SAPI's `ub_write` function
501/// is not available.
502///
503/// [`Error::SapiWriteUnavailable`]: crate::error::Error::SapiWriteUnavailable
504///
505/// # Examples
506///
507/// ```ignore
508/// use ext_php_rs::php_write;
509///
510/// // Write a byte literal
511/// php_write!(b"Hello World").expect("write failed");
512///
513/// // Write binary data with NUL bytes (would panic with php_print!)
514/// php_write!(b"Hello\x00World").expect("write failed");
515///
516/// // Write a byte slice
517/// let data: &[u8] = &[0x48, 0x65, 0x6c, 0x6c, 0x6f];
518/// php_write!(data).expect("write failed");
519/// ```
520#[macro_export]
521macro_rules! php_write {
522    ($data: expr) => {{ $crate::zend::write($data) }};
523}
524
525/// Writes binary data to PHP's output stream with output buffering support.
526///
527/// This macro is both binary-safe (can handle `NUL` bytes) AND respects PHP's
528/// output buffering (`ob_start()`). Use this when you need both capabilities.
529///
530/// # Arguments
531///
532/// * `$data` - A byte slice (`&[u8]`) or byte literal (`b"..."`) to write.
533///
534/// # Returns
535///
536/// The number of bytes written.
537///
538/// # Comparison
539///
540/// | Macro | Binary-safe | Output Buffering |
541/// |-------|-------------|------------------|
542/// | `php_print!` | No | Yes |
543/// | `php_write!` | Yes | No (unbuffered) |
544/// | `php_output!` | Yes | Yes |
545///
546/// # Examples
547///
548/// ```ignore
549/// use ext_php_rs::php_output;
550///
551/// // Write binary data that will be captured by ob_start()
552/// php_output!(b"Hello\x00World");
553///
554/// // Use with output buffering
555/// // ob_start();
556/// // php_output!(b"captured");
557/// // $data = ob_get_clean(); // Contains "captured"
558/// ```
559#[macro_export]
560macro_rules! php_output {
561    ($data: expr) => {{ $crate::zend::output_write($data) }};
562}
ext_php_rs/macros.rs

ext_php_rs/
macros.rs
