.gitignore Doxyfile @@ -1,5 +1,11 @@ <?php +/** + * \brief Backend class using the Alternative PHP Cache. + * + * This backend class uses the Alternative PHP Cache's user cache to store + * data. It requires that APC is both installed and enabled via php.ini. + */ class APCBackend extends BackendSkeleton { pca/backends/apc_backend.class.php @@ -1,8 +1,18 @@ <?php +/** + * \brief Backend class for testing using arrays for data storage. + * + * This backend class stores all data in a single array, which will be lost at + * the end of the PHP script, so it is not recommended to use this backend in + * production. + */ class ArrayBackend extends BackendSkeleton { + /** + * The array in which all data will be stored. + */ private $data; public function __construct($options) pca/backends/array_backend.class.php @@ -1,9 +1,36 @@ <?php +/** + * \brief Backend class using simple file-based storage. + * + * This backend class stores all data in files. It uses one file for each key + * => value pair. The filename, or, if the subdirectories option is enabled, + * the path and the filename, are the hexadecimal representation of the MD5 + * hash of the key. + * + * This backend requires garbage collection, please make sure to call gc() + * periodically. + * + * List of options: + * - directory: The path where all cached data will be stored + * - subdirectories: Because many filesystems don't scale well with many files + * in one directory, the FileBackend supports using up to 31 nested levels of + * subdirectories. If you for example set this value to '3', the file + * '70d064794720f5072cb960e1f3b93f6f' will be stored in the directory '7/0/d/' + * with the new filename '064794720f5072cb960e1f3b93f6f'. The default is 2. + * Set to 0 to disable. + */ class FileBackend extends BackendSkeleton { + /** + * \brief The directory which holds the cached data. + */ private $directory; + + /** + * \brief The level of subdirectories in the cache directory. + */ private $subdirectories = 2; public function __construct($options) @@ -19,6 +46,20 @@ class FileBackend extends BackendSkeleton } } + /** + * \brief Tries to find a suitable cache directory + * + * This function tries to find the temporary directory on a system. It uses + * the function sys_get_temp_dir(), which was added in PHP 5.2.1, but falls + * back to environment variables and a hackish trick employing the function + * tempnam() if the PHP version is < 5.2.1. + * + * This function uses make_temp_dir() to create a subdirectory called 'pca' + * in the temporary files directory of the server. + * + * @see make_temp_dir() + * @return The path to the cache directory. + */ private function get_temp_dir() { if(function_exists('sys_get_temp_dir')) @@ -32,6 +73,17 @@ class FileBackend extends BackendSkeleton return $this->make_temp_dir(dirname($tmpfile)); } + /** + * \brief Creates a directory 'pca' and returns it's path. + * + * This function is used by get_temp_dir() to create a subdirectory called + * 'pca' in the temporary files directory of the server (if it does not + * already exist'). + * + * @see get_temp_dir() + * @param $directory the directory in which a 'pca' subdirectory will be created. + * @return The path to the 'pca' subdirectory. + */ private function make_temp_dir($directory) { $directory .= DIRECTORY_SEPARATOR . 'pca'; @@ -40,6 +92,15 @@ class FileBackend extends BackendSkeleton return $directory; } + /** + * \brief Derives the filename for the cache file from a key + * + * This function derives the filename for the cache file from a key by + * using a hash function (currently md5). + * + * @param $key the key. + * @return The path to the cache file. + */ private function get_filename($key) { $file = md5($key); @@ -88,6 +149,20 @@ class FileBackend extends BackendSkeleton return false; } + /** + * \brief Walks through a directory and deletes expired/all cache files. + * + * This function is used both by the flush() operation and the garbage + * collection. It recursively walks through a directory and deletes all + * expired cache files or all files if the parameter $flush is set to true. + * + * @param $directory the directory that shall be cleaned. + * @param $flush when true, all cache files (even non-expired ones) will be + * deleted. + * + * @see flush() + * @see gc() + */ private function walk_directory($directory, $flush = false) { $dir = new DirectoryIterator($directory); pca/backends/file_backend.class.php @@ -1,5 +1,26 @@ <?php +/** + * \brief Backend class using memcached. + * + * This backend class uses memcached, a simple caching daemon. + * + * List of options: + * - server: Server information array (see below) for a single server. + * - servers: An array of server information arrays. If the option 'server' is + * given, this option will be ignored. + * - compression: Boolean value to control compression of values. Requires the + * zlib extension (default: false). + * + * Server information array: + * - host: IP address or hostname of the server (required). + * - port: Port of the server (default: 11211). + * - weight: Probability of this server being selected relative to total + * weight of all servers (default: 1). + * - timeout: Timeout for the server connection in seconds (default: 1). + * - retry_intervall: Time in seconds before trying to reconnect to a server + * that previously had a timeout (default: 15). + */ class MemcacheBackend extends BackendSkeleton { @@ -20,7 +41,7 @@ class MemcacheBackend extends BackendSkeleton isset($server["timeout"]) ? $server["timeout"] : 1, isset($server["retry_interval"]) ? $server["retry_interval"] : 15 ); - if($options["compression"]) + if(isset($options["compression"]) && $options['compression']) $this->flags += MEMCACHE_COMPRESSED; } } pca/backends/memcache_backend.class.php @@ -1,10 +1,46 @@ <?php +/** + * \brief Backend class using a database (mySQL; Postgres, ...). + * + * This backend uses PDO to store each (key, value, ttl) triplet in a row in a + * database which has to be manually created (see data/pdo-scheme.sql). + * + * If mySQL is used as database server, some queries will be optimized. This + * feature is also planned for other database servers. + * + * This backend requires garbage collection, please make sure to call gc() + * periodically. + * + * List of options: + * - pdo: A PDO connection. + * - dsn: The dsn of the database (only if pdo is not specified). + * - username: The username for the database server (optional). + * - password: The password for the database server (optional). + * - table_name: The table where cached values will be stored. The default is + * 'cache'. + * - optimize_sql: Boolean value. When set to false, queries won't be + * optimized for a specific database server. This option should only be used + * internally for unit testing. + */ + class PDOBackend extends BackendSkeleton { + /** + * \brief The PDO connection. + */ private $pdo; + + /** + * \brief The table where cached values will be stored. + */ private $table_name = 'cache'; + + /** + * The driver for which queries will be optimized. If set to null, generic + * queries will be used. + */ private $driver = null; public function __construct($options) pca/backends/pdo_backend.class.php @@ -1,15 +1,56 @@ <?php +/** + * \brief The base class for all backends. + * + * This abstract class is the base for all other backend classes. It defines + * all necessary functions. Some of these have to be overloaded, while others + * are already implemented as a fallback, but should still be overloaded in a + * child class if possible, to aviod performance penalties. + */ abstract class BackendSkeleton { + /** + * \brief The constructor should not be called directly, use PCA::factory + * instead. + * + * @see PCA::factory() + * @param $options an array of configuration options for the backend. Take + * a look at the individual backend's documentation for more details. + */ public function __construct($options) { } + /** + * \brief Checks if a key exists. + * + * If not implemented by a backend, it uses get() as fallback and simply + * checks if the value is null. + * + * @see get() + * @param $key the key to search for. + * @return Boolean value indicating whether the key exists or not. + */ public function exists($key) { return !is_null($this->get($key)); } + /** + * \brief Inserts a value if the key does not already exist. + * + * If not implemented by a backend, it uses exists() to check if the key + * already exists and only inserts the value if the key does not already + * exist. + * + * @see exists() + * @param $key the key that will be inserted. + * @param $value the data that will be cached. + * @param $ttl optional time to live in seconds. 0 means forever. + * @return True if the value was successfully inserted, false when the key + * already existed and was therefore not overridden or if there wase a + * problem inserting the data (e.g. cache full, ...). + */ public function add($key, $value, $ttl = 0) { if($this->exists($key)) @@ -17,14 +58,49 @@ abstract class BackendSkeleton return $this->set($key, $value, $ttl); } + /** + * \brief Inserts a value. + * + * @param $key the key that will be inserted. + * @param $value the data that will be cached. + * @param $ttl optional time to live in seconds. 0 means forever. + * @return True on success, false when there was a problem inserting the + * data (e.g. cache full, ...). + */ abstract public function set($key, $value, $ttl = 0); + /** + * \brief Retrieves a value. + * + * @param $key the key of the value. + * @return The value or null if there is no cached data for that key. + */ abstract public function get($key); + /** + * \brief Deletes a value. + * + * @param $key the key that will be removed. + * @return True if the data was successfully removed, false when no data + * with that key was stored. + */ abstract public function delete($key); + /** + * \brief Deletes all values. + * + * @return True on success, false if there was some kind of error. + */ abstract public function flush(); + /** + * \brief Runs the garbage collection. + * + * Some backends require garbage collection to remove expired entries from + * the cache, so this function should be called periodically. + * + * @return True on success, false if there was some kind of error. + */ public function gc() { return true; pca/backends/skeleton.php @@ -2,8 +2,23 @@ require_once(dirname(__FILE__) . '/backends/skeleton.php'); +/** + * \brief Implements a factory pattern to manage various backends. + * + * The PCA class implements two factory methods that both return a PCABackend + * instance. + */ final class PCA { + /** + * \brief The main method for creating a PCABackend instance of a specific + * type. + * + * @param $type the name of the backend (e.g. 'file' for FileBackend). + * @param $options an array of configuration options for the backend. Take + * a look at an individual backend's documentation for more details. + * @return An instance of the class PCABackend. + */ public static function factory($type, $options = array()) { if(include_once(dirname(__FILE__) . '/backends/' . $type . '_backend.class.php')) @@ -17,6 +32,21 @@ final class PCA { } } + /** + * \brief Returns the best-suited backend without the need for any + * configuration. + * + * Tries to guess the best backend type that will be supported by this + * version/configuration of PHP and automatically returns a PCABackend + * instance. This function is useful for applications, where the user + * shouldn't be overwhelmed with configuration options on install. + * + * The current strategy only knows 2 backends: + * - APCBackend: use when APC is installed and enabled + * - FileBackend: use as fallback + * + * @return An instance of the class PCABackend. + */ public static function get_best_backend() { if(ini_get('apc.enabled') && !(PHP_SAPI == 'cli' && !ini_get('apc.enable_cli'))) pca/pca.class.php d770aef273c65bb0aa4f2fe6370c09479f77ddcf David Triendl david@triendl.name http://github.com/soult/pca/commit/e327bdcfe0ddd9a429837a266064ee846014b77e e327bdcfe0ddd9a429837a266064ee846014b77e 2009-03-18T15:07:09-07:00 2009-03-18T15:07:09-07:00 Add documentation This commit adds doxygen-style comments as well as a Doxyfile. HTML documentation can now simple be generated by typing 'doxygen' into your shell. Please note that the documentation could still be improved a bit, but hey, it's a start. c8e6a358eb9ff3a9840679900dc284474a058257 David Triendl david@triendl.name