wp_transition_post_status()WP 2.3.0

Запускает хуки (события) для любых изменений статусов записей (с draft на publish, с publish на private и т.д.).

Эта функция вызывается в ядре WordPress из других функций, чтобы уведомить плагины, темы и функции ядра о смене статуса записи. А точнее, её ВСЕГДА вызывают wp_update_post(), wp_insert_post() и wp_publish_post().

wp_insert_post() вызывает этот хук всегда, когда создается или обновляется запись любого типа (кроме attachment).

Эта функция не меняет статус поста, она только вызывает хуки. Для реальной смены статуса поста, нужно обновить данные поста с помощью соответствующих функций: wp_update_post() или wp_publish_post().

Хуки, которые вызывает эта функция:

transition_post_status

Используйте когда нужно подключиться при любом изменении статуса.

do_action( 'transition_post_status', $new_status, $old_status, $post );
(old_status)_to_(new_status)

Используйте когда нужно подключиться при конкретных изменениях статуса (с одного на другой).

do_action( "{$old_status}_to_{$new_status}", $post );

Несколько полезных вариантов хука:

  • new_to_publish - при первой публикации новой записи, например если запись добавляется функцией wp_insert_post().
  • auto-draft_to_publish - при первой публикации новой записи из админки WP.
  • draft_to_publish - при публикации, сохраненной записи.
  • future_to_publish - при публикации запланированной записи.
(new_status)_(post_type)

Используйте когда нужно сделать что-либо для указанного статуса и типа поста.

do_action( "{$new_status}_{$post->post_type}", $post->ID, $post );

Несколько полезных вариантов хука:

  • publish_post - Позволяет сделать что-либо, когда пост (запись типа post) публикуется или обновляется. Срабатывает всегда когда создается/обновляется пост со статусом publish. Поэтому, если нужно делать что-либо один раз, только когда пост публикуется (а не обновляется), используйте хуки выше...

  • pending_post - срабатывает всякий раз когда создается/обновляется пост со статусом pending.

  • draft_post - срабатывает всякий раз когда создается/обновляется черновик - пост со статусом draft.
Список всех статусов, которые могут применяться в хуках:
  • new - если еще не было установленных никаких статусов.
  • publish - опубликованный пост (страница или тип записи).
  • pending - запись на рассмотрении перед публикацией.
  • draft - черновик записи.
  • auto-draft - только созданный пост, еще без заголовка, контента и другой информации.
  • future - запись запланированная к публикации в будущем.
  • private - запись не доступная не авторизованным пользователям.
  • inherit - ревизия или вложение (revision or attachment). Смотрите get_children().
  • trash - запись находящаяся в корзине.
Основа для: wp_publish_post()

Возвращает

null. Ничего не возвращает.

Использование

wp_transition_post_status( $new_status, $old_status, $post );
$new_status(строка) (обязательный)
Какой статус поста будет.
$old_status(строка) (обязательный)
Какой статус поста был.
$post(WP_Post) (обязательный)
Данные поста. Объект.

Примеры

0

#1 Посмотрим как работает функция

Для этого давайте взглянем на код функции wp_publish_post():

function wp_publish_post( $post ) {
	global $wpdb;

	if ( ! $post = get_post( $post ) )
		return;

	if ( 'publish' == $post->post_status )
		return;

	$wpdb->update( $wpdb->posts, array( 'post_status' => 'publish' ), array( 'ID' => $post->ID ) );

	clean_post_cache( $post->ID );

	$old_status = $post->post_status;
	$post->post_status = 'publish';

	// теперь, когда статус поста изменен, вызываем хуки,
	// к которым в последствии смогут подключится плагины, темы и другие функции.
	wp_transition_post_status( 'publish', $old_status, $post );

	do_action( 'edit_post', $post->ID, $post );

	do_action( "save_post_{$post->post_type}", $post->ID, $post, true );

	do_action( 'save_post', $post->ID, $post, true );

	do_action( 'wp_insert_post', $post->ID, $post, true );
}
0

#2 Использование хука {$old_status}_to_{$new_status}

Добавим действие, которое будет срабатывать при изменении статуса draft на publish - draft_to_publish, т.е. при публикации черновика.

