update caching documentation

NEWS

@@ -1,3 +1,5 @@
+    - added caching logic for expire times per cache file
+      (Norbert Rocher, Monte)
     - fixed html_select_date when field separator is "/"
       (Roberto Berto, Monte)
     - added YYYY-MM-DD format support to html_select_date

Smarty.class.php

@@ -13,7 +13,7 @@
  * License as published by the Free Software Foundation; either
  * version 2.1 of the License, or (at your option) any later version.
  *
- * This library is distributed in the hope that it will be useful,
+ * This library is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Lesser General Public License for more details.
@@ -92,7 +92,11 @@ class Smarty
     var $force_compile   =  false;      // force templates to compile every time,
                                         // overrides cache settings. default false.
 
-    var $caching         =  false;      // enable caching. true/false default false.
+    var $caching         =  0;     		// enable caching. can be one of 0/1/2.
+										// 0 = no caching
+										// 1 = use class cache_lifetime value
+										// 2 = use cache_lifetime in cache file
+										// default = 0.
     var $cache_dir       =  'cache';    // name of directory for template cache files
     var $cache_lifetime  =  3600;       // number of seconds cached content will persist.
 										// 0 = always regenerate cache,
@@ -1414,6 +1418,13 @@ function _run_insert_handler($args)
     {
         // put timestamp in cache header
         $this->_cache_info['timestamp'] = time();
+        if ($this->cache_lifetime > -1){
+            // expiration set
+            $this->_cache_info['expires'] = $this->_cache_info['timestamp'] + $this->cache_lifetime;
+        } else {
+            // cache will never expire
+            $this->_cache_info['expires'] = -1;
+        }
 
         // prepend the cache header info into cache file
         $results = serialize($this->_cache_info)."\n".$results;
@@ -1479,10 +1490,19 @@ function _run_insert_handler($args)
 
         $this->_cache_info = unserialize($cache_header);
 
+        if ($this->caching == 2 && isset ($this->_cache_info['expires'])){
+            // caching by expiration time
+            if ($this->_cache_info['expires'] > -1 && (time() > $this->_cache_info['expires'])) {
+            // cache expired, regenerate
+            return false;
+            }
+        } elseif ($this->caching == 1) {
+            // caching by lifetime
             if ($this->cache_lifetime > -1 && (time() - $this->_cache_info['timestamp'] > $this->cache_lifetime)) {
             // cache expired, regenerate
             return false;
             }
+        }
 
         if ($this->compile_check) {
             foreach ($this->_cache_info['template'] as $template_dep) {

docs/programmers.sgml

@@ -173,14 +173,17 @@
      <sect2 id="variable.caching">
       <title>$caching</title>
       <para>
-       This tells Smarty whether or not to cache the output of the
+	   This tells Smarty whether or not to cache the output of the templates.
-       templates. By default this is set to false. If your templates
+	   By default this is set to 0, or disabled. If your templates generate
-       generate redundant redundant content over and over again and
+	   redundant redundant content, it is advisable to turn on caching. This
-       again repeatedly, it is advisable to turn on caching. This will
+	   will result in significant performance gains. You can also have multiple
-       result in significant performance gains. You can also have
+	   caches for the same template. A value of 1 or 2 enables caching. 1 tells
-       multiple caches for the same template. See <link
+	   Smarty to use the current $cache_lifetime variable to determine if the
-        linkend="api.is.cached">is_cached</link> for details. This was
+	   cache has expired. A value of 2 tells Smarty to use the cache_lifetime
-       added to Smarty 1.3.0.
+	   value at the time the cache was generated. This way you can set the
+	   cache_lifetime just before fetching the template to have granular
+	   control over when that particular cache expires. See also <link
+	   linkend="api.is.cached">is_cached</link>.
       </para>
       <para>
        If $compile_check is enabled, the cached content will be
@@ -217,14 +220,15 @@
      <sect2 id="variable.cache.lifetime">
       <title>$cache_lifetime</title>
       <para>
-       This is the length of time in seconds that a template cache is
+	   This is the length of time in seconds that a template cache is valid.
-       valid. Once this time has expired, the cache will be
+	   Once this time has expired, the cache will be regenerated. $caching must
-       regenerated. $caching must be set to "true" for this setting to
+	   be set to "true" for this setting to work. You can also force the cache
-       work. You can also force the cache to expire with <link
+	   to expire with <link
-        linkend="api.clear.all.cache">clear_all_cache</link>. A setting
+	   linkend="api.clear.all.cache">clear_all_cache</link>. A setting of -1
-		of -1 will force the cache to never expire. A setting of 0 will cause
+	   will force the cache to never expire. A setting of 0 will cause the
-		the cache to always regenerate (which doesn't make much sense, you'd be
+	   cache to always regenerate (which doesn't make much sense, you'd be
-		better off setting caching=false.)
+	   better off setting caching=false.) If $caching = 2, then the cache
+	   expiration time is saved along with the template.
       </para>
      </sect2>
      <sect2 id="variable.cache.handler.func">

libs/Smarty.class.php

@@ -13,7 +13,7 @@
  * License as published by the Free Software Foundation; either
  * version 2.1 of the License, or (at your option) any later version.
  *
- * This library is distributed in the hope that it will be useful,
+ * This library is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Lesser General Public License for more details.
@@ -92,7 +92,11 @@ class Smarty
     var $force_compile   =  false;      // force templates to compile every time,
                                         // overrides cache settings. default false.
 
-    var $caching         =  false;      // enable caching. true/false default false.
+    var $caching         =  0;     		// enable caching. can be one of 0/1/2.
+										// 0 = no caching
+										// 1 = use class cache_lifetime value
+										// 2 = use cache_lifetime in cache file
+										// default = 0.
     var $cache_dir       =  'cache';    // name of directory for template cache files
     var $cache_lifetime  =  3600;       // number of seconds cached content will persist.
 										// 0 = always regenerate cache,
@@ -1414,6 +1418,13 @@ function _run_insert_handler($args)
     {
         // put timestamp in cache header
         $this->_cache_info['timestamp'] = time();
+        if ($this->cache_lifetime > -1){
+            // expiration set
+            $this->_cache_info['expires'] = $this->_cache_info['timestamp'] + $this->cache_lifetime;
+        } else {
+            // cache will never expire
+            $this->_cache_info['expires'] = -1;
+        }
 
         // prepend the cache header info into cache file
         $results = serialize($this->_cache_info)."\n".$results;
@@ -1479,10 +1490,19 @@ function _run_insert_handler($args)
 
         $this->_cache_info = unserialize($cache_header);
 
+        if ($this->caching == 2 && isset ($this->_cache_info['expires'])){
+            // caching by expiration time
+            if ($this->_cache_info['expires'] > -1 && (time() > $this->_cache_info['expires'])) {
+            // cache expired, regenerate
+            return false;
+            }
+        } elseif ($this->caching == 1) {
+            // caching by lifetime
             if ($this->cache_lifetime > -1 && (time() - $this->_cache_info['timestamp'] > $this->cache_lifetime)) {
             // cache expired, regenerate
             return false;
             }
+        }
 
         if ($this->compile_check) {
             foreach ($this->_cache_info['template'] as $template_dep) {