Sandboxed template rendering

AugustMiller · AugustMiller · commit 91cd60287c2a · 2026-01-27T14:43:20.000-08:00
diff --git a/docs/4.x/config/README.md b/docs/4.x/config/README.md
@@ -32,7 +32,7 @@ The most common way to customize your Craft project is by editing files in the [
 | [Routing](#url-rules) | `routes.php` | Custom HTTP routes.
 | [Application Configuration](#application-configuration) | `app.php`, `app.web.php`, `app.console.php` | Overrides for the root application and any of its [Components](https://www.yiiframework.com/doc/guide/2.0/en/concept-components).
 | Plugin Settings | `{plugin-handle}.php`, or other custom files | Consult the plugin’s documentation for specifics.
-| [Advanced](#advanced) | | Specific library options and/or behaviors that may be exposed in a non-standard way.
+| [Advanced](#advanced) | | Specific library options and/or behaviors that may be exposed in a non-standard way, like [Guzzle](#guzzle) or the Twig [sandbox environment](#twig-sandbox).
 
 ::: tip
 You may find other files in the `config/` folder, like `license.key` or the `project/` folder. Craft (and many plugins) will ask you to place config-adjacent files here, even if they don’t work in a consistent way.
@@ -515,6 +515,68 @@ The options defined here will be passed into new `GuzzleHttp\Client` instances.
 To use a proxy for _all_ requests, set an [httpProxy](config4:httpProxy) in general config. This will get merged with the Guzzle configuration, and passed to the front-end for use by JavaScript, in the [control panel](../control-panel.md). Setting a proxy only in Guzzle’s config will not affect Ajax requests!
 :::
 
+#### Twig Sandbox <Since ver="4.17.0" feature="Twig sandbox rendering" />
+
+When <config4:enableTwigSandbox> is _on_, some templates (like [system messages](../mail.md#system-messages)) are rendered in a Twig environment governed by a strict security policy.
+
+You can customize this policy via a `twig-sandbox.php` config file, which is merged on top of [Craft’s defaults](repo:craftcms/cms/blob/4.x/src/config/twig-sandbox.php).
+
+```php
+<?php return [
+    'allowedTags' => [
+        // Additional Twig tags to allow ...
+    ],
+    'allowedFilters' => [
+        // Additional Twig filters to allow ...
+    ],
+    'allowedFunctions' => [
+        // Additional Twig functions to allow ...
+    ],
+    'allowedMethods' => [
+        // Keys are class names;
+        // Values are arrays of methods to allow;
+        craft\elements\Asset::class => [
+            'getUploader',
+        ],
+    ],
+    'allowedProperties' => [
+        // Same format as the above.
+    ],
+    'allowedClasses' => [
+        // Each item must be a fully-qualified class name.
+        // Beware: *all* methods and properties are implicitly allowed!
+        craft\web\twig\variables\CraftVariable::class,
+    ],
+];
+```
+
+Internally, Craft uses PHP [attributes](https://www.php.net/manual/en/language.attributes.overview.php) to flag classes, methods, and properties as [allowed](craft4:craft\web\twig\AllowedInSandbox), so they do not appear in the default config array.
+
+::: tip
+If you find that sandboxed rendering is too restrictive, try adding features to the security policy one-by-one, _before_ completely disabling it.
+:::
+
+
+#### HTML Purifier
+
+JSON files containing valid [HTML Purifier configuration](https://htmlpurifier.org/live/configdoc/plain.html) can be added to `config/htmlpurifier/`.
+
+When creating a [Redactor](https://plugins.craftcms.com/redactor/) or [CKEditor](https://plugins.craftcms.com/ckeditor/) field, you can select one of your predefined purifier configs—or provide a one-off config object. The [`purify`](../dev/filters.md#purify) filter also accepts a reference to an existing config file or a complete config object.
+
+A simple config that scrubs everything but paragraph and anchor tags would look like this:
+
+```json
+{
+  "HTML.AllowedElements": "p, a",
+}
+```
+
+For security, any keys _not_ set will use their [defaults](https://github.com/ezyang/htmlpurifier/blob/master/plugins/phorum/config.default.php).
+
+::: tip
+Note that HTML Purifier expresses many options with dot notation, like `HTML.AllowedElements`. These are the literal keys, not an indication that keys should be nested!
+:::
+
 ### Custom Settings
 
 Settings defined in a `config/custom.php` file don’t map to or affect any built-in Craft features, but can useful to centralize data, flags, or secrets that otherwise don’t have a place to live.
@@ -555,26 +617,6 @@ $client->post('/donations', [
 If these settings need to be changed frequently, edited by a control panel user, or don’t depend on the environment, they may be a better fit for a [Global Set](../globals.md).
 :::
 
-#### HTML Purifier
-
-JSON files containing valid [HTML Purifier configuration](https://htmlpurifier.org/live/configdoc/plain.html) can be added to `config/htmlpurifier/`.
-
-When creating a [Redactor](https://plugins.craftcms.com/redactor/) or [CKEditor](https://plugins.craftcms.com/ckeditor/) field, you can select one of your predefined purifier configs—or provide a one-off config object. The [`purify`](../dev/filters.md#purify) filter also accepts a reference to an existing config file or a complete config object.
-
-A simple config that scrubs everything but paragraph and anchor tags would look like this:
-
-```json
-{
-  "HTML.AllowedElements": "p, a",
-}
-```
-
-For security, any keys _not_ set will use their [defaults](https://github.com/ezyang/htmlpurifier/blob/master/plugins/phorum/config.default.php).
-
-::: tip
-Note that HTML Purifier expresses many options with dot notation, like `HTML.AllowedElements`. These are the literal keys, not an indication that keys should be nested!
-:::
-
 <a id="php-constants"></a>
 
 ## Bootstrap Config
diff --git a/docs/4.x/extend/controllers.md b/docs/4.x/extend/controllers.md
@@ -255,6 +255,32 @@ public function actionFoo(): Response
 
 <craft4:craft\web\Controller::renderTemplate()> calls <craft4:craft\web\View::renderPageTemplate()> internally, which ensures all registered assets are added to the rendered HTML—then it will set the `Content-Type` header on the response, based template’s extension, or `text/html` when a MIME type can’t be determined.
 
+#### Sandboxing <Since ver="4.17.0" feature="Sandboxed Twig template rendering" />
+
+Some plugins may need to render templates defined by a control panel user, as Craft does with [system messages](../mail.md#system-messages).
+
+Providing access to low-level Craft APIs in this way is effectively a form of [remote code execution](https://www.cloudflare.com/learning/security/what-is-remote-code-execution/) for trusted users; whenever possible, this should be restricted to administrators, or enabled via a specific [permission](user-permissions.md).
+
+Your implementation should _always_ process these templates via the special sandbox view methods:
+
+```php
+// Load template from a database record or project config:
+$notification = Automator::getInstance()->getNotifications()->getActivityNotification();
+
+// Render safely via the sandbox environment:
+$message = Craft::$app->getView()->renderSandboxedString($notification->template, [
+    'user' => $user,
+]);
+```
+
+To render a regular, on-disk template, use <craft4:craft\web\View::renderSandboxedTemplate()>; to render an [object template](../system/object-templates.md), use <craft4:craft\web\View::renderSandboxedObjectTemplate()>.
+
+If a developer has opted out of sandbox rendering for a project where your plugin is installed (using the <config4:enableTwigSandbox> setting), these methods silently fall back to normal rendering.
+
+::: warning
+Any user-space templates that your plugin provides by default (say, seeded during the [install migration](migrations.md#plugin-install-migrations)) should be fully compatible with sandboxed rendering.
+:::
+
 #### Registering Assets
 
 To register an asset for inclusion in a rendered page, call one of the <craft4:craft\web\View> methods:
diff --git a/docs/4.x/mail.md b/docs/4.x/mail.md
@@ -43,6 +43,9 @@ Thanks for creating an account with {{systemName}}! To activate your account, cl
 If you were not expecting this email, just ignore it.
 ```
 
+When the <config4:enableTwigSandbox> setting is enabled, Craft uses a special Twig “sandbox” environment to load and render system messages.
+Features and APIs available in this mode can be [configured via `twig-sandbox.php`](../configure.md#twig-sandbox). <Since ver="4.17.0" feature="Twig sandbox rendering of system messages" />
+
 #### Variables
 
 Each system message (and subject line) is provided some special, context-specific variables, in addition to those available in normal Twig environments.
diff --git a/docs/5.x/configure.md b/docs/5.x/configure.md
@@ -36,7 +36,7 @@ The most common way to customize your Craft project is by editing files in the [
 | [Redirection](system/routing.md#redirection) | `redirects.php` | Additional patterns for redirection.
 | [Application Configuration](#application-configuration) | `app.php`, `app.web.php`, `app.console.php` | Overrides for the root application and any of its [Components](https://www.yiiframework.com/doc/guide/2.0/en/concept-components).
 | Plugin Settings | `{plugin-handle}.php`, or other custom files | Consult the plugin’s documentation for specifics.
-| [Advanced](#advanced) | | Specific library options and/or behaviors that may be exposed in a non-standard way.
+| [Advanced](#advanced) | | Specific library options and/or behaviors that may be exposed in a non-standard way, like [Guzzle](#guzzle) or the Twig [sandbox environment](#twig-sandbox).
 
 ::: tip
 You may find other files in the `config/` folder, like `license.key` or the `project/` folder. Craft (and many plugins) will ask you to place config-adjacent files here, even if they don’t work in a consistent way.
@@ -540,6 +540,67 @@ The options defined here will be passed into new `GuzzleHttp\Client` instances.
 To use a proxy for _all_ requests, set an [httpProxy](config5:httpProxy) in general config. This will get merged with the Guzzle configuration, and passed to the front-end for use by JavaScript, in the [control panel](system/control-panel.md). Setting a proxy only in Guzzle’s config will not affect Ajax requests!
 :::
 
+#### Twig Sandbox <Since ver="5.9.0" feature="Twig sandbox rendering" />
+
+When <config5:enableTwigSandbox> is _on_, some templates (like [system messages](system/mail.md#system-messages)) are rendered in a Twig environment governed by a strict security policy.
+
+You can customize this policy via a `twig-sandbox.php` config file, which is merged on top of [Craft’s defaults](repo:craftcms/cms/blob/5.x/src/config/twig-sandbox.php).
+
+```php
+<?php return [
+    'allowedTags' => [
+        // Additional Twig tags to allow ...
+    ],
+    'allowedFilters' => [
+        // Additional Twig filters to allow ...
+    ],
+    'allowedFunctions' => [
+        // Additional Twig functions to allow ...
+    ],
+    'allowedMethods' => [
+        // Keys are class names;
+        // Values are arrays of methods to allow;
+        craft\elements\Asset::class => [
+            'getUploader',
+        ],
+    ],
+    'allowedProperties' => [
+        // Same format as the above.
+    ],
+    'allowedClasses' => [
+        // Each item must be a fully-qualified class name.
+        // Beware: *all* methods and properties are implicitly allowed!
+        craft\web\twig\variables\CraftVariable::class,
+    ],
+];
+```
+
+Internally, Craft uses PHP [attributes](https://www.php.net/manual/en/language.attributes.overview.php) to flag classes, methods, and properties as [allowed](craft5:craft\web\twig\AllowedInSandbox), so they do not appear in the default config array.
+
+::: tip
+If you find that sandboxed rendering is too restrictive, try adding features to the security policy one-by-one, _before_ completely disabling it.
+:::
+
+#### HTML Purifier
+
+JSON files containing valid [HTML Purifier configuration](https://htmlpurifier.org/live/configdoc/plain.html) can be added to `config/htmlpurifier/`.
+
+When creating a [Redactor](plugin:redactor) or [CKEditor](plugin:ckeditor) field, you can select one of your predefined purifier configs—or provide a one-off config object. The [`purify`](reference/twig/filters.md#purify) filter also accepts a reference to an existing config file or a complete config object.
+
+A simple config that scrubs everything but paragraph and anchor tags would look like this:
+
+```json
+{
+  "HTML.AllowedElements": "p, a",
+}
+```
+
+For security, any keys _not_ set will use their [defaults](https://github.com/ezyang/htmlpurifier/blob/master/plugins/phorum/config.default.php).
+
+::: tip
+Note that HTML Purifier expresses many options with dot notation, like `HTML.AllowedElements`. These are the literal keys, not an indication that keys should be nested!
+:::
+
 ### Custom Settings
 
 Settings defined in a `config/custom.php` file don’t map to or affect any built-in Craft features, but can useful to centralize data, flags, or secrets that otherwise don’t have a place to live.
@@ -580,26 +641,6 @@ $client->post('/donations', [
 If these settings need to be changed frequently, edited by a control panel user, or don’t depend on the environment, they may be a better fit for a [Global Set](reference/element-types/globals.md).
 :::
 
-#### HTML Purifier
-
-JSON files containing valid [HTML Purifier configuration](https://htmlpurifier.org/live/configdoc/plain.html) can be added to `config/htmlpurifier/`.
-
-When creating a [Redactor](plugin:redactor) or [CKEditor](plugin:ckeditor) field, you can select one of your predefined purifier configs—or provide a one-off config object. The [`purify`](reference/twig/filters.md#purify) filter also accepts a reference to an existing config file or a complete config object.
-
-A simple config that scrubs everything but paragraph and anchor tags would look like this:
-
-```json
-{
-  "HTML.AllowedElements": "p, a",
-}
-```
-
-For security, any keys _not_ set will use their [defaults](https://github.com/ezyang/htmlpurifier/blob/master/plugins/phorum/config.default.php).
-
-::: tip
-Note that HTML Purifier expresses many options with dot notation, like `HTML.AllowedElements`. These are the literal keys, not an indication that keys should be nested!
-:::
-
 <a id="php-constants"></a>
 
 ## Bootstrap Config
diff --git a/docs/5.x/extend/controllers.md b/docs/5.x/extend/controllers.md
@@ -259,6 +259,32 @@ public function actionFoo(): Response
 Plugins automatically get a [template root](template-roots.md) that exposes templates in their `templates/` directory, but modules must explicitly register a template root.
 :::
 
+#### Sandboxing <Since ver="5.9.0" feature="Sandboxed Twig template rendering" />
+
+Some plugins may need to render templates defined by a control panel user, as Craft does with [system messages](../system/mail.md#system-address)).
+
+Providing access to low-level Craft APIs in this way is effectively a form of [remote code execution](https://www.cloudflare.com/learning/security/what-is-remote-code-execution/) for trusted users; whenever possible, this should be restricted to administrators, or enabled via a specific [permission](user-permissions.md).
+
+Your implementation should _always_ process these templates via the special sandbox view methods:
+
+```php
+// Load template from a database record or project config:
+$notification = Automator::getInstance()->getNotifications()->getActivityNotification();
+
+// Render safely via the sandbox environment:
+$message = Craft::$app->getView()->renderSandboxedString($notification->template, [
+    'user' => $user,
+]);
+```
+
+To render a regular, on-disk template, use <craft5:craft\web\View::renderSandboxedTemplate()>; to render an [object template](../system/object-templates.md), use <craft5:craft\web\View::renderSandboxedObjectTemplate()>.
+
+If a developer has opted out of sandbox rendering for a project where your plugin is installed (using the <config5:enableTwigSandbox> setting), these methods silently fall back to normal rendering.
+
+::: warning
+Any user-space templates that your plugin provides by default (say, seeded during the [install migration](migrations.md#plugin-install-migrations)) should be fully compatible with sandboxed rendering.
+:::
+
 #### Registering Assets
 
 To register an asset for inclusion in a rendered page, call one of the <craft5:craft\web\View> methods:
diff --git a/docs/5.x/system/mail.md b/docs/5.x/system/mail.md
@@ -42,6 +42,9 @@ Thanks for creating an account with {{systemName}}! To activate your account, cl
 If you were not expecting this email, just ignore it.
 ```
 
+When the <config5:enableTwigSandbox> setting is enabled, Craft uses a special Twig “sandbox” environment to load and render system messages.
+Features and APIs available in this mode can be [configured via `twig-sandbox.php`](../configure.md#twig-sandbox). <Since ver="5.9.0" feature="Twig sandbox rendering of system messages" />
+
 #### Variables
 
 Each system message (and subject line) is provided some special, context-specific variables, in addition to those available in normal Twig environments.
