mirror of
https://github.com/twigphp/Twig.git
synced 2026-08-30 20:16:45 +00:00
Clarify source function trust requirements
This commit is contained in:
@@ -1,26 +1,43 @@
|
||||
``source``
|
||||
==========
|
||||
|
||||
The ``source`` function returns the content of a template without rendering it:
|
||||
The ``source`` function returns the content of a resource without rendering it.
|
||||
The resource can be a Twig template or any other file exposed by the configured
|
||||
template loader:
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
{{ source('template.html.twig') }}
|
||||
{{ source(some_var) }}
|
||||
|
||||
The function uses the same template loaders as the ones used to include
|
||||
templates. With the filesystem loader, it can read any file under the configured
|
||||
loader paths, even when the file does not contain Twig syntax.
|
||||
|
||||
.. warning::
|
||||
|
||||
The return value is considered safe and is not escaped automatically. Use
|
||||
the ``escape`` filter explicitly when the returned content should be
|
||||
escaped:
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
{{ source('message.txt')|escape }}
|
||||
|
||||
Only pass trusted resource names to ``source()`` and configure loader paths
|
||||
to contain no secrets or untrusted files. In sandboxed templates, allow the
|
||||
``source`` function only when every loader-accessible resource is safe for
|
||||
template authors to read.
|
||||
|
||||
When you set the ``ignore_missing`` flag, Twig will return an empty string if
|
||||
the template does not exist:
|
||||
the resource does not exist:
|
||||
|
||||
.. code-block:: twig
|
||||
|
||||
{{ source('template.html.twig', ignore_missing = true) }}
|
||||
|
||||
The function uses the same template loaders as the ones used to include
|
||||
templates. So, if you are using the filesystem loader, the templates are looked
|
||||
for in the paths defined by it.
|
||||
|
||||
Arguments
|
||||
---------
|
||||
|
||||
* ``name``: The name of the template to read
|
||||
* ``ignore_missing``: Whether to ignore missing templates or not
|
||||
* ``name``: The name of the resource to read
|
||||
* ``ignore_missing``: Whether to ignore missing resources or not
|
||||
|
||||
Reference in New Issue
Block a user