gregwar / cache
A lightweight file-system cache system
Installs: 3 893 140
Dependents: 17
Suggesters: 0
Security: 0
Stars: 111
Watchers: 7
Forks: 31
Open Issues: 7
Requires
- php: >=5.3
README
This is a lightweight cache system based on file and directories.
Usage
Step 1: Install it
Via composer:
{ "require": { "gregwar/cache": "1.0.*" } }
Or with a clone of the repository:
git clone https://github.com/Gregwar/Cache.git
Or downloading it:
Step 2: Setup the rights
You need your PHP script to have access to the cache directory, you can for instance
create a cache
directory (be sure the web server can write it):
mkdir cache
Step 3: Access the cache
To access the cache, you can do like this:
<?php include('vendor/autoload.php'); // If using composer use Gregwar\Cache\Cache; $cache = new Cache; $cache->setCacheDirectory('cache'); // This is the default // If the cache exists, this will return it, else, the closure will be called // to create this image $data = $cache->getOrCreate('red-square.png', array(), function($filename) { $i = imagecreatetruecolor(100, 100); imagefill($i, 0, 0, 0xff0000); imagepng($i, $filename); }); header('Content-type: image/png'); echo $data;
This will render a red square. If the cache file (which will look like `cache/r/e/d/-/s/red-square.png') exists, it will be read, else, the closure will be called in order to create the cache file.
API
You can use the following methods:
setCacheDirectory($directory)
: sets the cache directory (see below).setActualCacheDirectory($directory)
: sets the actual cache directory (see below).exists($filename, $conditions = array())
: check that the $filename file exists in the cache, checking the conditions (see below).check($filename, $conditions = array())
: alias forexists
.getCacheFile($filename, $actual = false, $mkdir = false)
: gets the cache file. If the$actual
flag is true, the actual cache file name will be returned (see below), if the$mkdir
flag is true, the cache file directories tree will be created.set($filename, $contents)
: write contents to$filename
cache file.write($filename, $contents)
: alias forset()
get($filename, $conditions = array())
: if the cache file for$filename
exists, contents will be returned, else,NULL
will be returned.setPrefixSize($prefixSize)
: sets the prefix size for directories, default is 5. For instance, the cache file forhelloworld.txt
, will be'h/e/l/l/o/helloworld.txt
.setDirectoryMode($directoryMode)
: sets the directory mode when creating directories, default is0755
. Does not affect any directories previously created.getOrCreate($filename, $conditions = array(), $function, $file = false)
: this will check if the$filename
cache file exists and verifies$conditions
(see below). If the cache file is OK, it will return its contents. Else, it will call the$function
, passing it the target file, this function can write the file given in parameter or just return data. Then, cache data will be returned. If$file
flag is set, the cache file name will be returned instead of file data.
Note: consider using an hash for the $filename
cache file, to avoid special characters.
Conditions
You can use conditions to manage file expirations on the cache, there is two way of expiring:
- Using
max-age
, in seconds, to set the maximum age of the file - Using
younger-than
, by passing another file, this will compare the modification date and regenerate the cache if the given file is younger.
For instance, if you want to uppercase a file:
<?php use Gregwar\Cache\Cache; $cache = new Cache; $data = $cache->getOrCreate('uppercase.txt', array( 'younger-than' => 'original.txt' ), function() { echo "Generating file...\n"; return strtoupper(file_get_contents('original.txt')); }); echo $data;
This will be create the uppercase.txt
cache file by uppercasing the original.txt
if the cache file
does not exists or if the original.txt
file is more recent than the cache file.
For instance:
php uppercase.php # Will generate the cache file
php uppercase.php # Will not generate the cache file
touch original.txt # Sets the last modification time to now
php uppercase.php # Will re-generate the cache file
Cache directory and actual cache directory
In some cases, you'll want to get the cache file name. For instance, if you're caching
images, you'll want to give a string like cache/s/o/m/e/i/someimage.png
to put it into
an <img>
tag. This can be done by passing the $file
argument to the getOrCreate
to true,
or directly using getCacheFile
method (see above).
However, the visible cache
directory of your users is not the same as the absolute path
you want to access. To do that, you can set both the cache directory and the actual cache directory.
The cache directory is the prefix visible by the users (for instance: cache/s/o/m/e/i/someimage.png
),
and the actual cache directory is the prefix to use to actually access to the image (for instance:
/var/www/somesite/cache/s/o/m/e/i/someimage.png
). This way, the file will be accessed using absolute
path and the cache file returned will directly be usable for your user's browsers.
License
This repository is under the MIT license, have a look at the LICENCE
file.