set_transient() │ WP 2.8.0

Встановлює або оновлює часову опцію.

Якщо тимчасова опція, що записується, вже існує, то функція оновить час життя існуючої опції та її значення.

Тимчасові опції дають можливість стандартно і легко зберігати дані тимчасово базу даних (кешувати дані). Дані зберігаються у зазначену опцію, яка може називатися як завгодно і якій задається час життя, після якого опція буде видалена. Тимчасові опції ідентичні звичайним опціям WordPress. Відрізняються лише тим, що до тимчасових опцій додається час опції. Ці дані зберігаються в таблицю wp_options .

Якщо на сайті встановлено плагін об’єктного кешування , то тимчасові опції зберігатимуться в об’єктний кеш, а не таблицю wp_options . Дивіться: wp_cache_set()

Авто-завантаження опцій . Усі опції з прапором autoloadу таблиці wp_options запитуються одним запитом із БД і зберігаються у php масив (кеш). параметр $autoload в add_option() .

Однак, якщо для тимчасової опції встановлено параметр $expiration , то вона не завантажуватиметься автоматично в глобальний масив опцій і при її отриманні буде робитися 2 простих запити до БД: один на отримання самої опції, інший на отримання часу життя опції. Ця нотатка справедлива, якщо на сайті не встановлено об’єктне кешування.

WordPress зберігає час закінчення транзитної опції в окрему опцію з ім’ям (ключом):

_transient_timeout_{$transient}

У значенні буде зберігатися число – тимчасова мітка UNIX – це час, коли опція буде вважатися простроченою. Наприклад, число може мати такий вигляд 1636453079.

Серіалізувати значення опції не потрібно . Якщо значення має бути серіалізоване, це буде зроблено автоматично перед збереженням.

Видалення тимчасових опцій. WP видаляє їх автоматично після закінчення терміну давності. Для цього кроном запускається функція delete_expired_transients() .

Хуки з функції

pre_set_transient_(transient)

expiration_of_transient_(transient)

set_transient_(transient)

setted_transient

Повертає

true|false. true – тимчасова опція була збережена. false – опція не збережена.

Використання

set_transient ($ transient, $ value, $ expiration);

$transient (рядок) (обов’язковий)

Назва часової опції. Максимальна довжина 172 знаки. Очікуються дані з екранованими слешами, очищення слєшів робиться автоматично перед записом до БД. Функція автоматично захищає від ін’єкцій SQL.

$value (змішаний) (обов’язковий)

Значення часової опції. Очікуються дані з екранованими слешами, очищення слєшів робиться автоматично перед записом до БД. Функція захищає від ін’єкцій SQL. Серіалізація, якщо передається масив, також виконується автоматично.

$expiration (рядок/масив/число/об’єкт/логічний)

Час життя опції в секундах, починаючи з моменту. Наприклад, щоб записати опцію на день, потрібно вказати 60 * 60 * 24.

Якщо вказати 0 – опція ніколи не відійде і не матиме терміну давності. Виходить це буде звичайна опція, тільки з префіксом _transient_у її назві – це означатиме, що вона тимчасова і при чищенні таблиці wp_options її можна буде сміливо видаляти, без ризику, щось зіпсувати.

Для зручності в WordPress існують спеціальні константи часу :

MINUTE_IN_SECONDS– 60 (секунд)
HOUR_IN_SECONDS– 60*MINUTE_IN_SECONDS
DAY_IN_SECONDS– 24* HOUR_IN_SECONDS
WEEK_IN_SECONDS– 7 * DAY_IN_SECONDS
YEAR_IN_SECONDS– 365*DAY_IN_SECONDS

За замовчуванням: 0

Приклади

#1 Збережемо запит

Цей приклад показує, як зберегти результат складного SQL запиту у тимчасову опцію на 12 годин:

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

Далі, щоб отримати результат, використовуйте get_transient() .

#2 Збережемо запит на 5 останніх постів у транзитну опцію

У цьому прикладі показано, як отримати 5 останніх постів та зберегти результат на один день у тимчасову опцію.

// робимо запит
$latest_post = новий WP_Query( array(
	'post_type' => 'post',
	'posts_per_page' => 5,
	'orderby' => 'date',
	'order' => 'DESC'
)));

// Збережіть результати в транзитну опцію з ім'ям latest_5_posts
set_transient( 'latest_5_posts', $latest_post, DAY_IN_SECONDS );

