Ticket #38249: 38249.patch

src/wp-includes/template.php

@@ -144 +144 @@
 /**
  * Retrieve path of author template in current or parent template.
  *
+ * The hierarchy for this template looks like:
+ *
+ *     1. author-{nicename}.php
+ *     2. author-{id}.php
+ *     3. author.php
+ * 
+ * An example of this is:
+ *
+ *     1. author-john.php
+ *     2. author-1.php
+ *     3. author.php
+ * 
  * The template hierarchy is filterable via the {@see 'author_template_hierarchy'} hook.
  * The template path is filterable via the {@see 'author_template'} hook.
  *
@@ -170 +182 @@
 /**
  * Retrieve path of category template in current or parent template.
  *
- * Works by first retrieving the current slug, for example 'category-default.php',
- * and then trying category ID, for example 'category-1.php', and will finally fall
- * back to category.php template, if those files don't exist.
+ * The hierarchy for this template looks like:
  *
+ *     1. category-{slug}.php
+ *     2. category-{id}.php
+ *     3. category.php
+ * 
+ * An example of this is:
+ *
+ *     1. category-news.php
+ *     2. category-2.php
+ *     3. category.php
+ * 
  * The template hierarchy is filterable via the {@see 'category_template_hierarchy'} hook.
  * The template path is filterable via the {@see 'category_template'} hook.
  *
  * @since 1.5.0
+ * @since 4.7.0 The decoded form of `category-{slug}.php` was added to the top of the
+ *              template hierarchy when the category slug contains multibyte characters.
  *
  * @see get_query_template()
  *
@@ -206 +228 @@
 /**
  * Retrieve path of tag template in current or parent template.
  *
- * Works by first retrieving the current tag name, for example 'tag-wordpress.php',
- * and then trying tag ID, for example 'tag-1.php', and will finally fall back to
- * tag.php template, if those files don't exist.
+ * The hierarchy for this template looks like:
  *
+ *     1. tag-{slug}.php
+ *     2. tag-{id}.php
+ *     3. tag.php
+ * 
+ * An example of this is:
+ *
+ *     1. tag-wordpress.php
+ *     2. tag-3.php
+ *     3. tag.php
+ * 
  * The template hierarchy is filterable via the {@see 'tag_template_hierarchy'} hook.
  * The template path is filterable via the {@see 'tag_template'} hook.
  *
  * @since 2.3.0
+ * @since 4.7.0 The decoded form of `tag-{slug}.php` was added to the top of the
+ *              template hierarchy when the tag slug contains multibyte characters.
  *
  * @see get_query_template()
  *
@@ -240 +272 @@
 }
 
 /**
- * Retrieve path of taxonomy template in current or parent template.
+ * Retrieve path of custom taxonomy term template in current or parent template.
+ *
+ * The hierarchy for this template looks like:
+ *
+ *     1. taxonomy-{taxonomy_slug}-{term_slug}.php
+ *     2. taxonomy-{taxonomy_slug}.php
+ *     3. taxonomy.php
  *
- * Retrieves the taxonomy and term, if term is available. The template is
- * prepended with 'taxonomy-' and followed by both the taxonomy string and
- * the taxonomy string followed by a dash and then followed by the term.
- *
- * The taxonomy and term template is checked and used first, if it exists.
- * Second, just the taxonomy template is checked, and then finally, taxonomy.php
- * template is used. If none of the files exist, then it will fall back on to
- * index.php.
+ * An example of this is:
+ *
+ *     1. taxonomy-location-texas.php
+ *     2. taxonomy-location.php
+ *     3. taxonomy.php
  *
  * The template hierarchy is filterable via the {@see 'taxonomy_template_hierarchy'} hook.
  * The template path is filterable via the {@see 'taxonomy_template'} hook.
  *
  * @since 2.5.0
+ * @since 4.7.0 The decoded form of `taxonomy-{taxonomy_slug}-{term_slug}.php` was added to the top of the
+ *              template hierarchy when the term slug contains multibyte characters.
  *
  * @see get_query_template()
  *
- * @return string Full path to taxonomy template file.
+ * @return string Full path to custom taxonomy term template file.
  */
 function get_taxonomy_template() {
         $term = get_queried_object();
@@ -300 +337 @@
 /**
  * Retrieve path of home template in current or parent template.
  *
- * This is the template used for the page containing the blog posts.
- * Attempts to locate 'home.php' first before falling back to 'index.php'.
- *
  * The template hierarchy is filterable via the {@see 'home_template_hierarchy'} hook.
  * The template path is filterable via the {@see 'home_template'} hook.
  *
@@ -339 +373 @@
 /**
  * Retrieve path of page template in current or parent template.
  *
- * Will first look for the specifically assigned page template.
- * Then will search for 'page-{slug}.php', followed by 'page-{id}.php',
- * and finally 'page.php'.
+ * The hierarchy for this template looks like:
+ *
+ *     1. {Page template}
+ *     2. page-{page_name}.php
+ *     3. page-{id}.php
+ *     4. page.php
+ *
+ * An example of this is:
+ *
+ *     1. page-templates/full-width.php
+ *     2. page-about.php
+ *     3. page-4.php
+ *     4. page.php
  *
  * The template hierarchy is filterable via the {@see 'page_template_hierarchy'} hook.
  * The template path is filterable via the {@see 'page_template'} hook.
  *
  * @since 1.5.0
+ * @since 4.7.0 The decoded form of `page-{page_name}.php` was added to the top of the
+ *              template hierarchy when the page name contains multibyte characters.
  *
  * @see get_query_template()
  *
@@ -416 +462 @@
 /**
  * Retrieve path of single template in current or parent template.
  *
+ * The hierarchy for this template looks like:
+ *
+ *     1. single-{post_type}-{post_name}.php
+ *     2. single-{post_type}.php
+ *     3. single.php
+ * 
+ * An example of this is:
+ *
+ *     1. single-post-hello-world.php
+ *     2. single-post.php
+ *     3. single.php
+ * 
  * The template hierarchy is filterable via the {@see 'single_template_hierarchy'} hook.
  * The template path is filterable via the {@see 'single_template'} hook.
  *
  * @since 1.5.0
  * @since 4.4.0 `single-{post_type}-{post_name}.php` was added to the top of the template hierarchy.
+ * @since 4.7.0 The decoded form of `single-{post_type}-{post_name}.php` was added to the top of the
+ *              template hierarchy when the post name contains multibyte characters.
  *
  * @see get_query_template()
  *
@@ -450 +510 @@
 /**
  * Retrieves an embed template path in the current or parent template.
  *
- * By default the WordPress-template is returned.
+ * The hierarchy for this template looks like:
+ *
+ *     1. embed-{post_type}-{post_format}.php
+ *     2. embed-{post_type}.php
+ *     3. embed.php
+ *
+ * An example of this is:
+ *
+ *     1. embed-post-audio.php
+ *     2. embed-post.php
+ *     3. embed.php
  *
  * The template hierarchy is filterable via the {@see 'embed_template_hierarchy'} hook.
  * The template path is filterable via the {@see 'embed_template'} hook.
@@ -498 +568 @@
 /**
  * Retrieve path of attachment template in current or parent template.
  *
- * The attachment path first checks if the first part of the mime type exists.
- * The second check is for the second part of the mime type. The last check is
- * for both types separated by an underscore. If neither are found then the file
- * 'attachment.php' is checked and returned.
+ * The hierarchy for this template looks like:
  *
- * Some examples for the 'text/plain' mime type are 'text.php', 'plain.php', and
- * finally 'text-plain.php'.
+ *     1. {mime_type}-{sub_type}.php
+ *     2. {sub_type}.php
+ *     3. {mime_type}.php
+ *     4. attachment.php
+ *
+ * An example of this is:
+ *
+ *     1. image-jpeg.php
+ *     2. jpeg.php
+ *     3. image.php
+ *     4. attachment.php
  *
  * The template hierarchy is filterable via the {@see 'attachment_template_hierarchy'} hook.
  * The template path is filterable via the {@see 'attachment_template'} hook.
  *
  * @since 2.0.0
+ * @since 4.3.0 The order of the mime type logic was reversed so the hierarchy is more logical.
  *
  * @see get_query_template()
  *