[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Template loading functions.
   4   *
   5   * @package WordPress
   6   * @subpackage Template
   7   */
   8  
   9  /**
  10   * Retrieve path to a template
  11   *
  12   * Used to quickly retrieve the path of a template without including the file
  13   * extension. It will also check the parent theme, if the file exists, with
  14   * the use of locate_template(). Allows for more generic template location
  15   * without the use of the other get_*_template() functions.
  16   *
  17   * @since 1.5.0
  18   *
  19   * @param string   $type      Filename without extension.
  20   * @param string[] $templates An optional list of template candidates.
  21   * @return string Full path to template file.
  22   */
  23  function get_query_template( $type, $templates = array() ) {
  24      $type = preg_replace( '|[^a-z0-9-]+|', '', $type );
  25  
  26      if ( empty( $templates ) ) {
  27          $templates = array( "{$type}.php" );
  28      }
  29  
  30      /**
  31       * Filters the list of template filenames that are searched for when retrieving a template to use.
  32       *
  33       * The dynamic portion of the hook name, `$type`, refers to the filename -- minus the file
  34       * extension and any non-alphanumeric characters delimiting words -- of the file to load.
  35       * The last element in the array should always be the fallback template for this query type.
  36       *
  37       * Possible hook names include:
  38       *
  39       *  - `404_template_hierarchy`
  40       *  - `archive_template_hierarchy`
  41       *  - `attachment_template_hierarchy`
  42       *  - `author_template_hierarchy`
  43       *  - `category_template_hierarchy`
  44       *  - `date_template_hierarchy`
  45       *  - `embed_template_hierarchy`
  46       *  - `frontpage_template_hierarchy`
  47       *  - `home_template_hierarchy`
  48       *  - `index_template_hierarchy`
  49       *  - `page_template_hierarchy`
  50       *  - `paged_template_hierarchy`
  51       *  - `privacypolicy_template_hierarchy`
  52       *  - `search_template_hierarchy`
  53       *  - `single_template_hierarchy`
  54       *  - `singular_template_hierarchy`
  55       *  - `tag_template_hierarchy`
  56       *  - `taxonomy_template_hierarchy`
  57       *
  58       * @since 4.7.0
  59       *
  60       * @param string[] $templates A list of template candidates, in descending order of priority.
  61       */
  62      $templates = apply_filters( "{$type}_template_hierarchy", $templates );
  63  
  64      $template = locate_template( $templates );
  65  
  66      $template = locate_block_template( $template, $type, $templates );
  67  
  68      /**
  69       * Filters the path of the queried template by type.
  70       *
  71       * The dynamic portion of the hook name, `$type`, refers to the filename -- minus the file
  72       * extension and any non-alphanumeric characters delimiting words -- of the file to load.
  73       * This hook also applies to various types of files loaded as part of the Template Hierarchy.
  74       *
  75       * Possible hook names include:
  76       *
  77       *  - `404_template`
  78       *  - `archive_template`
  79       *  - `attachment_template`
  80       *  - `author_template`
  81       *  - `category_template`
  82       *  - `date_template`
  83       *  - `embed_template`
  84       *  - `frontpage_template`
  85       *  - `home_template`
  86       *  - `index_template`
  87       *  - `page_template`
  88       *  - `paged_template`
  89       *  - `privacypolicy_template`
  90       *  - `search_template`
  91       *  - `single_template`
  92       *  - `singular_template`
  93       *  - `tag_template`
  94       *  - `taxonomy_template`
  95       *
  96       * @since 1.5.0
  97       * @since 4.8.0 The `$type` and `$templates` parameters were added.
  98       *
  99       * @param string   $template  Path to the template. See locate_template().
 100       * @param string   $type      Sanitized filename without extension.
 101       * @param string[] $templates A list of template candidates, in descending order of priority.
 102       */
 103      return apply_filters( "{$type}_template", $template, $type, $templates );
 104  }
 105  
 106  /**
 107   * Retrieve path of index template in current or parent template.
 108   *
 109   * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'}
 110   * and {@see '$type_template'} dynamic hooks, where `$type` is 'index'.
 111   *
 112   * @since 3.0.0
 113   *
 114   * @see get_query_template()
 115   *
 116   * @return string Full path to index template file.
 117   */
 118  function get_index_template() {
 119      return get_query_template( 'index' );
 120  }
 121  
 122  /**
 123   * Retrieve path of 404 template in current or parent template.
 124   *
 125   * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'}
 126   * and {@see '$type_template'} dynamic hooks, where `$type` is '404'.
 127   *
 128   * @since 1.5.0
 129   *
 130   * @see get_query_template()
 131   *
 132   * @return string Full path to 404 template file.
 133   */
 134  function get_404_template() {
 135      return get_query_template( '404' );
 136  }
 137  
 138  /**
 139   * Retrieve path of archive template in current or parent template.
 140   *
 141   * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'}
 142   * and {@see '$type_template'} dynamic hooks, where `$type` is 'archive'.
 143   *
 144   * @since 1.5.0
 145   *
 146   * @see get_query_template()
 147   *
 148   * @return string Full path to archive template file.
 149   */
 150  function get_archive_template() {
 151      $post_types = array_filter( (array) get_query_var( 'post_type' ) );
 152  
 153      $templates = array();
 154  
 155      if ( count( $post_types ) == 1 ) {
 156          $post_type   = reset( $post_types );
 157          $templates[] = "archive-{$post_type}.php";
 158      }
 159      $templates[] = 'archive.php';
 160  
 161      return get_query_template( 'archive', $templates );
 162  }
 163  
 164  /**
 165   * Retrieve path of post type archive template in current or parent template.
 166   *
 167   * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'}
 168   * and {@see '$type_template'} dynamic hooks, where `$type` is 'archive'.
 169   *
 170   * @since 3.7.0
 171   *
 172   * @see get_archive_template()
 173   *
 174   * @return string Full path to archive template file.
 175   */
 176  function get_post_type_archive_template() {
 177      $post_type = get_query_var( 'post_type' );
 178      if ( is_array( $post_type ) ) {
 179          $post_type = reset( $post_type );
 180      }
 181  
 182      $obj = get_post_type_object( $post_type );
 183      if ( ! ( $obj instanceof WP_Post_Type ) || ! $obj->has_archive ) {
 184          return '';
 185      }
 186  
 187      return get_archive_template();
 188  }
 189  
 190  /**
 191   * Retrieve path of author template in current or parent template.
 192   *
 193   * The hierarchy for this template looks like:
 194   *
 195   * 1. author-{nicename}.php
 196   * 2. author-{id}.php
 197   * 3. author.php
 198   *
 199   * An example of this is:
 200   *
 201   * 1. author-john.php
 202   * 2. author-1.php
 203   * 3. author.php
 204   *
 205   * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'}
 206   * and {@see '$type_template'} dynamic hooks, where `$type` is 'author'.
 207   *
 208   * @since 1.5.0
 209   *
 210   * @see get_query_template()
 211   *
 212   * @return string Full path to author template file.
 213   */
 214  function get_author_template() {
 215      $author = get_queried_object();
 216  
 217      $templates = array();
 218  
 219      if ( $author instanceof WP_User ) {
 220          $templates[] = "author-{$author->user_nicename}.php";
 221          $templates[] = "author-{$author->ID}.php";
 222      }
 223      $templates[] = 'author.php';
 224  
 225      return get_query_template( 'author', $templates );
 226  }
 227  
 228  /**
 229   * Retrieve path of category template in current or parent template.
 230   *
 231   * The hierarchy for this template looks like:
 232   *
 233   * 1. category-{slug}.php
 234   * 2. category-{id}.php
 235   * 3. category.php
 236   *
 237   * An example of this is:
 238   *
 239   * 1. category-news.php
 240   * 2. category-2.php
 241   * 3. category.php
 242   *
 243   * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'}
 244   * and {@see '$type_template'} dynamic hooks, where `$type` is 'category'.
 245   *
 246   * @since 1.5.0
 247   * @since 4.7.0 The decoded form of `category-{slug}.php` was added to the top of the
 248   *              template hierarchy when the category slug contains multibyte characters.
 249   *
 250   * @see get_query_template()
 251   *
 252   * @return string Full path to category template file.
 253   */
 254  function get_category_template() {
 255      $category = get_queried_object();
 256  
 257      $templates = array();
 258  
 259      if ( ! empty( $category->slug ) ) {
 260  
 261          $slug_decoded = urldecode( $category->slug );
 262          if ( $slug_decoded !== $category->slug ) {
 263              $templates[] = "category-{$slug_decoded}.php";
 264          }
 265  
 266          $templates[] = "category-{$category->slug}.php";
 267          $templates[] = "category-{$category->term_id}.php";
 268      }
 269      $templates[] = 'category.php';
 270  
 271      return get_query_template( 'category', $templates );
 272  }
 273  
 274  /**
 275   * Retrieve path of tag template in current or parent template.
 276   *
 277   * The hierarchy for this template looks like:
 278   *
 279   * 1. tag-{slug}.php
 280   * 2. tag-{id}.php
 281   * 3. tag.php
 282   *
 283   * An example of this is:
 284   *
 285   * 1. tag-wordpress.php
 286   * 2. tag-3.php
 287   * 3. tag.php
 288   *
 289   * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'}
 290   * and {@see '$type_template'} dynamic hooks, where `$type` is 'tag'.
 291   *
 292   * @since 2.3.0
 293   * @since 4.7.0 The decoded form of `tag-{slug}.php` was added to the top of the
 294   *              template hierarchy when the tag slug contains multibyte characters.
 295   *
 296   * @see get_query_template()
 297   *
 298   * @return string Full path to tag template file.
 299   */
 300  function get_tag_template() {
 301      $tag = get_queried_object();
 302  
 303      $templates = array();
 304  
 305      if ( ! empty( $tag->slug ) ) {
 306  
 307          $slug_decoded = urldecode( $tag->slug );
 308          if ( $slug_decoded !== $tag->slug ) {
 309              $templates[] = "tag-{$slug_decoded}.php";
 310          }
 311  
 312          $templates[] = "tag-{$tag->slug}.php";
 313          $templates[] = "tag-{$tag->term_id}.php";
 314      }
 315      $templates[] = 'tag.php';
 316  
 317      return get_query_template( 'tag', $templates );
 318  }
 319  
 320  /**
 321   * Retrieve path of custom taxonomy term template in current or parent template.
 322   *
 323   * The hierarchy for this template looks like:
 324   *
 325   * 1. taxonomy-{taxonomy_slug}-{term_slug}.php
 326   * 2. taxonomy-{taxonomy_slug}.php
 327   * 3. taxonomy.php
 328   *
 329   * An example of this is:
 330   *
 331   * 1. taxonomy-location-texas.php
 332   * 2. taxonomy-location.php
 333   * 3. taxonomy.php
 334   *
 335   * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'}
 336   * and {@see '$type_template'} dynamic hooks, where `$type` is 'taxonomy'.
 337   *
 338   * @since 2.5.0
 339   * @since 4.7.0 The decoded form of `taxonomy-{taxonomy_slug}-{term_slug}.php` was added to the top of the
 340   *              template hierarchy when the term slug contains multibyte characters.
 341   *
 342   * @see get_query_template()
 343   *
 344   * @return string Full path to custom taxonomy term template file.
 345   */
 346  function get_taxonomy_template() {
 347      $term = get_queried_object();
 348  
 349      $templates = array();
 350  
 351      if ( ! empty( $term->slug ) ) {
 352          $taxonomy = $term->taxonomy;
 353  
 354          $slug_decoded = urldecode( $term->slug );
 355          if ( $slug_decoded !== $term->slug ) {
 356              $templates[] = "taxonomy-$taxonomy-{$slug_decoded}.php";
 357          }
 358  
 359          $templates[] = "taxonomy-$taxonomy-{$term->slug}.php";
 360          $templates[] = "taxonomy-$taxonomy.php";
 361      }
 362      $templates[] = 'taxonomy.php';
 363  
 364      return get_query_template( 'taxonomy', $templates );
 365  }
 366  
 367  /**
 368   * Retrieve path of date template in current or parent template.
 369   *
 370   * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'}
 371   * and {@see '$type_template'} dynamic hooks, where `$type` is 'date'.
 372   *
 373   * @since 1.5.0
 374   *
 375   * @see get_query_template()
 376   *
 377   * @return string Full path to date template file.
 378   */
 379  function get_date_template() {
 380      return get_query_template( 'date' );
 381  }
 382  
 383  /**
 384   * Retrieve path of home template in current or parent template.
 385   *
 386   * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'}
 387   * and {@see '$type_template'} dynamic hooks, where `$type` is 'home'.
 388   *
 389   * @since 1.5.0
 390   *
 391   * @see get_query_template()
 392   *
 393   * @return string Full path to home template file.
 394   */
 395  function get_home_template() {
 396      $templates = array( 'home.php', 'index.php' );
 397  
 398      return get_query_template( 'home', $templates );
 399  }
 400  
 401  /**
 402   * Retrieve path of front page template in current or parent template.
 403   *
 404   * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'}
 405   * and {@see '$type_template'} dynamic hooks, where `$type` is 'frontpage'.
 406   *
 407   * @since 3.0.0
 408   *
 409   * @see get_query_template()
 410   *
 411   * @return string Full path to front page template file.
 412   */
 413  function get_front_page_template() {
 414      $templates = array( 'front-page.php' );
 415  
 416      return get_query_template( 'frontpage', $templates );
 417  }
 418  
 419  /**
 420   * Retrieve path of Privacy Policy page template in current or parent template.
 421   *
 422   * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'}
 423   * and {@see '$type_template'} dynamic hooks, where `$type` is 'privacypolicy'.
 424   *
 425   * @since 5.2.0
 426   *
 427   * @see get_query_template()
 428   *
 429   * @return string Full path to privacy policy template file.
 430   */
 431  function get_privacy_policy_template() {
 432      $templates = array( 'privacy-policy.php' );
 433  
 434      return get_query_template( 'privacypolicy', $templates );
 435  }
 436  
 437  /**
 438   * Retrieve path of page template in current or parent template.
 439   *
 440   * The hierarchy for this template looks like:
 441   *
 442   * 1. {Page Template}.php
 443   * 2. page-{page_name}.php
 444   * 3. page-{id}.php
 445   * 4. page.php
 446   *
 447   * An example of this is:
 448   *
 449   * 1. page-templates/full-width.php
 450   * 2. page-about.php
 451   * 3. page-4.php
 452   * 4. page.php
 453   *
 454   * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'}
 455   * and {@see '$type_template'} dynamic hooks, where `$type` is 'page'.
 456   *
 457   * @since 1.5.0
 458   * @since 4.7.0 The decoded form of `page-{page_name}.php` was added to the top of the
 459   *              template hierarchy when the page name contains multibyte characters.
 460   *
 461   * @see get_query_template()
 462   *
 463   * @return string Full path to page template file.
 464   */
 465  function get_page_template() {
 466      $id       = get_queried_object_id();
 467      $template = get_page_template_slug();
 468      $pagename = get_query_var( 'pagename' );
 469  
 470      if ( ! $pagename && $id ) {
 471          // If a static page is set as the front page, $pagename will not be set.
 472          // Retrieve it from the queried object.
 473          $post = get_queried_object();
 474          if ( $post ) {
 475              $pagename = $post->post_name;
 476          }
 477      }
 478  
 479      $templates = array();
 480      if ( $template && 0 === validate_file( $template ) ) {
 481          $templates[] = $template;
 482      }
 483      if ( $pagename ) {
 484          $pagename_decoded = urldecode( $pagename );
 485          if ( $pagename_decoded !== $pagename ) {
 486              $templates[] = "page-{$pagename_decoded}.php";
 487          }
 488          $templates[] = "page-{$pagename}.php";
 489      }
 490      if ( $id ) {
 491          $templates[] = "page-{$id}.php";
 492      }
 493      $templates[] = 'page.php';
 494  
 495      return get_query_template( 'page', $templates );
 496  }
 497  
 498  /**
 499   * Retrieve path of search template in current or parent template.
 500   *
 501   * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'}
 502   * and {@see '$type_template'} dynamic hooks, where `$type` is 'search'.
 503   *
 504   * @since 1.5.0
 505   *
 506   * @see get_query_template()
 507   *
 508   * @return string Full path to search template file.
 509   */
 510  function get_search_template() {
 511      return get_query_template( 'search' );
 512  }
 513  
 514  /**
 515   * Retrieve path of single template in current or parent template. Applies to single Posts,
 516   * single Attachments, and single custom post types.
 517   *
 518   * The hierarchy for this template looks like:
 519   *
 520   * 1. {Post Type Template}.php
 521   * 2. single-{post_type}-{post_name}.php
 522   * 3. single-{post_type}.php
 523   * 4. single.php
 524   *
 525   * An example of this is:
 526   *
 527   * 1. templates/full-width.php
 528   * 2. single-post-hello-world.php
 529   * 3. single-post.php
 530   * 4. single.php
 531   *
 532   * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'}
 533   * and {@see '$type_template'} dynamic hooks, where `$type` is 'single'.
 534   *
 535   * @since 1.5.0
 536   * @since 4.4.0 `single-{post_type}-{post_name}.php` was added to the top of the template hierarchy.
 537   * @since 4.7.0 The decoded form of `single-{post_type}-{post_name}.php` was added to the top of the
 538   *              template hierarchy when the post name contains multibyte characters.
 539   * @since 4.7.0 `{Post Type Template}.php` was added to the top of the template hierarchy.
 540   *
 541   * @see get_query_template()
 542   *
 543   * @return string Full path to single template file.
 544   */
 545  function get_single_template() {
 546      $object = get_queried_object();
 547  
 548      $templates = array();
 549  
 550      if ( ! empty( $object->post_type ) ) {
 551          $template = get_page_template_slug( $object );
 552          if ( $template && 0 === validate_file( $template ) ) {
 553              $templates[] = $template;
 554          }
 555  
 556          $name_decoded = urldecode( $object->post_name );
 557          if ( $name_decoded !== $object->post_name ) {
 558              $templates[] = "single-{$object->post_type}-{$name_decoded}.php";
 559          }
 560  
 561          $templates[] = "single-{$object->post_type}-{$object->post_name}.php";
 562          $templates[] = "single-{$object->post_type}.php";
 563      }
 564  
 565      $templates[] = 'single.php';
 566  
 567      return get_query_template( 'single', $templates );
 568  }
 569  
 570  /**
 571   * Retrieves an embed template path in the current or parent template.
 572   *
 573   * The hierarchy for this template looks like:
 574   *
 575   * 1. embed-{post_type}-{post_format}.php
 576   * 2. embed-{post_type}.php
 577   * 3. embed.php
 578   *
 579   * An example of this is:
 580   *
 581   * 1. embed-post-audio.php
 582   * 2. embed-post.php
 583   * 3. embed.php
 584   *
 585   * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'}
 586   * and {@see '$type_template'} dynamic hooks, where `$type` is 'embed'.
 587   *
 588   * @since 4.5.0
 589   *
 590   * @see get_query_template()
 591   *
 592   * @return string Full path to embed template file.
 593   */
 594  function get_embed_template() {
 595      $object = get_queried_object();
 596  
 597      $templates = array();
 598  
 599      if ( ! empty( $object->post_type ) ) {
 600          $post_format = get_post_format( $object );
 601          if ( $post_format ) {
 602              $templates[] = "embed-{$object->post_type}-{$post_format}.php";
 603          }
 604          $templates[] = "embed-{$object->post_type}.php";
 605      }
 606  
 607      $templates[] = 'embed.php';
 608  
 609      return get_query_template( 'embed', $templates );
 610  }
 611  
 612  /**
 613   * Retrieves the path of the singular template in current or parent template.
 614   *
 615   * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'}
 616   * and {@see '$type_template'} dynamic hooks, where `$type` is 'singular'.
 617   *
 618   * @since 4.3.0
 619   *
 620   * @see get_query_template()
 621   *
 622   * @return string Full path to singular template file
 623   */
 624  function get_singular_template() {
 625      return get_query_template( 'singular' );
 626  }
 627  
 628  /**
 629   * Retrieve path of attachment template in current or parent template.
 630   *
 631   * The hierarchy for this template looks like:
 632   *
 633   * 1. {mime_type}-{sub_type}.php
 634   * 2. {sub_type}.php
 635   * 3. {mime_type}.php
 636   * 4. attachment.php
 637   *
 638   * An example of this is:
 639   *
 640   * 1. image-jpeg.php
 641   * 2. jpeg.php
 642   * 3. image.php
 643   * 4. attachment.php
 644   *
 645   * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'}
 646   * and {@see '$type_template'} dynamic hooks, where `$type` is 'attachment'.
 647   *
 648   * @since 2.0.0
 649   * @since 4.3.0 The order of the mime type logic was reversed so the hierarchy is more logical.
 650   *
 651   * @see get_query_template()
 652   *
 653   * @global array $posts
 654   *
 655   * @return string Full path to attachment template file.
 656   */
 657  function get_attachment_template() {
 658      $attachment = get_queried_object();
 659  
 660      $templates = array();
 661  
 662      if ( $attachment ) {
 663          if ( false !== strpos( $attachment->post_mime_type, '/' ) ) {
 664              list( $type, $subtype ) = explode( '/', $attachment->post_mime_type );
 665          } else {
 666              list( $type, $subtype ) = array( $attachment->post_mime_type, '' );
 667          }
 668  
 669          if ( ! empty( $subtype ) ) {
 670              $templates[] = "{$type}-{$subtype}.php";
 671              $templates[] = "{$subtype}.php";
 672          }
 673          $templates[] = "{$type}.php";
 674      }
 675      $templates[] = 'attachment.php';
 676  
 677      return get_query_template( 'attachment', $templates );
 678  }
 679  
 680  /**
 681   * Retrieve the name of the highest priority template file that exists.
 682   *
 683   * Searches in the STYLESHEETPATH before TEMPLATEPATH and wp-includes/theme-compat
 684   * so that themes which inherit from a parent theme can just overload one file.
 685   *
 686   * @since 2.7.0
 687   * @since 5.5.0 The `$args` parameter was added.
 688   *
 689   * @param string|array $template_names Template file(s) to search for, in order.
 690   * @param bool         $load           If true the template file will be loaded if it is found.
 691   * @param bool         $require_once   Whether to require_once or require. Has no effect if `$load` is false.
 692   *                                     Default true.
 693   * @param array        $args           Optional. Additional arguments passed to the template.
 694   *                                     Default empty array.
 695   * @return string The template filename if one is located.
 696   */
 697  function locate_template( $template_names, $load = false, $require_once = true, $args = array() ) {
 698      $located = '';
 699      foreach ( (array) $template_names as $template_name ) {
 700          if ( ! $template_name ) {
 701              continue;
 702          }
 703          if ( file_exists( STYLESHEETPATH . '/' . $template_name ) ) {
 704              $located = STYLESHEETPATH . '/' . $template_name;
 705              break;
 706          } elseif ( file_exists( TEMPLATEPATH . '/' . $template_name ) ) {
 707              $located = TEMPLATEPATH . '/' . $template_name;
 708              break;
 709          } elseif ( file_exists( ABSPATH . WPINC . '/theme-compat/' . $template_name ) ) {
 710              $located = ABSPATH . WPINC . '/theme-compat/' . $template_name;
 711              break;
 712          }
 713      }
 714  
 715      if ( $load && '' !== $located ) {
 716          /**
 717           * Fires before a located template is loaded.
 718           *
 719           * @since 6.1.0
 720           *
 721           * @param string       $located        The template filename.
 722           * @param string|array $template_names Template file(s) to search for, in order.
 723           * @param bool         $require_once   Whether to require_once or require.
 724           * @param array        $args           Additional arguments passed to the template.
 725           */
 726          do_action( 'wp_before_load_template', $located, $template_names, $require_once, $args );
 727  
 728          load_template( $located, $require_once, $args );
 729  
 730          /**
 731           * Fires after a located template is loaded.
 732           *
 733           * @since 6.1.0
 734           *
 735           * @param string       $located        The template filename.
 736           * @param string|array $template_names Template file(s) to search for, in order.
 737           * @param bool         $require_once   Whether to require_once or require.
 738           * @param array        $args           Additional arguments passed to the template.
 739           */
 740          do_action( 'wp_after_load_template', $located, $template_names, $require_once, $args );
 741      }
 742  
 743      return $located;
 744  }
 745  
 746  /**
 747   * Require the template file with WordPress environment.
 748   *
 749   * The globals are set up for the template file to ensure that the WordPress
 750   * environment is available from within the function. The query variables are
 751   * also available.
 752   *
 753   * @since 1.5.0
 754   * @since 5.5.0 The `$args` parameter was added.
 755   *
 756   * @global array      $posts
 757   * @global WP_Post    $post          Global post object.
 758   * @global bool       $wp_did_header
 759   * @global WP_Query   $wp_query      WordPress Query object.
 760   * @global WP_Rewrite $wp_rewrite    WordPress rewrite component.
 761   * @global wpdb       $wpdb          WordPress database abstraction object.
 762   * @global string     $wp_version
 763   * @global WP         $wp            Current WordPress environment instance.
 764   * @global int        $id
 765   * @global WP_Comment $comment       Global comment object.
 766   * @global int        $user_ID
 767   *
 768   * @param string $_template_file Path to template file.
 769   * @param bool   $require_once   Whether to require_once or require. Default true.
 770   * @param array  $args           Optional. Additional arguments passed to the template.
 771   *                               Default empty array.
 772   */
 773  function load_template( $_template_file, $require_once = true, $args = array() ) {
 774      global $posts, $post, $wp_did_header, $wp_query, $wp_rewrite, $wpdb, $wp_version, $wp, $id, $comment, $user_ID;
 775  
 776      if ( is_array( $wp_query->query_vars ) ) {
 777          /*
 778           * This use of extract() cannot be removed. There are many possible ways that
 779           * templates could depend on variables that it creates existing, and no way to
 780           * detect and deprecate it.
 781           *
 782           * Passing the EXTR_SKIP flag is the safest option, ensuring globals and
 783           * function variables cannot be overwritten.
 784           */
 785          // phpcs:ignore WordPress.PHP.DontExtract.extract_extract
 786          extract( $wp_query->query_vars, EXTR_SKIP );
 787      }
 788  
 789      if ( isset( $s ) ) {
 790          $s = esc_attr( $s );
 791      }
 792  
 793      if ( $require_once ) {
 794          require_once $_template_file;
 795      } else {
 796          require $_template_file;
 797      }
 798  }