From: fabien Date: Wed, 11 Nov 2009 17:32:47 +0000 (+0000) Subject: moved template cache configuration to the main Twig_Environment class. X-Git-Url: http://git.silmor.de/gitweb/?a=commitdiff_plain;h=df585dea8236724a6d887c059898580534a57a99;p=konrad%2Ftwig.git moved template cache configuration to the main Twig_Environment class. WARNING: This is an API change which is NOT backward compatible. The loaders do not take the cache and autoReload options anymore. Instead, the Twig_Environment class has two new options: cache and auto_reload. Read the updated documentation for more information. git-svn-id: http://svn.twig-project.org/trunk@134 93ef8e89-cb99-4229-a87c-7fa0fa45744b --- diff --git a/doc/01-Introduction.markdown b/doc/01-Introduction.markdown index 52b581c..abdea39 100644 --- a/doc/01-Introduction.markdown +++ b/doc/01-Introduction.markdown @@ -85,7 +85,9 @@ rendering with the `display()` method. Twig also comes with a filesystem loader: [php] - $loader = new Twig_Loader_Filesystem('/path/to/templates', '/path/to/compilation_cache'); - $twig = new Twig_Environment($loader); + $loader = new Twig_Loader_Filesystem('/path/to/templates'); + $twig = new Twig_Environment($loader, array( + 'cache' => '/path/to/compilation_cache', + )); $template = $twig->loadTemplate('index.html'); diff --git a/doc/03-Twig-for-Developers.markdown b/doc/03-Twig-for-Developers.markdown index 4ac9fd5..9457eae 100644 --- a/doc/03-Twig-for-Developers.markdown +++ b/doc/03-Twig-for-Developers.markdown @@ -25,20 +25,28 @@ looks roughly like this: require_once '/path/to/lib/Twig/Autoloader.php'; Twig_Autoloader::register(); - $loader = new Twig_Loader_Filesystem('/path/to/templates', '/path/to/compilation_cache'); - $twig = new Twig_Environment($loader); + $loader = new Twig_Loader_Filesystem('/path/to/templates'); + $twig = new Twig_Environment($loader, array( + 'cache' => '/path/to/compilation_cache', + )); This will create a template environment with the default settings and a loader that looks up the templates in the `/path/to/templates/` folder. Different loaders are available and you can also write your own if you want to load templates from a database or other resources. +>**CAUTION** +>Before Twig 0.9.3, the `cache` option did not exist, and the cache directory +>was passed as a second argument of the loader. + +- + >**NOTE** ->Notice that the second argument of the loader is a compilation cache ->directory, where Twig caches the compiled templates to avoid the parsing ->phase for sub-sequent requests. It is very different from the cache you might ->want to add for the evaluated templates. For such a need, you can use any ->available PHP cache library. +>Notice that the second argument of the environment is an array of options. +>The `cache` option is a compilation cache directory, where Twig caches the +>compiled templates to avoid the parsing phase for sub-sequent requests. It +>is very different from the cache you might want to add for the evaluated +>templates. For such a need, you can use any available PHP cache library. To load a template from this environment you just have to call the `loadTemplate()` method which then returns a `Twig_Template` instance: @@ -77,6 +85,29 @@ The following options are available: * `base_template_class`: The base template class to use for generated templates (default to `Twig_Template`). + * `cache`: It 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 + set this option to `false` for better performance. If you don't provide the + `auto_reload` option, it will be determined automatically base on the + `debug` value. + +>**CAUTION** +>Before Twig 0.9.3, the `cache` and `auto_reload` options did not exist. They +>was passed as a second and third arguments of the filesystem loader +>respectively. + Loaders ------- @@ -88,28 +119,8 @@ system. 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 compilation 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); +APC. See the `cache` and `auto_reload` options of `Twig_Environment` above for +more information. ### Built-in Loaders @@ -120,20 +131,20 @@ Here a list of the built-in loaders Twig provides: to load them. [php] - $loader = new Twig_Loader_Filesystem($templateDir, $cacheDir, $autoReload); + $loader = new Twig_Loader_Filesystem($templateDir); * `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); + $loader = new Twig_Loader_String($cacheDir); * `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); + $loader = new Twig_Loader_Array($templates); ### Create your own Loader @@ -150,6 +161,13 @@ All loaders implement the `Twig_LoaderInterface`: * @return string The class name of the compiled template */ public function load($name); + + /** + * Sets the Environment related to this loader. + * + * @param Twig_Environment $env A Twig_Environment instance + */ + public function setEnvironment(Twig_Environment $env); } But if you want to create your own loader, you'd better inherit from the diff --git a/lib/Twig/Environment.php b/lib/Twig/Environment.php index 32414f4..ab3995b 100644 --- a/lib/Twig/Environment.php +++ b/lib/Twig/Environment.php @@ -17,6 +17,8 @@ class Twig_Environment protected $loader; protected $trimBlocks; protected $debug; + protected $autoReload; + protected $cache; protected $lexer; protected $parser; protected $compiler; @@ -28,6 +30,33 @@ class Twig_Environment protected $runtimeInitialized; protected $loadedTemplates; + /** + * Constructor. + * + * Available options: + * + * * debug: When set to `true`, the generated templates have a __toString() + * method that you can use to display the generated nodes (default to + * false). + * + * * trim_blocks: Mimicks the behavior of PHP by removing the newline that + * follows instructions if present (default to false). + * + * * charset: The charset used by the templates (default to utf-8). + * + * * base_template_class: The base template class to use for generated + * templates (default to Twig_Template). + * + * * 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 + * + * * auto_reload: Whether to reload the template is the original source changed. + * If you don't provide the auto_reload option, it will be + * determined automatically base on the debug value. + */ public function __construct(Twig_LoaderInterface $loader = null, $options = array()) { if (null !== $loader) @@ -39,8 +68,10 @@ class Twig_Environment $this->trimBlocks = isset($options['trim_blocks']) ? (bool) $options['trim_blocks'] : false; $this->charset = isset($options['charset']) ? $options['charset'] : 'UTF-8'; $this->baseTemplateClass = isset($options['base_template_class']) ? $options['base_template_class'] : 'Twig_Template'; + $this->autoReload = isset($options['auto_reload']) ? (bool) $options['auto_reload'] : $this->debug; $this->extensions = array(new Twig_Extension_Core()); $this->runtimeInitialized = false; + $this->setCache(isset($options['cache']) ? $options['cache'] : null); } public function getBaseTemplateClass() @@ -68,6 +99,36 @@ class Twig_Environment return $this->debug; } + public function isAutoReload() + { + return $this->autoReload; + } + + public function setAutoReload($autoReload) + { + $this->autoReload = (Boolean) $autoReload; + } + + public function getCache() + { + return $this->cache; + } + + public function setCache($cache) + { + $this->cache = null === $cache ? sys_get_temp_dir().DIRECTORY_SEPARATOR.'twig_'.md5(dirname(__FILE__)) : $cache; + + if (false !== $this->cache && !is_dir($this->cache)) + { + mkdir($this->cache, 0755, true); + } + } + + public function getCacheFilename($name) + { + return $this->getCache() ? $this->getCache().'/twig_'.md5($name).'.php' : false; + } + public function getTrimBlocks() { return $this->trimBlocks; diff --git a/lib/Twig/Loader.php b/lib/Twig/Loader.php index 2433d55..2e0f3fe 100644 --- a/lib/Twig/Loader.php +++ b/lib/Twig/Loader.php @@ -19,38 +19,9 @@ */ abstract class Twig_Loader implements Twig_LoaderInterface { - protected $cache; - 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 string $cache The compiler cache directory - * @param Boolean $autoReload Whether to reload the template is the original source changed - */ - public function __construct($cache = null, $autoReload = true) - { - $this->cache = null === $cache ? sys_get_temp_dir().DIRECTORY_SEPARATOR.'twig_'.md5(dirname(__FILE__)) : $cache; - - if (false !== $this->cache && !is_dir($this->cache)) - { - mkdir($this->cache, 0755, true); - } - - $this->autoReload = $autoReload; - } - - /** * Loads a template by name. * * @param string $name The template name @@ -66,7 +37,7 @@ abstract class Twig_Loader implements Twig_LoaderInterface return $cls; } - if (false === $this->cache) + if (false === $cache = $this->env->getCacheFilename($name)) { list($source, ) = $this->getSource($name); $this->evalString($source, $name); @@ -74,7 +45,6 @@ abstract class Twig_Loader implements Twig_LoaderInterface return $cls; } - $cache = $this->getCacheFilename($name); if (!file_exists($cache)) { list($source, $mtime) = $this->getSource($name); @@ -87,7 +57,7 @@ abstract class Twig_Loader implements Twig_LoaderInterface $this->save($this->compile($source, $name), $cache); } - elseif ($this->autoReload) + elseif ($this->env->isAutoReload()) { list($source, $mtime) = $this->getSource($name); if (filemtime($cache) < $mtime) @@ -127,11 +97,6 @@ abstract class Twig_Loader implements Twig_LoaderInterface $this->env = $env; } - public function getCacheFilename($name) - { - return $this->cache.'/twig_'.md5($name).'.php'; - } - protected function compile($source, $name) { return $this->env->compile($this->env->parse($this->env->tokenize($source, $name))); diff --git a/lib/Twig/Loader/Array.php b/lib/Twig/Loader/Array.php index ca238b8..265f3d0 100644 --- a/lib/Twig/Loader/Array.php +++ b/lib/Twig/Loader/Array.php @@ -23,16 +23,12 @@ class Twig_Loader_Array extends Twig_Loader /** * Constructor. * - * @param array $templates An array of templates (keys are the names, and values are the source code) - * @param string $cache The compiler cache directory - * @param Boolean $autoReload Whether to reload the template is the original source changed + * @param array $templates An array of templates (keys are the names, and values are the source code) * * @see Twig_Loader */ - public function __construct(array $templates, $cache = null) + public function __construct(array $templates) { - parent::__construct($cache); - $this->templates = array(); foreach ($templates as $name => $template) { diff --git a/lib/Twig/Loader/Filesystem.php b/lib/Twig/Loader/Filesystem.php index fdd1ad8..839421b 100644 --- a/lib/Twig/Loader/Filesystem.php +++ b/lib/Twig/Loader/Filesystem.php @@ -23,17 +23,11 @@ class Twig_Loader_Filesystem extends Twig_Loader /** * Constructor. * - * @param string|array $paths A path or an array of paths where to look for templates - * @param string $cache The compiler cache directory - * @param Boolean $autoReload Whether to reload the template is the original source changed - * - * @see Twig_Loader + * @param string|array $paths A path or an array of paths where to look for templates */ - public function __construct($paths, $cache = null, $autoReload = true) + public function __construct($paths) { $this->setPaths($paths); - - parent::__construct($cache, $autoReload); } /**