Changeset 56635

Timestamp:

09/20/2023 05:25:26 PM (11 months ago)

Author:

flixos90

Message:

Themes: Deprecate usage of TEMPLATEPATH and STYLESHEETPATH constants.

While generally the functions get_template_directory() and get_stylesheet_directory() were long recommended to use to get the parent or child theme directory, the TEMPLATEPATH and STYLESHEETPATH constants were still used in a few places in core, most importantly in template related logic.

The remaining usage was problematic as it prevented testability of certain key components of WordPress core.

This changeset replaces all remaining usage with the corresponding functions and effectively marks these constants as deprecated. It also adds test coverage accordingly and even unlocks some existing, previously commented out test coverage to work as expected.

Performance of the new approach has been benchmarked and shows no notable differences. Yet, given that the current theme directories are not expected to change within a regular WordPress page load, the get_template_directory() and get_stylesheet_directory() functions were amended with in-memory caching of the result, unless one of the defining values is being filtered.

Props thekt12, spacedmonkey, mukesh27, aaroncampbell, scribu, lloydbudd, cais, chipbennett, toscho, omarabid, CrazyJaco, DrewAPicture, obenland, wonderboymusic, nacin, helen, dd32, chriscct7, SergeyBiryukov, swissspidy, joemcgill, flixos90.
Fixes #18298.

Location:

trunk

Files:

• src/wp-admin/includes/theme.php (modified) (1 diff)
• src/wp-includes/comment-template.php (modified) (3 diffs)
• src/wp-includes/default-constants.php (modified) (2 diffs)
• src/wp-includes/load.php (modified) (1 diff)
• src/wp-includes/template.php (modified) (3 diffs)
• src/wp-includes/theme.php (modified) (5 diffs)
• tests/phpunit/tests/comment/commentsTemplate.php (modified) (1 diff)
• tests/phpunit/tests/comment/wpListComments.php (modified) (1 diff)
• tests/phpunit/tests/general/template.php (modified) (2 diffs)
• tests/phpunit/tests/template.php (modified) (1 diff)
• tests/phpunit/tests/theme.php (modified) (7 diffs)

trunk/src/wp-admin/includes/theme.php

@@ -1167 +1167 @@
      */
     if ( ! empty( $redirect ) ) {
+
+
+
         $functions_path = '';
-        if ( str_contains( STYLESHEETPATH, $extension ) ) {
-            $functions_path = STYLESHEETPATH . '/functions.php';
-        } elseif ( str_contains( TEMPLATEPATH, $extension ) ) {
-            $functions_path = TEMPLATEPATH . '/functions.php';
+        if ( str_contains( , $extension ) ) {
+            $functions_path =  . '/functions.php';
+        } elseif ( str_contains( , $extension ) ) {
+            $functions_path =  . '/functions.php';
         }
 

trunk/src/wp-includes/comment-template.php

@@ -1382 +1382 @@
  *
  * The `$file` path is passed through a filter hook called {@see 'comments_template'},
- * which includes the TEMPLATEPATH and $file combined. Tries the $filtered path
+ * which includes the  and $file combined. Tries the $filtered path
  * first and if it fails it will require the default comment template from the
  * default theme. If either does not exist, then the WordPress process will be
@@ -1601 +1601 @@
     }
 
-    $theme_template = STYLESHEETPATH . $file;
+    $stylesheet_path = get_stylesheet_directory();
+    $template_path   = get_template_directory();
+
+    $theme_template = $stylesheet_path . $file;
 
     /**
@@ -1614 +1617 @@
     if ( file_exists( $include ) ) {
         require $include;
-    } elseif ( file_exists( TEMPLATEPATH . $file ) ) {
-        require TEMPLATEPATH . $file;
+    } elseif ( file_exists(  . $file ) ) {
+        require  . $file;
     } else { // Backward compat code will be removed in a future release.
         require ABSPATH . WPINC . '/theme-compat/comments.php';

trunk/src/wp-includes/default-constants.php

@@ -408 +408 @@
      *
      * @since 1.5.0
+
+
      */
     define( 'TEMPLATEPATH', get_template_directory() );
@@ -415 +417 @@
      *
      * @since 2.1.0
+
+
      */
     define( 'STYLESHEETPATH', get_stylesheet_directory() );

trunk/src/wp-includes/load.php

@@ -1050 +1050 @@
     }
 
