WordPressプラグインでトランジェント（Transients API）を使う方法（set_transient・削除・WP-CLI）

Transients API（トランジェント）は、外部APIの応答や重いデータベースの問い合わせ結果を、有効期限つきで保存しておく WordPress の仕組みです。set_transient() で保存し、get_transient() で取り出し、delete_transient() で消します。毎回の処理を省けるので、ページの表示や外部サービスへの負荷を減らせます。

この記事のコードは、2026年11月時点の WordPress 7.1 と WP-CLI 2.12 で動作を確かめています。

基本の使い方

<?php
// 保存（名前・値・有効期限の秒数）
set_transient( 'myplugin_key', $data, HOUR_IN_SECONDS );

// 取り出し（無い・期限切れのときは false）
$data = get_transient( 'myplugin_key' );

// 削除
delete_transient( 'myplugin_key' );

押さえておく点は次のとおりです。

• 名前は172文字以内にします。ほかのプラグインと重ならないよう、myplugin_ のような接頭辞を付けます。
• 値には配列やオブジェクトも渡せます（自動でシリアライズされます）。
• 有効期限が切れた、または存在しないときは get_transient() が false を返します。そのため false そのものを値として保存すると、キャッシュがあるのか無いのか区別できません。
• トランジェントは「期限まで残っているとは限らない」キャッシュです。期限前に消えることがあるので、消えても作り直せるデータだけを入れます。

外部APIの結果をキャッシュする

WordPress.org の API から最新の WordPress のバージョンを取得し、12時間キャッシュする例です。プラグインのファイルに書いて使います。

<?php
/**
 * WordPress.org の API から最新の WordPress のバージョンを取得する（12時間キャッシュ）
 */
function myplugin_get_latest_wp_version() {
	$cache_key = 'myplugin_latest_wp_version';

	// キャッシュがあればそれを返す
	$cached = get_transient( $cache_key );
	if ( false !== $cached ) {
		return $cached;
	}

	$response = wp_remote_get(
		'https://api.wordpress.org/core/version-check/1.7/',
		array( 'timeout' => 10 )
	);

	// 失敗したときはキャッシュしない
	if ( is_wp_error( $response ) || 200 !== wp_remote_retrieve_response_code( $response ) ) {
		return '';
	}

	$data    = json_decode( wp_remote_retrieve_body( $response ), true );
	$version = $data['offers'][0]['version'] ?? '';

	if ( '' !== $version ) {
		set_transient( $cache_key, $version, 12 * HOUR_IN_SECONDS );
	}

	return $version;
}

試したところ、1回目は API への問い合わせで約0.6秒かかり、2回目以降はキャッシュから即座に返りました。

通信の失敗やエラー応答をそのままキャッシュすると、期限が切れるまで誤った結果を返し続けます。この例のように、成功したときだけ保存してください。

重いクエリの結果をキャッシュし、更新時に消す

閲覧数のカスタムフィールド（ここでは _myplugin_views）で並べた人気記事のIDを、6時間キャッシュする例です。投稿を保存・削除したときはキャッシュを消し、次に呼ばれたときに作り直します。

<?php
/**
 * 閲覧数（カスタムフィールド _myplugin_views）の多い投稿のIDを返す（6時間キャッシュ）
 */
function myplugin_get_popular_post_ids( $limit = 10 ) {
	$limit     = absint( $limit );
	$cache_key = 'myplugin_popular_' . $limit;

	$ids = get_transient( $cache_key );
	if ( false !== $ids ) {
		return $ids;
	}

	$ids = get_posts(
		array(
			'post_type'      => 'post',
			'post_status'    => 'publish',
			'posts_per_page' => $limit,
			'meta_key'       => '_myplugin_views',
			'orderby'        => 'meta_value_num',
			'order'          => 'DESC',
			'fields'         => 'ids',
			'no_found_rows'  => true,
		)
	);

	// 結果が0件でも空の配列として保存される（false ではないのでキャッシュとして使える）
	set_transient( $cache_key, $ids, 6 * HOUR_IN_SECONDS );

	return $ids;
}

