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


Generated: Fri Sep 18 01:00:03 2020 Cross-referenced by PHPXref 0.7.1