add_action( 'draft_to_publish', function( $post ){
	// ваш код
} );

Если нужно подключится к моменту одобрения (pending) поста, то нужно использовать хук pending_to_publish.

0

#3 Использование хука transition_post_status

Это общий хук, срабатывает когда нам нужно подключиться в момент смены любого статуса на любой. Хук передает 3 параметра: $new_status, $old_status, $post.

Этот пример показывает как подключаться, когда статус поста меняется с publish на любой другой статус:

add_action( 'transition_post_status', 'post_unpublished', 10, 3 );
function post_unpublished( $new_status, $old_status, $post ) {
	if ( $old_status == 'publish' && $new_status != 'publish' ) {
		// Пост снят с публикации
	}
}
0

#4 Хук, срабатывающий при любой смене статуса

add_action( 'transition_post_status', 'intercept_all_status_changes', 10, 3 );
function intercept_all_status_changes( $new_status, $old_status, $post ) {
	if ( $new_status != $old_status ) {
		// Статус поста изменен
	}
}
0

#5 Использование хука {$new_status}_{$post->post_type}

Если нужно подключиться к текущему статусу, независимо от того какой был статус до этого используем конструкцию: СТАТУС_ТИПЗАПИСИ.

Например, если нужно что-то сделать когда пост со статусом publish публикуется или обновляется, то конструкция будет выглядеть так publish_post:

add_action( 'publish_post', 'publish_post_action', 10, 2 );
function publish_post_action( $post_id, $post ){
	// делаем что-то при публикации поста
}

Обратите внимание, что этот хук будет срабатывать и при обновлении записи, если при обновлении статус указан publish или если статус не был указан, но при этом до этого он был publish.

Список изменений

С версии 2.3.0 Введена.

Код wp_transition_post_status() WP 6.1.1

function wp_transition_post_status( $new_status, $old_status, $post ) {
	/**
	 * Fires when a post is transitioned from one status to another.
	 *
	 * @since 2.3.0
	 *
	 * @param string  $new_status New post status.
	 * @param string  $old_status Old post status.
	 * @param WP_Post $post       Post object.
	 */
	do_action( 'transition_post_status', $new_status, $old_status, $post );

	/**
	 * Fires when a post is transitioned from one status to another.
	 *
	 * The dynamic portions of the hook name, `$new_status` and `$old_status`,
	 * refer to the old and new post statuses, respectively.
	 *
	 * Possible hook names include:
	 *
	 *  - `draft_to_publish`
	 *  - `publish_to_trash`
	 *  - `pending_to_draft`
	 *
	 * @since 2.3.0
	 *
	 * @param WP_Post $post Post object.
	 */
	do_action( "{$old_status}_to_{$new_status}", $post );

	/**
	 * Fires when a post is transitioned from one status to another.
	 *
	 * The dynamic portions of the hook name, `$new_status` and `$post->post_type`,
	 * refer to the new post status and post type, respectively.
	 *
	 * Possible hook names include:
	 *
	 *  - `draft_post`
	 *  - `future_post`
	 *  - `pending_post`
	 *  - `private_post`
	 *  - `publish_post`
	 *  - `trash_post`
	 *  - `draft_page`
	 *  - `future_page`
	 *  - `pending_page`
	 *  - `private_page`
	 *  - `publish_page`
	 *  - `trash_page`
	 *  - `publish_attachment`
	 *  - `trash_attachment`
	 *
	 * Please note: When this action is hooked using a particular post status (like
	 * 'publish', as `publish_{$post->post_type}`), it will fire both when a post is
	 * first transitioned to that status from something else, as well as upon
	 * subsequent post updates (old and new status are both the same).
	 *
	 * Therefore, if you are looking to only fire a callback when a post is first
	 * transitioned to a status, use the {@see 'transition_post_status'} hook instead.
	 *
	 * @since 2.3.0
	 * @since 5.9.0 Added `$old_status` parameter.
	 *
	 * @param int     $post_id    Post ID.
	 * @param WP_Post $post       Post object.
	 * @param string  $old_status Old post status.
	 */
	do_action( "{$new_status}_{$post->post_type}", $post->ID, $post, $old_status );
}