[ Index ]

PHP Cross Reference of WordPress

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


Generated: Mon Jun 1 01:00:03 2020 Cross-referenced by PHPXref 0.7.1