-    if ( TEMPLATEPATH !== STYLESHEETPATH ) {
-        $themes[] = STYLESHEETPATH;
-    }
-
-    $themes[] = TEMPLATEPATH;
+    $stylesheet_path = get_stylesheet_directory();
+    $template_path   = get_template_directory();
+
+    if ( $template_path !== $stylesheet_path ) {
+        $themes[] = $stylesheet_path;
+    }
+
+    $themes[] = $template_path;
 
     /*

trunk/src/wp-includes/template.php

@@ -685 +685 @@
  * Retrieves the name of the highest priority template file that exists.
  *
- * Searches in the STYLESHEETPATH before TEMPLATEPATH and wp-includes/theme-compat
- * so that themes which inherit from a parent theme can just overload one file.
+ * Searches in the stylesheet directory before the template directory and
+ * wp-includes/theme-compat so that themes which inherit from a parent theme
+ * can just overload one file.
  *
  * @since 2.7.0
@@ -700 +701 @@
  */
 function locate_template( $template_names, $load = false, $load_once = true, $args = array() ) {
+
+
+
+
     $located = '';
     foreach ( (array) $template_names as $template_name ) {
@@ -705 +710 @@
             continue;
         }
-        if ( file_exists( STYLESHEETPATH . '/' . $template_name ) ) {
-            $located = STYLESHEETPATH . '/' . $template_name;
+        if ( file_exists(  . '/' . $template_name ) ) {
+            $located =  . '/' . $template_name;
             break;
-        } elseif ( is_child_theme() && file_exists( TEMPLATEPATH . '/' . $template_name ) ) {
-            $located = TEMPLATEPATH . '/' . $template_name;
+        } elseif (  . '/' . $template_name ) ) {
+            $located =  . '/' . $template_name;
             break;
         } elseif ( file_exists( ABSPATH . WPINC . '/theme-compat/' . $template_name ) ) {

trunk/src/wp-includes/theme.php

@@ -158 +158 @@
  */
 function is_child_theme() {
-    return ( TEMPLATEPATH !== STYLESHEETPATH );
+    return );
 }
 
@@ -188 +188 @@
  *
  * @since 1.5.0
+
+
+
  *
  * @return string Path to active theme's stylesheet directory.
  */
 function get_stylesheet_directory() {
-    $stylesheet     = get_stylesheet();
-    $theme_root     = get_theme_root( $stylesheet );
-    $stylesheet_dir = "$theme_root/$stylesheet";
-
-    /**
-     * Filters the stylesheet directory path for the active theme.
-     *
-     * @since 1.5.0
-     *
-     * @param string $stylesheet_dir Absolute path to the active theme.
-     * @param string $stylesheet     Directory name of the active theme.
-     * @param string $theme_root     Absolute path to themes directory.
-     */
-    return apply_filters( 'stylesheet_directory', $stylesheet_dir, $stylesheet, $theme_root );
+    global $wp_stylesheet_path;
+
+    if ( null === $wp_stylesheet_path ) {
+        $stylesheet     = get_stylesheet();
+        $theme_root     = get_theme_root( $stylesheet );
+        $stylesheet_dir = "$theme_root/$stylesheet";
+
+        /**
+         * Filters the stylesheet directory path for the active theme.
+         *
+         * @since 1.5.0
+         *
+         * @param string $stylesheet_dir Absolute path to the active theme.
+         * @param string $stylesheet     Directory name of the active theme.
+         * @param string $theme_root     Absolute path to themes directory.
+         */
+        $stylesheet_dir = apply_filters( 'stylesheet_directory', $stylesheet_dir, $stylesheet, $theme_root );
+
+        // If there are filter callbacks, force the logic to execute on every call.
+        if ( has_filter( 'stylesheet' ) || has_filter( 'theme_root' ) || has_filter( 'stylesheet_directory' ) ) {
+            return $stylesheet_dir;
+        }
+
+        $wp_stylesheet_path = $stylesheet_dir;
+    }
+
+    return $wp_stylesheet_path;
 }
 
@@ -322 +338 @@
  *
  * @since 1.5.0
+
+
+
  *
  * @return string Path to active theme's template directory.
  */
 function get_template_directory() {
-    $template     = get_template();
-    $theme_root   = get_theme_root( $template );
-    $template_dir = "$theme_root/$template";
-
-    /**
-     * Filters the active theme directory path.
-     *
-     * @since 1.5.0
-     *
-     * @param string $template_dir The path of the active theme directory.
-     * @param string $template     Directory name of the active theme.
-     * @param string $theme_root   Absolute path to the themes directory.
-     */
-    return apply_filters( 'template_directory', $template_dir, $template, $theme_root );
+    global $wp_template_path;
+
+    if ( null === $wp_template_path ) {
+        $template     = get_template();
+        $theme_root   = get_theme_root( $template );
+        $template_dir = "$theme_root/$template";
+
+        /**
+         * Filters the active theme directory path.
+         *
+         * @since 1.5.0
+         *
+         * @param string $template_dir The path of the active theme directory.
+         * @param string $template     Directory name of the active theme.
+         * @param string $theme_root   Absolute path to the themes directory.
+         */
+        $template_dir = apply_filters( 'template_directory', $template_dir, $template, $theme_root );
+
+        // If there are filter callbacks, force the logic to execute on every call.
+        if ( has_filter( 'template' ) || has_filter( 'theme_root' ) || has_filter( 'template_directory' ) ) {
+            return $template_dir;
+        }
+
+        $wp_template_path = $template_dir;
+    }
+
+    return $wp_template_path;
 }
 
@@ -745 +777 @@
  * @global array                $sidebars_widgets
  * @global array                $wp_registered_sidebars
+
+
  *
  * @param string $stylesheet Stylesheet name.
  */
 function switch_theme( $stylesheet ) {
-    global $wp_theme_directories, $wp_customize, $sidebars_widgets, $wp_registered_sidebars;
+    global $wp_theme_directories, $wp_customize, $sidebars_widgets, $wp_registered_sidebars;
 
     $requirements = validate_theme_requirements( $stylesheet );
@@ -832 +866 @@
 
     update_option( 'theme_switched', $old_theme->get_stylesheet() );
+
+
+
+
+
+
+
 
     /**

trunk/tests/phpunit/tests/comment/commentsTemplate.php

@@ -11 +11 @@
 
     /**
+
+
+
+
+
+
+
+
      * @ticket 8071
      */

trunk/tests/phpunit/tests/comment/wpListComments.php

@@ -7 +7 @@
  */
 class Tests_Comment_WpListComments extends WP_UnitTestCase {
+
+
+
+
+
+
+
+
+
     /**
      * @ticket 35175

trunk/tests/phpunit/tests/general/template.php

@@ -11 +11 @@
 
 class Tests_General_Template extends WP_UnitTestCase {
+
     protected $wp_site_icon;
     public $site_icon_id;
@@ -42 +43 @@
         parent::set_up();
 
+
         $this->wp_site_icon = new WP_Site_Icon();
     }

trunk/tests/phpunit/tests/template.php

@@ -628 +628 @@
             ),
         );
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
     }
 

trunk/tests/phpunit/tests/theme.php

@@ -37 +37 @@
         parent::set_up();
 
+
         $this->orig_theme_dir = $wp_theme_directories;
-        $wp_theme_directories = array( WP_CONTENT_DIR . '/themes' );
+        $wp_theme_directories = array( WP_CONTENT_DIR . '/themes' );
 
         add_filter( 'extra_theme_headers', array( $this, 'theme_data_extra_headers' ) );
@@ -283 +284 @@
         for ( $i = 0; $i < 3; $i++ ) {
             foreach ( $themes as $name => $theme ) {
+
+
+
+
+
                 // Switch to this theme.
                 if ( 2 === $i ) {
@@ -290 +296 @@
                 }
 
-                $this->assertSame( $name, get_current_theme() );
+                $this->assertSame( $, get_current_theme() );
 
                 // Make sure the various get_* functions return the correct values.
@@ -296 +302 @@
                 $this->assertSame( $theme['Stylesheet'], get_stylesheet() );
 
-                $root_fs = get_theme_root();
+                $root_fs = get_theme_root();
                 $this->assertTrue( is_dir( $root_fs ) );
 
-                $root_uri = get_theme_root_uri();
+                $root_uri = get_theme_root_uri();
                 $this->assertNotEmpty( $root_uri );
 
@@ -310 +316 @@
                 $this->assertSame( $root_uri . '/' . get_template(), get_template_directory_uri() );
 
-                // get_query_template()
+                // Skip block themes for get_query_template() tests since this test is focused on classic templates.
+                if ( wp_is_block_theme() && current_theme_supports( 'block-templates' ) ) {
+                    continue;
+                }
 
                 // Template file that doesn't exist.
@@ -316 +325 @@
 
                 // Template files that do exist.
-                /*
                 foreach ( $theme['Template Files'] as $path ) {
-                    $file = basename($path, '.php');
-                    FIXME: untestable because get_query_template() uses TEMPLATEPATH.
-                    $this->assertSame('', get_query_template($file));
+                    $file = basename( $path, '.php' );
+
+                    // The functions.php file is not a template.
+                    if ( 'functions' === $file ) {
+                        continue;
+                    }
+
+                    // Underscores are not supported by `locate_template()`.
+                    if ( 'taxonomy-post_format' === $file ) {
+                        $file = 'taxonomy';
+                    }
+
+                    $child_theme_file  = get_stylesheet_directory() . '/' . $file . '.php';
+                    $parent_theme_file = get_template_directory() . '/' . $file . '.php';
+                    if ( file_exists( $child_theme_file ) ) {
+                        $this->assertSame( $child_theme_file, get_query_template( $file ) );
+                    } elseif ( file_exists( $parent_theme_file ) ) {
+                        $this->assertSame( $parent_theme_file, get_query_template( $file ) );
+                    } else {
+                        $this->assertSame( '', get_query_template( $file ) );
+                    }
                 }
-                */
 
                 // These are kind of tautologies but at least exercise the code.
@@ -856 +881 @@
 
     /**
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
      * Helper function to ensure that a block theme is available and active.
      */