Gancho add_action para publicaciones completamente nuevas

He leído extensamente el núcleo de WordPress y lo he probado todo. wp_transition_post_status(), new_to_publish(), new_{post_type}(), wp_insert_post().

Todos estos resultan, al final, poco confiables.

wp_transition_post_status() no es confiable porque el nuevo estado "publish" es el estado predeterminado tanto para crear nuevas publicaciones como para actualizar las existentes. El estado anterior no es confiable para definir qué es una nueva publicación y qué no, ya que puede ser draft, auto-draft, publish, etc.

new_to_publish() no funciona para tipos de publicaciones personalizados.

new_{post_type} solo pasa $post como parámetro, y no puedes saber si es nuevo o si se está actualizando uno existente.

wp_insert_post() tiene un parámetro $update que debería ser TRUE al actualizar publicaciones existentes y FALSE al crear nuevas, pero no es confiable porque devuelve TRUE para nuevas publicaciones debido a auto-draft.

Solución: Usar un post meta

Terminé usando un post meta personalizado al que llamé check_if_run_once que ejecutará cierta lógica solo una vez:

/**
*   Hacer algo cuando se crea un nuevo libro
*/
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')) ) {
        # Nueva Publicación

        # Hacer algo aquí...

        # Y actualizar el meta para que no se ejecute nuevamente
        update_post_meta( $post_id, 'check_if_run_once', true );
    }
}
add_action( 'wp_insert_post', 'new_book', 10, 3 );

Opcionalmente, si necesitas actualizar tus publicaciones existentes con el meta "check_if_run_once", para que no ejecute el código anterior en publicaciones existentes creadas antes de agregar esa función, podrías hacer:

/**
*   Esta es una función temporal para actualizar publicaciones existentes con el post meta "check_if_run_once"
*   Accede a tu sitio web iniciado sesión como administrador y agrega ?debug a la URL.
*/
function temporary_function() {
    if (current_user_can('manage_options')) {
        $posts = get_posts(array(
            'post_type' => 'book',
            'posts_per_page' => -1, // Puede que necesites paginar esto dependiendo de cuántas publicaciones tengas
            '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');
}

Dirigir con precisión la creación de una nueva entrada es en realidad más complicado de lo que parece. Técnicamente hay múltiples formas en que una entrada puede crearse o actualizarse, y hay muchas cosas no tan obvias que técnicamente también son entradas (como las revisiones, por ejemplo).

WordPress proporciona hooks dinámicos que rastrean no solo la creación de entradas, sino también qué era antes y en qué se convirtió. Consulta Transiciones de Estado de Entradas en el Codex.

Más por experimentación que siguiendo la documentación, esto funciona para mí (WP 3.3). Obtengo una llamada al hook transition_post_status con $new_status establecido como "auto-draft" cuando creas una nueva entrada.

function my_post_new($new_status, $old_status=null, $post=null){
    if ($new_status == "auto-draft"){
        // hacer cosas aquí
    }
}
add_action('transition_post_status', 'my_post_new');

Encontré que la mejor opción era verificar el estado de la publicación cuando se llama a wp_insert_post.

Cuando se crea una nueva publicación, el estado inicial es auto-draft.

if (!function_exists('benyonsFunction')) {
    function benyonsFunction($postId, $post) {
        if ($post->post_status == "auto-draft") {
            error_log('¡¡¡NUEVA PUBLICACIÓN!!!');
        }
    }
}

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

Este error_log solo se ejecutará una vez.

La forma más limpia y confiable de manejar esto para un tipo de publicación conocido es usar el hook {$new_status}_{$post->post_type} que proporciona el estado anterior y compararlo con "publish".

Por ejemplo, si quisieras activar una acción cuando se crea una nueva "página", usarías:

add_action( 'publish_page', function( int $post_id, \WP_Post $post, string $old_status ) {
    if ( 'publish' === $old_status ) {
        // Nada que hacer aquí.
        return;
    }
    // Aquí va la lógica de negocio.
}, 10, 3 );