爲開發者而生的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