added more documentation about loaders and changed the default value for the cache

git-svn-id: http://svn.twig-project.org/trunk@10 93ef8e89-cb99-4229-a87c-7fa0fa45744b

diff --git a/doc/03-Twig-for-Developers.markdown b/doc/03-Twig-for-Developers.markdown
index ce844c4..eba3148 100644 (file)
--- a/doc/03-Twig-for-Developers.markdown
+++ b/doc/03-Twig-for-Developers.markdown
@@ -74,7 +74,35 @@ Loaders
 -------
 
 Loaders are responsible for loading templates from a resource such as the file
-system. The environment will keep the compiled templates in memory.
+system.
+
+### Cache
+
+All template loaders can cache the compiled templates on the filesystem for
+future reuse. It speeds up Twig a lot as the templates are only compiled once;
+and the performance boost is even larger if you use a PHP accelerator such as
+APC.
+
+The cache can take three values:
+
+ * `null` (the default): Twig will create a sub-directory under the system
+   temp directory to store the compiled templates (not recommended as
+   templates from two projects with the same name will share the same cache if
+   your projects share the same Twig source code).
+
+ * `false`: disable the compile cache altogether (not recommended).
+
+ * An absolute path where to store the compiled templates.
+
+### Auto-reload
+
+When developing with Twig, it's useful to recompile the template whenever the
+source code changes. This is the default behavior for `Twig_Loader_Filesystem`
+for instance. In a production environment, you can turn this option off for
+better performance:
+
+    [php]
+    $loader = new Twig_Loader_Filesystem($templateDir, $cacheDir, false);
 
 ### Built-in Loaders
 
@@ -84,13 +112,22 @@ Here a list of the built-in loaders Twig provides:
    can find templates in folders on the file system and is the preferred way
    to load them.
 
+       [php]
+       $loader = new Twig_Loader_Filesystem($templateDir, $cacheDir, $autoReload);
+
  * `Twig_Loader_String`: Loads templates from a string. It's a dummy loader as
    you pass it the source code directly.
 
+       [php]
+       $loader = new Twig_Loader_String($cacheDir, $autoReload);
+
  * `Twig_Loader_Array`: Loads a template from a PHP array. It's passed an
    array of strings bound to template names. This loader is useful for unit
    testing.
 
+       [php]
+       $loader = new Twig_Loader_Array($templates, $cacheDir);
+
 ### Create your own Loader
 
 All loaders implement the `Twig_LoaderInterface`:
@@ -131,6 +168,14 @@ is how the built-in `Twig_Loader_String` reads:
       }
     }
 
+The `getSource()` method must return an array of two values:
+
+ * The first one is the template source code;
+
+ * The second one is the last modification time of the template (used by the
+   auto-reload feature), or `false` if the loader does not support
+   auto-reloading.
+
 Using Extensions
 ----------------
 

diff --git a/lib/Twig/Loader.php b/lib/Twig/Loader.php
index a90b97c..a6bf65b 100644 (file)
--- a/lib/Twig/Loader.php
+++ b/lib/Twig/Loader.php
@@ -23,9 +23,29 @@ abstract class Twig_Loader implements Twig_LoaderInterface
   protected $autoReload;
   protected $env;
 
+  /**
+   * Constructor.
+   *
+   * The cache can be one of three values:
+   *
+   *  * null (the default): Twig will create a sub-directory under the system tmp directory
+   *         (not recommended as templates from two projects with the same name will share the cache)
+   *
+   *  * false: disable the compile cache altogether
+   *
+   *  * An absolute path where to store the compiled templates
+   *
+   * @param
+   */
   public function __construct($cache = null, $autoReload = true)
   {
-    $this->cache      = $cache;
+    $this->cache = null === $this->cache ? sys_get_temp_dir().DIRECTORY_SEPARATOR.md5(dirname(__FILE__)) : $cache;
+
+    if (false !== $this->cache && !is_dir($this->cache))
+    {
+      mkdir($this->cache, 0777, true)
+    }
+
     $this->autoReload = $autoReload;
   }
 
@@ -47,7 +67,7 @@ abstract class Twig_Loader implements Twig_LoaderInterface
 
     list($template, $mtime) = $this->getSource($name);
 
-    if (is_null($this->cache))
+    if (false === $this->cache)
     {
       $this->evalString($template, $name);
 

diff --git a/lib/Twig/Loader/Array.php b/lib/Twig/Loader/Array.php
index 67068aa..c308831 100644 (file)
--- a/lib/Twig/Loader/Array.php
+++ b/lib/Twig/Loader/Array.php
@@ -20,8 +20,10 @@ class Twig_Loader_Array extends Twig_Loader
 {
   protected $templates;
 
-  public function __construct(array $templates)
+  public function __construct(array $templates, $cache = null)
   {
+    parent::__construct($cache);
+
     $this->templates = array();
     foreach ($templates as $name => $template)
     {