Deprecate is_main_query()

[ethitter]

The function is_main_query() is misleading, and rather useless. In practical situations, it is necessary to reference the method in the current query object, such as when used at the pre_get_posts action.

The example in the Codex is even wrong:

  add_action( 'pre_get_posts', 'foo_modify_query_exclude_category' );

  function foo_modify_query_exclude_category( $query ) {
      if ( ! is_admin() && is_main_query() && ! $query->get( 'cat' ) )
          $query->set( 'cat', '-5' );
  }

I propose deprecating the function as an encouragement for users to refer to the query object method instead.

Also suggested in ticket:13961:29.

Corrected the Codex example.

Originally, ​http://developer.wordpress.com/2012/05/14/querying-posts-without-query_posts/ used the function rather than the method. When I protested, JJJ came up with a fairly good explanation for why using the function actually made more sense in that situation. I disagreed, but it wasn't edited tat the time. It has since been changed.

I kick myself for introducing the function. I really do. It had its purpose, to be a compliment to a WP_Query method the same way a function like is_author() is.

It also does have a legitimate use. It means, simply: "Is $wp_query the main query?" This is false whenever query_posts() gets used. Given this function's purpose was to go up against query_posts(), it seemed like it could be useful. I didn't realize at the time how easily it'd be abused.

It is worth noting that we could actually detect, inside is_main_query(), if pre_get_posts is the current hook. We could even go so far — not easily, but it is possible — to forcibly call the method on the query object when the function is summoned inside pre_get_posts. That's going overboard, but still, it's possible.

I don't entirely see what benefit deprecating this function will have. Maybe just a _doing_it_wrong() when used inside pre_get_posts.

This is an okay function with a unique use case.

Like nacin noted, is_main_query() is explicitly intended to answer the question: "is the current global $wp_query object the one that WordPress created in the main query loop, or is it otherwise altered?"

People misusing it isn't the reason to deprecate it (I.E. query_posts()) -- neither is being able to use it out of order (I.E. current_user_can() before $wp->init()).

Better error-handing/developer-feedback when misusing functions is great, but is_main_query() isn't any worse than query_posts() in this regard.

If the day ever comes where we deprecate query_posts(), we would want to deprecate is_main_query() at the same time. Without query_posts() there's no natural way in WordPress core to stomp the main query.

Okay, nacin and johnjamesjacoby made good points, so _doing_it_wrong() seems like a better idea to me.

I've added a new patch that reflects this, taking nacin's recommended approach of checking the current action; the wording could probably use some work.