Cache_Lite

指定のデータをファイルにキャッシュできます。

導入

pear.batを用いて、次のようにインストールするのが簡単です。

pear install Cache_Lite

またはDownload - Cache_LiteからCache_Lite-*.*.*.tgzをダウンロードし、それに含まれるCacheディレクトリをpearのディレクトリへコピーします。

オブジェクトの生成

void constructor Cache_Lite::Cache_Lite (
    array $options = array(NULL) )

Manual :: コンストラクタ (日本語) Manual :: Constructor (英語)

キャッシュの動作は引数の$optionsで指定します。

`$options`の設定値
配列のキー	データ型	意味	既定値
cacheDir	string	キャッシュファイルを配置するディレクトリ (末尾はスラッシュ)	/tmp/
caching	boolean	キャッシュの有効/無効	TRUE
lifeTime	integer	キャッシュの生存期間 (秒単位)	3600
fileLocking	boolean	ファイルロックの有効/無効	TRUE
writeControl	boolean	書き込み制御の有効/無効	TRUE
readControl	boolean	読み込み制御の有効/無効	TRUE
readControlType	string	読み込み制御のタイプ	crc32
pearErrorMode	integer	PEAR エラーモード	CACHE_LITE_ERROR_RETURN
fileNameProtection	boolean	ファイル名を保護するかどうか	TRUE
automaticSerialization	boolean	自動シリアライズの有効/無効	FALSE
memoryCaching	boolean	"メモリキャッシング" の有効/無効	FALSE
onlyMemoryCaching	boolean	"メモリキャッシングのみ" の有効/無効	FALSE
memoryCachingLimit	integer	メモリキャッシュにストアするレコードの最大数	1000
automaticCleaningFactor	integer	自動クリーニングプロセスの実行頻度 (1/automaticCleaningFactorの確率で削除)	0
hashedDirectoryLevel	integer	ハッシュ化されたディレクトリ構造のレベル	0
errorHandlingAPIBreak	boolean		FALSE

Manual :: コンストラクタ

キャッシュの保存場所

'cacheDir'を指定しないときは既定の'/tmp/'となり、Windows環境ではこれはC:\tmp\のようなパスとなります。≫環境によるルートディレクトリの違い

指定のディレクトリが存在しないときは、保存されません。

キャッシュの自動削除

'automaticCleaningFactor'を指定すると、古いキャッシュが自動で削除されるようになります。古いと判断する基準は同時に指定する'lifeTime'の期間であり、そのキャッシュの保存時の期間の指定は無関係です。また削除される対象は、'cacheDir'にある[cache_]から始まるファイル名のファイルすべてであり、グループは無関係です。

なお'lifeTime'は、そのキャッシュを使用するときに、まだ有効かどうかを判断する指針です。よって'automaticCleaningFactor'などで削除しない限り、生存期間を過ぎてもそのまま残り続けます。

エラー内容の確認

処理に失敗するようならば、$optionsで'pearErrorMode=>CACHE_LITE_ERROR_DIE'を指定します。これによりスクリプトがすぐに停止するため、デバッグに便利です。たとえばキャッシュを保存するディレクトリが存在しない、もしくは書き込みに失敗するときには、Cache_Lite : Unable to write cache fileと返されます。

設定例

たとえば次のようにパラメータを指定すると、

$options = array(
    'cacheDir'=>'/tmp/',
    'lifeTime'=>3600,
    'automaticCleaningFactor'=>200
    );
$cache = new Cache_Lite( $options );

キャッシュは/tmp/に保存されます。そして1/200の確率で、そのときその/tmp/ディレクトリに保存されていた、3600秒より前に更新されたファイルが削除されます。

キャッシュへの書き込み

boolean Cache_Lite::save (
    string $data ,            // 保存するデータ
    string $id = NULL ,       // キャッシュID
    string $group = 'default' // キャッシュグループ名
    )

Manual :: キャッシュファイルにデータを保存する

Cache_Lite::save()実行時にCache_Lite : Unable to write cache fileとエラーとなる場合には、キャッシュファイルを保存するディレクトリの指定に誤りがあるか、または書き込みの権限がない可能性があります。

同じキャッシュディレクトリを使い回し、$idが重複する恐れがあるならば、キャッシュの上書きを避けるために$groupも指定します。

キャッシュのファイル名

キャッシュのファイル名は、既定で

'cache_'.md5( $group ).'_'.md5( $id )

のように、キャッシュグループ名とIDからmd5()関数で計算されたハッシュ値から構成されます。このとき$groupの既定値は'default'であることから、グループ名を指定しないときはそれのハッシュ値が用いられ

'cache_c21f969b5f03d33d43e04f8f136e7682_'.md5( $id )

のファイル名になります。ただしコンストラクタのパラメータで'fileNameProtection'をFALSEとしたときは、この限りではなく、

'cache_'.$group.'_'.$id

のようにグループ名やIDがそのままファイル名となります。この場合には、特殊文字に対する注意が必要となります。

キャッシュからの読み込み

string Cache_Lite::get (
    string $id ,                            // キャッシュID
    string $group = 'default' ,             // キャッシュグループ名
    boolean $doNotTestCacheValidity = FALSE // TRUEならば、キャッシュの正当性をテストしない
    )

有効なキャッシュがない場合には、FALSEが返されます。

サンプルコード

特定のページからの読み込みをキャッシュする場合を考えます。

require_once 'Cache/Lite.php';

$url = "http://example.com"; // 読み込むページのURL
$id = $url;                  // キャッシュID (ここではページのURL)

$options = array(
    'cacheDir'=>$_SERVER[ 'DOCUMENT_ROOT' ].'/tmp/',
    'lifeTime'=>60,
    'pearErrorMode'=>CACHE_LITE_ERROR_DIE
    );

if( !file_exists( $options[ 'cacheDir' ] ) )
{
    // キャッシュのディレクトリが存在しないならば、それを作成する
    mkdir( $options[ 'cacheDir' ], 0705 );
}

$cache = new Cache_Lite( $options );

// キャッシュから読み込む
$data = $cache->get( $id );
if( $data === FALSE )
{
    // キャッシュが無効であれば、URLから読み込む
    $data = file_get_contents( $url );

    // キャッシュに保存する
    $cache->save( $data, $id );
}

var_dump( $data );