From 3a962003e9dcbf7015f13baedad08b0a71012a33 Mon Sep 17 00:00:00 2001
From: Pascal Birchler <swissspidy@git.wordpress.org>
Date: Mon, 12 Feb 2024 16:06:47 +0000
Subject: [PATCH] Shortcodes: Always return an array in
 `shortcode_parse_atts()`.

Previously, `shortcode_parse_atts()` would return the input (an empty string) if a shortcode had no attributes, even though the documentation said otherwise.

Always returning an (empty) array reduces confusion and improves developer experience as the return value does not have to be manually checked in the shortcode itself.

Props: nicolefurlan, swissspidy, johnbillion, bedas.
Fixes #59249.

git-svn-id: https://develop.svn.wordpress.org/trunk@57597 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-includes/media.php         |  4 ----
 src/wp-includes/shortcodes.php    | 10 +++++-----
 tests/phpunit/tests/shortcode.php | 27 ++++++++++++++++++++++++---
 3 files changed, 29 insertions(+), 12 deletions(-)

diff --git a/src/wp-includes/media.php b/src/wp-includes/media.php
index 69a6d53299..b5e477e7f7 100644
--- a/src/wp-includes/media.php
+++ b/src/wp-includes/media.php
@@ -2354,10 +2354,6 @@ add_shortcode( 'caption', 'img_caption_shortcode' );
  * @return string HTML content to display the caption.
  */
 function img_caption_shortcode( $attr, $content = '' ) {
-	if ( ! $attr ) {
-		$attr = array();
-	}
-
 	// New-style shortcode with the caption inside the shortcode with the link and image tags.
 	if ( ! isset( $attr['caption'] ) ) {
 		if ( preg_match( '#((?:<a [^>]+>\s*)?<img [^>]+>(?:\s*</a>)?)(.*)#is', $content, $matches ) ) {
diff --git a/src/wp-includes/shortcodes.php b/src/wp-includes/shortcodes.php
index cf88b2195f..bc7ade1a2f 100644
--- a/src/wp-includes/shortcodes.php
+++ b/src/wp-includes/shortcodes.php
@@ -600,11 +600,13 @@ function get_shortcode_atts_regex() {
  * retrieval of the attributes, since all attributes have to be known.
  *
  * @since 2.5.0
+ * @since 6.5.0 The function now always returns an empty array,
+ *              even if the original arguments string cannot be parsed or is empty.
  *
  * @param string $text Shortcode arguments list.
- * @return array|string Array of attribute values keyed by attribute name.
- *                      Returns empty array if there are no attributes.
- *                      Returns the original arguments string if it cannot be parsed.
+ * @return array Array of attribute values keyed by attribute name.
+ *               Returns empty array if there are no attributes
+ *               or if the original arguments string cannot be parsed.
  */
 function shortcode_parse_atts( $text ) {
 	$atts    = array();
@@ -635,8 +637,6 @@ function shortcode_parse_atts( $text ) {
 				}
 			}
 		}
-	} else {
-		$atts = ltrim( $text );
 	}
 
 	return $atts;
diff --git a/tests/phpunit/tests/shortcode.php b/tests/phpunit/tests/shortcode.php
index e8aa82c5a8..2c5b04d02e 100644
--- a/tests/phpunit/tests/shortcode.php
+++ b/tests/phpunit/tests/shortcode.php
@@ -105,9 +105,13 @@ class Tests_Shortcode extends WP_UnitTestCase {
 		return $out;
 	}
 
+	/**
+	 * @ticket 59249
+	 */
 	public function test_noatts() {
 		do_shortcode( '[test-shortcode-tag /]' );
-		$this->assertSame( '', $this->atts );
+		$this->assertIsArray( $this->atts );
+		$this->assertEmpty( $this->atts );
 		$this->assertSame( 'test-shortcode-tag', $this->tagname );
 	}
 
@@ -181,9 +185,13 @@ class Tests_Shortcode extends WP_UnitTestCase {
 		$this->assertSame( 'test-shortcode-tag', $this->tagname );
 	}
 
+	/**
+	 * @ticket 59249
+	 */
 	public function test_noatts_enclosing() {
 		do_shortcode( '[test-shortcode-tag]content[/test-shortcode-tag]' );
-		$this->assertSame( '', $this->atts );
+		$this->assertIsArray( $this->atts );
+		$this->assertEmpty( $this->atts );
 		$this->assertSame( 'content', $this->content );
 		$this->assertSame( 'test-shortcode-tag', $this->tagname );
 	}
@@ -208,10 +216,14 @@ class Tests_Shortcode extends WP_UnitTestCase {
 		$this->assertSame( 'test-shortcode-tag', $this->tagname );
 	}
 
+	/**
+	 * @ticket 59249
+	 */
 	public function test_unclosed() {
 		$out = do_shortcode( '[test-shortcode-tag]' );
 		$this->assertSame( '', $out );
-		$this->assertSame( '', $this->atts );
+		$this->assertIsArray( $this->atts );
+		$this->assertEmpty( $this->atts );
 		$this->assertSame( 'test-shortcode-tag', $this->tagname );
 	}
 
@@ -998,4 +1010,13 @@ EOF;
 		);
 		$this->assertSame( 'test-shortcode-tag', $this->tagname );
 	}
+
+	/**
+	 * @ticket 59249
+	 */
+	public function test_shortcode_parse_atts_empty() {
+		$out = shortcode_parse_atts( '' );
+		$this->assertIsArray( $out, 'Return value is not an array' );
+		$this->assertEmpty( $out, 'Returned array is not empty' );
+	}
 }