Додаткові параметри для отримання постів див. у описі WP_Query .

#3 Час життя опції можна змінити лише вказавши третій параметр

Все, що описано нижче, справедливо тільки якщо не використовується зовнішній кеш об’єктів.

При використанні функції для оновлення вже існуючої часової опції, у якої ще не минув термін дії, відсутність третього параметра (значення терміну дії) збереже існуючий термін дії.

Наприклад:

$initial = time();
set_transient( 'foo', 'bar', 300);
sleep(10);
$update = time();
set_transient( 'foo', 'barbar');

У цьому випадку термін дії залишиться який був до цього $initial + 300(і не зміниться на time() + 300, або не буде видалений), тому що якщо не вказати параметр $expiration, то значення терміну дії ніяк не обробляється і залишиться тим, що було.

Будьте обережні, тому що ви можете ненавмисно встановити рівний час життя никогда не истекает, якщо термін дії закінчився і зроблений другий виклик без параметра $expiration.

список змін

З версії 2.8.0

Введено.

Код `set_transient() set transient` ^{WP 6.0.2}

wp-includes/option.php

function set_transient( $transient, $value, $expiration = 0 ) {

	$ expiration = (int) $ expiration;

	/**
	 * Filters a specific transient before its value is set.
	 *
	 * Dynamic port of the hook name, `$transient`, refers to the transient name.
	 *
	 * @ Since 3.0.0
	 * @since 4.2.0 The `$expiration` parameter was added.
	 * @since 4.4.0 The `$transient` parameter was added.
	 *
	 * @param mixed $value New value of transient.
	 * @param int $expiration Time until expiration in seconds.
	 * @param string $transient Transient name.
	 */
	$value = apply_filters( "pre_set_transient_{$transient}", $value, $expiration, $transient );

	/**
	 * Filters expiration for transient before its value is set.
	 *
	 * Dynamic port of the hook name, `$transient`, refers to the transient name.
	 *
	 * @ Since 4.4.0
	 *
	 * @param int $expiration Time until expiration in seconds. Use 0 for no expiration.
	 * @param mixed $value New value of transient.
	 * @param string $transient Transient name.
	 */
	$expiration = apply_filters( "expiration_of_transient_{$transient}", $expiration, $value, $transient );

	if ( wp_using_ext_object_cache() || wp_installing() ) {
		$result = wp_cache_set( $transient, $value, 'transient', $expiration );
	} else {
		$transient_timeout = '_transient_timeout_'. $transient;
		$transient_option = '_transient_'. $transient;

		if ( false === get_option( $transient_option ) ) {
			$autoload = 'yes';
			if ($ expiration) {
				$autoload = 'no';
				add_option( $transient_timeout, time() + $expiration, '', 'no' );
			}
			$result = add_option( $transient_option, $value, '', $autoload );
		} else {
			// If expiration is requested, but the transient has no timeout option,
			// delete, then re-create transient rather than update.
			$update = true;

			if ($ expiration) {
				if ( false === get_option( $transient_timeout ) ) {
					delete_option ($ transient_option);
					add_option( $transient_timeout, time() + $expiration, '', 'no' );
					$result = add_option( $transient_option, $value, '', 'no' );
					$update = false;
				} else {
					update_option( $transient_timeout, time() + $ expiration );
				}
			}

			if ($update) {
				$result = update_option( $transient_option, $ value );
			}
		}
	}

	if ($result) {

		/**
		 * Fires after the value for a specific transient has been set.
		 *
		 * Dynamic port of the hook name, `$transient`, refers to the transient name.
		 *
		 * @ Since 3.0.0
		 * @since 3.6.0 The `$value` and `$expiration` parameters були added.
		 * @since 4.4.0 The `$transient` parameter was added.
		 *
		 * @param mixed $value Transient value.
		 * @param int $expiration Time until expiration in seconds.
		 * @param string $transient Name of the transient.
		 */
		do_action( "set_transient_{$transient}", $value, $expiration, $transient);

		/**
		 * Fires after the value for a transient has been set.
		 *
		 * @ Since 3.0.0
		 * @since 3.6.0 The `$value` and `$expiration` parameters були added.
		 *
		 * @param string $transient Name of the transient.
		 * @param mixed $value Transient value.
		 * @param int $expiration Time until expiration in seconds.
		 */
		do_action( 'setted_transient', $transient, $value, $expiration);
	}

	return $result;
}