• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

Transients API

提供: WordPress Codex 日本語版
移動先: 案内検索

ページ名検討中: このページ名「Transients API」について改名が提案されています。ご意見をお寄せください。

この項目「Transients API」は、翻訳チェック待ちの項目です。加筆、訂正などを通して、Codex ドキュメンテーションにご協力下さい。

このページは WordPress Transients API についての技術的な文書です。この API はキャッシュされるデータを一時的にデータベースへ保存するためのシンプルで標準化された方法を提供します。この方法ではデータに名前と有効期限を設定し、期限が来るとデータが削除されます。

訳注:一時的に保存されるべきデータを以下「Transient」と表記します。

Transients API は Options API に似ていますが、有効期限という機能を使うことで、キャッシュされるデータを一時的に wp_options テーブルへ保存するという処理をシンプルに実現します。

  • 参考: 名前に「site_」がついた関数は基本的に、それがつかない関数と同じ機能を持ちますが、WordPress をマルチサイトで使うときにネットワーク全体で利用できる点が異なります。
  • 参考: Transient は本質的にキャッシングプラグインによってスピードアップされます。一方、Options API はそうではありません。たとえば memcached プラグインは、データベースではなく高速なメモリー内に Transient を保存します。こうした理由から、Transient は有効期限を持つデータのために使うべきです。また、必ずデータベースにあると想定してはなりません。そうではない場合もあるからです。

この記事が想定する読者は WordPress のテーマ作者、プラグイン作者、そして特定のデータをキャッシュする必要があるが指定した期限までに更新されるようにしたい(更新されなければ削除する)と考えている人です。この文書は PHP の基本的な理解を必要とします。

関数リファレンス

Transient の保存/取得
Transient の削除

Transients API の使い方

Transient を保存する

Transient を保存するには set_transient() /en を使います:

set_transient( $transient, $value, $expiration );
$transient 
(文字列) キャッシュされるデータにつけるユニークな識別子。長さ 45 文字以下であること。注意: site_ の Transient を使う場合は 40 文字以下とする。
$value 
(配列|オブジェクト) 保存するデータ。ふつうの変数または配列/オブジェクト。複雑なデータはこの API がシリアライズしてくれる。
$expiration 
(整数) データを更新するまでの最大の秒数。Transient は $expiration より前に期限切れする場合があるが(外部オブジェクトキャッシュや、データベースのアップグレードによる)、$expiration を過ぎると値を決して返さない。

例えば $special_query_results オブジェクトを 12 時間保存しておくには次のようにします:

set_transient( 'special_query_results', $special_query_results, 60*60*12 );

時間の定数を使う

WordPress 3.5 で、時間を表記しやすくするために定数がいくつか導入されました。

MINUTE_IN_SECONDS  = 60 (秒)
HOUR_IN_SECONDS    = 60 * MINUTE_IN_SECONDS  (1時間)
DAY_IN_SECONDS     = 24 * HOUR_IN_SECONDS    (1日)
WEEK_IN_SECONDS    = 7 * DAY_IN_SECONDS      (1週間)
YEAR_IN_SECONDS    = 365 * DAY_IN_SECONDS    (1年)

例えば、上記のコード例は次のようにシンプルにできます:

set_transient( 'special_query_results', $special_query_results, 12 * HOUR_IN_SECONDS );

Transient を取得する

保存された Transient を取得するには get_transient() /en を使います:

get_transient( $transient );
$transient 
(文字列) set_transient() で Transient を保存するときにつけたユニークな名前。

上の例で保存した $special_query_results を取得するには:

$special_query_results = get_transient( 'special_query_results' );

もし Transient が存在しないか、有効期限切れの場合、get_transient()false を返します。このチェックにはふつうの等価演算子 == ではなく、厳密な等価演算子 === を使うべきです。なぜなら、整数値 0(または "empty" や "false" っぽい他のデータ)を保存したい場合もあるからです。false がこのような意味を持つため、Transient に単一の真偽値 (true/false)を保存するのは避けるべきです。配列に格納するか、整数に変換しましょう。

使用例:

if ( false === ( $value = get_transient( 'value' ) ) ) {
    // Transient が存在しない場合、この部分のコードが実行されます。
    $value = ... // ここで Transient の値を設定し直します
}
// $value に対して処理を行います

上記のコードは Transient を取得し、$value に格納しています。if ブロック内のコードは、取得すべき有効な Transient がないときだけ実行されます。

保存された Transient を削除する

Transient は、最後に set_transient() /en を実行してから指定した秒数($expiration)が経過すると自動的に消滅します。しかし、手動で強制的に削除することもできます。これは指定した動作(投稿の保存、カテゴリーの追加など)に応じて Transient を更新するのに役立ちます。

delete_transient( $transient );
$transient 
(文字列) set_transient() で Transient を保存するときにつけたユニークな名前。

上の例で保存した $special_query_results を削除するには:

delete_transient( 'special_query_results' );

完全な例

上記の関数をすべて組み込んだ、Transient を利用するコードの例を示します。

<?php
// Transient データを取得する
if ( false === ( $special_query_results = get_transient( 'special_query_results' ) ) ) {
    // Transient データがなかったら、データを生成して保存する
    $special_query_results = new WP_Query( 'cat=5&order=random&tag=tech&post_meta_key=thumbnail' );
	set_transient( 'special_query_results', $special_query_results, 12 * HOUR_IN_SECONDS );
}

// データ $special_query_results を使います...
?>

delete_transient() /en を使った例も紹介します。この場合、edit_term /en アクションに関数を登録し、カテゴリーやタグが編集されたときに実行されるようにします(タームを編集することで保存したデータが無効になるので削除したい、と仮定します)。

<?php
// Transient を削除する関数を作成します
function edit_term_delete_transient() {
    delete_transient( 'special_query_results' );
}
// 関数を edit_term アクションにフックし、カテゴリーやタグが編集されたときに実行されるようにします
add_action( 'edit_term', 'edit_term_delete_transient' );
?>

最後の例は、Transient を WP_Query と組み合わせて「先頭固定表示の投稿」を取得します:

<?php 
// Transient をチェックして、無ければ WP_Query を実行
if ( false === ( $featured = get_transient( 'foo_featured_posts' ) ) ) {

    $featured = new WP_Query(
        array(
            'category' => 'featured',
            'posts_per_page' => 5
        ));
 
    // 結果を Transient へ保存。12 時間後に無効にする。
    set_transient( 'foo_featured_posts', $featured, 12 * HOUR_IN_SECONDS );
} ?>

// ふつうにループを回す
<?php if ( $featured->have_posts() ) : ?>

    <?php while ( $featured->have_posts() ) : $featured->the_post(); ?>
        // 先頭固定表示の投稿があったので、処理する(表示など)
    <?php endwhile; ?>

<?php else: ?>
    // 先頭固定表示の投稿がない場合
<?php endif; ?>
 
<?php wp_reset_postdata(); ?>

プラグインやテーマの中で Transient を使うためには数行のコードを追加するだけですが、適切な状況(データベース負荷の高いデータ検索や複雑なデータ処理)で使えば、サイトのロード時間を短縮することができます。

外部リソース

最新英語版: WordPress Codex » Transients API最新版との差分