21763720164

Committed 06 Feb 2026 07:47PM UTC coverage: 34.79% (+0.3%) from 34.453%

Build # 21763720164

Build Type

push

github

Committed by

web-flow

Commit Message

feat: eval PHP code from files (#671)

Coverage Stats

32 of 39 new or added lines in 1 file covered. (82.05%)

2117 of 6085 relevant lines covered (34.79%)

23.68 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

82.05

/src/php_eval.rs

//! Execute embedded PHP code within a running PHP extension.
//!
//! This module provides a way to compile and execute PHP code that has been
//! embedded into the extension binary at compile time using `include_bytes!`.
//!
//! Uses `zend_compile_string` + `zend_execute` (not `zend_eval_string`)
//! to avoid security scanner false positives and compatibility issues
//! with hardened PHP configurations.
//!
//! # Example
//!
//! ```rust,ignore
//! use ext_php_rs::php_eval;
//!
//! // Both include_bytes! and include_str! are supported:
//! const SETUP_BYTES: &[u8] = include_bytes!("../php/setup.php");
//! const SETUP_STR: &str = include_str!("../php/setup.php");
//!
//! php_eval::execute(SETUP_BYTES).expect("failed to execute embedded PHP");
//! php_eval::execute(SETUP_STR).expect("failed to execute embedded PHP");
//! ```

use crate::ffi;
use crate::types::ZendStr;
use crate::zend::try_catch;
use std::fmt;
use std::mem;
use std::panic::AssertUnwindSafe;

/// Errors that can occur when executing embedded PHP code.
#[derive(Debug)]
pub enum PhpEvalError {
    /// The code does not start with a `<?php` open tag.
    MissingOpenTag,
    /// PHP failed to compile the code (syntax error).
    CompilationFailed,
    /// The code executed but threw an unhandled exception.
    ExecutionFailed,
    /// A PHP fatal error (bailout) occurred during execution.
    Bailout,
}

impl fmt::Display for PhpEvalError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            PhpEvalError::MissingOpenTag => {
                write!(f, "PHP code must start with a <?php open tag")
            }
            PhpEvalError::CompilationFailed => write!(f, "PHP compilation failed (syntax error)"),
            PhpEvalError::ExecutionFailed => {
                write!(f, "PHP execution threw an unhandled exception")
            }
            PhpEvalError::Bailout => write!(f, "PHP fatal error (bailout) during execution"),
        }
    }
}

impl std::error::Error for PhpEvalError {}

/// Execute embedded PHP code within the running PHP engine.
///
/// The code **must** start with a `<?php` opening tag (case-insensitive),
/// optionally preceded by a UTF-8 BOM and/or whitespace. The tag is
/// stripped before compilation. The C wrapper uses
/// `ZEND_COMPILE_POSITION_AFTER_OPEN_TAG` (on PHP 8.2+) so the scanner
/// starts directly in PHP mode.
///
/// Error reporting is suppressed during execution and restored afterward,
/// matching the pattern used by production PHP extensions like Blackfire.
///
/// # Arguments
///
/// * `code` - Raw PHP source, typically from `include_bytes!` or
///   `include_str!`. Any type implementing `AsRef<[u8]>` is accepted.
///
/// # Errors
///
/// Returns [`PhpEvalError::MissingOpenTag`] if the code does not start
/// with `<?php`. Returns other [`PhpEvalError`] variants if compilation
/// fails, an exception is thrown, or a fatal error occurs.
pub fn execute(code: impl AsRef<[u8]>) -> Result<(), PhpEvalError> {
    let code = strip_bom(code.as_ref());
    let code = strip_php_open_tag(code).ok_or(PhpEvalError::MissingOpenTag)?;

    if code.is_empty() {
        return Ok(());
    }

    let source = ZendStr::new(code, false);

    // Suppress error reporting so compilation warnings from embedded
    // code don't bubble up to the application's error handler.
    // Saved outside `try_catch` so it is always restored, even on bailout.
    let eg = unsafe { ffi::ext_php_rs_executor_globals() };
    let prev_error_reporting = unsafe { mem::replace(&mut (*eg).error_reporting, 0) };

    let result = try_catch(AssertUnwindSafe(|| unsafe {
        let op_array = ffi::ext_php_rs_zend_compile_string(
            source.as_ptr().cast_mut(),
            c"embedded_php".as_ptr(),
        );

        if op_array.is_null() {
            return Err(PhpEvalError::CompilationFailed);
        }

        ffi::ext_php_rs_zend_execute(op_array);

        if !(*eg).exception.is_null() {
            return Err(PhpEvalError::ExecutionFailed);
        }

        Ok(())
    }));

    unsafe { (*eg).error_reporting = prev_error_reporting };

    match result {
        Err(_) => Err(PhpEvalError::Bailout),
        Ok(inner) => inner,
    }
}

