Twig for 开发者
原文:Twig for Developers 翻译:小虾米(QQ:509129)
Twig for 开发者
本章描述了Twig的API,而不是模板语言。这将是最有用的参考对于那些实现模板接口的用户来说,而不是那些创建Twig模板的人来说。
基础知识(Basics)
Twig使用一个名为环境(environment)的中心对象(类Twig_Environment)。该类的实例用于存储配置和扩展,用于从文件系统或其他位置加载模板。
大多数应用程序将在应用程序初始化时创建一个Twig_Environment对象,并将其用于加载模板。在某些情况下,如果使用不同的配置,那么有多个环境并排使用是非常有用的。
配置Twig到加载模板的最简单方法是这样的:
这将创建一个带有默认设置的模板环境和一个加载器,它会查找/ path / to / templates /文件夹中的模板。不同的加载器是可用的,如果想从数据库或其他资源加载模板,也可以编写自己的文件。
注意,环境(environment)的第二个参数是一系列选项。缓存选项是一个编译缓存目录,其中Twig缓存已编译的模板,以避免对次序列请求的解析阶段。它与您可能想要为评估的模板添加的缓存非常不同。对于这样的需求,您可以使用任何可用的PHP缓存库。
渲染模板(Rendering Templates)
要从Twig环境中加载模板,请调用load()方法,该方法返回Twig_TemplateWrapper实例:
要使用一些变量来呈现模板,请调用render()方法:
display()方法是直接输出模板的快捷方式。
您还可以加载并呈现模板一次搞定:
如果模板定义了块,则可以通过renderBlock()调用来单独呈现它们:
环境选项(Environment Options)
当创建一个新的Twig_Environment实例时,可以将一系列选项作为构造函数的第二个参数:
以下选项可供选择:
debug 布尔类型(boolean)
当设置为true时,生成的模板有一个__toString()方法,您可以使用它来显示生成的节点(默认为false)。
charset 字符串类型(string)(默认为utf-8)
用于生成模板的基础模板类。
cache 字符串类型(string) 或 false
一个绝对路径,用于存储已编译的模板,或者是false来禁用缓存(这是默认的)。
auto_reload 布尔类型(boolean)
当使用Twig进行开发时,每当源代码发生变化时重新编译模板是很有用的。如果您不为auto_reload选项提供一个值,那么它将根据调试值自动确定。
strict_variables 布尔类型(boolean)
如果设置为false,Twig将静默地忽略无效的变量(不存在的变量和属性/方法),并以null值替换它们。当设置为true时,Twig会抛出一个异常(默认为false)。
autoescape 字符串类型(string)
设置默认的自动转义策略(名称、html、js、css、url、html_attr,或一个PHP回调,它接受模板“文件名”并返回转义策略的使用——回调不能是一个函数名,以避免与内置的转义策略发生冲突);设置为false来禁用自动转义。名称逃逸策略决定了基于模板文件名扩展的模板的转义策略(这一策略不会在运行时造成任何开销,因为自动转义是在编译时完成的)。
optimizations 整型类型(integer)
一个标志(默认为- 1)的标志(默认为- 1),所有的优化都被启用;将其设置为0来禁用。
加载器(Loaders)
加载程序负责从资源(如文件系统)加载模板。
编译缓存(Compilation Cache)
所有模板加载器都可以在文件系统上缓存已编译的模板,以备将来重用。它加速了Twig的速度,因为模板只编译一次;如果使用APC这样的PHP加速器,性能的提升就会更大。请参阅上面的缓存和auto_reload选项以获得更多信息。
内置的加载器(Built-in Loaders)
下面是内置的loaders Twig提供的列表:
Twig_Loader_Filesystem
Twig_Loader_Filesystem从文件系统加载模板。这个加载器可以在文件系统的文件夹中找到模板,并且是加载它们的首选方法:
它还可以在一系列目录中寻找模板:
有了这样的配置,Twig将首先在$ templateDir1中寻找模板,如果它们不存在,那么它就会在$ templateDir2中寻找它们。
您可以通过addPath()和prependPath()方法添加或prepend路径:
文件系统加载器还支持名称空间模板。这允许在有自己的模板路径的不同名称空间中对模板进行分组。
当使用setpath()、addPath()和prependPath()方法时,将名称空间指定为第二个参数(当未指定时,这些方法将在“main”命名空间上执行):
名称空间模板可以通过特殊的@ namespace_name / template_path符号来访问:
Twig_Loader_Filesystem支持绝对和相对路径。使用相对路径是首选的,因为它使缓存键独立于项目根目录(例如,它允许从构建服务器中缓存缓存,其中目录可能与生产服务器上使用的目录不同):
当没有将根路径作为第二个参数传递时,Twig会使用getcwd()相对路径。
Twig_Loader_Array
Twig_Loader_Array从一个PHP数组加载一个模板。它传递了绑定到模板名称的字符串数组:
这个加载器对于单元测试非常有用。它还可以用于小型项目,其中将所有模板存储在一个PHP文件中可能是有意义的。
当使用带有缓存机制的数组加载程序时,您应该知道每当模板内容“变化”(缓存键是模板的源代码)时,都会生成一个新的缓存键。如果您不想看到缓存失控,您需要自己处理旧的缓存文件。
wig_Loader_Chain
Twig_Loader_Chain将模板加载到其他加载器:
在寻找模板时,Twig会依次尝试每个加载器,一旦找到模板,它就会返回。当呈现来自上面例子中的index.htm模板,Twig将用$ loader2加载它,但是base.html模板将从$ loader1加载。
Twig_Loader_Chain接受任何实现Twig_LoaderInterface的加载器。
还可以通过addLoader()方法添加loaders。
创建自己的加载器
所有加载器都实现Twig_LoaderInterface:
如果当前缓存的模板仍然是新鲜的,给定了最后的修改时间,或者其他错误,则isFresh()方法必须返回true。
getSourceContext()方法必须返回Twig_Source的一个实例。
使用扩展(Using Extensions)
Twig扩展是将新特性添加到Twig的包。使用扩展很简单就是使用addExtension()方法:
Twig与以下扩展捆绑在一起:
Twig_Extension_Core:定义Twig的所有核心特性。
Twig_Extension_Escaper:添加自动输出-转义,以及避免/无法避免代码块的可能性。
Twig_Extension_Sandbox:将沙箱模式添加到默认的Twig环境中,从而安全评估不受信任的代码。
Twig_Extension_Profiler:启用了内置的Twig分析器。
twig_extension_优化:在编译之前优化节点树。
核心、逃避者和优化器扩展不需要添加到Twig环境中,因为它们是默认注册的。
内置扩展(Built-in Extensions)
本节描述内置扩展添加的特性。
阅读关于扩展Twig的章节,了解如何创建自己的扩展。
核心扩展(Core Extension)
核心扩展定义了Twig的所有核心特性:
转义扩展(Escaper Extension)
转义扩展增加了自动输出转义到Twig。它定义了一个标签、autoescape和一个过滤器,raw。
在创建转义扩展时,您可以打开或关闭全局输出转义策略:
如果设置为html,模板中的所有变量都可以通过(使用html转义策略),除非使用raw过滤器:
您还可以使用自动转义标签改变本地的转义模式:
autoescape标签对包含的文件没有影响。
转义规则执行如下:
直接在模板中使用的文本(整数、布尔值、数组等)不会自动转义:
结果永远是文字或有标记的安全的表达式不会自动转义:
在打印之前,在其他过滤器被应用后,转义被应用:
raw过滤器只能在过滤器链的末端使用:
如果链中的最后一个过滤器对于当前上下文(例如html或js)是安全的,则不应用自动转义。escape和escape(“html”)标记为安全的html,escape(“js”)在JavaScript上是安全的,raw是安全的。
注意,自动转义有一些限制,因为转义是在评估后的表达式中应用的。例如,当使用连接时,{ { foo | raw ~ bar } }不会给出预期的结果,因为它是在连接的结果上应用的,而不是在单个变量上(因此,raw 过滤器在这里不会产生任何效果)。
沙箱扩展(Sandbox Extension)
可以使用sandbox扩展来评估不受信任的代码。禁止使用不安全的属性和方法。沙箱安全性由策略实例管理。默认情况下,Twig附带一个策略类:Twig_Sandbox_SecurityPolicy。这个类允许你列出一些标签、过滤器、属性和方法:
使用前一个配置,安全策略只允许使用if标记和上过滤器。此外,模板只能调用getTitle()和getBody()方法在文章对象上,以及标题和主体公共属性。其他的都不允许,并生成Twig_Sandbox_SecurityError异常。
策略对象是sandbox构造函数的第一个参数:
默认情况下,sandbox模式是禁用的,当使用sandbox标记包含不受信任的模板代码时,应该启用这个模式:
您可以将所有模板都通过true作为扩展构造函数的第二个参数:
分析器扩展(Profiler Extension)
profiler扩展允许对Twig模板进行分析器;它应该只在您的开发机器上使用,因为它增加了一些开销:
一个配置文件包含用于模板、块和宏执行的时间和内存消耗信息。
您还可以将数据转储到Blackfire.io兼容的格式:
上传资料,以使其可视化(先创建一个免费帐户):
优化器扩展(Optimizer Extension)
优化器扩展在编译之前优化节点树:
默认情况下,所有的优化都是打开的。您可以通过将它们传递给构造函数来选择要启用的函数:
Twig支持以下优化:
Twig_NodeVisitor_Optimizer::OPTIMIZE_ALL,启用所有优化(这是默认值)。
Twig_NodeVisitor_Optimizer::OPTIMIZE_NONE,禁用所有优化。这减少了编译时间,但是它可以增加执行时间和内存。
Twig_NodeVisitor_Optimizer::OPTIMIZE_FOR,在可能的情况下,通过移除循环变量的创建来优化for标记。
Twig_NodeVisitor_Optimizer::OPTIMIZE_RAW_FILTER,尽可能删除raw过滤器。
Twig_NodeVisitor_Optimizer::OPTIMIZE_VAR_ACCESS,可以在可能的情况下简化编译时模板中的变量的创建和访问。
异常(Exceptions)
Twig可以抛出异常:
Twig_Error:所有错误的基本异常。
Twig_Error_Syntax:抛出来告诉用户模板语法有问题。
Twig_Error_Runtime:当运行时发生错误时抛出(例如,当一个过滤器不存在时)。
Twig_Error_Loader:在模板加载过程中抛出错误。
Twig_Sandbox_SecurityError:当一个不允许的标记、过滤器或方法被调用在一个沙盒模板中时抛出。
Last updated