前面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