为开发者而生的Twig（上）-Twig使用指南

前面2篇介绍了《为模版设计师而生的Twig》，已经暂停了好久没有进行翻译了。接下来继续介绍《为开发者而生的Twig》，由于内容较长，因此也分为两部分，本文为第一部分。这一章主要是介绍Twig的API，而不是模板语言。这将是实现应用程序的模板接口的开发者最有用的参考，对于创造Twig模板的人则意义有限。

1. Basics (基础知识)

Twig使用一个叫作environment（环境，Twig_Environment类的实例）的核心对象。这个类的实例被用于存储配置和扩展，以及从文件系统或其余位置加载模板。 

大多数应用在程序初始化的时候会建立一个Twig_Environment对象，并使用它来加载模板。在某些状况下，若是有多个环境并行，而且不一样的配置都在使用，那么这会颇有用。 

经过配置Twig来为你的应用程序加载模板的最简单的方法，看起来大体是这样的：

require_once '/path/to/lib/Twig/Autoloader.php';
Twig_Autoloader::register(); 

$loader = new Twig_Loader_Filesystem('/path/to/templates');
$twig = new Twig_Environment($loader, array(
    'cache' => '/path/to/compilation_cache',
    ));

这将使用默认设置建立一个模板environment(环境)和一个查找 /path/to/templates/ 目录下的模板的加载器。不一样的加载器是同时可用的，若是你想要从数据库或其余资源加载模板，你也能够本身编写一个。

提示：注意environment的第二个参数是一个数组选项。cache 选项是编译缓存目录，即Twig缓存已经编译的模板，用于避免后续请求的解析。这可能和你想要添加到缓存的估算模板有很大的不一样。对于这样的需求，你可使用任何可用的PHP缓存库。

要从这个 environment 中加载模板，你只须要调用 loadTemplate() 方法，而后它返回一个Twig_Template实例：

$template = $twig->loadTemplate('index.html');

为了使用一些变量渲染模板，能够调用 render() 方法：

echo $template->render(array('the' => 'variables', 'go' => 'here'));

提示： display() 方法是直接输出模板的快捷方式。

你还能够一举加载和渲染模板：

echo $twig->render('index.html', array('the' => 'variables', 'go' => 'here'));

2. Environment Options （环境变量的选项）

当建立一个新的Twig_Environment实例时，你能够传递一个options数组做为构造函数的第二个参数：

$twig = new Twig_Environment($loader, array('debug' => true));

如下是可用的选项：

● debug boolean

    若是设置为true，生成的模板有一个__toString（）方法，你能够用它来显示生成的节点（默认为false）。

● charset string (默认是 `utf-8`)

    模板使用的字符集。

● base_template_class sting (默认是 `Twig_Template`)

    基本模板类，以用于生成模板。

● cache string|false

    加载编译后的模板（缓存模板）的绝对路径, 若是设成false，则禁用缓存缓存(默认是false)。

● auto_reload boolean

    当你使用Twig进行开发，这会很是有用，由于代码改变的时候会从新编译模板。若是您没有提供auto_reload选项的值，它会根据debug的值自动判断。

● strict_variables boolean

    若是设成false，Twig会悄悄忽略掉非法的变量（包括不存在的变量、属性、方法）并使用null值替代他们（默认是false）。当设成true，Twig则会抛出一个异常。

● autoescape string|boolean

    若是设成true，HTML自动转义功能将会默认为全部模板开启（默认是true）。

    Twig 1.8中，你可使用（html, js, false）做为转义策略(false是禁用转义功能)。

    Twig 1.9中，你可使用（css, url, html_attr，或PHP回调函数）做为转义策略。

    （这里的PHP回调函数，要可以经过模板的文件名返回一个转义策略。而且这个回调函数不能和内建的转义策略的函数名冲突。）

    Twig 1.17中, 文件名转义策略肯定了一个模板要使用的转义策略取决于它的模板文件名扩展。

    （这个策略并不会在运行时产生任何开销，由于在编译的时候自动转义就已经完成了。）

● optimizations integer

    一个指示要使用那种优化方式的标志(默认是：-1，启用全部优化; 设为0的话，就是禁用)。

3. Loaders （加载器）

加载器负责从一个资源（如：文件系统）中加载模板。

3.1 Compilation Cache（编译缓存）

