jdorn / file-system-cache
an easy way to cache data in the file system
Installs: 40 201
Dependents: 0
Suggesters: 0
Security: 0
Stars: 54
Watchers: 10
Forks: 13
Open Issues: 2
Requires
- php: >=5.3.0
This package is auto-updated.
Last update: 2024-10-30 01:38:45 UTC
README
A simple PHP class for caching data in the filesystem. Major features include:
- Support for TTL when storing data
- Support for "Newer Than" parameter when retrieving data
- Every call is an atomic operation with proper file locking
- Can group cache keys together for easy invalidation
- Composer support
- PHPUnit tests
Getting Started
FileSystemCache can be installed with Composer or downloaded manually.
With Composer
If you're already using Composer, just add jdorn/file-system-cache
to your composer.json
file.
FileSystemCache works with Composer's autoloader out of the bat.
{ "require": { "jdorn/file-system-cache": "dev-master" } }
Manually
If you aren't using Composer, you just need to include lib/FileSystemCache.php
in your script.
require_once("path/to/FileSystemCache.php");
Setting the Cache Directory
By default, all cached data is stored in the cache
directory relative to the currently executing script.
You can change this by setting the $cacheDir static property.
<?php FileSystemCache::$cacheDir = '/tmp/cache';
FileSystemCache needs write access to the cache directory.
It's easiest if Apache (or whatever web server you're using) owns the directory.
Cache Keys
All of FileSystemCache's methods operate on Cache Keys. There is a generateCacheKey
method that returns a Cache Key object.
You can pass in almost anything as the key data (array, object, string, number). Any non-strings will be serialized and hashed.
<?php //array of data $key_data = array( 'user_id'=>1001, 'ip address'=>'10.1.1.1' ); //string $key_data = 'my_key'; //object $key_data = new SomeObject(); //number $key_data = 1005; //generate a key object $key = FileSystemCache::generateCacheKey($key_data);
You can group cache keys together to better organize your data and make invalidation easier.
<?php $key_data = 'my_key'; //store in root directory (same as leaving out second parameter) $key = FileSystemCache::generateCacheKey($key_data, null); //store in 'group1' directory $key = FileSystemCache::generateCacheKey($key_data, 'group1'); //store in 'group1/subgroup' directory $key = FileSystemCache::generateCacheKey($key_data, 'group1/subgroup');
The resulting file structure will look like:
$cacheDir/
| +- my_key.cache
| +- group1/
| | +- my_key.cache
| | +- subgroup/
| | | +- my_key.cache
Store
Data is serialized before storing, so you can use strings, array, objects, or numbers.
$data = array( 'this'=>'is some data I want to cache', 'it'=>'can be a string, array, object, or number.' ); $key = FileSystemCache::generateCacheKey('mykey'); FileSystemCache::store($key, $data);
If you want the data to expire automatically after a set amount of time, use the optional ttl
parameter.
// Expire automatically after 1 hour (3600 seconds) FileSystemCache::store($key, $data, 3600);
Retrieve
You retrieve data using the same cache key you used to store it. False
will be returned if the data was not cached or expired.
$data = FileSystemCache::retrieve($key); // If there was a cache miss if($data === false) { ... }
You can specify a newer than
timestamp to only retrieve cached data that was stored after a certain time.
This is useful for storing a compiled version of a source file.
$file = 'source_file.txt'; $modified = filemtime($file); $key = FileSystemCache::generateCacheKey($file); $data = FileSystemCache::retrieve($key, $modified); // If there was a cache miss if($data === false) { ... }
Get and Modify
There is an atomic Get and Modify
method as well.
FileSystemCache::getAndModify($key, function($value) { $value->count++; return $value; });
If the data was originally cached with a TTL, you can pass true
as the 3rd parameter to resset the TTL.
Otherwise, it will be based on the original time it was stored.
Invalidate
You can invalidate a single cache key or a group of cache keys.
FileSystemCache::invalidate($key); FileSystemCache::invalidateGroup('mygroup');
Invalidating a group is done recursively by default and all sub-groups will also be invalidated.
If you pass false
as the 2nd parameter, you can make it non-recursive.
FileSystemCache::invalidateGroup('mygroup', false);
Running the Tests
You need PHPUnit installed to run the tests. Configuration is defined in phpunit.xml.dist
. Running the tests is easy:
phpunit