fn strip_bom(code: &[u8]) -> &[u8] {
    if code.starts_with(&[0xEF, 0xBB, 0xBF]) {
        &code[3..]
    } else {
        code
    }
}

fn strip_php_open_tag(code: &[u8]) -> Option<&[u8]> {
    let trimmed = match code.iter().position(|b| !b.is_ascii_whitespace()) {
        Some(pos) => &code[pos..],
        None => return None,
    };

    if trimmed.len() >= 5 && trimmed[..5].eq_ignore_ascii_case(b"<?php") {
        Some(trimmed[5..].trim_ascii_start())
    } else {
        None
    }
}

#[cfg(feature = "embed")]
#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used)]
    use super::*;
    use crate::embed::Embed;

    #[test]
    fn test_execute_with_php_open_tag() {
        Embed::run(|| {
            let result = execute(b"<?php $x = 42;");
            assert!(result.is_ok());
        });
    }

    #[test]
    fn test_execute_with_php_open_tag_and_newline() {
        Embed::run(|| {
            let result = execute(b"<?php\n$x = 42;");
            assert!(result.is_ok());
        });
    }

    #[test]
    fn test_execute_tag_only() {
        Embed::run(|| {
            let result = execute(b"<?php");
            assert!(result.is_ok());
        });
    }

    #[test]
    fn test_execute_exception() {
        Embed::run(|| {
            let result = execute(b"<?php throw new \\RuntimeException('test');");
            assert!(matches!(result, Err(PhpEvalError::ExecutionFailed)));
        });
    }

    #[test]
    fn test_execute_missing_open_tag() {
        Embed::run(|| {
            let result = execute(b"$x = 1 + 2;");
            assert!(matches!(result, Err(PhpEvalError::MissingOpenTag)));
        });
    }

    #[test]
    fn test_execute_compilation_error() {
        Embed::run(|| {
            let result = execute(b"<?php this is not valid php {{{");
            assert!(matches!(result, Err(PhpEvalError::CompilationFailed)));
        });
    }

    #[test]
    fn test_execute_with_bom() {
        Embed::run(|| {
            let mut code = vec![0xEF, 0xBB, 0xBF];
            code.extend_from_slice(b"<?php $x = 'bom_test';");
            let result = execute(&code);
            assert!(result.is_ok());
        });
    }

    #[test]
    fn test_execute_defines_variable() {
        Embed::run(|| {
            let result = execute(b"<?php $embed_test = 'hello from embedded php';");
            assert!(result.is_ok());

            let val = Embed::eval("$embed_test;");
            assert!(val.is_ok());
            assert_eq!(val.unwrap().string().unwrap(), "hello from embedded php");
        });
    }

    #[test]
    fn test_execute_empty_code() {
        Embed::run(|| {
            let result = execute(b"");
            assert!(matches!(result, Err(PhpEvalError::MissingOpenTag)));
        });
    }

    #[test]
    fn test_execute_include_bytes_pattern() {
        Embed::run(|| {
            let code: &[u8] = b"<?php\n\
                $embedded_value = 42;\n\
                define('EMBEDDED_CONST', true);\n";
            let result = execute(code);
            assert!(result.is_ok());
        });
    }

    #[test]
    fn test_execute_with_str() {
        Embed::run(|| {
            let code: &str = "<?php $str_test = 'from_str';";
            let result = execute(code);
            assert!(result.is_ok());

            let val = Embed::eval("$str_test;");
            assert!(val.is_ok());
            assert_eq!(val.unwrap().string().unwrap(), "from_str");
        });
    }

    #[test]
    fn test_execute_with_string() {
        Embed::run(|| {
            let code = String::from("<?php $string_test = 'from_string';");
            let result = execute(code);
            assert!(result.is_ok());

            let val = Embed::eval("$string_test;");
            assert!(val.is_ok());
            assert_eq!(val.unwrap().string().unwrap(), "from_string");
        });
    }

    #[test]
    fn test_execute_with_vec() {
        Embed::run(|| {
            let code: Vec<u8> = b"<?php $vec_test = 'from_vec';".to_vec();
            let result = execute(code);
            assert!(result.is_ok());

            let val = Embed::eval("$vec_test;");
            assert!(val.is_ok());
            assert_eq!(val.unwrap().string().unwrap(), "from_vec");
        });
    }

    #[test]
    fn test_strip_bom() {
        let cases: &[(&[u8], &[u8])] = &[
            (&[0xEF, 0xBB, 0xBF, b'h', b'i'], b"hi"),
            (b"hello", b"hello"),
            (b"", b""),
        ];
        for (input, expected) in cases {
            assert_eq!(
                super::strip_bom(input),
                *expected,
                "input: {:?}",
                String::from_utf8_lossy(input)
            );
        }
    }

    #[test]
    fn test_strip_php_open_tag() {
        let cases: &[(&[u8], Option<&[u8]>)] = &[
            (b"<?php $x;", Some(b"$x;")),
            (b"<?php\n$x;", Some(b"$x;")),
            (b"<?php\r\n$x;", Some(b"$x;")),
            (b"<?php\t\n  $x;", Some(b"$x;")),
            (b"<?php", Some(b"")),
            (b"  <?php $x;", Some(b"$x;")),
            (b"<?PHP $x;", Some(b"$x;")),
            (b"<?Php\n$x;", Some(b"$x;")),
            (b"", None),
            (b"   ", None),
            (b"$x = 1;", None),
            (b"hello", None),
        ];
        for (input, expected) in cases {
            assert_eq!(
                super::strip_php_open_tag(input),
                *expected,
                "input: {:?}",
                String::from_utf8_lossy(input)
            );
        }
    }
}

