Determine if, within a post, you are on page 2 or greater - Wordpress documentation circular

Question

I am trying to run a function that executes only on the first page of any post. So, if a post is paginated because you have used the <!--nextpage--> tag and you are on page 2 or greater of that article, then the function should not run.

Even the Wordpress documentation is confused how to do this:

When the page being displayed is "paged". This refers to an archive or the main page being split up over several pages and will return true on 2nd and subsequent pages of posts. This does not refer to a Post or Page whose content has been divided into pages using the nextpage QuickTag. To check if a Post or Page has been divided into pages using the nextpage QuickTag, see A_Paged_Page section.

Further details:

I currently use the following code in my functions.php to move my featured image within posts from the default position above the first paragraph and below the title, to underneath the first paragraph.

The problem is that it also shows the featured image, in the same spot, on pages 2, 3, 4, etc of the same article (when I have used <!--nextpage-->). The featured image should only show on the first page of any article.

add_filter( 'the_content', 'insert_feat_image', 20 );
function insert_feat_image( $content ) {
if (!is_single(array(xxxxx))) {
  global $post;
  if (has_post_thumbnail($post->ID)) {
    $caption = 'xxxx';
    $img = 'xxx';
    $content = xxx;
  }
  return $content;
}  else {
    $contentnormal = preg_replace('#(<p>.*?</p>)#','$1'.$img . $caption, $content, 1);}
     return $contentnormal;
}

I removed some potentially identifying code that is not relevant to this question (xxx).

Answer 1

The problem is that it also shows the featured image, in the same spot, on pages 2, 3, 4, etc of the same article (when I have used <!--nextpage-->). The featured image should only show on the first page of any article.

In that case, then this might work for you:

function insert_feat_image( $content ) {
    global $page, $multipage;

    if ( $multipage && $page <= 1 ) {
        // it's the 1st page, so run your code here.
    } // else, it's not paginated or not the 1st page

    return $content;
}

Explanation about the global variables above:

1. $multipage is a boolean flag indicating whether the page/post is paginated using the <!--nextpage--> tag (or the Page Break block in Gutenberg), and the flag would be a true, as long as the post contains the <!--nextpage--> tag and that the global post data has already been setup, e.g. the_post() or setup_postdata() has been called. (which is true when inside The Loop)

2. The page number is stored in $page, but the number can also be retrieved using get_query_var( 'page' ). (yes, it's page and not paged)

Alternate Solution

If you just wanted to know whether it's the first page or not, regardless how the page/post was paginated (and only if it was paginated or in the case of archives, it means there are more than one page of results), you can try this instead which should work on any pages (single Post/Page/CPT, category archives, search results pages, etc.):

function insert_feat_image( $content ) {
    global $page, $multipage, $paged, $wp_query;

    $page_num = max( 1, $page, $paged );
    /* Or you can use:
    $page_num = max( 1, get_query_var( 'page' ), get_query_var( 'paged' ) );
    */

    if ( ( $multipage || $wp_query->max_num_pages > 1 ) && $page_num <= 1 ) {
        // it's the 1st page, so run your code here.
    } // else, it's not paginated or not the 1st page

    return $content;
}

Answer 2

If you are trying to determine if a singular single.php post page is on a paged() page number then this will require a little more logic.

But if you are simply trying execute a function if a post is on an archive page one... then this should be pretty straight forward doing this...

<?=
// args
$args = [
  'post_type' => 'post',
  'posts_per_page' => 10,
  'paged' => get_query_var('paged') ? absint(get_query_var('paged')) : 1
];

// setup query
$query = new WP_Query($args);

This will detect what page your are on with above query...

<?php

// if above query page number is 1
if($query['paged'] === 1 ) {

  // do stuff

}

Hopefully makes sense. Let me know if not.