updated docs for caching, added clear_all_cache() directive

FAQ

@@ -21,8 +21,42 @@ A: Smarty reads the template files and creates PHP scripts from them. Once
    the template files again. If you change a template file, Smarty will
    recreate the PHP script for it. All this is done automatically by Smarty.
    Template designers never need to mess with the generated PHP scripts or even
-   know of their existance.
+   know of their existance. (NOTE: you can turn off this compile checking step
+   in Smarty for increased performance.)
 
+Q: Why can't I just use APC <http://apc.communityconnect.com/> (or Zend Cache)?
+A: Smarty and these cache solutions have nothing in common. What APC does is
+   caches compiled bytecode of your PHP scripts in shared memory or in a file.
+   This speeds up server response and saves the compilation step. Smarty
+   creates PHP scripts (which APC will cache nicely) and also has it's own
+   internal caching mechanism for the output of the template contents. For
+   example, if you have a template that requires several database queries,
+   Smarty can cache this output, saving the need to call the database every
+   time. APC cannot help you here. Smarty and APC (or Zend Cache) actually
+   complement each other nicely. If performance is of the utmost importance, we
+   would recommend using one of these with any PHP application, using Smarty or
+   not.
+
+Q: Is Smarty faster than <insert other PHP template engine>?
+A: This would mostly depend on the other template engine, but as a
+   general rule of thumb: Without a PHP caching solution like APC or
+   Zend Cache, Smarty is most likely as fast, or possibly slower. With
+   APC, Smarty is mostly like as fast or much faster. The reason is
+   this: Smarty generates PHP scripts from your templates. The more
+   templates your application has, the more PHP scripts Smarty
+   generates. This in turn requires more time for the PHP parser to
+   compile the PHP scripts. With APC, this compilation step is cached.
+   So as the complexity of the templates increase, the performance
+   savings go up accordingly. Also, most other template solutions parse
+   the template files on each invocation. The more complex the
+   templates are, the longer they take to parse them.
+   
+   The above comparison assumes that you are not using Smarty's
+   built-in ability to cache templates. If you are, that makes this
+   comparison pretty useless since Smarty will basically be displaying
+   static content instead of generating templates, which of course will
+   be magnitudes faster.
+   
 Q: Do you have a mailing list?
 A: Yes. Subscribe by sending an e-mail to subscribe-smarty@lists.ispi.net. This
    is also archived at http://marc.theaimsgroup.com/ under www/smarty

Smarty.class.php

@@ -256,6 +256,22 @@ class Smarty
             return $results;
 	}
 
