Login and Registration: Set correct default values in wp_signon().

The `$credentials['user_login']` and `$credentials['user_password']` parameters are passed by reference to the `wp_authenticate` action, and are at that point [https://www.php.net/manual/en/language.references.pass.php#124383 created as null] if they don't exist in the array.

This commit sets those values to an empty string, resolving two PHP 8.1 deprecation notices:
 * One from `preg_replace()` in `wp_strip_all_tags()` via `sanitize_user()` in `wp_authenticate()`:
{{{
Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated
}}}
 * One from `trim()` in `wp_authenticate()` itself:
{{{
Deprecated: trim(): Passing null to parameter #1 ($string) of type string is deprecated
}}}

Includes documenting the `$credentials` parameter using hash notation.

Follow-up to [6643], [37697].

Props lenasterg, TobiasBg, ocean90, afragen, lkraav, SergeyBiryukov.
Fixes #56850.

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

Author: SergeyBiryukov

src/wp-includes/user.php

@@ -26,13 +26,24 @@
  *
  * @global string $auth_secure_cookie
  *
- * @param array       $credentials   Optional. User info in order to sign on.
+ * @param array       $credentials {
+ *     Optional. User info in order to sign on.
+ *
+ *     @type string $user_login    Username.
+ *     @type string $user_password User password.
+ *     @type bool   $remember      Whether to 'remember' the user. Increases the time
+ *                                 that the cookie will be kept. Default false.
+ * }
  * @param string|bool $secure_cookie Optional. Whether to use secure cookie.
  * @return WP_User|WP_Error WP_User on success, WP_Error on failure.
  */
 function wp_signon( $credentials = array(), $secure_cookie = '' ) {
 	if ( empty( $credentials ) ) {
-		$credentials = array(); // Back-compat for plugins passing an empty string.
+		$credentials = array(
+			'user_login'    => '',
+			'user_password' => '',
+			'remember'      => false,
+		);
 
 		if ( ! empty( $_POST['log'] ) ) {
 			$credentials['user_login'] = wp_unslash( $_POST['log'] );

tests/phpunit/tests/auth.php

@@ -444,6 +444,25 @@ public function test_wp_signon_using_email_with_an_apostrophe() {
 		$this->assertInstanceOf( 'WP_User', wp_signon() );
 	}
 
+	/**
+	 * Tests that PHP 8.1 "passing null to non-nullable" deprecation notices
+	 * are not thrown when `user_login` and `user_password` parameters are empty.
+	 *
+	 * The notices that we should not see:
+	 * `Deprecated: preg_replace(): Passing null to parameter #3 ($subject) of type array|string is deprecated`.
+	 * `Deprecated: trim(): Passing null to parameter #1 ($string) of type string is deprecated`.
+	 *
+	 * @ticket 56850
+	 */
+	public function test_wp_signon_does_not_throw_deprecation_notices_with_default_parameters() {
+		$error = wp_signon();
+		$this->assertWPError( $error, 'The result should be an instance of WP_Error.' );
+
+		$error_codes = $error->get_error_codes();
+		$this->assertContains( 'empty_username', $error_codes, 'The "empty_username" error code should be present.' );
+		$this->assertContains( 'empty_password', $error_codes, 'The "empty_password" error code should be present.' );
+	}
+
 	/**
 	 * HTTP Auth headers are used to determine the current user.
 	 *