wincache_ucache_add

(PECL wincache >= 1.1.0)

wincache_ucache_add — 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する

説明

wincache_ucache_add ( string $key , mixed $value [, int $ttl = 0 ] ) : bool
wincache_ucache_add ( array $values [, mixed $unused = NULL [, int $ttl = 0 ]] ) : bool

変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加します。 追加された変数は、有効期限に達するか、 wincache_ucache_delete() あるいは wincache_ucache_clear() で削除されるまではキャッシュに残り続けます。

パラメータ

key

変数を格納するときに、この名前のキーを使います。 同じキーで既に変数が格納されているときは、この関数は失敗して FALSE を返します。 key は大文字小文字を区別します。同じキーがあっても値を上書きしたい場合は wincache_ucache_set() 関数をかわりに使います。 key には name => value のペアの配列を渡すこともできます。 この場合は name がキーとなります。 この形式を使えば複数の値を一度の操作でキャッシュに格納できるので、競合状態になることを防げます。

value

格納したい変数の値。ファイルハンドルのようなリソース型以外のすべてのデータ型をサポートしています。 最初のパラメータが配列の場合は、このパラメータは無視されます。 一般的な指針として、key に配列を渡す場合は value を NULL にしておきましょう。 value がオブジェクト、あるいはオブジェクトを含む配列である場合は、 オブジェクトがシリアライズされます。オブジェクトのシリアライズについての詳細は __sleep() を参照ください。

values

キーと値の連想配列。

ttl

変数のキャッシュ内での生存時間を秒単位で指定します。 ttl で指定した秒数が経過すると、 格納されている変数はキャッシュから削除されます。 このパラメータのデフォルト値は 0 で、これは wincache_ucache_delete() あるいは wincache_ucache_clear() で明示的に削除するまでキャッシュに残り続けることを意味します。

返り値

key が文字列のときは、成功した場合に TRUE、失敗した場合に FALSE を返します。

key が配列のときの返り値は、次のようになります。

  • 配列内のすべての name => value ペアが設定できた場合は、空の配列を返します。
  • 配列内の name => value ペアがひとつも設定できなかった場合は、FALSE を返します。
  • 成功したペアと失敗したペアがある場合は、ユーザーキャッシュへの追加に失敗した name=>value ペアを含む配列を返します。

例

例1 wincache_ucache_add() で key を文字列にする例

<?php
$bar = 'BAR';
var_dump(wincache_ucache_add('foo', $bar));
var_dump(wincache_ucache_add('foo', $bar));
var_dump(wincache_ucache_get('foo'));
?>

上の例の出力は以下となります。

bool(true)
bool(false)
string(3) "BAR"

例2 wincache_ucache_add() で key を配列にする例

<?php
$colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
var_dump(wincache_ucache_add($colors_array));
var_dump(wincache_ucache_add($colors_array));
var_dump(wincache_ucache_get('Blue'));
?>

上の例の出力は以下となります。

array(0) { } 
array(4) { 
  ["green"]=> int(-1) 
  ["Blue"]=> int(-1) 
  ["yellow"]=> int(-1) 
  ["cyan"]=> int(-1) 
} 
string(1) "6"

参考