+/*======================================================================*\
+	Function:	clear_all_cache()
+	Purpose:	clear all the cached template files.
+\*======================================================================*/
+
+	function clear_all_cache()
+	{
+		while($curr_file = readdir($this->cache_dir)) {
+			if ($curr_file == '.' || $curr_file == '..')
+				continue;
+			if(substr($curr_file,-4) == '.che')
+				unlink($curr_file);
+		}		
+	}
+	
+	
 /*======================================================================*\
 	Function:	compile()
 	Purpose:	called to compile the templates

docs.sgml

@@ -116,6 +116,7 @@
 			although this may not be needed (nor recommended)
 			since the engine is so customizable.</para></listitem>
 		</itemizedlist>
+		<listitem><para>Built-in caching support (new in 1.3.0)</para></listitem>
 	</sect1>
 	<sect1>
 		<title>How Smarty works</title>
@@ -130,10 +131,16 @@
 		</sect2>
 		<sect2><title>Caching</title>
 		<para>
-			Our initial intention was to build caching into Smarty. However,
+			Smarty can cache the output of your generated templates. By default
-			since the template engine is actually executing PHP scripts instead of
+			this is disabled. If you enable caching, Smarty will store a copy
-			parsing template files, the need for a cache was dramatically reduced.
+			of the generated template output, and use this until the copy
-			We may implement this in a future version of Smarty as the need arises.
+			expires, regenerating a new one. If your templates generate the
+			same content over and over, using the cache will result in huge
+			performance gains. The default cache expire time is one hour, and
+			can be configured from the class. The exception to the rule is the
+			<link linkend="function.insert">insert</link> tag. Anything
+			generated by the insert tag is not cached, but run dynamically on
+			every invocation, even within cached content.
 		</para>
 		</sect2>
 	</sect1>
@@ -157,7 +164,9 @@
 		Each installation of a Smarty application minimally needs a templates
 		directory and a compiled templates directory. If you use configuration
 		files you will also need a directory for those. By default these are
-		named "templates", and "templates_c" and "configs" respectively.
+		named "templates", and "templates_c" and "configs" respectively. If you
+		plan on using caching, you will need to create a "cache" directory, also
+		with permission to write files.
 		</para>
 		<para>
 		Copy the Smarty.class.php, Smarty.addons.php and Config_File.class.php
@@ -178,6 +187,10 @@
 gtar -zxvf Smarty-1.0.tar.gz
 mkdir templates_c
 chown nobody:nobody templates_c
+chmod 700 templates_c
+mkdir cache
+chown nobody:nobody cache
+chmod 700 cache
 </programlisting>
 		</example>
 		<para>
@@ -200,19 +213,51 @@ chown nobody:nobody templates_c
 			<para>
 				Upon each invocation of the PHP application, Smarty recursively
 				traverses the template directory and its subdirectories and
-				searches for all the files with the template extension that
+				searches for templates that have changed (later time stamp)
-				have changed (later time stamp) since the last time they were
+				since the last time they were compiled. For each one that has
-				compiled. For each one that has changed, it recompiles that
+				changed, it recompiles that template. By default this variable
-				template. By default this variable is set to true. The compile
+				is set to true. Once an application is put into production and
-				check has very minimal impact on the application performance.
+				it is initially compiled, the compile_check step is no longer
-				However, once an application is put into production and it is
+				needed. Be sure to set $compile_check to "false" to improve
-				initially compiled, the compile_check step is no longer needed.
+				performance! Note that if you change this to "false" and a
-				You may set this to "false" *after* the initial compile. Then
+				template file is changed, you will *not* see the change since
-				Smarty will no longer check for changed template files. Note
+				the template will not get recompiled. See <link
-				that if you change this to "false" and a template file is
+				linkend="setting.force.compile">$force_compile</link>
-				changed, you will *not* see the change since the template will
+			</para>
-				not get recompiled. Set it to "true", invoke the application,
+		</sect2>
-				then set it back to "false".
+		<sect2 id="setting.force.compile">
+			<title>$force_compile</title>
+			<para>
+				This forces Smarty to compile all templates on every
+				invocation. This setting overrides $compile_check. By default
+				this is disabled. This is handy for development and debugging.
+				It should never be used in a production environment.
+			</para>
+		</sect2>
+		<sect2 id="setting.caching">
+			<title>$caching</title>
+			<para>
+				This tells Smarty whether or not to cache the output of the
+				templates. By default this is set to false. If your templates
+				generate the same content over and over, it is advisable to
+				turn on caching. This will result significant performance
+				gains. Smarty uses a combination of the template being called
+				and the URL ($PHP_SELF) for the cache indentification. This way
+				you can have multiple caches for the same template. NOTE: If
+				you ever turn caching off after templates are compiled, be sure
+				to recompile all of your templates once. Otherwise you may get
+				undesireable results. This was added to Smarty 1.3.0.
+			</para>
+		</sect2>
+		<sect2 id="setting.cache.lifetime">
+			<title>$cache_lifetime</title>
+			<para>
+				This is the length of time in seconds that a template cache is
+				valid. Once this time has expired, the cache will be
+				regenerated. $caching must be set to "true" for this setting to
+				work. You can also force the cache to expire with <link
+				linkend="api.clear.all.cache">clear_all_cache</link>. This was
+				added to Smarty 1.3.0.
 			</para>
 		</sect2>
 		<sect2 id="template.dir">
@@ -226,10 +271,18 @@ chown nobody:nobody templates_c
 			<title>$compile_dir</title>
 			<para>
 				This is the name of the directory where compiled templates are
-				located. By default this is "./templates_c". NOTE: this was
+				located. By default this is "./templates_c". This was
 				added to Smarty version 1.2.1.
 			</para>
 		</sect2>
+		<sect2>
+			<title>$cache_dir</title>
+			<para>
+				This is the name of the directory where template caches are
+				located. By default this is "./cache". This was
+				added to Smarty version 1.3.0.
+			</para>
+		</sect2>
 		<sect2>
 			<title>$compile_dir_ext</title>
 			<para>
@@ -375,6 +428,19 @@ chown nobody:nobody templates_c
 				This clears the values of all assigned variables.
 			</para>
 		</sect2>
+		<sect2 id="api.clear.all.cache">
+			<title>clear_all_cache</title>
+			<funcsynopsis>
+			<funcprototype>
+			<funcdef>void <function>clear_all_cache</function></funcdef>
+				<paramdef><parameter></parameter></paramdef>
+			</funcprototype>
+			</funcsynopsis>
+			<para>
+				This clears the entire template cache. This was added to Smarty
+				1.3.0.
+			</para>
+		</sect2>
 		<sect2>
 			<title>get_template_vars</title>
 			<funcsynopsis>
@@ -815,7 +881,7 @@ Intro = """This is a value that spans more
 </programlisting>
 </example>
 		</sect2>
-		<sect2>
+		<sect2 id="function.insert">
 			<title>insert</title>
 			<para>
 			The insert tag in Smarty serves a special purpose. You may
@@ -856,11 +922,10 @@ Intro = """This is a value that spans more
 			and display the returned results in place of the insert tag.
 			</para>
 			<para>
-			Another thing to keep in mind for the insert tag is caching. Smarty does not
+			A note on caching: If you have caching turned on, insert tags will
-			currently support caching but if that is eventually implemented, insert
+			not be cached. They will run dynamically every time the page is
-			tags will not be cached. They will run dynamically every time the page
+			created. This works good for things like banners, polls, live
-			is created. This works good for things like banners, polls, live weather,
+			weather, user feedback areas, etc.
-			user feedback areas, etc.
 			</para>
 		</sect2>
 		<sect2>

libs/Smarty.class.php

@@ -256,6 +256,22 @@ class Smarty
             return $results;
 	}
 
+/*======================================================================*\
+	Function:	clear_all_cache()
+	Purpose:	clear all the cached template files.
+\*======================================================================*/
+
+	function clear_all_cache()
+	{
+		while($curr_file = readdir($this->cache_dir)) {
+			if ($curr_file == '.' || $curr_file == '..')
+				continue;
+			if(substr($curr_file,-4) == '.che')
+				unlink($curr_file);
+		}		
+	}
+	
+	
 /*======================================================================*\
 	Function:	compile()
 	Purpose:	called to compile the templates