Location: PHPKode > scripts > File cache class > file-cache-class/filecacheclass.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Class: File cache class</title>
</head>
<body>
<center><h1>Class: File cache class</h1></center>
<hr />
<ul>
<p><b>Version:</b> <tt>@(#) $Id: filecacheclass.class,v 1.28 2003/11/21 07:50:44 mlemos Exp $</tt></p>
<h2><a name="table_of_contents">Contents</a></h2>
<ul>
<li><a href="#2.1.1">Summary</a></li>
<ul>
<li><a href="#3.2.0">Name</a></li>
<li><a href="#3.2.0.0">Author</a></li>
<li><a href="#3.2.0.1">Copyright</a></li>
<li><a href="#3.2.0.2">Version</a></li>
<li><a href="#3.2.0.3">Parent classes</a></li>
<li><a href="#4.2.0">Purpose</a></li>
<li><a href="#4.2.0.0">Usage</a></li>
<li><a href="#4.2.0.1">Example</a></li>
</ul>
<li><a href="#5.1.1">Variables</a></li>
<ul>
<li><a href="#6.2.3">path</a></li>
<li><a href="#6.2.4">flush_cache_file</a></li>
</ul>
<li><a href="#7.1.1">Inherited variables</a></li>
<li><a href="#9.1.1">Functions</a></li>
<ul>
<li><a href="#10.2.7">verifycache</a></li>
<li><a href="#12.2.8">storedata</a></li>
<li><a href="#14.2.9">retrievefromcache</a></li>
<li><a href="#16.2.10">closecache</a></li>
<li><a href="#16.2.11">voidcache</a></li>
<li><a href="#16.2.12">updating</a></li>
</ul>
<li><a href="#19.1.1">Inherited functions</a></li>
</ul>
<p><a href="#table_of_contents">Top of the table of contents</a></p>
</ul>
<hr />
<ul>
<h2><li><a name="2.1.1">Summary</a></li></h2>
<ul>
<h3><a name="3.2.0">Name</a></h3>
<p>File cache class</p>
<h3><a name="3.2.0.0">Author</a></h3>
<p>Manuel Lemos (<a href="mailto:hide@address.com">hide@address.com</a>)</p>
<h3><a name="3.2.0.1">Copyright</a></h3>
<p>Copyright &copy; (C) Manuel Lemos 2001-2003</p>
<h3><a name="3.2.0.2">Version</a></h3>
<p>@(#) $Id: filecacheclass.class,v 1.28 2003/11/21 07:50:44 mlemos Exp $</p>
<h3><a name="3.2.0.3">Parent classes</a></h3>
<ul>
<p><li>Data cache class (abstract)</li></p>
<p><b>Version:</b> <tt>@(#) $Id: datacacheclass.class,v 1.28 2003/11/21 07:50:44 mlemos Exp $</tt></p>
</ul>
<h3><a name="4.2.0">Purpose</a></h3>
<p>Caching any type of data in files.</p>
<p> This class is able to manage data to be stored in cache files in a way that it may be safely stored and retrieved even when there may be many concurrent processes attempting to access the same data.</p>
<p></p>
<h3><a name="4.2.0.0">Usage</a></h3>
<p>To use this class, its functions must be called in the correct order.</p>
<p> First specify the path of the file in which the cached data will be stored assigning the <tt><a href="#variable_path">path</a></tt> variable.</p>
<p> Use the function <tt><a href="#function_verifycache">verifycache</a></tt> to check if the cache file exists and is upto date. If it is, use the function <tt><a href="#function_retrievefromcache">retrievefromcache</a></tt> read the cached data. If the cache is not upto date, use the function <tt><a href="#function_storedata">storedata</a></tt> to store the data that you want to be cached.</p>
<p> Additionally, the function <tt><a href="#function_voidcache">voidcache</a></tt> may be used to safely eliminate a cache file to assure that next time the cache needs to be regenerated.</p>
<h3><a name="4.2.0.1">Example</a></h3>
<p>Here follows an example of typical use of this class:</p>
<pre>&lt;?php
	
	/*
	 *  First create an object of the class.
	 */
	$cache_object=&amp;new file_cache_class;
	
	/*
	 *  Then set the variable of the path of the cache file.
	 *  In the end, take a look at the contents of this file.
	 */
	$cache_object-&gt;path='mycachefile.cache';
	
	/*
	 *  If we want to take different action if the cache is being updated,
	 *  we can ask the class to tell if an update is in progress.
	 */
	$success=$cache_object-&gt;updating($updating);
	
	/*
	 *  Check the success value to make sure there was no error.
	 */
	if($success)
	{
		if($updating)
		{
			echo 'Sorry, the cache file is being updated by another process running simultaneously. ';
			echo 'Please come back later.';
		}
		else
		{
			
			/*
			 *  Now verify if the cache file exists is upto date.
			 */
			$success=$cache_object-&gt;verifycache($updated);
			
			/*
			 *  Check the success value to make sure there was no error.
			 */
			if($success)
			{
				
				/*
				 *  Is the cache file upto date?
				 */
				if($updated)
				{
					
					/*
					 *  Yes. Now, let's read from the cache file and output the stored data.
					 */
					$endofcache=0;
					for(;!$endofcache;)
					{
						$success=$cache_object-&gt;retrievefromcache($data,$endofcache);
						if(!($success))
							break;
						echo $data;
					}
				}
				else
				{
					
					/*
					 *  No.  The cache file needs to be regenerated from fresh data.
					 *  Let's say that this is all the data I need to store in the cache.
					 */
					$data=&quot;Hello world! :-)\n&quot;;
					
					/*
					 *  If necessary, set the cache timeout period in seconds.
					 */
					$cachetimeout=60;
					$cache_object-&gt;setexpirytime($cachetimeout);
					
					/*
					 *  Store the cache data, all at once.
					 */
					$success=$cache_object-&gt;storedata($data,1);
					
					/*
					 *  If it was all ok, let's display the data.
					 */
					if($success)
					{
						echo $data;
					}
				}
			}
		}
	}
	
	/*
	 *  Finally, let's just do some error handling.
	 */
	if(!($success))
	{
		echo ('Error: '.$cache_object-&gt;error.&quot;\n&quot;);
	}
?&gt;</pre>
<p></p>
<p><a href="#table_of_contents">Table of contents</a></p>
</ul>
</ul>
<hr />
<ul>
<h2><li><a name="variables"></a><a name="5.1.1">Variables</a></li></h2>
<ul>
<li><tt><a href="#variable_path">path</a></tt></li><br />
<li><tt><a href="#variable_flush_cache_file">flush_cache_file</a></tt></li><br />
<p><a href="#table_of_contents">Table of contents</a></p>
<h3><a name="variable_path"></a><li><a name="6.2.3">path</a></li></h3>
<h3>Type</h3>
<p><tt><i>string</i></tt></p>
<h3>Default value</h3>
<p><tt>''</tt></p>
<h3>Purpose</h3>
<p>Path of the file in which the cached data is stored.</p>
<h3>Usage</h3>
<p>Set with different file paths for different types of data that you want to cache.</p>
<p><a href="#variables">Variables</a></p>
<h3><a name="variable_flush_cache_file"></a><li><a name="6.2.4">flush_cache_file</a></li></h3>
<h3>Type</h3>
<p><tt><i>bool</i></tt></p>
<h3>Default value</h3>
<p><tt>0</tt></p>
<h3>Purpose</h3>
<p>Flag that determines whether the <tt><a href="#function_storedata">storedata</a></tt> function should flush the cache file after writing all the cache data.</p>
<h3>Usage</h3>
<p>Set to <tt>1</tt> if you want to make sure that the all cache file writing errors are verified.</p>
<p><a href="#variables">Variables</a></p>
<p><a href="#table_of_contents">Table of contents</a></p>
</ul>
</ul>
<ul>
<h2><li><a name="functions"></a><a name="7.1.1">Inherited variables</a></li></h2>
<ul>
<li>error</li><br />
<li>reopenupdatedcache</li><br />
<li>headers</li><br />
<li>cache_buffer_length</li><br />
<li>automatic_headers</li><br />
<li>verify_headers</li><br />
<p><a href="#table_of_contents">Table of contents</a></p>
</ul>
</ul>
<hr />
<ul>
<h2><li><a name="functions"></a><a name="9.1.1">Functions</a></li></h2>
<ul>
<li><tt><a href="#function_verifycache">verifycache</a></tt></li><br />
<li><tt><a href="#function_storedata">storedata</a></tt></li><br />
<li><tt><a href="#function_retrievefromcache">retrievefromcache</a></tt></li><br />
<li><tt><a href="#function_closecache">closecache</a></tt></li><br />
<li><tt><a href="#function_voidcache">voidcache</a></tt></li><br />
<li><tt><a href="#function_updating">updating</a></tt></li><br />
<p><a href="#table_of_contents">Table of contents</a></p>
<h3><a name="function_verifycache"></a><li><a name="10.2.7">verifycache</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i>bool</i> verifycache(</tt><ul>
<tt>(output) <i>bool &amp;</i> </tt><tt><a href="#argument_verifycache_updated">updated</a></tt><tt></tt></ul>
<tt>)</tt></p>
<h3>Purpose</h3>
<p>Verify if the cache file is upto date.</p>
<p> If the cache file does not exist or is not upto date, this function will lock the cache file to prevent simultaneous accesses from concurrent processes. Then it opens the file, making it ready to be rewritten with upto date cache data.</p>
<p> If the cache file exists and is upto date, this function will lock the file to prevent attempts from  concurrent processes to change the file. Then it opens the file, making it ready to retrieve the cached data from it.</p>
<h3>Usage</h3>
<p>Use this function first to figure whether you can already retrieve the cached data or otherwise you need to regenerate the data to store in the cache file.</p>
<h3>Arguments</h3>
<ul>
<p><tt><b><a name="argument_verifycache_updated">updated</a></b></tt> - Reference to a variable that will hold a flag value that tells whether the cache exists and is upto date.</p>
</ul>
<h3>Return value</h3>
<p>Success boolean flag.  If this flag is <tt>0</tt> then the <tt><a href="#variable_error">error</a></tt> variable contains the error message that explains the failure.</p>
<p><a href="#functions">Functions</a></p>
<h3><a name="function_storedata"></a><li><a name="12.2.8">storedata</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i>bool</i> storedata(</tt><ul>
<tt>(input and output) <i>string &amp;</i> </tt><tt><a href="#argument_storedata_data">data</a></tt><tt>,<br />
</tt><tt><i>bool</i> </tt><tt><a href="#argument_storedata_endofcache">endofcache</a></tt><tt></tt></ul>
<tt>)</tt></p>
<h3>Purpose</h3>
<p>Store data in the cache file.</p>
<h3>Usage</h3>
<p>Use this function after calling the <tt><a href="#function_verifycache">verifycache</a></tt> function if it has returned the information that the cache file is not upto date.</p>
<p> If this function fails to write to the cache file, it will attempt to delete the file to minimize the chances that a partially written file be later mistaken as an upto date cache file.</p>
<h3>Arguments</h3>
<ul>
<p><tt><b><a name="argument_storedata_data">data</a></b></tt> - Reference to a variable that contains the data that is meant to be stored in the cache.</p>
<p><tt><b><a name="argument_storedata_endofcache">endofcache</a></b></tt> - Flag value that indicates whether the data being passed is the last chunk of data to be stored in the cache, or otherwise there is still more data to be passed in subsequent calls to this function.</p>
</ul>
<h3>Return value</h3>
<p>Success boolean flag.  If this flag is <tt>0</tt> then the <tt><a href="#variable_error">error</a></tt> variable contains the error message that explains the failure.</p>
<p><a href="#functions">Functions</a></p>
<h3><a name="function_retrievefromcache"></a><li><a name="14.2.9">retrievefromcache</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i>bool</i> retrievefromcache(</tt><ul>
<tt>(output) <i>string &amp;</i> </tt><tt><a href="#argument_retrievefromcache_data">data</a></tt><tt>,<br />
</tt><tt>(output) <i>bool &amp;</i> </tt><tt><a href="#argument_retrievefromcache_endofcache">endofcache</a></tt><tt></tt></ul>
<tt>)</tt></p>
<h3>Purpose</h3>
<p>Retrieve data from the cache file.</p>
<h3>Usage</h3>
<p>Use this function after calling the <tt><a href="#function_verifycache">verifycache</a></tt> function if it has returned that the cache file is upto date.</p>
<p> This function may also be called after having stored all cache data with the function <tt><a href="#function_storedata">storedata</a></tt>, if the variable <tt><a href="#variable_reopenupdatedcache">reopenupdatedcache</a></tt> is set to <tt>1.</tt></p>
<h3>Arguments</h3>
<ul>
<p><tt><b><a name="argument_retrievefromcache_data">data</a></b></tt> - Reference to a variable that will contain the data that is retrieved from the cache.</p>
<p><tt><b><a name="argument_retrievefromcache_endofcache">endofcache</a></b></tt> - Flag value that indicates whether the data retrieved from the cache is the last chunk of data, or otherwise there is still more data to be retrieved with subsequent calls to this function.</p>
</ul>
<h3>Return value</h3>
<p>Success boolean flag.  If this flag is <tt>0</tt> then the <tt><a href="#variable_error">error</a></tt> variable contains the error message that explains the failure.</p>
<p><a href="#functions">Functions</a></p>
<h3><a name="function_closecache"></a><li><a name="16.2.10">closecache</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i></i> closecache(</tt><tt>)</tt></p>
<h3>Purpose</h3>
<p>Close any cache files that were left open for update or for retrieving.</p>
<h3>Usage</h3>
<p>Use this function to close the cache file that was left open after <tt><a href="#function_verifycache">verifycache</a></tt> and for some reason your program will not finish updating the cache file with the <tt><a href="#function_storedata">storedata</a></tt> function or retrieve its contents to the end with <tt><a href="#function_retrievefromcache">retrievefromcache</a></tt>.</p>
<p><a href="#functions">Functions</a></p>
<h3><a name="function_voidcache"></a><li><a name="16.2.11">voidcache</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i>bool</i> voidcache(</tt><tt>)</tt></p>
<h3>Purpose</h3>
<p>Safely delete the cache file if exists to make sure that next time the cache is accessed it will need to be regenerated.</p>
<h3>Usage</h3>
<p>Use this function to void the cache file at any time except after it has been opened by the function <tt><a href="#function_verifycache">verifycache</a></tt> and until it has been closed by the functions <tt><a href="#function_storedata">storedata</a></tt> or <tt><a href="#function_retrievefromcache">retrievefromcache</a></tt>.</p>
<h3>Return value</h3>
<p>Success boolean flag.  If this flag is <tt>0</tt> then the <tt><a href="#variable_error">error</a></tt> variable contains the error message that explains the failure.</p>
<p><a href="#functions">Functions</a></p>
<h3><a name="function_updating"></a><li><a name="16.2.12">updating</a></li></h3>
<h3>Synopsis</h3>
<p><tt><i>bool</i> updating(</tt><ul>
<tt>(output) <i>bool &amp;</i> </tt><tt><a href="#argument_updating_updating">updating</a></tt><tt></tt></ul>
<tt>)</tt></p>
<h3>Purpose</h3>
<p>Determine whether the cache file is being locked for update by a concurrent process. This function may be useful when you want to take a different action because the process that updates the cache file may take a long time to finish.</p>
<h3>Usage</h3>
<p>Call this function when you need to determine if the cache file is accessible for reading or updating.</p>
<h3>Arguments</h3>
<ul>
<p><tt><b><a name="argument_updating_updating">updating</a></b></tt> - Flag value that indicates whether the cache is being updated by a concurrent process.</p>
</ul>
<h3>Return value</h3>
<p>Success boolean flag.  If this flag is <tt>0</tt> then the <tt><a href="#variable_error">error</a></tt> variable contains the error message that explains the failure.</p>
<p><a href="#functions">Functions</a></p>
<p><a href="#table_of_contents">Table of contents</a></p>
</ul>
</ul>
<ul>
<h2><li><a name="functions"></a><a name="19.1.1">Inherited functions</a></li></h2>
<ul>
<li>setheader</li><br />
<li>verifycache</li><br />
<li>setexpirydate</li><br />
<li>setexpirytime</li><br />
<li>storedata</li><br />
<li>retrievefromcache</li><br />
<li>closecache</li><br />
<li>voidcache</li><br />
<li>updating</li><br />
<p><a href="#table_of_contents">Table of contents</a></p>
</ul>
</ul>

<hr />
<address>Manuel Lemos (<a href="mailto:hide@address.com">hide@address.com</a>)</address>
</body>
</html>
Return current item: File cache class