// 投稿を保存・削除したらキャッシュを消す
function myplugin_flush_popular_cache( $post_id ) {
	if ( wp_is_post_revision( $post_id ) || wp_is_post_autosave( $post_id ) ) {
		return;
	}
	foreach ( array( 5, 10, 20 ) as $limit ) {
		delete_transient( 'myplugin_popular_' . $limit );
	}
}
add_action( 'save_post_post', 'myplugin_flush_popular_cache' );
add_action( 'deleted_post', 'myplugin_flush_popular_cache' );

キャッシュするのは投稿オブジェクトではなくIDの配列にしています。保存するデータが小さくなり、表示するときは最新のタイトルなどを取り直せます。

名前の先頭が同じトランジェントをまとめて消す

名前に引数などを含めていて、消す対象の名前をすべて書き出せない場合は、データベースから接頭辞で消す方法があります。トランジェントは wp_options テーブルに _transient_名前 と _transient_timeout_名前（有効期限）の2行で保存されているので、両方を消します。

<?php
/**
 * 名前が $prefix で始まるトランジェントをデータベースからまとめて消す
 * （外部オブジェクトキャッシュを使っている環境では効かない）
 */
function myplugin_delete_transients_by_prefix( $prefix ) {
	global $wpdb;

	if ( wp_using_ext_object_cache() ) {
		return 0;
	}

	return $wpdb->query(
		$wpdb->prepare(
			"DELETE FROM {$wpdb->options} WHERE option_name LIKE %s OR option_name LIKE %s",
			$wpdb->esc_like( '_transient_' . $prefix ) . '%',
			$wpdb->esc_like( '_transient_timeout_' . $prefix ) . '%'
		)
	);
}

データベースを直接変更するため、同じリクエストの中では WordPress の内部キャッシュに古い値が残っていることがあります（試したところ、削除した直後の get_transient() は古い値を返し、次のリクエストでは false になりました）。

有効期限に使える定数

有効期限は秒数で指定します。WordPress には次の定数があります。

有効期限に 0 を指定すると期限なしになります。期限なしのトランジェントは、ページを開くたびに読み込まれる自動読み込み（autoload）の対象になります。期限つきのものは自動読み込みされません。大きなデータを期限なしで保存すると、全ページの読み込みが重くなるので避けてください。

期限切れのトランジェントはいつ消えるか

データベースに保存されたトランジェントは、期限が切れてもすぐには消えません。

• 期限切れのトランジェントを get_transient() で読もうとしたときに、その場で削除されます。
• WordPress は1日1回の WP-Cron イベント delete_expired_transients で、期限切れのトランジェントをまとめて削除します（このイベントは管理画面を開いたときに登録されます）。

オブジェクトキャッシュとの関係

Redis や Memcached などの永続オブジェクトキャッシュ（object-cache.php ドロップイン）を入れている環境では、トランジェントはデータベースではなくオブジェクトキャッシュに保存されます。コードを変える必要はありませんが、次の点が変わります。

• wp_options テーブルにトランジェントの行ができないので、前述の接頭辞での削除は効きません。
• キャッシュサーバーの容量が足りなくなると、期限前に消えることがあります。

どちらに保存されているかは、WP-CLI の wp transient type で確認できます。

wp_cache_get()・wp_cache_set() を直接使う方法もあります。永続オブジェクトキャッシュが無い環境では、wp_cache_set() で保存した値はそのリクエストの間しか残りません。リクエストをまたいで残したい値はトランジェントを使い、1回のリクエストの中で同じ処理を繰り返さないためのキャッシュには wp_cache_* を使う、と使い分けます。

WP-CLIでトランジェントを確認・削除する

# 保存先（データベースかオブジェクトキャッシュか）を確認
wp transient type

# 名前で絞り込んで一覧（有効期限を読みやすく表示）
wp transient list --search='myplugin_*' --human-readable

# 値を取得・保存・削除
wp transient get myplugin_latest_wp_version
wp transient set myplugin_test_key "test" 3600
wp transient delete myplugin_test_key

# 期限切れのトランジェントをまとめて削除
wp transient delete --expired

# すべてのトランジェントを削除
wp transient delete --all

外部オブジェクトキャッシュを使っている環境では、wp transient list や wp transient delete --all はデータベースに保存されたものしか対象にしない、という警告が出ます。その場合、オブジェクトキャッシュ側のトランジェントを消すには wp cache flush でキャッシュ全体を消去します。

関連記事

• オブジェクトキャッシュとトランジェントの違い
• WordPressのトランジェントを削除する方法
• WordPressでMemcachedを使う設定