全部的模板加载器均可以在文件系统中缓存编译后的模板，以供未来能够重用。由于模板只须要编译一次，这使得Twig变得很快！而且若是你使用PHP加速器（如APC）的话，性能的提高将会更大。关于 Twig_Environment 的 cache 和 auto_reload 选项的更懂信息请参照上面的内容。

3.2 Built-in Loaders（内建加载器）

这是Twig提供的内建加载器的列表：

● Twig_Loader_Filesystem （文件系统加载器）

    1.10版中新增了 prependPath() 方法和对命名空间的支持。

Twig_Loader_Filesystem从文件系统中加载模板。该加载器能够在文件系统上的文件夹找到模板，而且这是加载他们的首选方法：

$loader = new Twig_Loader_Filesystem($templateDir);

它也能够寻找目录数组中的模板：

$loader = new Twig_Loader_Filesystem(array($templateDir1, $templateDir2));

在这样的配置下，Twig将首先在$templateDir1查找模板，若是它们不存在，它会回退到$templateDir2继续寻找。

您能够经过 addPath()方法和 prependPath() 添加或预先准备的路径：

$loader->addPath($templateDir3);
$loader->prependPath($templateDir4);

这个文件系统加载器也支持名称空间的模板。这容许你将不一样路径下的模板使用不一样的命名空间给模板进行分组。

当使用 setPaths()、addPath()、prependPath() 方法的时候，请指定命名空间做为第二个参数（若是没有指定，这些方法将做用于“main”这个命名空间）：

$loader->addPath($templateDir, 'admin');

命名空间的模板，能够经过特殊的符号 @namespace_name/template_path 来访问：

$twig->render('@admin/index.html', array());

● Twig_Loader_Array（数组加载器）

Twig_Loader_Array从一个PHP数组加载模板。它传递一个字符串数组，数组的key做为模板名称和字符串进行绑定：

$loader = new Twig_Loader_Array(array(
    'index.html' => 'Hello {{ name }}!',
));
$twig = new Twig_Environment($loader);
echo $twig->render('index.html', array('name' => 'Fabien'));

这个加载器对单元测试很是有用。它也能够用于把全部模板存储在一个单一PHP文件的小项目中，这多是明智之举。

提示：当使用数组或字符串加载器做为缓存机制时，你应该知道，每次模板内容变化时一个新的cache key会被生产。（這里的cache key是模板源代码的cache key。）。若是你不想看到你的缓存失控增加，你须要本身负责清除旧的缓存文件。

● Twig_Loader_Chain （链加载器）

Twig_Loader_Chain 表明加载的模板，用于其余加载器：
$loader1 = new Twig_Loader_Array(array(
    'base.html' => '{% block content %}{% endblock %}',
));
$loader2 = new Twig_Loader_Array(array(
    'index.html' => '{% extends "base.html" %}{% block content %}Hello {{ name }}{% endblock %}',
    'base.html'  => 'Will never be loaded',
));
 
$loader = new Twig_Loader_Chain(array($loader1, $loader2));
$twig = new Twig_Environment($loader);

当寻找一个模板时，Twig会依次尝试每一个加载器，一旦发现模板会尽快返回。

从上面的例子中，当渲染 index.html 模板时，Twig会从$loader2加载它，而 base.html 模板时则将会从 $loader1 被加载。

    提示：你也能够经过 addLoader() 方法添加加载器。

3.3 Create your own Loader（建立你本身的加载器）

全部的加载器都是Twig_LoaderInterface接口的实现：

interface Twig_LoaderInterface
{
    /**
     * Gets the source code of a template, given its name.
     *
     * @param  string $name string The name of the template to load
     *
     * @return string The template source code
     */
    function getSource($name);
 
    /**
     * Gets the cache key to use for the cache for a given template name.
     *
     * @param  string $name string The name of the template to load
     *
     * @return string The cache key
     */
    function getCacheKey($name);
 
    /**
     * Returns true if the template is still fresh.
     *
     * @param string    $name The template name
     * @param timestamp $time The last modification time of the cached template
     */
    function isFresh($name, $time);
}

若是当前缓存的模板是新的，那么 isFresh() 方法必须返回true，不然的话应该返回最后修改时间或false。

提示：在Twig 1.11.0中，当你使用链加载器时，能够从Twig_ExistsLoaderInterface的实现更快的建立你的加载器。

下篇将从 Using Extensions 继续翻译，敬请期待。

原文：为开发者而生的Twig（上）-Twig使用指南  http://loiy.net/post/1051.html