Phalcon Volt Sandbox Mode: Which Constructs Are Blocked and How Are Custom Functions Whitelisted?

Answer

In Phalcon 4.x Volt, sandbox mode is enforced at compile time. Disallowed tags, filters, functions and PHP embedding raise a compile-time violation before rendering. The core whitelist of tags and filters is fixed in the compiler and is not designed to be extended per application without changing source. Custom functions registered with $compiler->addFunction() are not automatically permitted in sandboxed templates; they must be explicitly allowed for the sandbox to compile them.

PHP embedding via raw blocks and {%%} style blocks is blocked in sandbox mode. Macro definition is allowed within the fixed whitelist, but cross-template inheritance between sandboxed and non-sandboxed templates is prevented by the compiler checks.

Confirmed facts for Phalcon 4.x

• Sandbox enforcement is compile time. Violations surface as a Phalcon\Volt\CompileException during compilation, not at runtime.
• The sandbox has a built-in whitelist of tags and filters. Typical allowed tags include set, include, extend, block, macro, etc. Typical allowed filters include default, escape, format, etc. This set is hard-coded in the Volt Compiler and is not configurable via setOptions in Phalcon 4.x.
• Custom functions added via $compiler->addFunction() are not automatically trusted. They must be explicitly whitelisted for sandbox use. In practice this is done via the sandbox options when creating the Volt engine, e.g. functions allowed list, not by addFunction alone.
• Raw PHP embedding is blocked. Constructs that would emit PHP code are rejected at compile time in sandbox mode.

Likely explanation and uncertainty

The exact names of the allowed tags/filters and the option key used to whitelist custom functions varies slightly between Phalcon 4.x minor releases and between the Compiler API and the Volt engine wrapper. Model knowledge indicates the whitelist is fixed and custom functions require explicit whitelisting, but the precise option name and whether macros can be defined at all in sandbox mode is not verified against current source and requires live verification for your version.

Template inheritance and macros: macros are part of the core whitelist, so definition is permitted. The sandbox prevents a sandboxed template from extending or including a non-sandboxed template, and vice versa, to avoid leaking untrusted code into a trusted context. This behavior is likely but should be verified for your exact version.

Verification steps for your case

1. Enable sandbox and compile a minimal test template.
2. Attempt to use a tag or filter outside the core whitelist. Expect a compile exception.
3. Inspect compiled PHP. Disallowed constructs should be replaced with a throw referencing a sandbox violation.
4. Register a custom function with addFunction, compile a template using it with sandbox enabled and no whitelist entry. Expect a violation.
5. Add the same function name to the sandbox allowed functions list, recompile, and verify compilation succeeds.

// Example verification pattern
$volt = new \Phalcon\Volt\Engine($di, '/path/to/cache');
$volt->setOptions([
 'sandbox' => true,
 // 'functions' => ['safe_helper'], // option name may vary by version
]);

Changing the whitelist after a template has been compiled does not affect already cached PHP. Force a full recompile when testing.

Missing diagnostic detail that changes recommendation: which exact Phalcon 4.x version and whether you instantiate Volt via Phalcon\Volt\Engine with setOptions or via the Compiler directly. The option key for allowed functions and the exact tag list are version-specific.