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.

git-svn-id: https://develop.svn.wordpress.org/trunk@48209 602fd350-edb4-49c9-b593-d223f7449a82

5 files changed, 65 insertions, 10 deletions

diff --git a/src/wp-includes/general-template.php b/src/wp-includes/general-template.php
index 6827b425e7..d2eccbb617 100644
--- a/src/wp-includes/general-template.php
+++ b/src/wp-includes/general-template.php
@@ -16,8 +16,10 @@
  * "special".
  *
  * @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 ) {
 	/**
@@ -38,7 +40,9 @@ function get_header( $name = null ) {
 
 	$templates[] = 'header.php';
 
-	locate_template( $templates, true );
+	if ( ! locate_template( $templates, true ) ) {
+		return false;
+	}
 }
 
 /**
@@ -51,8 +55,10 @@ function get_header( $name = null ) {
  * "special".
  *
  * @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 ) {
 	/**
@@ -73,7 +79,9 @@ function get_footer( $name = null ) {
 
 	$templates[] = 'footer.php';
 
-	locate_template( $templates, true );
+	if ( ! locate_template( $templates, true ) ) {
+		return false;
+	}
 }
 
 /**
@@ -86,8 +94,10 @@ function get_footer( $name = null ) {
  * "special".
  *
  * @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 ) {
 	/**
@@ -108,7 +118,9 @@ function get_sidebar( $name = null ) {
 
 	$templates[] = 'sidebar.php';
 
-	locate_template( $templates, true );
+	if ( ! locate_template( $templates, true ) ) {
+		return false;
+	}
 }
 
 /**
@@ -128,9 +140,11 @@ function get_sidebar( $name = null ) {
  * "special".
  *
  * @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 ) {
 	/**
@@ -165,7 +179,9 @@ function get_template_part( $slug, $name = null ) {
 	 */
 	do_action( 'get_template_part', $slug, $name, $templates );
 
-	locate_template( $templates, true, false );
+	if ( ! locate_template( $templates, true, false ) ) {
+		return false;
+	}
 }
 
 /**
diff --git a/tests/phpunit/data/themedir1/default/footer.php b/tests/phpunit/data/themedir1/default/footer.php
new file mode 100644
index 0000000000..e36f7f7118
--- /dev/null
+++ b/tests/phpunit/data/themedir1/default/footer.php
@@ -0,0 +1 @@
+Footer
diff --git a/tests/phpunit/data/themedir1/default/header.php b/tests/phpunit/data/themedir1/default/header.php
new file mode 100644
index 0000000000..74fcd1a347
--- /dev/null
+++ b/tests/phpunit/data/themedir1/default/header.php
@@ -0,0 +1 @@
+Header
diff --git a/tests/phpunit/data/themedir1/default/sidebar.php b/tests/phpunit/data/themedir1/default/sidebar.php
new file mode 100644
index 0000000000..96438493b6
--- /dev/null
+++ b/tests/phpunit/data/themedir1/default/sidebar.php
@@ -0,0 +1 @@
+Sidebar
diff --git a/tests/phpunit/tests/general/template.php b/tests/phpunit/tests/general/template.php
index 170a86d9f9..e387a49944 100644
--- a/tests/phpunit/tests/general/template.php
+++ b/tests/phpunit/tests/general/template.php
@@ -631,15 +631,51 @@ class Tests_General_Template extends WP_UnitTestCase {
 	/**
 	 * @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();
+		$this->assertNull( get_template_part( 'template', 'part' ) );
+	}
 
-		self::assertSame( 'Template Part', trim( $output ) );
-		self::assertSame( null, $part );
+	/**
+	 * @ticket 40969
+	 */
+	function test_get_template_part_returns_false_on_failure() {
+		$this->assertFalse( get_template_part( 'non-existing-template' ) );
 	}
 }