Хук add_action для абсолютно нового поста?

Я тщательно изучил ядро WordPress и перепробовал все возможные варианты. wp_transition_post_status(), new_to_publish(), new_{post_type}(), wp_insert_post().

Все эти методы, в конечном счете, ненадежны.

wp_transition_post_status() ненадежен, потому что новый статус "publish" является статусом по умолчанию как для создания новых записей, так и для обновления существующих. Старый статус также ненадежен для определения новой записи, так как он может быть draft, auto-draft, publish и т.д.

new_to_publish() не работает для пользовательских типов записей.

new_{post_type} передает только параметр $post, и невозможно определить, создается новая запись или обновляется существующая.

wp_insert_post() имеет параметр $update, который должен быть TRUE при обновлении существующих записей и FALSE при создании новых, но он ненадежен, так как возвращает TRUE для новых записей из-за auto-draft.

Решение: Использование метаполя записи

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

/**
*   Выполнить действие при создании новой книги
*/
function new_book($post_id, $post, $update) {
    if ( $post->post_type == 'book' && $post->post_status == 'publish' && empty(get_post_meta($post_id, 'check_if_run_once')) ) {
        # Новая запись

        # Выполнить действия здесь...

        # Обновить метаполе, чтобы код не выполнялся повторно
        update_post_meta( $post_id, 'check_if_run_once', true );
    }
}
add_action( 'wp_insert_post', 'new_book', 10, 3 );

Дополнительно, если вам нужно обновить существующие записи метаполем "check_if_run_once", чтобы код выше не выполнялся для записей, созданных до добавления этой функции, можно сделать следующее:

/**
*   Временная функция для обновления существующих записей метаполем "check_if_run_once"
*   Для использования войдите на сайт как администратор и добавьте ?debug к URL.
*/
function temporary_function() {
    if (current_user_can('manage_options')) {
        $posts = get_posts(array(
            'post_type' => 'book',
            'posts_per_page' => -1, // Возможно, потребуется пагинация в зависимости от количества записей
            'fields' => 'ids'
        ));
        foreach($posts as $post_id) {
            update_post_meta($post_id, 'check_if_run_once', true);
        }
    }
}
if (isset($_GET['debug'])) {
    add_action('init', 'temporary_function');
}

Точное отслеживание создания новой записи на самом деле сложнее, чем кажется. Технически существует несколько способов, которыми запись может быть создана или обновлена, а также множество не столь очевидных вещей, которые технически также являются записями (например, ревизии).

WordPress предоставляет динамические хуки, которые отслеживают не только создание записи, но и то, чем она была и чем стала. См. Переходы статусов записей в Кодексе.

Больше экспериментируя, чем следуя документации, я нашел рабочее решение (для WP 3.3). Хук transition_post_status срабатывает с параметром $new_status, установленным в "auto-draft", при создании нового поста.

function my_post_new($new_status, $old_status=null, $post=null){
    if ($new_status == "auto-draft"){
        // здесь выполняем нужные действия
    }
}
add_action('transition_post_status', 'my_post_new');

Я обнаружил, что лучшим вариантом будет проверять статус записи при вызове wp_insert_post.

Когда создаётся новая запись, её первоначальный статус — auto-draft.

if (!function_exists('benyonsFunction')) {
    function benyonsFunction($postId, $post) {
        if ($post->post_status == "auto-draft") {
            error_log('НОВАЯ ЗАПИСЬ!!!');
        }
    }
}

add_action('wp_insert_post', 'benyonsFunction', 10, 2);

Этот error_log сработает только один раз.

Наиболее чистый и надежный способ обработки этого для известного типа записи - использовать хук {$new_status}_{$post->post_type}, который предоставляет старый статус и сравнить его с "publish".

Например, если вы хотите выполнить действие при создании новой "страницы", вы должны использовать:

add_action( 'publish_page', function( int $post_id, \WP_Post $post, string $old_status ) {
    if ( 'publish' === $old_status ) {
        // Ничего делать не нужно.
        return;
    }
    // Здесь размещается бизнес-логика.
}, 10, 3 );