Passwords: Deprecate second parameter of `wp_new_user_notification()`.

The second parameter `$plaintext_pass` was removed in [33023] and restored as `$notify` in [33620] with a different behavior. If you have a plugin overriding `wp_new_user_notification()` which hasn't been updated you would get a notification with your username and the password "both".
To prevent this the second parameter is now deprecated and reintroduced as the third parameter.

Adds unit tests.

Props kraftbj, adamsilverstein, welcher, ocean90.
Fixes #33654.

(Don't ask for new pluggables kthxbye)

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

src/wp-admin/includes/user.php

@@ -176,7 +176,7 @@ function edit_user( $user_id = 0 ) {
 		$user_id = wp_update_user( $user );
 	} else {
 		$user_id = wp_insert_user( $user );
-		wp_new_user_notification( $user_id, 'both' );
+		wp_new_user_notification( $user_id, null, 'both' );
 	}
 	return $user_id;
 }

src/wp-admin/network/site-new.php

@@ -94,7 +94,7 @@ if ( wp_validate_action( 'add-site' ) ) {
 		if ( false === $user_id )
 			wp_die( __( 'There was an error creating the user.' ) );
 		else
-			wp_new_user_notification( $user_id, 'both' );
+			wp_new_user_notification( $user_id, null, 'both' );
 	}
 
 	$wpdb->hide_errors();

src/wp-admin/network/site-users.php

@@ -77,7 +77,7 @@ if ( $action ) {
 				if ( false === $user_id ) {
 		 			$update = 'err_new_dup';
 				} else {
-					wp_new_user_notification( $user_id, 'both' );
+					wp_new_user_notification( $user_id, null, 'both' );
 					add_user_to_blog( $id, $user_id, $_POST['new_role'] );
 					$update = 'newuser';
 				}

src/wp-admin/network/user-new.php

@@ -51,7 +51,7 @@ if ( wp_validate_action( 'add-user' ) ) {
 		if ( ! $user_id ) {
 	 		$add_user_errors = new WP_Error( 'add_user_fail', __( 'Cannot add user.' ) );
 		} else {
-			wp_new_user_notification( $user_id, 'both' );
+			wp_new_user_notification( $user_id, null, 'both' );
 			wp_redirect( add_query_arg( array('update' => 'added'), 'user-new.php' ) );
 			exit;
 		}

src/wp-includes/pluggable.php

@@ -1690,16 +1690,22 @@ if ( !function_exists('wp_new_user_notification') ) :
  *
  * @since 2.0.0
  * @since 4.3.0 The `$plaintext_pass` parameter was changed to `$notify`.
+ * @since 4.3.1 The `$plaintext_pass` parameter was deprecated. `$notify` added as a third parameter.
  *
  * @global wpdb         $wpdb      WordPress database object for queries.
  * @global PasswordHash $wp_hasher Portable PHP password hashing framework instance.
  *
- * @param int    $user_id User ID.
- * @param string $notify  Optional. Type of notification that should happen. Accepts 'admin' or an empty
- *                        string (admin only), or 'both' (admin and user). The empty string value was kept
- *                        for backward-compatibility purposes with the renamed parameter. Default empty.
+ * @param int    $user_id    User ID.
+ * @param null   $deprecated Not used (argument deprecated).
+ * @param string $notify     Optional. Type of notification that should happen. Accepts 'admin' or an empty
+ *                           string (admin only), or 'both' (admin and user). The empty string value was kept
+ *                           for backward-compatibility purposes with the renamed parameter. Default empty.
  */
-function wp_new_user_notification( $user_id, $notify = '' ) {
+function wp_new_user_notification( $user_id, $deprecated = null, $notify = '' ) {
+	if ( $deprecated !== null ) {
+		_deprecated_argument( __FUNCTION__, '4.3.1' );
+	}
+
 	global $wpdb, $wp_hasher;
 	$user = get_userdata( $user_id );
 

src/wp-includes/user-functions.php

@@ -2012,7 +2012,7 @@ function register_new_user( $user_login, $user_email ) {
 
 	update_user_option( $user_id, 'default_password_nag', true, true ); //Set up the Password change nag.
 
-	wp_new_user_notification( $user_id, 'both' );
+	wp_new_user_notification( $user_id, null, 'both' );
 
 	return $user_id;
 }

tests/phpunit/tests/user.php

@@ -679,4 +679,86 @@ class Tests_User extends WP_UnitTestCase {
 		$this->assertEquals( $user->user_email, 'test2@test.com' );
 	}
 
+	/**
+	 * Testing wp_new_user_notification email statuses.
+	 *
+	 * @dataProvider data_wp_new_user_notifications
+	 * @ticket 33654
+	 */
+	function test_wp_new_user_notification( $notify, $admin_email_sent_expected, $user_email_sent_expected ) {
+		unset( $GLOBALS['phpmailer']->mock_sent );
+
+		$was_admin_email_sent = false;
+		$was_user_email_sent = false;
+
+		$user = $this->factory->user->create( $this->user_data );
+
+		wp_new_user_notification( $user, null, $notify );
+
+		/*
+		 * Check to see if a notification email was sent to the
+		 * post author `blackburn@battlefield3.com` and and site admin `admin@example.org`.
+		 */
+		if ( ! empty( $GLOBALS['phpmailer']->mock_sent ) ) {
+			$was_admin_email_sent = ( isset( $GLOBALS['phpmailer']->mock_sent[0] ) && WP_TESTS_EMAIL == $GLOBALS['phpmailer']->mock_sent[0]['to'][0][0] );
+			$was_user_email_sent = ( isset( $GLOBALS['phpmailer']->mock_sent[1] ) && 'blackburn@battlefield3.com' == $GLOBALS['phpmailer']->mock_sent[1]['to'][0][0] );
+		}
+
+		$this->assertSame( $admin_email_sent_expected, $was_admin_email_sent, 'Admin email result was not as expected in test_wp_new_user_notification' );
+		$this->assertSame( $user_email_sent_expected , $was_user_email_sent, 'User email result was not as expected in test_wp_new_user_notification' );
+	}
+
+	/**
+	 * Data provider for test_wp_new_user_notification().
+	 *
+	 * Passes the three available options for the $notify parameter and the expected email
+	 * emails sent status as a bool.
+	 *
+	 * @return array {
+	 *     @type array {
+	 *         @type string $post_args               The arguments that will merged with the $_POST array.
+	 *         @type bool $admin_email_sent_expected The expected result of whether an email was sent to the admin.
+	 *         @type bool $user_email_sent_expected  The expected result of whether an email was sent to the user.
+	 *     }
+	 * }
+	 */
+	function data_wp_new_user_notifications() {
+		return array(
+			array(
+				'',
+				true,
+				false,
+			),
+			array(
+				'admin',
+				true,
+				false,
+			),
+			array(
+				'both',
+				true,
+				true,
+			),
+		);
+	}
+
+	/**
+	 * Set up a user and try sending a notification using the old, deprecated
+	 * function signature `wp_new_user_notification( $user, 'plaintext_password' );`.
+	 *
+	 * @ticket 33654
+	 * @expectedDeprecated wp_new_user_notification
+	 */
+	function test_wp_new_user_notification_old_signature_throws_deprecated_warning() {
+		$user = $this->factory->user->create(
+			array(
+				'role'       => 'author',
+				'user_login' => 'test_wp_new_user_notification',
+				'user_pass'  => 'password',
+				'user_email' => 'test@test.com',
+			)
+		);
+
+		wp_new_user_notification( $user, 'this_is_deprecated' );
+	}
 }