Changeset 48209

Timestamp:

06/28/2020 11:08:57 PM (4 years ago)

Author:

SergeyBiryukov

Message:

Themes: Add a return value to theme functions calling locate_template():

• get_header()
• get_footer()
• get_sidebar()
• get_template_part()

These functions now return false if the template file could not be found, to allow for easier debugging.

Props tferry, sphakka, johnbillion, pento, davidbinda, desrosj, birgire, garrett-eclipse, williampatton, davidbaumwald, SergeyBiryukov.
Fixes #40969.

Location:

trunk

Files:

• src/wp-includes/general-template.php (modified) (8 diffs)
• tests/phpunit/data/themedir1/default/footer.php (added)
• tests/phpunit/data/themedir1/default/header.php (added)
• tests/phpunit/data/themedir1/default/sidebar.php (added)
• tests/phpunit/tests/general/template.php (modified) (1 diff)

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

@@ -17 +17 @@
  *
  * @since 1.5.0
+ * @since 5.5.0 A return value was added.
  *
  * @param string $name The name of the specialised header.
+ * @return void|false Void on success, false if the template does not exist.
  */
 function get_header( $name = null ) {
@@ -39 +41 @@
     $templates[] = 'header.php';
 
-    locate_template( $templates, true );
+    if ( ! locate_template( $templates, true ) ) {
+        return false;
+    }
 }
 
@@ -52 +56 @@
  *
  * @since 1.5.0
+ * @since 5.5.0 A return value was added.
  *
  * @param string $name The name of the specialised footer.
+ * @return void|false Void on success, false if the template does not exist.
  */
 function get_footer( $name = null ) {
@@ -74 +80 @@
     $templates[] = 'footer.php';
 
-    locate_template( $templates, true );
+    if ( ! locate_template( $templates, true ) ) {
+        return false;
+    }
 }
 
@@ -87 +95 @@
  *
  * @since 1.5.0
+ * @since 5.5.0 A return value was added.
  *
  * @param string $name The name of the specialised sidebar.
+ * @return void|false Void on success, false if the template does not exist.
  */
 function get_sidebar( $name = null ) {
@@ -109 +119 @@
     $templates[] = 'sidebar.php';
 
-    locate_template( $templates, true );
+    if ( ! locate_template( $templates, true ) ) {
+        return false;
+    }
 }
 
@@ -129 +141 @@
  *
  * @since 3.0.0
+ * @since 5.5.0 A return value was added.
  *
  * @param string $slug The slug name for the generic template.
  * @param string $name The name of the specialised template.
+ * @return void|false Void on success, false if the template does not exist.
  */
 function get_template_part( $slug, $name = null ) {
@@ -166 +180 @@
     do_action( 'get_template_part', $slug, $name, $templates );
 
-    locate_template( $templates, true, false );
+    if ( ! locate_template( $templates, true, false ) ) {
+        return false;
+    }
 }
 

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

@@ -632 +632 @@
      * @ticket 40969
      */
-    function test_get_template_part_returns_nothing() {
-        ob_start();
+    function test_get_header_returns_nothing_on_success() {
+        $this->expectOutputRegex( '/Header/' );
+
+        // The `get_header()` function must not return anything
+        // due to themes in the wild that may echo its return value.
+        $this->assertNull( get_header() );
+    }
+
+    /**
+     * @ticket 40969
+     */
+    function test_get_footer_returns_nothing_on_success() {
+        $this->expectOutputRegex( '/Footer/' );
+
+        // The `get_footer()` function must not return anything
+        // due to themes in the wild that may echo its return value.
+        $this->assertNull( get_footer() );
+    }
+
+    /**
+     * @ticket 40969
+     */
+    function test_get_sidebar_returns_nothing_on_success() {
+        $this->expectOutputRegex( '/Sidebar/' );
+
+        // The `get_sidebar()` function must not return anything
+        // due to themes in the wild that may echo its return value.
+        $this->assertNull( get_sidebar() );
+    }
+
+    /**
+     * @ticket 40969
+     */
+    function test_get_template_part_returns_nothing_on_success() {
+        $this->expectOutputRegex( '/Template Part/' );
 
         // The `get_template_part()` function must not return anything
         // due to themes in the wild that echo its return value.
-        $part   = get_template_part( 'template', 'part' );
-        $output = ob_get_clean();
-
-        self::assertSame( 'Template Part', trim( $output ) );
-        self::assertSame( null, $part );
+        $this->assertNull( get_template_part( 'template', 'part' ) );
+    }
+
+    /**
+     * @ticket 40969
+     */
+    function test_get_template_part_returns_false_on_failure() {
+        $this->assertFalse( get_template_part( 'non-existing-template' ) );
     }
 }