Docs: Indicate that get_posts() can take a query string in addition to an array of query vars.

A string is supported by virtue of `wp_parse_args()` being used on the supplied arguments. While a string is not currently passed to `get_posts()` in core, a significant number of plugins are doing so. So in addition to documenting actual ecosystem usage, this also adds a test to ensure that supplying a query string continues to be supported in the future.

Developed in WordPress#11179

Follow-up to r11528.

Props rodrigosprimo, westonruter, shailu25, mukesh27.
See #64224, WordPress#10047.
Fixes #64813.


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

Author: westonruter

src/wp-includes/post.php

@@ -2599,8 +2599,9 @@ function is_post_embeddable( $post = null ) {
  * @see WP_Query
  * @see WP_Query::parse_query()
  *
- * @param array $args {
- *     Optional. Arguments to retrieve posts. See WP_Query::parse_query() for all available arguments.
+ * @param array|string $args {
+ *     Optional. Array or query string of arguments to retrieve posts.
+ *     See WP_Query::parse_query() for all available arguments.
  *
  *     @type int        $numberposts      Total number of posts to retrieve. Is an alias of `$posts_per_page`
  *                                        in WP_Query. Accepts -1 for all. Default 5.

tests/phpunit/tests/post/getPosts.php

@@ -163,4 +163,17 @@ public function test_explicit_offset_non_0_should_override_paged() {
 
 		$this->assertSame( array( $p3 ), $found );
 	}
+
+	/**
+	 * Verifies that get_posts() accepts a query string for the `$args` parameter.
+	 *
+	 * @ticket 64813
+	 */
+	public function test_should_accept_query_string_args(): void {
+		self::factory()->post->create();
+		$second_post_id = self::factory()->post->create();
+		$found_post_ids = get_posts( 'numberposts=1&fields=ids' );
+
+		$this->assertSame( array( $second_post_id ), $found_post_ids );
+	}
 }