[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

title

Body

[close]

/wp-includes/ -> query.php (source)

   1  <?php
   2  /**
   3   * WordPress Query API
   4   *
   5   * The query API attempts to get which part of WordPress the user is on. It
   6   * also provides functionality for getting URL query information.
   7   *
   8   * @link https://codex.wordpress.org/The_Loop More information on The Loop.
   9   *
  10   * @package WordPress
  11   * @subpackage Query
  12   */
  13  
  14  /**
  15   * Retrieve variable in the WP_Query class.
  16   *
  17   * @since 1.5.0
  18   * @since 3.9.0 The `$default` argument was introduced.
  19   *
  20   * @global WP_Query $wp_query Global WP_Query instance.
  21   *
  22   * @param string $var       The variable key to retrieve.
  23   * @param mixed  $default   Optional. Value to return if the query variable is not set. Default empty.
  24   * @return mixed Contents of the query variable.
  25   */
  26  function get_query_var( $var, $default = '' ) {
  27      global $wp_query;
  28      return $wp_query->get( $var, $default );
  29  }
  30  
  31  /**
  32   * Retrieve the currently-queried object.
  33   *
  34   * Wrapper for WP_Query::get_queried_object().
  35   *
  36   * @since 3.1.0
  37   *
  38   * @global WP_Query $wp_query Global WP_Query instance.
  39   *
  40   * @return object Queried object.
  41   */
  42  function get_queried_object() {
  43      global $wp_query;
  44      return $wp_query->get_queried_object();
  45  }
  46  
  47  /**
  48   * Retrieve ID of the current queried object.
  49   *
  50   * Wrapper for WP_Query::get_queried_object_id().
  51   *
  52   * @since 3.1.0
  53   *
  54   * @global WP_Query $wp_query Global WP_Query instance.
  55   *
  56   * @return int ID of the queried object.
  57   */
  58  function get_queried_object_id() {
  59      global $wp_query;
  60      return $wp_query->get_queried_object_id();
  61  }
  62  
  63  /**
  64   * Set query variable.
  65   *
  66   * @since 2.2.0
  67   *
  68   * @global WP_Query $wp_query Global WP_Query instance.
  69   *
  70   * @param string $var   Query variable key.
  71   * @param mixed  $value Query variable value.
  72   */
  73  function set_query_var( $var, $value ) {
  74      global $wp_query;
  75      $wp_query->set( $var, $value );
  76  }
  77  
  78  /**
  79   * Sets up The Loop with query parameters.
  80   *
  81   * Note: This function will completely override the main query and isn't intended for use
  82   * by plugins or themes. Its overly-simplistic approach to modifying the main query can be
  83   * problematic and should be avoided wherever possible. In most cases, there are better,
  84   * more performant options for modifying the main query such as via the {@see 'pre_get_posts'}
  85   * action within WP_Query.
  86   *
  87   * This must not be used within the WordPress Loop.
  88   *
  89   * @since 1.5.0
  90   *
  91   * @global WP_Query $wp_query Global WP_Query instance.
  92   *
  93   * @param array|string $query Array or string of WP_Query arguments.
  94   * @return array List of post objects.
  95   */
  96  function query_posts( $query ) {
  97      $GLOBALS['wp_query'] = new WP_Query();
  98      return $GLOBALS['wp_query']->query( $query );
  99  }
 100  
 101  /**
 102   * Destroys the previous query and sets up a new query.
 103   *
 104   * This should be used after query_posts() and before another query_posts().
 105   * This will remove obscure bugs that occur when the previous WP_Query object
 106   * is not destroyed properly before another is set up.
 107   *
 108   * @since 2.3.0
 109   *
 110   * @global WP_Query $wp_query     Global WP_Query instance.
 111   * @global WP_Query $wp_the_query Copy of the global WP_Query instance created during wp_reset_query().
 112   */
 113  function wp_reset_query() {
 114      $GLOBALS['wp_query'] = $GLOBALS['wp_the_query'];
 115      wp_reset_postdata();
 116  }
 117  
 118  /**
 119   * After looping through a separate query, this function restores
 120   * the $post global to the current post in the main query.
 121   *
 122   * @since 3.0.0
 123   *
 124   * @global WP_Query $wp_query Global WP_Query instance.
 125   */
 126  function wp_reset_postdata() {
 127      global $wp_query;
 128  
 129      if ( isset( $wp_query ) ) {
 130          $wp_query->reset_postdata();
 131      }
 132  }
 133  
 134  /*
 135   * Query type checks.
 136   */
 137  
 138  /**
 139   * Determines whether the query is for an existing archive page.
 140   *
 141   * Month, Year, Category, Author, Post Type archive...
 142   *
 143   * For more information on this and similar theme functions, check out
 144   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 145   * Conditional Tags} article in the Theme Developer Handbook.
 146   *
 147   * @since 1.5.0
 148   *
 149   * @global WP_Query $wp_query Global WP_Query instance.
 150   *
 151   * @return bool
 152   */
 153  function is_archive() {
 154      global $wp_query;
 155  
 156      if ( ! isset( $wp_query ) ) {
 157          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 158          return false;
 159      }
 160  
 161      return $wp_query->is_archive();
 162  }
 163  
 164  /**
 165   * Determines whether the query is for an existing post type archive page.
 166   *
 167   * For more information on this and similar theme functions, check out
 168   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 169   * Conditional Tags} article in the Theme Developer Handbook.
 170   *
 171   * @since 3.1.0
 172   *
 173   * @global WP_Query $wp_query Global WP_Query instance.
 174   *
 175   * @param string|array $post_types Optional. Post type or array of posts types to check against.
 176   * @return bool
 177   */
 178  function is_post_type_archive( $post_types = '' ) {
 179      global $wp_query;
 180  
 181      if ( ! isset( $wp_query ) ) {
 182          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 183          return false;
 184      }
 185  
 186      return $wp_query->is_post_type_archive( $post_types );
 187  }
 188  
 189  /**
 190   * Determines whether the query is for an existing attachment page.
 191   *
 192   * For more information on this and similar theme functions, check out
 193   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 194   * Conditional Tags} article in the Theme Developer Handbook.
 195   *
 196   * @since 2.0.0
 197   *
 198   * @global WP_Query $wp_query Global WP_Query instance.
 199   *
 200   * @param int|string|array|object $attachment Attachment ID, title, slug, or array of such.
 201   * @return bool
 202   */
 203  function is_attachment( $attachment = '' ) {
 204      global $wp_query;
 205  
 206      if ( ! isset( $wp_query ) ) {
 207          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 208          return false;
 209      }
 210  
 211      return $wp_query->is_attachment( $attachment );
 212  }
 213  
 214  /**
 215   * Determines whether the query is for an existing author archive page.
 216   *
 217   * If the $author parameter is specified, this function will additionally
 218   * check if the query is for one of the authors specified.
 219   *
 220   * For more information on this and similar theme functions, check out
 221   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 222   * Conditional Tags} article in the Theme Developer Handbook.
 223   *
 224   * @since 1.5.0
 225   *
 226   * @global WP_Query $wp_query Global WP_Query instance.
 227   *
 228   * @param mixed $author Optional. User ID, nickname, nicename, or array of User IDs, nicknames, and nicenames
 229   * @return bool
 230   */
 231  function is_author( $author = '' ) {
 232      global $wp_query;
 233  
 234      if ( ! isset( $wp_query ) ) {
 235          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 236          return false;
 237      }
 238  
 239      return $wp_query->is_author( $author );
 240  }
 241  
 242  /**
 243   * Determines whether the query is for an existing category archive page.
 244   *
 245   * If the $category parameter is specified, this function will additionally
 246   * check if the query is for one of the categories specified.
 247   *
 248   * For more information on this and similar theme functions, check out
 249   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 250   * Conditional Tags} article in the Theme Developer Handbook.
 251   *
 252   * @since 1.5.0
 253   *
 254   * @global WP_Query $wp_query Global WP_Query instance.
 255   *
 256   * @param mixed $category Optional. Category ID, name, slug, or array of Category IDs, names, and slugs.
 257   * @return bool
 258   */
 259  function is_category( $category = '' ) {
 260      global $wp_query;
 261  
 262      if ( ! isset( $wp_query ) ) {
 263          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 264          return false;
 265      }
 266  
 267      return $wp_query->is_category( $category );
 268  }
 269  
 270  /**
 271   * Determines whether the query is for an existing tag archive page.
 272   *
 273   * If the $tag parameter is specified, this function will additionally
 274   * check if the query is for one of the tags specified.
 275   *
 276   * For more information on this and similar theme functions, check out
 277   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 278   * Conditional Tags} article in the Theme Developer Handbook.
 279   *
 280   * @since 2.3.0
 281   *
 282   * @global WP_Query $wp_query Global WP_Query instance.
 283   *
 284   * @param mixed $tag Optional. Tag ID, name, slug, or array of Tag IDs, names, and slugs.
 285   * @return bool
 286   */
 287  function is_tag( $tag = '' ) {
 288      global $wp_query;
 289  
 290      if ( ! isset( $wp_query ) ) {
 291          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 292          return false;
 293      }
 294  
 295      return $wp_query->is_tag( $tag );
 296  }
 297  
 298  /**
 299   * Determines whether the query is for an existing custom taxonomy archive page.
 300   *
 301   * If the $taxonomy parameter is specified, this function will additionally
 302   * check if the query is for that specific $taxonomy.
 303   *
 304   * If the $term parameter is specified in addition to the $taxonomy parameter,
 305   * this function will additionally check if the query is for one of the terms
 306   * specified.
 307   *
 308   * For more information on this and similar theme functions, check out
 309   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 310   * Conditional Tags} article in the Theme Developer Handbook.
 311   *
 312   * @since 2.5.0
 313   *
 314   * @global WP_Query $wp_query Global WP_Query instance.
 315   *
 316   * @param string|array     $taxonomy Optional. Taxonomy slug or slugs.
 317   * @param int|string|array $term     Optional. Term ID, name, slug or array of Term IDs, names, and slugs.
 318   * @return bool True for custom taxonomy archive pages, false for built-in taxonomies (category and tag archives).
 319   */
 320  function is_tax( $taxonomy = '', $term = '' ) {
 321      global $wp_query;
 322  
 323      if ( ! isset( $wp_query ) ) {
 324          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 325          return false;
 326      }
 327  
 328      return $wp_query->is_tax( $taxonomy, $term );
 329  }
 330  
 331  /**
 332   * Determines whether the query is for an existing date archive.
 333   *
 334   * For more information on this and similar theme functions, check out
 335   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 336   * Conditional Tags} article in the Theme Developer Handbook.
 337   *
 338   * @since 1.5.0
 339   *
 340   * @global WP_Query $wp_query Global WP_Query instance.
 341   *
 342   * @return bool
 343   */
 344  function is_date() {
 345      global $wp_query;
 346  
 347      if ( ! isset( $wp_query ) ) {
 348          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 349          return false;
 350      }
 351  
 352      return $wp_query->is_date();
 353  }
 354  
 355  /**
 356   * Determines whether the query is for an existing day archive.
 357   *
 358   * A conditional check to test whether the page is a date-based archive page displaying posts for the current day.
 359   *
 360   * For more information on this and similar theme functions, check out
 361   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 362   * Conditional Tags} article in the Theme Developer Handbook.
 363   *
 364   * @since 1.5.0
 365   *
 366   * @global WP_Query $wp_query Global WP_Query instance.
 367   *
 368   * @return bool
 369   */
 370  function is_day() {
 371      global $wp_query;
 372  
 373      if ( ! isset( $wp_query ) ) {
 374          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 375          return false;
 376      }
 377  
 378      return $wp_query->is_day();
 379  }
 380  
 381  /**
 382   * Determines whether the query is for a feed.
 383   *
 384   * For more information on this and similar theme functions, check out
 385   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 386   * Conditional Tags} article in the Theme Developer Handbook.
 387   *
 388   * @since 1.5.0
 389   *
 390   * @global WP_Query $wp_query Global WP_Query instance.
 391   *
 392   * @param string|array $feeds Optional feed types to check.
 393   * @return bool
 394   */
 395  function is_feed( $feeds = '' ) {
 396      global $wp_query;
 397  
 398      if ( ! isset( $wp_query ) ) {
 399          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 400          return false;
 401      }
 402  
 403      return $wp_query->is_feed( $feeds );
 404  }
 405  
 406  /**
 407   * Is the query for a comments feed?
 408   *
 409   * @since 3.0.0
 410   *
 411   * @global WP_Query $wp_query Global WP_Query instance.
 412   *
 413   * @return bool
 414   */
 415  function is_comment_feed() {
 416      global $wp_query;
 417  
 418      if ( ! isset( $wp_query ) ) {
 419          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 420          return false;
 421      }
 422  
 423      return $wp_query->is_comment_feed();
 424  }
 425  
 426  /**
 427   * Determines whether the query is for the front page of the site.
 428   *
 429   * This is for what is displayed at your site's main URL.
 430   *
 431   * Depends on the site's "Front page displays" Reading Settings 'show_on_front' and 'page_on_front'.
 432   *
 433   * If you set a static page for the front page of your site, this function will return
 434   * true when viewing that page.
 435   *
 436   * Otherwise the same as @see is_home()
 437   *
 438   * For more information on this and similar theme functions, check out
 439   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 440   * Conditional Tags} article in the Theme Developer Handbook.
 441   *
 442   * @since 2.5.0
 443   *
 444   * @global WP_Query $wp_query Global WP_Query instance.
 445   *
 446   * @return bool True, if front of site.
 447   */
 448  function is_front_page() {
 449      global $wp_query;
 450  
 451      if ( ! isset( $wp_query ) ) {
 452          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 453          return false;
 454      }
 455  
 456      return $wp_query->is_front_page();
 457  }
 458  
 459  /**
 460   * Determines whether the query is for the blog homepage.
 461   *
 462   * The blog homepage is the page that shows the time-based blog content of the site.
 463   *
 464   * is_home() is dependent on the site's "Front page displays" Reading Settings 'show_on_front'
 465   * and 'page_for_posts'.
 466   *
 467   * If a static page is set for the front page of the site, this function will return true only
 468   * on the page you set as the "Posts page".
 469   *
 470   * For more information on this and similar theme functions, check out
 471   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 472   * Conditional Tags} article in the Theme Developer Handbook.
 473   *
 474   * @since 1.5.0
 475   *
 476   * @see is_front_page()
 477   * @global WP_Query $wp_query Global WP_Query instance.
 478   *
 479   * @return bool True if blog view homepage, otherwise false.
 480   */
 481  function is_home() {
 482      global $wp_query;
 483  
 484      if ( ! isset( $wp_query ) ) {
 485          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 486          return false;
 487      }
 488  
 489      return $wp_query->is_home();
 490  }
 491  
 492  /**
 493   * Determines whether the query is for the Privacy Policy page.
 494   *
 495   * The Privacy Policy page is the page that shows the Privacy Policy content of the site.
 496   *
 497   * is_privacy_policy() is dependent on the site's "Change your Privacy Policy page" Privacy Settings 'wp_page_for_privacy_policy'.
 498   *
 499   * This function will return true only on the page you set as the "Privacy Policy page".
 500   *
 501   * For more information on this and similar theme functions, check out
 502   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 503   * Conditional Tags} article in the Theme Developer Handbook.
 504   *
 505   * @since 5.2.0
 506   *
 507   * @global WP_Query $wp_query Global WP_Query instance.
 508   *
 509   * @return bool
 510   */
 511  function is_privacy_policy() {
 512      global $wp_query;
 513  
 514      if ( ! isset( $wp_query ) ) {
 515          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 516          return false;
 517      }
 518  
 519      return $wp_query->is_privacy_policy();
 520  }
 521  
 522  /**
 523   * Determines whether the query is for an existing month archive.
 524   *
 525   * For more information on this and similar theme functions, check out
 526   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 527   * Conditional Tags} article in the Theme Developer Handbook.
 528   *
 529   * @since 1.5.0
 530   *
 531   * @global WP_Query $wp_query Global WP_Query instance.
 532   *
 533   * @return bool
 534   */
 535  function is_month() {
 536      global $wp_query;
 537  
 538      if ( ! isset( $wp_query ) ) {
 539          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 540          return false;
 541      }
 542  
 543      return $wp_query->is_month();
 544  }
 545  
 546  /**
 547   * Determines whether the query is for an existing single page.
 548   *
 549   * If the $page parameter is specified, this function will additionally
 550   * check if the query is for one of the pages specified.
 551   *
 552   * For more information on this and similar theme functions, check out
 553   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 554   * Conditional Tags} article in the Theme Developer Handbook.
 555   *
 556   * @see is_single()
 557   * @see is_singular()
 558   *
 559   * @since 1.5.0
 560   *
 561   * @global WP_Query $wp_query Global WP_Query instance.
 562   *
 563   * @param int|string|array $page Optional. Page ID, title, slug, or array of such. Default empty.
 564   * @return bool Whether the query is for an existing single page.
 565   */
 566  function is_page( $page = '' ) {
 567      global $wp_query;
 568  
 569      if ( ! isset( $wp_query ) ) {
 570          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 571          return false;
 572      }
 573  
 574      return $wp_query->is_page( $page );
 575  }
 576  
 577  /**
 578   * Determines whether the query is for paged results and not for the first page.
 579   *
 580   * For more information on this and similar theme functions, check out
 581   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 582   * Conditional Tags} article in the Theme Developer Handbook.
 583   *
 584   * @since 1.5.0
 585   *
 586   * @global WP_Query $wp_query Global WP_Query instance.
 587   *
 588   * @return bool
 589   */
 590  function is_paged() {
 591      global $wp_query;
 592  
 593      if ( ! isset( $wp_query ) ) {
 594          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 595          return false;
 596      }
 597  
 598      return $wp_query->is_paged();
 599  }
 600  
 601  /**
 602   * Determines whether the query is for a post or page preview.
 603   *
 604   * For more information on this and similar theme functions, check out
 605   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 606   * Conditional Tags} article in the Theme Developer Handbook.
 607   *
 608   * @since 2.0.0
 609   *
 610   * @global WP_Query $wp_query Global WP_Query instance.
 611   *
 612   * @return bool
 613   */
 614  function is_preview() {
 615      global $wp_query;
 616  
 617      if ( ! isset( $wp_query ) ) {
 618          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 619          return false;
 620      }
 621  
 622      return $wp_query->is_preview();
 623  }
 624  
 625  /**
 626   * Is the query for the robots file?
 627   *
 628   * @since 2.1.0
 629   *
 630   * @global WP_Query $wp_query Global WP_Query instance.
 631   *
 632   * @return bool
 633   */
 634  function is_robots() {
 635      global $wp_query;
 636  
 637      if ( ! isset( $wp_query ) ) {
 638          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 639          return false;
 640      }
 641  
 642      return $wp_query->is_robots();
 643  }
 644  
 645  /**
 646   * Determines whether the query is for a search.
 647   *
 648   * For more information on this and similar theme functions, check out
 649   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 650   * Conditional Tags} article in the Theme Developer Handbook.
 651   *
 652   * @since 1.5.0
 653   *
 654   * @global WP_Query $wp_query Global WP_Query instance.
 655   *
 656   * @return bool
 657   */
 658  function is_search() {
 659      global $wp_query;
 660  
 661      if ( ! isset( $wp_query ) ) {
 662          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 663          return false;
 664      }
 665  
 666      return $wp_query->is_search();
 667  }
 668  
 669  /**
 670   * Determines whether the query is for an existing single post.
 671   *
 672   * Works for any post type, except attachments and pages
 673   *
 674   * If the $post parameter is specified, this function will additionally
 675   * check if the query is for one of the Posts specified.
 676   *
 677   * For more information on this and similar theme functions, check out
 678   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 679   * Conditional Tags} article in the Theme Developer Handbook.
 680   *
 681   * @see is_page()
 682   * @see is_singular()
 683   *
 684   * @since 1.5.0
 685   *
 686   * @global WP_Query $wp_query Global WP_Query instance.
 687   *
 688   * @param int|string|array $post Optional. Post ID, title, slug, or array of such. Default empty.
 689   * @return bool Whether the query is for an existing single post.
 690   */
 691  function is_single( $post = '' ) {
 692      global $wp_query;
 693  
 694      if ( ! isset( $wp_query ) ) {
 695          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 696          return false;
 697      }
 698  
 699      return $wp_query->is_single( $post );
 700  }
 701  
 702  /**
 703   * Determines whether the query is for an existing single post of any post type
 704   * (post, attachment, page, custom post types).
 705   *
 706   * If the $post_types parameter is specified, this function will additionally
 707   * check if the query is for one of the Posts Types specified.
 708   *
 709   * For more information on this and similar theme functions, check out
 710   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 711   * Conditional Tags} article in the Theme Developer Handbook.
 712   *
 713   * @see is_page()
 714   * @see is_single()
 715   *
 716   * @since 1.5.0
 717   *
 718   * @global WP_Query $wp_query Global WP_Query instance.
 719   *
 720   * @param string|array $post_types Optional. Post type or array of post types. Default empty.
 721   * @return bool Whether the query is for an existing single post of any of the given post types.
 722   */
 723  function is_singular( $post_types = '' ) {
 724      global $wp_query;
 725  
 726      if ( ! isset( $wp_query ) ) {
 727          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 728          return false;
 729      }
 730  
 731      return $wp_query->is_singular( $post_types );
 732  }
 733  
 734  /**
 735   * Determines whether the query is for a specific time.
 736   *
 737   * For more information on this and similar theme functions, check out
 738   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 739   * Conditional Tags} article in the Theme Developer Handbook.
 740   *
 741   * @since 1.5.0
 742   *
 743   * @global WP_Query $wp_query Global WP_Query instance.
 744   *
 745   * @return bool
 746   */
 747  function is_time() {
 748      global $wp_query;
 749  
 750      if ( ! isset( $wp_query ) ) {
 751          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 752          return false;
 753      }
 754  
 755      return $wp_query->is_time();
 756  }
 757  
 758  /**
 759   * Determines whether the query is for a trackback endpoint call.
 760   *
 761   * For more information on this and similar theme functions, check out
 762   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 763   * Conditional Tags} article in the Theme Developer Handbook.
 764   *
 765   * @since 1.5.0
 766   *
 767   * @global WP_Query $wp_query Global WP_Query instance.
 768   *
 769   * @return bool
 770   */
 771  function is_trackback() {
 772      global $wp_query;
 773  
 774      if ( ! isset( $wp_query ) ) {
 775          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 776          return false;
 777      }
 778  
 779      return $wp_query->is_trackback();
 780  }
 781  
 782  /**
 783   * Determines whether the query is for an existing year archive.
 784   *
 785   * For more information on this and similar theme functions, check out
 786   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 787   * Conditional Tags} article in the Theme Developer Handbook.
 788   *
 789   * @since 1.5.0
 790   *
 791   * @global WP_Query $wp_query Global WP_Query instance.
 792   *
 793   * @return bool
 794   */
 795  function is_year() {
 796      global $wp_query;
 797  
 798      if ( ! isset( $wp_query ) ) {
 799          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 800          return false;
 801      }
 802  
 803      return $wp_query->is_year();
 804  }
 805  
 806  /**
 807   * Determines whether the query has resulted in a 404 (returns no results).
 808   *
 809   * For more information on this and similar theme functions, check out
 810   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 811   * Conditional Tags} article in the Theme Developer Handbook.
 812   *
 813   * @since 1.5.0
 814   *
 815   * @global WP_Query $wp_query Global WP_Query instance.
 816   *
 817   * @return bool
 818   */
 819  function is_404() {
 820      global $wp_query;
 821  
 822      if ( ! isset( $wp_query ) ) {
 823          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 824          return false;
 825      }
 826  
 827      return $wp_query->is_404();
 828  }
 829  
 830  /**
 831   * Is the query for an embedded post?
 832   *
 833   * @since 4.4.0
 834   *
 835   * @global WP_Query $wp_query Global WP_Query instance.
 836   *
 837   * @return bool Whether we're in an embedded post or not.
 838   */
 839  function is_embed() {
 840      global $wp_query;
 841  
 842      if ( ! isset( $wp_query ) ) {
 843          _doing_it_wrong( __FUNCTION__, __( 'Conditional query tags do not work before the query is run. Before then, they always return false.' ), '3.1.0' );
 844          return false;
 845      }
 846  
 847      return $wp_query->is_embed();
 848  }
 849  
 850  /**
 851   * Determines whether the query is the main query.
 852   *
 853   * For more information on this and similar theme functions, check out
 854   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 855   * Conditional Tags} article in the Theme Developer Handbook.
 856   *
 857   * @since 3.3.0
 858   *
 859   * @global WP_Query $wp_query Global WP_Query instance.
 860   *
 861   * @return bool
 862   */
 863  function is_main_query() {
 864      if ( 'pre_get_posts' === current_filter() ) {
 865          $message = sprintf(
 866              /* translators: 1: pre_get_posts 2: WP_Query->is_main_query() 3: is_main_query() 4: link to codex is_main_query() page. */
 867              __( 'In %1$s, use the %2$s method, not the %3$s function. See %4$s.' ),
 868              '<code>pre_get_posts</code>',
 869              '<code>WP_Query->is_main_query()</code>',
 870              '<code>is_main_query()</code>',
 871              __( 'https://codex.wordpress.org/Function_Reference/is_main_query' )
 872          );
 873          _doing_it_wrong( __FUNCTION__, $message, '3.7.0' );
 874      }
 875  
 876      global $wp_query;
 877      return $wp_query->is_main_query();
 878  }
 879  
 880  /*
 881   * The Loop. Post loop control.
 882   */
 883  
 884  /**
 885   * Whether current WordPress query has results to loop over.
 886   *
 887   * @since 1.5.0
 888   *
 889   * @global WP_Query $wp_query Global WP_Query instance.
 890   *
 891   * @return bool
 892   */
 893  function have_posts() {
 894      global $wp_query;
 895      return $wp_query->have_posts();
 896  }
 897  
 898  /**
 899   * Determines whether the caller is in the Loop.
 900   *
 901   * For more information on this and similar theme functions, check out
 902   * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
 903   * Conditional Tags} article in the Theme Developer Handbook.
 904   *
 905   * @since 2.0.0
 906   *
 907   * @global WP_Query $wp_query Global WP_Query instance.
 908   *
 909   * @return bool True if caller is within loop, false if loop hasn't started or ended.
 910   */
 911  function in_the_loop() {
 912      global $wp_query;
 913      return $wp_query->in_the_loop;
 914  }
 915  
 916  /**
 917   * Rewind the loop posts.
 918   *
 919   * @since 1.5.0
 920   *
 921   * @global WP_Query $wp_query Global WP_Query instance.
 922   */
 923  function rewind_posts() {
 924      global $wp_query;
 925      $wp_query->rewind_posts();
 926  }
 927  
 928  /**
 929   * Iterate the post index in the loop.
 930   *
 931   * @since 1.5.0
 932   *
 933   * @global WP_Query $wp_query Global WP_Query instance.
 934   */
 935  function the_post() {
 936      global $wp_query;
 937      $wp_query->the_post();
 938  }
 939  
 940  /*
 941   * Comments loop.
 942   */
 943  
 944  /**
 945   * Whether there are comments to loop over.
 946   *
 947   * @since 2.2.0
 948   *
 949   * @global WP_Query $wp_query Global WP_Query instance.
 950   *
 951   * @return bool
 952   */
 953  function have_comments() {
 954      global $wp_query;
 955      return $wp_query->have_comments();
 956  }
 957  
 958  /**
 959   * Iterate comment index in the comment loop.
 960   *
 961   * @since 2.2.0
 962   *
 963   * @global WP_Query $wp_query Global WP_Query instance.
 964   *
 965   * @return object
 966   */
 967  function the_comment() {
 968      global $wp_query;
 969      return $wp_query->the_comment();
 970  }
 971  
 972  /**
 973   * Redirect old slugs to the correct permalink.
 974   *
 975   * Attempts to find the current slug from the past slugs.
 976   *
 977   * @since 2.1.0
 978   */
 979  function wp_old_slug_redirect() {
 980      if ( is_404() && '' !== get_query_var( 'name' ) ) {
 981          // Guess the current post_type based on the query vars.
 982          if ( get_query_var( 'post_type' ) ) {
 983              $post_type = get_query_var( 'post_type' );
 984          } elseif ( get_query_var( 'attachment' ) ) {
 985              $post_type = 'attachment';
 986          } elseif ( get_query_var( 'pagename' ) ) {
 987              $post_type = 'page';
 988          } else {
 989              $post_type = 'post';
 990          }
 991  
 992          if ( is_array( $post_type ) ) {
 993              if ( count( $post_type ) > 1 ) {
 994                  return;
 995              }
 996              $post_type = reset( $post_type );
 997          }
 998  
 999          // Do not attempt redirect for hierarchical post types
1000          if ( is_post_type_hierarchical( $post_type ) ) {
1001              return;
1002          }
1003  
1004          $id = _find_post_by_old_slug( $post_type );
1005  
1006          if ( ! $id ) {
1007              $id = _find_post_by_old_date( $post_type );
1008          }
1009  
1010          /**
1011           * Filters the old slug redirect post ID.
1012           *
1013           * @since 4.9.3
1014           *
1015           * @param int $id The redirect post ID.
1016           */
1017          $id = apply_filters( 'old_slug_redirect_post_id', $id );
1018  
1019          if ( ! $id ) {
1020              return;
1021          }
1022  
1023          $link = get_permalink( $id );
1024  
1025          if ( get_query_var( 'paged' ) > 1 ) {
1026              $link = user_trailingslashit( trailingslashit( $link ) . 'page/' . get_query_var( 'paged' ) );
1027          } elseif ( is_embed() ) {
1028              $link = user_trailingslashit( trailingslashit( $link ) . 'embed' );
1029          }
1030  
1031          /**
1032           * Filters the old slug redirect URL.
1033           *
1034           * @since 4.4.0
1035           *
1036           * @param string $link The redirect URL.
1037           */
1038          $link = apply_filters( 'old_slug_redirect_url', $link );
1039  
1040          if ( ! $link ) {
1041              return;
1042          }
1043  
1044          wp_redirect( $link, 301 ); // Permanent redirect
1045          exit;
1046      }
1047  }
1048  
1049  /**
1050   * Find the post ID for redirecting an old slug.
1051   *
1052   * @see wp_old_slug_redirect()
1053   *
1054   * @since 4.9.3
1055   * @access private
1056   *
1057   * @global wpdb $wpdb WordPress database abstraction object.
1058   *
1059   * @param string $post_type The current post type based on the query vars.
1060   * @return int $id The Post ID.
1061   */
1062  function _find_post_by_old_slug( $post_type ) {
1063      global $wpdb;
1064  
1065      $query = $wpdb->prepare( "SELECT post_id FROM $wpdb->postmeta, $wpdb->posts WHERE ID = post_id AND post_type = %s AND meta_key = '_wp_old_slug' AND meta_value = %s", $post_type, get_query_var( 'name' ) );
1066  
1067      // if year, monthnum, or day have been specified, make our query more precise
1068      // just in case there are multiple identical _wp_old_slug values
1069      if ( get_query_var( 'year' ) ) {
1070          $query .= $wpdb->prepare( ' AND YEAR(post_date) = %d', get_query_var( 'year' ) );
1071      }
1072      if ( get_query_var( 'monthnum' ) ) {
1073          $query .= $wpdb->prepare( ' AND MONTH(post_date) = %d', get_query_var( 'monthnum' ) );
1074      }
1075      if ( get_query_var( 'day' ) ) {
1076          $query .= $wpdb->prepare( ' AND DAYOFMONTH(post_date) = %d', get_query_var( 'day' ) );
1077      }
1078  
1079      $id = (int) $wpdb->get_var( $query );
1080  
1081      return $id;
1082  }
1083  
1084  /**
1085   * Find the post ID for redirecting an old date.
1086   *
1087   * @see wp_old_slug_redirect()
1088   *
1089   * @since 4.9.3
1090   * @access private
1091   *
1092   * @global wpdb $wpdb WordPress database abstraction object.
1093   *
1094   * @param string $post_type The current post type based on the query vars.
1095   * @return int $id The Post ID.
1096   */
1097  function _find_post_by_old_date( $post_type ) {
1098      global $wpdb;
1099  
1100      $date_query = '';
1101      if ( get_query_var( 'year' ) ) {
1102          $date_query .= $wpdb->prepare( ' AND YEAR(pm_date.meta_value) = %d', get_query_var( 'year' ) );
1103      }
1104      if ( get_query_var( 'monthnum' ) ) {
1105          $date_query .= $wpdb->prepare( ' AND MONTH(pm_date.meta_value) = %d', get_query_var( 'monthnum' ) );
1106      }
1107      if ( get_query_var( 'day' ) ) {
1108          $date_query .= $wpdb->prepare( ' AND DAYOFMONTH(pm_date.meta_value) = %d', get_query_var( 'day' ) );
1109      }
1110  
1111      $id = 0;
1112      if ( $date_query ) {
1113          $id = (int) $wpdb->get_var( $wpdb->prepare( "SELECT post_id FROM $wpdb->postmeta AS pm_date, $wpdb->posts WHERE ID = post_id AND post_type = %s AND meta_key = '_wp_old_date' AND post_name = %s" . $date_query, $post_type, get_query_var( 'name' ) ) );
1114  
1115          if ( ! $id ) {
1116              // Check to see if an old slug matches the old date
1117              $id = (int) $wpdb->get_var( $wpdb->prepare( "SELECT ID FROM $wpdb->posts, $wpdb->postmeta AS pm_slug, $wpdb->postmeta AS pm_date WHERE ID = pm_slug.post_id AND ID = pm_date.post_id AND post_type = %s AND pm_slug.meta_key = '_wp_old_slug' AND pm_slug.meta_value = %s AND pm_date.meta_key = '_wp_old_date'" . $date_query, $post_type, get_query_var( 'name' ) ) );
1118          }
1119      }
1120  
1121      return $id;
1122  }
1123  
1124  /**
1125   * Set up global post data.
1126   *
1127   * @since 1.5.0
1128   * @since 4.4.0 Added the ability to pass a post ID to `$post`.
1129   *
1130   * @global WP_Query $wp_query Global WP_Query instance.
1131   *
1132   * @param WP_Post|object|int $post WP_Post instance or Post ID/object.
1133   * @return bool True when finished.
1134   */
1135  function setup_postdata( $post ) {
1136      global $wp_query;
1137  
1138      if ( ! empty( $wp_query ) && $wp_query instanceof WP_Query ) {
1139          return $wp_query->setup_postdata( $post );
1140      }
1141  
1142      return false;
1143  }
1144  
1145  /**
1146   * Generates post data.
1147   *
1148   * @since 5.2.0
1149   *
1150   * @global WP_Query $wp_query Global WP_Query instance.
1151   *
1152   * @param WP_Post|object|int $post WP_Post instance or Post ID/object.
1153   * @return array|bool Elements of post, or false on failure.
1154   */
1155  function generate_postdata( $post ) {
1156      global $wp_query;
1157  
1158      if ( ! empty( $wp_query ) && $wp_query instanceof WP_Query ) {
1159          return $wp_query->generate_postdata( $post );
1160      }
1161  
1162      return false;
1163  }


Generated: Mon Jun 17 08:20:02 2019 Cross-referenced by PHPXref 0.7