Author: Tobias Schlitt
Date: 2006-01-15 14:56:51 +0100 (Sun, 15 Jan 2006)
New Revision: 1853
Log:
- Major documentation update.
- Making example general runable.
- Synced example with inline docs.
Modified:
packages/Cache/trunk/docs/example_ezpublish.php
packages/Cache/trunk/docs/example_general.php
packages/Cache/trunk/src/exceptions/invalid_data.php
packages/Cache/trunk/src/exceptions/invalid_id.php
packages/Cache/trunk/src/exceptions/invalid_location.php
packages/Cache/trunk/src/exceptions/invalid_storage_class.php
packages/Cache/trunk/src/exceptions/used_location.php
packages/Cache/trunk/src/manager.php
packages/Cache/trunk/src/storage.php
packages/Cache/trunk/src/storage/file.php
packages/Cache/trunk/src/storage/file/array.php
packages/Cache/trunk/src/storage/file/eval_array.php
packages/Cache/trunk/src/storage/file/plain.php
Modified: packages/Cache/trunk/docs/example_ezpublish.php
===================================================================
--- packages/Cache/trunk/docs/example_ezpublish.php 2006-01-14 18:38:42 UTC
(rev 1852)
+++ packages/Cache/trunk/docs/example_ezpublish.php 2006-01-15 13:56:51 UTC
(rev 1853)
@@ -31,12 +31,11 @@
// Initialize data and try to grep from cache
$data = '';
-if ( !( $data = $cache->restore( $id, $attributes ) ) )
+if ( ( $data = $cache->restore( $id, $attributes ) ) === false )
{
-
// No data in cache or data has expired. Generate new data...
- $data = generateMyData(); // What ever exactly happens to create it in
eZP
-
+ // What ever exactly happens to create it in eZp.
+ $data = generateMyData();
// ... and store it inside the cache
$cache->store( $id, $attributes, $data );
}
Modified: packages/Cache/trunk/docs/example_general.php
===================================================================
--- packages/Cache/trunk/docs/example_general.php 2006-01-14 18:38:42 UTC
(rev 1852)
+++ packages/Cache/trunk/docs/example_general.php 2006-01-15 13:56:51 UTC
(rev 1853)
@@ -8,59 +8,98 @@
* @license http://ez.no/licenses/new_bsd New BSD License
*/
+require_once 'Base/trunk/src/base.php';
+
+// Some pre-work, needed by the example
+$basePath = dirname( __FILE__ ).'/cache';
+
+function getUniqueId()
+{
+ return 'This is a unique ID';
+}
+
/**
- * Global configuration
+ * Autoload ezc classes
+ *
+ * @param string $class_name
*/
+function __autoload( $class_name )
+{
+ if ( ezcBase::autoload( $class_name ) )
+ {
+ return;
+ }
+ if ( strpos( $class_name, '_' ) !== false )
+ {
+ $file = str_replace( '_', '/', $class_name ) . '.php';
+ require_once( $file );
+ }
+}
-// Caches are configured globally. You configure the caches you need
-// once in a central file and can use the later on everywhere in your
-// application.
+// Central creation and configuration of the caches
+// The ezcCacheManager just stores the configuration right now and
+// performs sanity checks. The [EMAIL PROTECTED] ezcCacheStorage} instances
+// will be created on demand, when you use them for the first time
+// Configuration options for a cache [EMAIL PROTECTED] ezcCacheStorage}
$options = array(
- 'ttl' => 60*60*24*2, // Default would be 24hrs, here 48hrs
+ 'ttl' => 60*60*24*2, // Default would be 1 day, here 2 days
);
-// Options could also be storage dependant. The only global option is
-// 'ttl', the time-to-live.
+// Create a cache named "content", that resides in /var/cache/content
+// The cache instance will use the [EMAIL PROTECTED] ezcCacheStorageFileArray}
class
+// to store the cache data. The time-to-live for cache items is set as
+// defined above.
+ezcCacheManager::createCache( 'content', $basePath.'/content',
'ezcCacheStorageFileArray', $options );
-CacheManager::createCache( 'content', '/var/cache/content',
'ezcCacheStorageView', $options );
-CacheManager::createCache( 'template', '/var/cache/templates',
'ezcCacheStorageTemplate', $options );
-CacheManager::createCache( 'image', '/var/cache/images',
'ezcCacheStorageArray', $options );
+// Create another cache, called "template" in /var/cache/templates.
+// This cache will use the [EMAIL PROTECTED] ezcCacheStorageFilePlain} class
to store
+// cache data. It has the same TTL as the cache defined above.
+ezcCacheManager::createCache( 'template', $basePath.'/templates',
'ezcCacheStorageFilePlain', $options );
-// 3 caches are now available in the manager:
-// - 'content', located in /var/cache/content, using the eZ publish specific
View storage
-// - 'template', located in /var/cache/templates, using the eZ publish
specific Template storage
-// - 'image', located in /var/cache/images, using the builtin Array storage.;
+// Somewhere in the application you can access the caches
+
+// Get the instance of the cache called "content"
+// Now the instance of [EMAIL PROTECTED] ezcCacheStorageFileArray is created
and
+// returned to be used. Next time you access this cache, the created
+// instance will be reused.
+$cache = ezcCacheManager::getCache( 'content' );
-/**
- * Storing and restoring data
- */
-
-// First retreive tha cache you want to access from the manager.
-$cache = CacheManager::getCache( 'content' );
-
-// Prepare your data identification, use some attributes and a unique ID
+// Specify any number of attributes to identify the cache item you want
+// to store. This attributes can be used later to perform operations
+// on a set of cache items, that share a common attribute.
$attributes = array( 'node' => 2, 'area' => 'admin', 'lang' => 'en-GB' );
+// This function is not part of the Cache package. You have to define
+// unique IDs for your cache items yourself.
$id = getUniqueId();
-// Initialize your data variable
+// Initialize the data variable you want to restore
$data = '';
-// Check if data is available in the cache
-if ( !( $data = $cache->restore( $id, $attributes ) ) )
+// Check if data is available in the cache. The restore method returns
+// the cached data, if available, or bool false.
+if ( ( $data = $cache->restore( $id, $attributes ) ) === false ) {
+ // The cache item we tried to restore does not exist, so we have to
+ // generate the data.
+ $data = array( 'This is some data', 'and some more data.' );
+ // For testing we echo something here...
+ echo "No cache data found. Generated some.\n".var_export( $data, true
)."\n";
+ // Now we store the data in the cache. It will be available through
+ // restore, next time the code is reached
+ $cache->store( $id, $data, $attributes );
+}
+else
{
- // No data in cache or data has expired. Generate new data...
- $data = generateMyData();
- // ... and store it inside the cache
- $cache->store( $id, $attributes, $data );
+ // We found cache data. Let's echo the information.
+ echo "Cache data found.\n".var_export( $data, true )."\n";
}
-/**
- * Deleting and purgin caches.
- */
+// In some other place you can access the second defined cache.
+$cache = ezcCacheManager::getCache( 'template' );
-// Retreive the correct cache again
-$cache = CacheManager::getCache( 'template' );
+// Here we are removing cache items. We do not specify an ID (which would
+// have meant to delete 1 specific cache item), but only an array of
+// attributes. This will result in all cache items to be deleted, that
+// have this attribute assigned.
+$cache->delete( null, array( 'node' => 5 ) );
-// Remove all cache blocks that have the attribute "node" set to "2".
-$cache->delete( null, array( 'node' => 2 ) );
?>
Modified: packages/Cache/trunk/src/exceptions/invalid_data.php
===================================================================
--- packages/Cache/trunk/src/exceptions/invalid_data.php 2006-01-14
18:38:42 UTC (rev 1852)
+++ packages/Cache/trunk/src/exceptions/invalid_data.php 2006-01-15
13:56:51 UTC (rev 1853)
@@ -9,8 +9,18 @@
*/
/**
- * The given type of data could not be stored.
+ * Thrown if the data to be stored in a cache can not be handled by the
storage.
+ * Most [EMAIL PROTECTED] ezcCacheStorage} implementations are only capable of
storing
+ * scalar and array values, so this exception will be thrown when an
incompatible
+ * type is submitted for storage, like object or resource.
+ *
+ * [EMAIL PROTECTED] ezcCacheStorage::store()}
+ * [EMAIL PROTECTED] ezcCacheStorageFile::store()}
*
+ * [EMAIL PROTECTED] ezcCacheStorageFileArray::prepareData()}
+ * [EMAIL PROTECTED] ezcCacheStorageFileEvalArray::prepareData()}
+ * [EMAIL PROTECTED] ezcCacheStorageFilePlain::prepareData()}
+ *
* @package Cache
* @version //autogen//
*/
Modified: packages/Cache/trunk/src/exceptions/invalid_id.php
===================================================================
--- packages/Cache/trunk/src/exceptions/invalid_id.php 2006-01-14 18:38:42 UTC
(rev 1852)
+++ packages/Cache/trunk/src/exceptions/invalid_id.php 2006-01-15 13:56:51 UTC
(rev 1853)
@@ -10,6 +10,9 @@
/**
* Exception that is thrown if the given cache ID does not exist.
+ * Caches must be created using [EMAIL PROTECTED]
ezcCacheManager::createCache()} before
+ * they can be access using [EMAIL PROTECTED] ezcCacheManager::getCache()}. If
you try to
+ * access a non-existent cache ID, this exception will be thrown.
*
* @package Cache
* @version //autogen//
Modified: packages/Cache/trunk/src/exceptions/invalid_location.php
===================================================================
--- packages/Cache/trunk/src/exceptions/invalid_location.php 2006-01-14
18:38:42 UTC (rev 1852)
+++ packages/Cache/trunk/src/exceptions/invalid_location.php 2006-01-15
13:56:51 UTC (rev 1853)
@@ -14,6 +14,8 @@
*
* @package Cache
* @version //autogen//
+ *
+ * @todo: Deprecated because of ezcBaseFile* exceptions. Remove.
*/
class ezcCacheInvalidLocationException extends ezcCacheException
{
Modified: packages/Cache/trunk/src/exceptions/invalid_storage_class.php
===================================================================
--- packages/Cache/trunk/src/exceptions/invalid_storage_class.php
2006-01-14 18:38:42 UTC (rev 1852)
+++ packages/Cache/trunk/src/exceptions/invalid_storage_class.php
2006-01-15 13:56:51 UTC (rev 1853)
@@ -10,6 +10,10 @@
/**
* Exception that is thrown when an invalid storage class is used.
+ * All storage classes used with the [EMAIL PROTECTED] ezcCacheManager}, by
creating a
+ * cache instance, using [EMAIL PROTECTED] ezcCacheManager::createCache()}. If
you
+ * provide a non-existant storage class or a class that does not derive from
+ * [EMAIL PROTECTED] ezcCacheStorage}, this exception will be thrown.
*
* @package Cache
* @version //autogen//
Modified: packages/Cache/trunk/src/exceptions/used_location.php
===================================================================
--- packages/Cache/trunk/src/exceptions/used_location.php 2006-01-14
18:38:42 UTC (rev 1852)
+++ packages/Cache/trunk/src/exceptions/used_location.php 2006-01-15
13:56:51 UTC (rev 1853)
@@ -10,6 +10,11 @@
/**
* Exception that is thrown when a given location is already in use.
+ * Only one cache may reside in a specific location to avoid conflicts while
+ * storing ([EMAIL PROTECTED] ezcCacheStorage::store()}) and restoring
+ * ([EMAIL PROTECTED] ezcCacheStorage::restore()}) data from a cache. If you
try to
+ * configure a cache to be used in location that is already taken by another
+ * cachein ezcCacheManager::createCache(), this exception will be thrown.
*
* @package Cache
* @version //autogen//
Modified: packages/Cache/trunk/src/manager.php
===================================================================
--- packages/Cache/trunk/src/manager.php 2006-01-14 18:38:42 UTC (rev
1852)
+++ packages/Cache/trunk/src/manager.php 2006-01-15 13:56:51 UTC (rev
1853)
@@ -10,42 +10,82 @@
*/
/**
- * Class to manage multiple ezcCacheStorage objects at once. Implements
- * singleton for caches which access a certain location The usage of this
- * class is not mandatory, but recommended. ezcCacheStorage objects can
- * also be used on their own.
+ * This is the main class of the Cache package. It gives you a handy interface
+ * to create and manage multiple caches at once. It enables you to configure
+ * all caches you need in your application in a central place and access them
+ * on demand in any place in your application.
*
+ * The use of ezcCacheManager is not required, but recommended. If you only
+ * need a few (or maybe just 1) cache instance, you can use and instanciate
+ * a [EMAIL PROTECTED] ezcCacheStorage} class directly.
+ *
+ * Usage example for ezcCacheManager:
* <code>
- * // Global configuration
- *
- * $options = array(
- * 'ttl' => 60*60*24*2, // Default would be 1 day, here 2 days
- * );
- * CacheManager::createCache( 'content', '/var/cache/content',
'ezcCacheStorageView', $options );
- * CacheManager::createCache( 'template', '/var/cache/templates',
'ezcCacheStorageTemplate', $options );
- *
- * // Somewhere in the application
- *
- * $cache = CacheManager::getCache( 'content' );
- *
- * $attributes = array( 'node' => 2, 'area' => 'admin', 'lang' => 'en-GB' );
- * $id = getUniqueId();
- *
- * $data = '';
- * // Check if data is available in the cache
- * if ( !( $data = $cache->restore( $id, $attributes )) ) {
- * // No, so create data...
- * $data = generateMyData();
- * // ... and store it inside the cache
- * $cache->store( $id, $attributes, $data );
- * }
- *
- * // Somewhere else...
- *
- * $cache = CacheManager::getCache( 'template' );
- *
- * // Remove all cache blocks of node 2
- * $cache->delete( null, array( 'node' => 2 ) );
+ * // Central creation and configuration of the caches
+ * // The ezcCacheManager just stores the configuration right now and
+ * // performs sanity checks. The [EMAIL PROTECTED] ezcCacheStorage} instances
+ * // will be created on demand, when you use them for the first time
+ *
+ * // Configuration options for a cache [EMAIL PROTECTED] ezcCacheStorage}
+ * $options = array(
+ * 'ttl' => 60*60*24*2, // Default would be 1 day, here 2 days
+ * );
+ *
+ * // Create a cache named "content", that resides in /var/cache/content
+ * // The cache instance will use the [EMAIL PROTECTED]
ezcCacheStorageFileArray} class
+ * // to store the cache data. The time-to-live for cache items is set as
+ * // defined above.
+ * ezcCacheManager::createCache( 'content', $basePath.'/content',
'ezcCacheStorageFileArray', $options );
+ *
+ * // Create another cache, called "template" in /var/cache/templates.
+ * // This cache will use the [EMAIL PROTECTED] ezcCacheStorageFilePlain}
class to store
+ * // cache data. It has the same TTL as the cache defined above.
+ * ezcCacheManager::createCache( 'template', $basePath.'/templates',
'ezcCacheStorageFilePlain', $options );
+ *
+ * // Somewhere in the application you can access the caches
+ *
+ * // Retreive the cache we configured earlier and identified it as "content".
+ * // Right now the instance of [EMAIL PROTECTED] ezcCacheStorageFileArray} is
created and
+ * // returned to be used. Next time you access this cache, the created
+ * // instance will be reused.
+ * $cache = ezcCacheManager::getCache( 'content' );
+ *
+ * // Specify any number of attributes to identify the cache item you want
+ * // to store. This attributes can be used later to perform operations
+ * // on a set of cache items, that share a common attribute.
+ * $attributes = array( 'node' => 2, 'area' => 'admin', 'lang' => 'en-GB' );
+ * // This function is not part of the Cache package. You have to define
+ * // unique IDs for your cache items yourself.
+ * $id = getUniqueId();
+ *
+ * // Initialize the data variable you want to restore
+ * $data = '';
+ * // Check if data is available in the cache. The restore method returns
+ * // the cached data, if available, or bool false.
+ * if ( ( $data = $cache->restore( $id, $attributes ) ) === false ) {
+ * // The cache item we tried to restore does not exist, so we have to
+ * // generate the data.
+ * $data = array( 'This is some data', 'and some more data.' );
+ * // For testing we echo something here...
+ * echo "No cache data found. Generated some.\n".var_export( $data, true
)."\n";
+ * // Now we store the data in the cache. It will be available through
+ * // restore, next time the code is reached
+ * $cache->store( $id, $data, $attributes );
+ * }
+ * else
+ * {
+ * // We found cache data. Let's echo the information.
+ * echo "Cache data found.\n".var_export( $data, true )."\n";
+ * }
+ *
+ * // In some other place you can access the second defined cache.
+ * $cache = ezcCacheManager::getCache( 'template' );
+ *
+ * // Here we are removing cache items. We do not specify an ID (which would
+ * // have meant to delete 1 specific cache item), but only an array of
+ * // attributes. This will result in all cache items to be deleted, that
+ * // have this attribute assigned.
+ * $cache->delete( null, array( 'node' => 5 ) );
* </code>
*
* @package Cache
@@ -73,7 +113,7 @@
private static $configurations = array();
/**
- * Private. This is a static class only.
+ * Private. This class has static methods only.
*
* @see {ezcCacheManager::createCache()}
* @see {ezcCacheManager::getCache()}
@@ -107,21 +147,26 @@
* );
* </code>
*
- * @param string $id ID of the cache to create.
- * @param string $location Location to create the cache in.
- * @param string $storageClass Subclass of [EMAIL PROTECTED]
ezcCacheStorage}.
- * @param array(string) $options Options for the cache.
+ * @param string $id ID of the cache to create.
+ * @param string $location Location to create the cache in.
+ * @param string $storageClass Subclass of [EMAIL PROTECTED]
ezcCacheStorage}.
+ * @param array(string=>string) $options Options for the cache.
* @return void
*
* @throws ezcBaseFileNotFoundException
* If the given location does not exist or is not a
- * directory.
+ * directory (thrown by sanity checks performed when storing the
+ * configuration of a cache to ensure the latter calls to
+ * [EMAIL PROTECTED] ezcCacheManager::getCache()} do not fail).
* @throws ezcBaseFilePermissionException
- * If the given location is not read/writeable.
+ * If the given location is not read/writeable (thrown by sanity
+ * checks performed when storing the configuration of a cache to
+ * ensure the latter calls to [EMAIL PROTECTED]
ezcCacheManager::getCache()}
+ * do not fail).
* @throws ezcCacheUsedLocationException
* If the given location is already in use by another cache.
* @throws ezcCacheInvalidStorageClassException
- * If the given storage class does not exist or is no subclas of
+ * If the given storage class does not exist or is no subclass of
* ezcCacheStorage.
*/
public static function createCache( $id, $location, $storageClass,
$options = array() )
@@ -169,14 +214,32 @@
* @param string $id The ID of the cache to return.
* @return ezcCacheStorage The cache with the given ID.
*
+ * @throws ezcCacheInvalidIdException
+ * If the ID of a cache you try to access does not exist. To access
+ * a cache using this method, it first hast to be created using
+ * [EMAIL PROTECTED] ezcCacheManager::createCache()}.
* @throws ezcBaseFileNotFoundException
- * If the storage location does not exist.
+ * If the storage location does not exist. This should usually not
+ * happen, since [EMAIL PROTECTED] ezcCacheManager::createCache()}
already
+ * performs sanity checks for the cache location. In case this
+ * exception is thrown, your cache location has been corrupted
+ * after the cache was configured.
* @throws ezcBaseFileNotFoundException
- * If the storage location is not a directory.
+ * If the storage location is not a directory. This should usually
+ * not happen, since [EMAIL PROTECTED]
ezcCacheManager::createCache()} already
+ * performs sanity checks for the cache location. In case this
+ * exception is thrown, your cache location has been corrupted
+ * after the cache was configured.
* @throws ezcBaseFilePermissionException
- * If the storage location is not writeable.
+ * If the storage location is not writeable. This should usually
not
+ * happen, since [EMAIL PROTECTED] ezcCacheManager::createCache()}
already
+ * performs sanity checks for the cache location. In case this
+ * exception is thrown, your cache location has been corrupted
+ * after the cache was configured.
* @throws ezcBaseSettingNotFoundException
- * If an unknown option is set.
+ * If you tried to set a non-existent option value. The accpeted
+ * options depend on th ezcCacheStorage implementation and my
+ * vary.
*/
public static function getCache( $id )
{
Modified: packages/Cache/trunk/src/storage/file/array.php
===================================================================
--- packages/Cache/trunk/src/storage/file/array.php 2006-01-14 18:38:42 UTC
(rev 1852)
+++ packages/Cache/trunk/src/storage/file/array.php 2006-01-15 13:56:51 UTC
(rev 1853)
@@ -10,12 +10,20 @@
*/
/**
- * This implements a simple storage to cache array and scalar values
- * on the filesystem. Unlike it's brother storage class
- * ezcCacheStorageFileEvalarray, this class uses "include" to restore
- * the data, whereas ezcCacheStorageFileEvalarray uses an eval() call
- * to restore data.
+ * This class implements a simple storage to cache array and scalar values
+ * on the filesystem. It takes it's base methods from the extended
+ * storage base class [EMAIL PROTECTED] ezcCacheStorageFile}.
*
+ * This cache storage implementation stores arrays and scalar values
+ * (int, float, string, bool) in files on your harddisc as PHP code. This makes
+ * the restoring of cache data extremly fast, since the stored data is simply
+ * included and parsed by the PHP interpreter.
+ *
+ * Another storage class with a similar approach exists,
+ * [EMAIL PROTECTED] ezcCacheStorageFileEvalArray}. This class is uses exactly
the same
+ * mechanisms as ezcCacheStorageFileArray, except that is does not simply
+ * require the stored source code, but uses eval() to restore the data.
+ *
* Main purpose behind these 2 similar implementations is the following:
* Most byte code caches are capable of caching code for included files,
* but not for eval()ed strings. Therefore the *Evalarray class will
@@ -25,7 +33,13 @@
* with your PHP installation, the use of ezcCacheStorageFileArray is
* recommende over the usage of ezcCacheStorageEvalarray.
*
- * For example code see [EMAIL PROTECTED] ezcCacheManager}.
+ * For example code of using a cache storage, see [EMAIL PROTECTED]
ezcCacheManager}.
+ *
+ * The Cache package contains several other implementations of
+ * [EMAIL PROTECTED] ezcCacheStorageFile}. As there are:
+ *
+ * - ezcCacheStorageFileEvalArray
+ * - ezcCacheStorageFilePlain
*
* @package Cache
*/
@@ -54,7 +68,9 @@
* @return string The serialized data
*
* @throws ezcCacheInvalidDataException
- * If the data submitted is an object or a resource.
+ * If the data submitted is an object or a resource, since this
+ * implementation of [EMAIL PROTECTED] ezcCacheStorageFile} can
only deal with
+ * scalar and array values.
*/
protected function prepareData( $data )
{
Modified: packages/Cache/trunk/src/storage/file/eval_array.php
===================================================================
--- packages/Cache/trunk/src/storage/file/eval_array.php 2006-01-14
18:38:42 UTC (rev 1852)
+++ packages/Cache/trunk/src/storage/file/eval_array.php 2006-01-15
13:56:51 UTC (rev 1853)
@@ -10,22 +10,34 @@
*/
/**
- * This implements a simple storage to cache array and scalar values
- * on the filesystem. Unlike it's brother storage class
- * ezcCacheStorageFileArray, this class uses eval() to restore
- * the data, whereas ezcCacheStorageFileArray uses "include" to restore
- * data.
+ * This class implements a simple storage to cache array and scalar values
+ * on the filesystem. It takes it's base methods from the extended
+ * storage base class [EMAIL PROTECTED] ezcCacheStorageFile}.
*
+ * This cache storage implementation stores arrays and scalar values
+ * (int, float, string, bool) in files on your harddisc as PHP code. In
+ * contrast to it's sibling class [EMAIL PROTECTED] ezcCacheStorageFileArray},
the stored
+ * PHP code is not simply required to restore the cache data, but is
+ * evaluated using PHP's eval() function.
+ *
* Main purpose behind these 2 similar implementations is the following:
* Most byte code caches are capable of caching code for included files,
- * but not for eval()ed strings. Therefore the *Evalarray class will
- * permit you to get your cached data not cached a second time by an
- * accellerator like APC, whereas the *Array class will permit you to
- * explicitly allow this. ATTENTION: If you do not use a byte code cache
- * with your PHP installation, the use of ezcCacheStorageFileArray is
- * recommende over the usage of ezcCacheStorageEvalarray.
+ * but not for eval()'ed strings. Therefore the
+ * [EMAIL PROTECTED] ezcCacheStorageFileEvalarray} class will permit you to
get your cached
+ * data not cached a second time by an accellerator like APC, whereas the
+ * [EMAIL PROTECTED] ezcCacheStorageFileArray} class will permit you to
explicitly allow
+ * this. ATTENTION: If you do not use a byte code cache with your PHP
+ * installation, the use of [EMAIL PROTECTED] ezcCacheStorageFileArray} is
recommende over
+ * the usage of [EMAIL PROTECTED] ezcCacheStorageEvalarray}, since eval() is
much slower
+ * than directly requiring the stored PHP code.
*
- * For example code see [EMAIL PROTECTED] ezcCacheManager}.
+ * For example code of using a cache storage, see [EMAIL PROTECTED]
ezcCacheManager}.
+ *
+ * The Cache package contains several other implementations of
+ * [EMAIL PROTECTED] ezcCacheStorageFile}. As there are:
+ *
+ * - ezcCacheStorageFileArray
+ * - ezcCacheStorageFilePlain
*
* @package Cache
*/
@@ -53,7 +65,9 @@
* @return string The serialized data
*
* @throws ezcCacheInvalidDataException
- * If the data submitted is an object or a resource.
+ * If the data submitted is an object or a resource, since this
+ * implementation of [EMAIL PROTECTED] ezcCacheStorageFile} can
only deal with
+ * scalar and array values.
*/
protected function prepareData( $data )
{
Modified: packages/Cache/trunk/src/storage/file/plain.php
===================================================================
--- packages/Cache/trunk/src/storage/file/plain.php 2006-01-14 18:38:42 UTC
(rev 1852)
+++ packages/Cache/trunk/src/storage/file/plain.php 2006-01-15 13:56:51 UTC
(rev 1853)
@@ -10,11 +10,32 @@
*/
/**
- * This implements a simple storage to cache scalar values
- * on the filesystem.
+ * This class implements a simple storage to cache plain text
+ * on the filesystem. It takes it's base methods from the extended
+ * storage base class [EMAIL PROTECTED] ezcCacheStorageFile}.
+ *
+ * In contrast to other [EMAIL PROTECTED] ezcCacheStorageFile}
implementations, the stored
+ * cache data is restored using PHP's file_get_contents() class. This cache
+ * is not capable to store array values. If numeric values are stored the
+ * restored values will be of type string. The same applies to values of the
+ * simple type bool. It is highly recommended that you cast the resulting
+ * value to it's correct type, also PHP will automatically perform this cast
+ * when necessary. An explicit cast ensures, that type consistant comparisons
+ * (using the === or !== operators) will not fail on restored cache data.
+ *
+ * An even better solution, if you want to store non-string values, are the
+ * usage of [EMAIL PROTECTED] ezcCacheStorageFileArray} and
+ * [EMAIL PROTECTED] ezcCacheStorageFileEvalArray} storage classes, since
those keep the
+ * variable types of you cached data consistant.
+ *
+ * For example code of using a cache storage, see [EMAIL PROTECTED]
ezcCacheManager}.
+ *
+ * The Cache package contains several other implementations of
+ * [EMAIL PROTECTED] ezcCacheStorageFile}. As there are:
+ *
+ * - ezcCacheStorageFileArray
+ * - ezcCacheStorageFilePlain
*
- * For example code see [EMAIL PROTECTED] ezcCacheManager}.
- *
* @package Cache
*/
class ezcCacheStorageFilePlain extends ezcCacheStorageFile
@@ -42,7 +63,9 @@
* @return string The serialized data
*
* @throws ezcCacheInvalidDataException
- * If the data submitted is an object, resource or array.
+ * If the data submitted is an array,object or a resource, since
+ * this implementation of [EMAIL PROTECTED] ezcCacheStorageFile}
can only deal
+ * with scalar values.
*/
protected function prepareData( $data )
{
Modified: packages/Cache/trunk/src/storage/file.php
===================================================================
--- packages/Cache/trunk/src/storage/file.php 2006-01-14 18:38:42 UTC (rev
1852)
+++ packages/Cache/trunk/src/storage/file.php 2006-01-15 13:56:51 UTC (rev
1853)
@@ -11,11 +11,23 @@
/**
* This class implements most of the methods which have been declared abstract
- * inside ezcCacheStorage, but also declares 2 new methods abstract, which
have to
- * be implemented by the specific storage driver. This class is a common base
class
- * for all simple file based storage classes.
+ * in [EMAIL PROTECTED] ezcCacheStorage}, but also declares 2 new methods
abstract, which
+ * have to be implemented by storage driver itself.
*
- * For example code see [EMAIL PROTECTED] ezcCacheManager}.
+ * This class is a common base class for all file system based storage classes.
+ * To implement a file system based cache storage, you simply have to derive
+ * from this class and implement the [EMAIL PROTECTED]
ezcCacheStorageFile::fetchData()}
+ * and [EMAIL PROTECTED] ezcCacheStorageFile::prepareData()} methods.
Everything else is
+ * done for you by the ezcCacheStorageFile base class.
+ *
+ * For example code of using a cache storage, see [EMAIL PROTECTED]
ezcCacheManager}.
+ *
+ * The Cache package already contains several implementations of
+ * [EMAIL PROTECTED] ezcCacheStorageFile}. As there are:
+ *
+ * - ezcCacheStorageFileArray
+ * - ezcCacheStorageFileEvalArray
+ * - ezcCacheStorageFilePlain
*
* @package Cache
*/
@@ -39,6 +51,11 @@
*
* @param mixed $data Simple type or array
* @return string The serialized data
+ *
+ * @throws ezcCacheInvalidDataException
+ * If the data submitted can not be handled by the implementation
+ * of [EMAIL PROTECTED] ezcCacheStorageFile}. Most implementations
can not
+ * handle objects and resources.
*/
abstract protected function prepareData( $data );
@@ -56,16 +73,34 @@
* implementations also use the attributes for storage purposes. Attributes
* form some kind of "extended ID".
*
- * @param string $id The unique identifier for the data stored.
- * @param mixed $data The data to store.
- * @param array $attributes Attributes that describe the cached data.
+ * @param string $id Unique identifier for the data.
+ * @param mixed $data The data to store.
+ * @param array(string=>string) $attributes Attributes describing the
+ * cached data.
*
- * @return string The ID string of the newly cached data.
+ * @return string The ID string of the newly cached data.
*
* @throws ezcBaseFilePermissionException
- * If an already existsing cache file could not be unlinked.
+ * If an already existsing cache file could not be unlinked to
+ * store the new data (may occur, when a cache item's TTL
+ * has expired and the file should be stored with more actual
+ * data). This exception means most likely that your cache diretory
+ * has been corrupted by external influences (file permission
+ * change).
* @throws ezcBaseFilePermissionException
* If the directory to store the cache file could not be created.
+ * This exception means most likely that your cache diretory
+ * has been corrupted by external influences (file permission
+ * change).
+ * @throws ezcBaseFileIoException
+ * If an error occured while writing the data to the cache. If this
+ * exception occurs, a serious error occured and your storage might
+ * be corruped (e.g. broken network connection, file system broken,
+ * ...).
+ * @throws ezcCacheInvalidDataException
+ * If the data submitted can not be handled by the implementation
+ * of [EMAIL PROTECTED] ezcCacheStorageFile}. Most implementations
can not
+ * handle objects and resources.
*/
public function store( $id, $data, $attributes = array() )
{
@@ -107,10 +142,17 @@
* them. BEWARE: Finding cache data only by ID can be much
* slower than finding it by ID and attributes.
*
- * @param string $id The cache ID to restore data from.
- * @param array $attributes Attributed describing the data to restore.
+ * @param string $id The item ID to restore.
+ * @param array(string=>string) $attributes Attributes describing the
+ * data to restore.
*
* @return mixed|bool The cached data on success, otherwise false.
+ *
+ * @throws ezcBaseFilePermissionException
+ * If an already existsing cache file could not be unlinked.
+ * This exception means most likely that your cache diretory
+ * has been corrupted by external influences (file permission
+ * change).
*/
public function restore( $id, $attributes = array() )
{
@@ -152,12 +194,16 @@
* If you only provide attributes for deletion of cache data, all cache
* data matching these attributes will be purged.
*
- * @param string $id The ID of the data to purge.
- * @param array $attributes Attributes describing the data to purge.
+ * @param string $id The item ID to purge.
+ * @param array(string=>string) $attributes Attributes describing the
+ * data to restore.
* @return void
*
* @throws ezcBaseFilePermissionException
- * If a cache file could not be unlinked.
+ * If an already existsing cache file could not be unlinked.
+ * This exception means most likely that your cache diretory
+ * has been corrupted by external influences (file permission
+ * change).
*/
public function delete( $id = null, $attributes = array() )
{
@@ -185,8 +231,9 @@
* This method determines if cache data described by the given ID and/or
* attributes exists. It returns the number of cache data items found.
*
- * @param string $id The ID of the cache data.
- * @param array $attributes Attributes to describe the data.
+ * @param string $id The item ID.
+ * @param array(string=>string) $attributes Attributes describing the
+ * data to restore.
* @return bool If cache data with the specified criteria
exists.
*/
public function countDataItems( $id = null, $attributes = array() )
@@ -199,10 +246,11 @@
* before it gets outdated. In case the cache object is already
* outdated or does not exists, this method returns 0.
*
- * @param string $id The ID of the cache data.
- * @param array $attributes Attributes to describe the data.
+ * @param string $id The item ID.
+ * @param array(string=>string) $attributes Attributes describing the
+ * data to restore.
* @access public
- * @return int The remaining lifetime ( 0 if nonexists or oudated ).
+ * @return int The remaining lifetime (0 if nonexists or oudated).
*/
public function getRemainingLifetime( $id, $attributes = array() )
{
@@ -217,8 +265,9 @@
/**
* Search the storage for data.
*
- * @param string $id The unique identifier provided by you
- * @param array $attributes Attributes to search for
+ * @param string $id An item ID.
+ * @param array(string=>string) $attributes Attributes describing the
+ * data to restore.
* @return void
*/
private function search( $id = null, $attributes = array() )
@@ -233,13 +282,26 @@
* Checks if the location exists and tries to create it, if not. Also
checks
* if the location is read-/writeable and throws an exception, if not.
*
+ * @return void
+ *
* @throws ezcBaseFileNotFoundException
- * If the storage location does not exist.
+ * If the storage location does not exist. This should usually not
+ * happen, since [EMAIL PROTECTED] ezcCacheManager::createCache()}
already
+ * performs sanity checks for the cache location. In case this
+ * exception is thrown, your cache location has been corrupted
+ * after the cache was configured.
* @throws ezcBaseFileNotFoundException
- * If the storage location is not a directory.
+ * If the storage location is not a directory. This should usually
+ * not happen, since [EMAIL PROTECTED]
ezcCacheManager::createCache()} already
+ * performs sanity checks for the cache location. In case this
+ * exception is thrown, your cache location has been corrupted
+ * after the cache was configured.
* @throws ezcBaseFilePermissionException
- * If the storage location is not writeable.
- * @return void
+ * If the storage location is not writeable. This should usually
not
+ * happen, since [EMAIL PROTECTED] ezcCacheManager::createCache()}
already
+ * performs sanity checks for the cache location. In case this
+ * exception is thrown, your cache location has been corrupted
+ * after the cache was configured.
*/
protected function validateLocation()
{
@@ -266,11 +328,12 @@
* attributes. This is the default implementation and can be overloaded if
* necessary.
*
- * @param string $id The ID.
- * @param array(string) $attr The attributes.
+ * @param string $id The ID.
+ * @param array(string=>string) $attributes Attributes describing the
+ * data to restore.
* @return string The generated identifier
*/
- public function generateIdentifier( $id, $attr = null )
+ public function generateIdentifier( $id, $attributes = null )
{
$filename = (string) $id;
$illegalFileNameChars = array(
@@ -286,10 +349,10 @@
' ' => '%',
':' => '+',
);
- if ( is_array( $attr ) && count( $attr ) > 0 )
+ if ( is_array( $attributes ) && count( $attributes ) > 0 )
{
- ksort( $attr );
- foreach ( $attr as $key => $val )
+ ksort( $attributes );
+ foreach ( $attributes as $key => $val )
{
$attrStr = '-' . strtr( $key, $illegalChars ) . ':' . strtr(
$val, $illegalChars );
if ( strlen( $filename . $attrStr ) > 250 )
Modified: packages/Cache/trunk/src/storage.php
===================================================================
--- packages/Cache/trunk/src/storage.php 2006-01-14 18:38:42 UTC (rev
1852)
+++ packages/Cache/trunk/src/storage.php 2006-01-15 13:56:51 UTC (rev
1853)
@@ -11,11 +11,25 @@
/**
* This is the abstract base class for all cache storages. It provides
- * the interface to be implemented by a cache backend as well as some
- * convenience methods every of these have in common. It is not recommended
- * to use a cache object directly, but to utilize the [EMAIL PROTECTED]
ezcCacheManager}.
+ * the interface to be implemented by a cache backend as abstract methods.
+ * For your convenience it contains some methods you can utilize to create your
+ * own storage implementation (e.g. for storing cache data into a database).
+ *
+ * Implementations of ezcCacheStorage can be used with the
+ * [EMAIL PROTECTED] ezcCacheManager} or on their own. If you want to
implement a cache
+ * storage backend that stores cache data in a file on your harddisc, there
+ * is an extended version of ezcCacheStorage, [EMAIL PROTECTED]
ezcCacheStorageFile},
+ * which already implements large parts of the API and leaves only
+ * very few work for you to do.
*
- * For example code see [EMAIL PROTECTED] ezcCacheManager}.
+ * For example code of using a cache storage, see [EMAIL PROTECTED]
ezcCacheManager}.
+ *
+ * The Cache package already contains several implementations of
+ * [EMAIL PROTECTED] ezcCacheStorageFile}. As there are:
+ *
+ * - ezcCacheStorageFileArray
+ * - ezcCacheStorageFileEvalArray
+ * - ezcCacheStorageFilePlain
*
* @package Cache
*/
@@ -57,17 +71,31 @@
* to 1 day. Specific ezcCacheStorage implementations can have
* additional options.
*
- * @param string $location Path to the cache location
- * @param array(string) $options Options
+ * @param string $location Path to the cache location
+ * @param array(string=>string) $options Options for the cache.
*
* @throws ezcBaseFileNotFoundException
- * If the storage location does not exist.
+ * If the storage location does not exist. This should usually not
+ * happen, since [EMAIL PROTECTED] ezcCacheManager::createCache()}
already
+ * performs sanity checks for the cache location. In case this
+ * exception is thrown, your cache location has been corrupted
+ * after the cache was configured.
* @throws ezcBaseFileNotFoundException
- * If the storage location is not a directory.
+ * If the storage location is not a directory. This should usually
+ * not happen, since [EMAIL PROTECTED]
ezcCacheManager::createCache()} already
+ * performs sanity checks for the cache location. In case this
+ * exception is thrown, your cache location has been corrupted
+ * after the cache was configured.
* @throws ezcBaseFilePermissionException
- * If the storage location is not writeable.
+ * If the storage location is not writeable. This should usually
not
+ * happen, since [EMAIL PROTECTED] ezcCacheManager::createCache()}
already
+ * performs sanity checks for the cache location. In case this
+ * exception is thrown, your cache location has been corrupted
+ * after the cache was configured.
* @throws ezcBaseSettingNotFoundException
- * If an unknown option is set.
+ * If you tried to set a non-existent option value. The accpeted
+ * options depend on th ezcCacheStorage implementation and my
+ * vary.
*/
public function __construct( $location, $options = null )
{
@@ -90,16 +118,34 @@
* implementations also use the attributes for storage purposes. Attributes
* form some kind of "extended ID".
*
- * @param string $id The unique identifier for the data stored.
- * @param mixed $data The data to store.
- * @param array $attributes Attributes that describe the cached data.
+ * @param string $id The item ID.
+ * @param mixed $data The data to store.
+ * @param array(string=>string) $attributes Attributes that describe the
+ * cached data.
*
* @return string The ID of the newly cached data.
*
* @throws ezcBaseFilePermissionException
- * If an already existsing cache file could not be unlinked.
+ * If an already existsing cache file could not be unlinked to
+ * store the new data (may occur, when a cache item's TTL
+ * has expired and the file should be stored with more actual
+ * data). This exception means most likely that your cache diretory
+ * has been corrupted by external influences (file permission
+ * change).
* @throws ezcBaseFilePermissionException
* If the directory to store the cache file could not be created.
+ * This exception means most likely that your cache diretory
+ * has been corrupted by external influences (file permission
+ * change).
+ * @throws ezcBaseFileIoException
+ * If an error occured while writing the data to the cache. If this
+ * exception occurs, a serious error occured and your storage might
+ * be corruped (e.g. broken network connection, file system broken,
+ * ...).
+ * @throws ezcCacheInvalidDataException
+ * If the data submitted can not be handled by the implementation
+ * of [EMAIL PROTECTED] ezcCacheStorage}. Most implementations can
not
+ * handle objects and resources.
*/
abstract public function store( $id, $data, $attributes = array() );
@@ -119,10 +165,17 @@
* them. BEWARE: Finding cache data only by ID can be much
* slower than finding it by ID and attributes.
*
- * @param string $id The cache ID to restore data from.
- * @param array $attributes Attributed describing the data to restore.
+ * @param string $id The item ID.
+ * @param array(string=>string) $attributes Attributes that describe the
+ * cached data.
*
* @return mixed The cached data on success, otherwise false.
+ *
+ * @throws ezcBaseFilePermissionException
+ * If an already existsing cache file could not be unlinked.
+ * This exception means most likely that your cache diretory
+ * has been corrupted by external influences (file permission
+ * change).
*/
abstract public function restore( $id, $attributes = array() );
@@ -138,11 +191,15 @@
* If you only provide attributes for deletion of cache data, all cache
* data matching these attributes will be purged.
*
- * @param string $id The ID of the data to purge.
- * @param array $attributes Attributes describing the data to purge.
+ * @param string $id The item ID.
+ * @param array(string=>string) $attributes Attributes that describe the
+ * cached data.
*
* @throws ezcBaseFilePermissionException
- * If a cache file could not be unlinked.
+ * If an already existsing cache file could not be unlinked.
+ * This exception means most likely that your cache diretory
+ * has been corrupted by external influences (file permission
+ * change).
*/
abstract public function delete( $id = null, $attributes = array() );
@@ -151,8 +208,8 @@
* This method determines if cache data described by the given ID and/or
* attributes exists. It returns the number of cache data items found.
*
- * @param string $id The ID of the cache data.
- * @param array $attributes Attributes to describe the data.
+ * @param string $id The item ID.
+ * @param array(string=>string) $attributes Attributes that describe the
* @return int The number of cache data items found matching the criteria.
*/
abstract public function countDataItems( $id = null, $attributes = array()
);
@@ -162,8 +219,8 @@
* before it gets outdated. In case the cache object is already
* outdated or does not exists, this method returns 0.
*
- * @param string $id The ID of the cache data.
- * @param array $attributes Attributes to describe the data.
+ * @param string $id The item ID.
+ * @param array(string=>string) $attributes Attributes that describe the
* @access public
* @return int The remaining lifetime ( 0 if nonexists or oudated ).
*/
@@ -184,7 +241,11 @@
/**
* Return the currently set options.
- * Return the currently set options.
+ * Return the currently set options. The options are returned on an array
+ * that has the same format as the one passed to
+ * [EMAIL PROTECTED] ezcCacheStorage::setOptions()}. The possible options
for a storage
+ * depend on it's implementation. For an overview of common options, see
+ * [EMAIL PROTECTED] ezcCacheStorage::setOptions()}.
*
* @return array The options
*/
@@ -195,11 +256,25 @@
/**
* Set new options.
+ * This method allows you to change the options of a cache storage. Change
+ * of options take effect directly after this method has been called. The
+ * available options depend on the ezcCacheStorage implementation. All
+ * implementations have to offer the follwoing options:
+ *
+ * - ttl The time-to-life. After this time span, a cache item
becomes
+ * invalid and will be purged. The
+ * [EMAIL PROTECTED] ezcCacheStorage::restore()} method will
then return
+ * false.
+ * - extension The "extension" for your cache items. This is usually the
+ * file name extension, when you deal with file system based
+ * caches or e.g. a database ID extension.
*
- * @param array $options The options
+ * @param array(string=>string) $options The options to set.
*
* @throws ezcBaseSettingNotFoundException
- * If the desired option does not exist.
+ * If you tried to set a non-existent option value. The accpeted
+ * options depend on th ezcCacheStorage implementation and my
+ * vary.
*/
public function setOptions( $options = null )
{
--
svn-components mailing list
[email protected]
http://lists.ez.no/mailman/listinfo/svn-components