1	//! Execute embedded PHP code within a running PHP extension.
2	//!
3	//! This module provides a way to compile and execute PHP code that has been
4	//! embedded into the extension binary at compile time using `include_bytes!`.
5	//!
6	//! Uses `zend_compile_string` + `zend_execute` (not `zend_eval_string`)
7	//! to avoid security scanner false positives and compatibility issues
8	//! with hardened PHP configurations.
9	//!
10	//! # Example
11	//!
12	//! ```rust,ignore
13	//! use ext_php_rs::php_eval;
14	//!
15	//! // Both include_bytes! and include_str! are supported:
16	//! const SETUP_BYTES: &[u8] = include_bytes!("../php/setup.php");
17	//! const SETUP_STR: &str = include_str!("../php/setup.php");
18	//!
19	//! php_eval::execute(SETUP_BYTES).expect("failed to execute embedded PHP");
20	//! php_eval::execute(SETUP_STR).expect("failed to execute embedded PHP");
21	//! ```
22
23	use crate::ffi;
24	use crate::types::ZendStr;
25	use crate::zend::try_catch;
26	use std::fmt;
27	use std::mem;
28	use std::panic::AssertUnwindSafe;
29
30	/// Errors that can occur when executing embedded PHP code.
31	#[derive(Debug)]
32	pub enum PhpEvalError {
33	/// The code does not start with a `<?php` open tag.
34	MissingOpenTag,
35	/// PHP failed to compile the code (syntax error).
36	CompilationFailed,
37	/// The code executed but threw an unhandled exception.
38	ExecutionFailed,
39	/// A PHP fatal error (bailout) occurred during execution.
40	Bailout,
41	}
42
43	impl fmt::Display for PhpEvalError {
NEW 44	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {	×
NEW 45	match self {	×
46	PhpEvalError::MissingOpenTag => {
NEW 47	write!(f, "PHP code must start with a <?php open tag")	×
48	}
NEW 49	PhpEvalError::CompilationFailed => write!(f, "PHP compilation failed (syntax error)"),	×
50	PhpEvalError::ExecutionFailed => {
NEW 51	write!(f, "PHP execution threw an unhandled exception")	×
52	}
NEW 53	PhpEvalError::Bailout => write!(f, "PHP fatal error (bailout) during execution"),	×
54	}
55	}
56	}
57
58	impl std::error::Error for PhpEvalError {}
59
60	/// Execute embedded PHP code within the running PHP engine.
61	///
62	/// The code must start with a `<?php` opening tag (case-insensitive),
63	/// optionally preceded by a UTF-8 BOM and/or whitespace. The tag is
64	/// stripped before compilation. The C wrapper uses
65	/// `ZEND_COMPILE_POSITION_AFTER_OPEN_TAG` (on PHP 8.2+) so the scanner
66	/// starts directly in PHP mode.
67	///
68	/// Error reporting is suppressed during execution and restored afterward,
69	/// matching the pattern used by production PHP extensions like Blackfire.
70	///
71	/// # Arguments
72	///
73	/// * `code` - Raw PHP source, typically from `include_bytes!` or
74	/// `include_str!`. Any type implementing `AsRef<[u8]>` is accepted.
75	///
76	/// # Errors
77	///
78	/// Returns [`PhpEvalError::MissingOpenTag`] if the code does not start
79	/// with `<?php`. Returns other [`PhpEvalError`] variants if compilation
80	/// fails, an exception is thrown, or a fatal error occurs.
81	pub fn execute(code: impl AsRef<[u8]>) -> Result<(), PhpEvalError> {	13✔
82	let code = strip_bom(code.as_ref());	39✔
83	let code = strip_php_open_tag(code).ok_or(PhpEvalError::MissingOpenTag)?;	65✔
84
85	if code.is_empty() {	22✔
86	return Ok(());	1✔
87	}
88
89	let source = ZendStr::new(code, false);	30✔
90
91	// Suppress error reporting so compilation warnings from embedded
92	// code don't bubble up to the application's error handler.
93	// Saved outside `try_catch` so it is always restored, even on bailout.
94	let eg = unsafe { ffi::ext_php_rs_executor_globals() };	20✔
95	let prev_error_reporting = unsafe { mem::replace(&mut (*eg).error_reporting, 0) };	30✔
96
97	let result = try_catch(AssertUnwindSafe(\|\| unsafe {	20✔
98	let op_array = ffi::ext_php_rs_zend_compile_string(	20✔
99	source.as_ptr().cast_mut(),	20✔
100	c"embedded_php".as_ptr(),	20✔
101	);
102
103	if op_array.is_null() {	20✔
104	return Err(PhpEvalError::CompilationFailed);	1✔
105	}
106
107	ffi::ext_php_rs_zend_execute(op_array);	18✔
108
109	if !(*eg).exception.is_null() {	9✔
110	return Err(PhpEvalError::ExecutionFailed);	1✔
111	}
112
113	Ok(())	8✔
114	}));
115
116	unsafe { (*eg).error_reporting = prev_error_reporting };	10✔
117
118	match result {	10✔
NEW 119	Err(_) => Err(PhpEvalError::Bailout),	×
120	Ok(inner) => inner,	20✔
121	}
122	}
123
124	fn strip_bom(code: &[u8]) -> &[u8] {	16✔
125	if code.starts_with(&[0xEF, 0xBB, 0xBF]) {	48✔
126	&code[3..]	2✔
127	} else {
128	code	14✔
129	}
130	}
131
132	fn strip_php_open_tag(code: &[u8]) -> Option<&[u8]> {	25✔
133	let trimmed = match code.iter().position(\|b\| !b.is_ascii_whitespace()) {	126✔
134	Some(pos) => &code[pos..],	44✔
135	None => return None,	3✔
136	};
137
138	if trimmed.len() >= 5 && trimmed[..5].eq_ignore_ascii_case(b"<?php") {	88✔
139	Some(trimmed[5..].trim_ascii_start())	19✔
140	} else {
141	None	3✔
142	}
143	}
144
145	#[cfg(feature = "embed")]
146	#[cfg(test)]
147	mod tests {
148	#![allow(clippy::unwrap_used)]
149	use super::*;
150	use crate::embed::Embed;
151
152	#[test]
153	fn test_execute_with_php_open_tag() {
154	Embed::run(\|\| {
155	let result = execute(b"<?php $x = 42;");
156	assert!(result.is_ok());
157	});
158	}
159
160	#[test]
161	fn test_execute_with_php_open_tag_and_newline() {
162	Embed::run(\|\| {
163	let result = execute(b"<?php\n$x = 42;");
164	assert!(result.is_ok());
165	});
166	}
167
168	#[test]
169	fn test_execute_tag_only() {
170	Embed::run(\|\| {
171	let result = execute(b"<?php");
172	assert!(result.is_ok());
173	});
174	}
175
176	#[test]
177	fn test_execute_exception() {
178	Embed::run(\|\| {
179	let result = execute(b"<?php throw new \\RuntimeException('test');");
180	assert!(matches!(result, Err(PhpEvalError::ExecutionFailed)));
181	});
182	}
183
184	#[test]
185	fn test_execute_missing_open_tag() {
186	Embed::run(\|\| {
187	let result = execute(b"$x = 1 + 2;");
188	assert!(matches!(result, Err(PhpEvalError::MissingOpenTag)));
189	});
190	}
191
192	#[test]
193	fn test_execute_compilation_error() {
194	Embed::run(\|\| {
195	let result = execute(b"<?php this is not valid php {{{");
196	assert!(matches!(result, Err(PhpEvalError::CompilationFailed)));
197	});
198	}
199
200	#[test]
201	fn test_execute_with_bom() {
202	Embed::run(\|\| {
203	let mut code = vec![0xEF, 0xBB, 0xBF];
204	code.extend_from_slice(b"<?php $x = 'bom_test';");
205	let result = execute(&code);
206	assert!(result.is_ok());
207	});
208	}
209
210	#[test]
211	fn test_execute_defines_variable() {
212	Embed::run(\|\| {
213	let result = execute(b"<?php $embed_test = 'hello from embedded php';");
214	assert!(result.is_ok());
215
216	let val = Embed::eval("$embed_test;");
217	assert!(val.is_ok());
218	assert_eq!(val.unwrap().string().unwrap(), "hello from embedded php");
219	});
220	}
221
222	#[test]
223	fn test_execute_empty_code() {
224	Embed::run(\|\| {
225	let result = execute(b"");
226	assert!(matches!(result, Err(PhpEvalError::MissingOpenTag)));
227	});
228	}
229
230	#[test]
231	fn test_execute_include_bytes_pattern() {
232	Embed::run(\|\| {
233	let code: &[u8] = b"<?php\n\
234	$embedded_value = 42;\n\
235	define('EMBEDDED_CONST', true);\n";
236	let result = execute(code);
237	assert!(result.is_ok());
238	});
239	}
240
241	#[test]
242	fn test_execute_with_str() {
243	Embed::run(\|\| {
244	let code: &str = "<?php $str_test = 'from_str';";
245	let result = execute(code);
246	assert!(result.is_ok());
247
248	let val = Embed::eval("$str_test;");
249	assert!(val.is_ok());
250	assert_eq!(val.unwrap().string().unwrap(), "from_str");
251	});
252	}
253
254	#[test]
255	fn test_execute_with_string() {
256	Embed::run(\|\| {
257	let code = String::from("<?php $string_test = 'from_string';");
258	let result = execute(code);
259	assert!(result.is_ok());
260
261	let val = Embed::eval("$string_test;");
262	assert!(val.is_ok());
263	assert_eq!(val.unwrap().string().unwrap(), "from_string");
264	});
265	}
266
267	#[test]
268	fn test_execute_with_vec() {
269	Embed::run(\|\| {
270	let code: Vec<u8> = b"<?php $vec_test = 'from_vec';".to_vec();
271	let result = execute(code);
272	assert!(result.is_ok());
273
274	let val = Embed::eval("$vec_test;");
275	assert!(val.is_ok());
276	assert_eq!(val.unwrap().string().unwrap(), "from_vec");
277	});
278	}
279
280	#[test]
281	fn test_strip_bom() {
282	let cases: &[(&[u8], &[u8])] = &[
283	(&[0xEF, 0xBB, 0xBF, b'h', b'i'], b"hi"),
284	(b"hello", b"hello"),
285	(b"", b""),
286	];
287	for (input, expected) in cases {
288	assert_eq!(
289	super::strip_bom(input),
290	*expected,
291	"input: {:?}",
292	String::from_utf8_lossy(input)
293	);
294	}
295	}
296
297	#[test]
298	fn test_strip_php_open_tag() {
299	let cases: &[(&[u8], Option<&[u8]>)] = &[
300	(b"<?php $x;", Some(b"$x;")),
301	(b"<?php\n$x;", Some(b"$x;")),
302	(b"<?php\r\n$x;", Some(b"$x;")),
303	(b"<?php\t\n $x;", Some(b"$x;")),
304	(b"<?php", Some(b"")),
305	(b" <?php $x;", Some(b"$x;")),
306	(b"<?PHP $x;", Some(b"$x;")),
307	(b"<?Php\n$x;", Some(b"$x;")),
308	(b"", None),
309	(b" ", None),
310	(b"$x = 1;", None),
311	(b"hello", None),
312	];
313	for (input, expected) in cases {
314	assert_eq!(
315	super::strip_php_open_tag(input),
316	*expected,
317	"input: {:?}",
318	String::from_utf8_lossy(input)
319	);
320	}
321	}
322	}

extphprs / ext-php-rs / 21763720164

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous