enmi-conf.org: comparison wp/wp-includes/pluggable.php

equal deleted inserted replaced

-:3d4e9c994f10
+:a86126ab1dd4
 	 * Some WordPress functionality is based on the current user and not based on
 	 * the signed in user. Therefore, it opens the ability to edit and perform
 	 * actions on users who aren't signed in.
 	 *
 	 * @since 2.0.3
+	 *
 	 * @global WP_User $current_user The current user object which holds the user data.
 	 *
 	 * @param int    $id   User ID
 	 * @param string $name User's username
 	 * @return WP_User Current user User object
 	}
 endif;
 if ( ! function_exists( 'wp_mail' ) ) :
 	/**
-	 * Send mail, similar to PHP's mail
+	 * Sends an email, similar to PHP's mail function.
 	 *
 	 * A true return value does not automatically mean that the user received the
 	 * email successfully. It just only means that the method used was able to
 	 * process the request without any errors.
 	 *
-	 * Using the two 'wp_mail_from' and 'wp_mail_from_name' hooks allow from
+	 * The default content type is `text/plain` which does not allow using HTML.
-	 * creating a from address like 'Name <email@address.com>' when both are set. If
-	 * just 'wp_mail_from' is set, then just the email address will be used with no
-	 * name.
-	 *
-	 * The default content type is 'text/plain' which does not allow using HTML.
 	 * However, you can set the content type of the email by using the
 	 * {@see 'wp_mail_content_type'} filter.
 	 *
 	 * The default charset is based on the charset used on the blog. The charset can
 	 * be set using the {@see 'wp_mail_charset'} filter.
 	 *
 	 * @since 1.2.1
 	 *
-	 * @global PHPMailer $phpmailer
+	 * @global PHPMailer\PHPMailer\PHPMailer $phpmailer
 	 *
 	 * @param string|array $to          Array or comma-separated list of email addresses to send message.
 	 * @param string       $subject     Email subject
 	 * @param string       $message     Message contents
 	 * @param string|array $headers     Optional. Additional headers.
 	 * @param string|array $attachments Optional. Files to attach.
 	 * @return bool Whether the email contents were sent successfully.
 	 */
 	function wp_mail( $to, $subject, $message, $headers = '', $attachments = array() ) {
-		// Compact the input, apply the filters, and extract them back out
+		// Compact the input, apply the filters, and extract them back out.
 		/**
 		 * Filters the wp_mail() arguments.
 		 *
 		 * @since 2.2.0
 		if ( ! is_array( $attachments ) ) {
 			$attachments = explode( "\n", str_replace( "\r\n", "\n", $attachments ) );
 		}
 		global $phpmailer;
-		// (Re)create it, if it's gone missing
+		// (Re)create it, if it's gone missing.
-		if ( ! ( $phpmailer instanceof PHPMailer ) ) {
+		if ( ! ( $phpmailer instanceof PHPMailer\PHPMailer\PHPMailer ) ) {
-			require_once ABSPATH . WPINC . '/class-phpmailer.php';
+			require_once ABSPATH . WPINC . '/PHPMailer/PHPMailer.php';
-			require_once ABSPATH . WPINC . '/class-smtp.php';
+			require_once ABSPATH . WPINC . '/PHPMailer/SMTP.php';
-			$phpmailer = new PHPMailer( true );
+			require_once ABSPATH . WPINC . '/PHPMailer/Exception.php';
-		}
+			$phpmailer = new PHPMailer\PHPMailer\PHPMailer( true );
-		// Headers
+			$phpmailer::$validator = static function ( $email ) {
-		$cc = $bcc = $reply_to = array();
+				return (bool) is_email( $email );
+			};
+		}
+		// Headers.
+		$cc       = array();
+		$bcc      = array();
+		$reply_to = array();
 		if ( empty( $headers ) ) {
 			$headers = array();
 		} else {
 			if ( ! is_array( $headers ) ) {
-				// Explode the headers out, so this function can take both
+				// Explode the headers out, so this function can take
-				// string headers and an array of headers.
+				// both string headers and an array of headers.
 				$tempheaders = explode( "\n", str_replace( "\r\n", "\n", $headers ) );
 			} else {
 				$tempheaders = $headers;
 			}
 			$headers = array();
-			// If it's actually got contents
+			// If it's actually got contents.
 			if ( ! empty( $tempheaders ) ) {
-				// Iterate through the raw headers
+				// Iterate through the raw headers.
 				foreach ( (array) $tempheaders as $header ) {
 					if ( strpos( $header, ':' ) === false ) {
 						if ( false !== stripos( $header, 'boundary=' ) ) {
 							$parts    = preg_split( '/boundary=/i', trim( $header ) );
 							$boundary = trim( str_replace( array( "'", '"' ), '', $parts[1] ) );
 						}
 						continue;
 					}
-					// Explode them out
+					// Explode them out.
 					list( $name, $content ) = explode( ':', trim( $header ), 2 );
-					// Cleanup crew
+					// Cleanup crew.
 					$name    = trim( $name );
 					$content = trim( $content );
 					switch ( strtolower( $name ) ) {
-						// Mainly for legacy -- process a From: header if it's there
+						// Mainly for legacy -- process a "From:" header if it's there.
 						case 'from':
 							$bracket_pos = strpos( $content, '<' );
-							if ( $bracket_pos !== false ) {
+							if ( false !== $bracket_pos ) {
 								// Text before the bracketed email is the "From" name.
 								if ( $bracket_pos > 0 ) {
 									$from_name = substr( $content, 0, $bracket_pos - 1 );
 									$from_name = str_replace( '"', '', $from_name );
 									$from_name = trim( $from_name );
 							break;
 						case 'reply-to':
 							$reply_to = array_merge( (array) $reply_to, explode( ',', $content ) );
 							break;
 						default:
-							// Add it to our grand headers array
+							// Add it to our grand headers array.
 							$headers[ trim( $name ) ] = trim( $content );
 							break;
 					}
 				}
 			}
 		}
-		// Empty out the values that may be set
+		// Empty out the values that may be set.
 		$phpmailer->clearAllRecipients();
 		$phpmailer->clearAttachments();
 		$phpmailer->clearCustomHeaders();
 		$phpmailer->clearReplyTos();
-		// From email and name
+		// Set "From" name and email.
-		// If we don't have a name from the input headers
+		// If we don't have a name from the input headers.
 		if ( ! isset( $from_name ) ) {
 			$from_name = 'WordPress';
 		}
-		/* If we don't have an email from the input headers default to wordpress@$sitename
+		/*
-		 * Some hosts will block outgoing mail from this address if it doesn't exist but
+		 * If we don't have an email from the input headers, default to wordpress@$sitename
-		 * there's no easy alternative. Defaulting to admin_email might appear to be another
+		 * Some hosts will block outgoing mail from this address if it doesn't exist,
-		 * option but some hosts may refuse to relay mail from an unknown domain. See
+		 * but there's no easy alternative. Defaulting to admin_email might appear to be
-		 * https://core.trac.wordpress.org/ticket/5007.
+		 * another option, but some hosts may refuse to relay mail from an unknown domain.
-		 */
+		 * See https://core.trac.wordpress.org/ticket/5007.
+		 */
 		if ( ! isset( $from_email ) ) {
 			// Get the site domain and get rid of www.
-			$sitename = strtolower( $_SERVER['SERVER_NAME'] );
+			$sitename = wp_parse_url( network_home_url(), PHP_URL_HOST );
-			if ( substr( $sitename, 0, 4 ) == 'www.' ) {
+			if ( 'www.' === substr( $sitename, 0, 4 ) ) {
 				$sitename = substr( $sitename, 4 );
 			}
 			$from_email = 'wordpress@' . $sitename;
 		}
 		 */
 		$from_name = apply_filters( 'wp_mail_from_name', $from_name );
 		try {
 			$phpmailer->setFrom( $from_email, $from_name, false );
-		} catch ( phpmailerException $e ) {
+		} catch ( PHPMailer\PHPMailer\Exception $e ) {
 			$mail_error_data                             = compact( 'to', 'subject', 'message', 'headers', 'attachments' );
 			$mail_error_data['phpmailer_exception_code'] = $e->getCode();
 			/** This filter is documented in wp-includes/pluggable.php */
 			do_action( 'wp_mail_failed', new WP_Error( 'wp_mail_failed', $e->getMessage(), $mail_error_data ) );
 			return false;
 		}
-		// Set mail's subject and body
+		// Set mail's subject and body.
 		$phpmailer->Subject = $subject;
 		$phpmailer->Body    = $message;
-		// Set destination addresses, using appropriate methods for handling addresses
+		// Set destination addresses, using appropriate methods for handling addresses.
 		$address_headers = compact( 'to', 'cc', 'bcc', 'reply_to' );
 		foreach ( $address_headers as $address_header => $addresses ) {
 			if ( empty( $addresses ) ) {
 				continue;
 			}
 			foreach ( (array) $addresses as $address ) {
 				try {
-					// Break $recipient into name and address parts if in the format "Foo <bar@baz.com>"
+					// Break $recipient into name and address parts if in the format "Foo <bar@baz.com>".
 					$recipient_name = '';
 					if ( preg_match( '/(.*)<(.+)>/', $address, $matches ) ) {
 						if ( count( $matches ) == 3 ) {
 							$recipient_name = $matches[1];
 							break;
 						case 'reply_to':
 							$phpmailer->addReplyTo( $address, $recipient_name );
 							break;
 					}
-				} catch ( phpmailerException $e ) {
+				} catch ( PHPMailer\PHPMailer\Exception $e ) {
 					continue;
 				}
 			}
 		}
-		// Set to use PHP's mail()
+		// Set to use PHP's mail().
 		$phpmailer->isMail();
-		// Set Content-Type and charset
+		// Set Content-Type and charset.
-		// If we don't have a content-type from the input headers
+		// If we don't have a content-type from the input headers.
 		if ( ! isset( $content_type ) ) {
 			$content_type = 'text/plain';
 		}
 		/**
 		 */
 		$content_type = apply_filters( 'wp_mail_content_type', $content_type );
 		$phpmailer->ContentType = $content_type;
-		// Set whether it's plaintext, depending on $content_type
+		// Set whether it's plaintext, depending on $content_type.
-		if ( 'text/html' == $content_type ) {
+		if ( 'text/html' === $content_type ) {
 			$phpmailer->isHTML( true );
 		}
-		// If we don't have a charset from the input headers
+		// If we don't have a charset from the input headers.
 		if ( ! isset( $charset ) ) {
 			$charset = get_bloginfo( 'charset' );
 		}
-		// Set the content-type and charset
 		/**
 		 * Filters the default wp_mail() charset.
 		 *
 		 * @since 2.3.0
 		 *
 		 * @param string $charset Default email charset.
 		 */
 		$phpmailer->CharSet = apply_filters( 'wp_mail_charset', $charset );
-		// Set custom headers
+		// Set custom headers.
 		if ( ! empty( $headers ) ) {
 			foreach ( (array) $headers as $name => $content ) {
-				$phpmailer->addCustomHeader( sprintf( '%1$s: %2$s', $name, $content ) );
+				// Only add custom headers not added automatically by PHPMailer.
+				if ( ! in_array( $name, array( 'MIME-Version', 'X-Mailer' ), true ) ) {
+					try {
+						$phpmailer->addCustomHeader( sprintf( '%1$s: %2$s', $name, $content ) );
+					} catch ( PHPMailer\PHPMailer\Exception $e ) {
+						continue;
+					}
+				}
 			}
 			if ( false !== stripos( $content_type, 'multipart' ) && ! empty( $boundary ) ) {
-				$phpmailer->addCustomHeader( sprintf( "Content-Type: %s;\n\t boundary=\"%s\"", $content_type, $boundary ) );
+				$phpmailer->addCustomHeader( sprintf( 'Content-Type: %s; boundary="%s"', $content_type, $boundary ) );
 			}
 		}
 		if ( ! empty( $attachments ) ) {
 			foreach ( $attachments as $attachment ) {
 				try {
 					$phpmailer->addAttachment( $attachment );
-				} catch ( phpmailerException $e ) {
+				} catch ( PHPMailer\PHPMailer\Exception $e ) {
 					continue;
 				}
 			}
 		}
 		do_action_ref_array( 'phpmailer_init', array( &$phpmailer ) );
 		// Send!
 		try {
 			return $phpmailer->send();
-		} catch ( phpmailerException $e ) {
+		} catch ( PHPMailer\PHPMailer\Exception $e ) {
 			$mail_error_data                             = compact( 'to', 'subject', 'message', 'headers', 'attachments' );
 			$mail_error_data['phpmailer_exception_code'] = $e->getCode();
 			/**
-			 * Fires after a phpmailerException is caught.
+			 * Fires after a PHPMailer\PHPMailer\Exception is caught.
 			 *
 			 * @since 4.4.0
 			 *
-			 * @param WP_Error $error A WP_Error object with the phpmailerException message, and an array
+			 * @param WP_Error $error A WP_Error object with the PHPMailer\PHPMailer\Exception message, and an array
 			 *                        containing the mail recipient, subject, message, headers, and attachments.
 			 */
 			do_action( 'wp_mail_failed', new WP_Error( 'wp_mail_failed', $e->getMessage(), $mail_error_data ) );
 			return false;
 		 * @param string                $username Username or email address.
 		 * @param string                $password User password
 		 */
 		$user = apply_filters( 'authenticate', null, $username, $password );
-		if ( $user == null ) {
+		if ( null == $user ) {
-			// TODO what should the error message be? (Or would these even happen?)
+			// TODO: What should the error message be? (Or would these even happen?)
 			// Only needed if all authentication handlers fail to return anything.
-			$user = new WP_Error( 'authentication_failed', __( '<strong>ERROR</strong>: Invalid username, email address or incorrect password.' ) );
+			$user = new WP_Error( 'authentication_failed', __( '<strong>Error</strong>: Invalid username, email address or incorrect password.' ) );
 		}
 		$ignore_codes = array( 'empty_username', 'empty_password' );
-		if ( is_wp_error( $user ) && ! in_array( $user->get_error_code(), $ignore_codes ) ) {
+		if ( is_wp_error( $user ) && ! in_array( $user->get_error_code(), $ignore_codes, true ) ) {
+			$error = $user;
 			/**
 			 * Fires after a user login has failed.
 			 *
 			 * @since 2.5.0
 			 * @since 4.5.0 The value of `$username` can now be an email address.
-			 *
+			 * @since 5.4.0 The `$error` parameter was added.
-			 * @param string $username Username or email address.
+			 *
+			 * @param string   $username Username or email address.
+			 * @param WP_Error $error    A WP_Error object with the authentication failure details.
 			 */
-			do_action( 'wp_login_failed', $username );
+			do_action( 'wp_login_failed', $username, $error );
 		}
 		return $user;
 	}
 endif;
 	 * Log the current user out.
 	 *
 	 * @since 2.5.0
 	 */
 	function wp_logout() {
+		$user_id = get_current_user_id();
 		wp_destroy_current_session();
 		wp_clear_auth_cookie();
+		wp_set_current_user( 0 );
-		/**
-		 * Fires after a user is logged-out.
+		/**
+		 * Fires after a user is logged out.
 		 *
 		 * @since 1.5.0
-		 */
+		 * @since 5.5.0 Added the `$user_id` parameter.
-		do_action( 'wp_logout' );
+		 *
+		 * @param int $user_id ID of the user that was logged out.
+		 */
+		do_action( 'wp_logout', $user_id );
 	}
 endif;
 if ( ! function_exists( 'wp_validate_auth_cookie' ) ) :
 	/**
 	 *
 	 * @since 2.5.0
 	 *
 	 * @global int $login_grace_period
 	 *
-	 * @param string $cookie Optional. If used, will validate contents instead of cookie's
+	 * @param string $cookie Optional. If used, will validate contents instead of cookie's.
-	 * @param string $scheme Optional. The cookie scheme to use: auth, secure_auth, or logged_in
+	 * @param string $scheme Optional. The cookie scheme to use: 'auth', 'secure_auth', or 'logged_in'.
-	 * @return false|int False if invalid cookie, User ID if valid.
+	 * @return int|false User ID if valid cookie, false if invalid.
 	 */
 	function wp_validate_auth_cookie( $cookie = '', $scheme = '' ) {
-		if ( ! $cookie_elements = wp_parse_auth_cookie( $cookie, $scheme ) ) {
+		$cookie_elements = wp_parse_auth_cookie( $cookie, $scheme );
+		if ( ! $cookie_elements ) {
 			/**
 			 * Fires if an authentication cookie is malformed.
 			 *
 			 * @since 2.7.0
 			 *
 			 */
 			do_action( 'auth_cookie_malformed', $cookie, $scheme );
 			return false;
 		}
-		$scheme   = $cookie_elements['scheme'];
+		$scheme     = $cookie_elements['scheme'];
-		$username = $cookie_elements['username'];
+		$username   = $cookie_elements['username'];
-		$hmac     = $cookie_elements['hmac'];
+		$hmac       = $cookie_elements['hmac'];
-		$token    = $cookie_elements['token'];
+		$token      = $cookie_elements['token'];
-		$expired  = $expiration = $cookie_elements['expiration'];
+		$expired    = $cookie_elements['expiration'];
+		$expiration = $cookie_elements['expiration'];
-		// Allow a grace period for POST and Ajax requests
-		if ( wp_doing_ajax() || 'POST' == $_SERVER['REQUEST_METHOD'] ) {
+		// Allow a grace period for POST and Ajax requests.
+		if ( wp_doing_ajax() || 'POST' === $_SERVER['REQUEST_METHOD'] ) {
 			$expired += HOUR_IN_SECONDS;
 		}
-		// Quick check to see if an honest cookie has expired
+		// Quick check to see if an honest cookie has expired.
 		if ( $expired < time() ) {
 			/**
 			 * Fires once an authentication cookie has expired.
 			 *
 			 * @since 2.7.0
 			 *
-			 * @param array $cookie_elements An array of data for the authentication cookie.
+			 * @param string[] $cookie_elements An array of data for the authentication cookie.
 			 */
 			do_action( 'auth_cookie_expired', $cookie_elements );
 			return false;
 		}
 			/**
 			 * Fires if a bad username is entered in the user authentication process.
 			 *
 			 * @since 2.7.0
 			 *
-			 * @param array $cookie_elements An array of data for the authentication cookie.
+			 * @param string[] $cookie_elements An array of data for the authentication cookie.
 			 */
 			do_action( 'auth_cookie_bad_username', $cookie_elements );
 			return false;
 		}
 			/**
 			 * Fires if a bad authentication cookie hash is encountered.
 			 *
 			 * @since 2.7.0
 			 *
-			 * @param array $cookie_elements An array of data for the authentication cookie.
+			 * @param string[] $cookie_elements An array of data for the authentication cookie.
 			 */
 			do_action( 'auth_cookie_bad_hash', $cookie_elements );
 			return false;
 		}
 		$manager = WP_Session_Tokens::get_instance( $user->ID );
 		if ( ! $manager->verify( $token ) ) {
+			/**
+			 * Fires if a bad session token is encountered.
+			 *
+			 * @since 4.0.0
+			 *
+			 * @param string[] $cookie_elements An array of data for the authentication cookie.
+			 */
 			do_action( 'auth_cookie_bad_session_token', $cookie_elements );
 			return false;
 		}
-		// Ajax/POST grace period set above
+		// Ajax/POST grace period set above.
 		if ( $expiration < time() ) {
 			$GLOBALS['login_grace_period'] = 1;
 		}
 		/**
 		 * Fires once an authentication cookie has been validated.
 		 *
 		 * @since 2.7.0
 		 *
-		 * @param array   $cookie_elements An array of data for the authentication cookie.
+		 * @param string[] $cookie_elements An array of data for the authentication cookie.
-		 * @param WP_User $user            User object.
+		 * @param WP_User  $user            User object.
 		 */
 		do_action( 'auth_cookie_valid', $cookie_elements, $user );
 		return $user->ID;
 	}
 endif;
 if ( ! function_exists( 'wp_generate_auth_cookie' ) ) :
 	/**
-	 * Generate authentication cookie contents.
+	 * Generates authentication cookie contents.
 	 *
 	 * @since 2.5.0
 	 * @since 4.0.0 The `$token` parameter was added.
 	 *
-	 * @param int    $user_id    User ID
+	 * @param int    $user_id    User ID.
 	 * @param int    $expiration The time the cookie expires as a UNIX timestamp.
-	 * @param string $scheme     Optional. The cookie scheme to use: auth, secure_auth, or logged_in
+	 * @param string $scheme     Optional. The cookie scheme to use: 'auth', 'secure_auth', or 'logged_in'.
-	 * @param string $token      User's session token to use for this cookie
+	 *                           Default 'auth'.
+	 * @param string $token      User's session token to use for this cookie.
 	 * @return string Authentication cookie contents. Empty string if user does not exist.
 	 */
 	function wp_generate_auth_cookie( $user_id, $expiration, $scheme = 'auth', $token = '' ) {
 		$user = get_userdata( $user_id );
 		if ( ! $user ) {
 	}
 endif;
 if ( ! function_exists( 'wp_parse_auth_cookie' ) ) :
 	/**
-	 * Parse a cookie into its components
+	 * Parses a cookie into its components.
 	 *
 	 * @since 2.7.0
 	 *
-	 * @param string $cookie
+	 * @param string $cookie Authentication cookie.
-	 * @param string $scheme Optional. The cookie scheme to use: auth, secure_auth, or logged_in
+	 * @param string $scheme Optional. The cookie scheme to use: 'auth', 'secure_auth', or 'logged_in'.
-	 * @return array|false Authentication cookie components
+	 * @return string[]|false Authentication cookie components.
 	 */
 	function wp_parse_auth_cookie( $cookie = '', $scheme = '' ) {
 		if ( empty( $cookie ) ) {
 			switch ( $scheme ) {
 				case 'auth':
 	}
 endif;
 if ( ! function_exists( 'wp_set_auth_cookie' ) ) :
 	/**
-	 * Log in a user by setting authentication cookies.
+	 * Sets the authentication cookies based on user ID.
 	 *
 	 * The $remember parameter increases the time that the cookie will be kept. The
 	 * default the cookie is kept without remembering is two days. When $remember is
 	 * set, the cookies will be kept for 14 days or two weeks.
 	 *
 	 * @since 2.5.0
 	 * @since 4.3.0 Added the `$token` parameter.
 	 *
-	 * @param int    $user_id  User ID
+	 * @param int         $user_id  User ID.
-	 * @param bool   $remember Whether to remember the user
+	 * @param bool        $remember Whether to remember the user.
-	 * @param mixed  $secure   Whether the admin cookies should only be sent over HTTPS.
+	 * @param bool|string $secure   Whether the auth cookie should only be sent over HTTPS. Default is an empty
-	 *                         Default is_ssl().
+	 *                              string which means the value of `is_ssl()` will be used.
-	 * @param string $token    Optional. User's session token to use for this cookie.
+	 * @param string      $token    Optional. User's session token to use for this cookie.
 	 */
 	function wp_set_auth_cookie( $user_id, $remember = false, $secure = '', $token = '' ) {
 		if ( $remember ) {
 			/**
 			 * Filters the duration of the authentication cookie expiration period.
 		if ( '' === $secure ) {
 			$secure = is_ssl();
 		}
-		// Front-end cookie is secure when the auth cookie is secure and the site's home URL is forced HTTPS.
+		// Front-end cookie is secure when the auth cookie is secure and the site's home URL uses HTTPS.
 		$secure_logged_in_cookie = $secure && 'https' === parse_url( get_option( 'home' ), PHP_URL_SCHEME );
 		/**
-		 * Filters whether the connection is secure.
+		 * Filters whether the auth cookie should only be sent over HTTPS.
 		 *
 		 * @since 3.1.0
 		 *
-		 * @param bool $secure  Whether the connection is secure.
+		 * @param bool $secure  Whether the cookie should only be sent over HTTPS.
 		 * @param int  $user_id User ID.
 		 */
 		$secure = apply_filters( 'secure_auth_cookie', $secure, $user_id );
 		/**
-		 * Filters whether to use a secure cookie when logged-in.
+		 * Filters whether the logged in cookie should only be sent over HTTPS.
 		 *
 		 * @since 3.1.0
 		 *
-		 * @param bool $secure_logged_in_cookie Whether to use a secure cookie when logged-in.
+		 * @param bool $secure_logged_in_cookie Whether the logged in cookie should only be sent over HTTPS.
 		 * @param int  $user_id                 User ID.
-		 * @param bool $secure                  Whether the connection is secure.
+		 * @param bool $secure                  Whether the auth cookie should only be sent over HTTPS.
 		 */
 		$secure_logged_in_cookie = apply_filters( 'secure_logged_in_cookie', $secure_logged_in_cookie, $user_id, $secure );
 		if ( $secure ) {
 			$auth_cookie_name = SECURE_AUTH_COOKIE;
 		/** This filter is documented in wp-includes/pluggable.php */
 		if ( ! apply_filters( 'send_auth_cookies', true ) ) {
 			return;
 		}
-		// Auth cookies
+		// Auth cookies.
 		setcookie( AUTH_COOKIE, ' ', time() - YEAR_IN_SECONDS, ADMIN_COOKIE_PATH, COOKIE_DOMAIN );
 		setcookie( SECURE_AUTH_COOKIE, ' ', time() - YEAR_IN_SECONDS, ADMIN_COOKIE_PATH, COOKIE_DOMAIN );
 		setcookie( AUTH_COOKIE, ' ', time() - YEAR_IN_SECONDS, PLUGINS_COOKIE_PATH, COOKIE_DOMAIN );
 		setcookie( SECURE_AUTH_COOKIE, ' ', time() - YEAR_IN_SECONDS, PLUGINS_COOKIE_PATH, COOKIE_DOMAIN );
 		setcookie( LOGGED_IN_COOKIE, ' ', time() - YEAR_IN_SECONDS, COOKIEPATH, COOKIE_DOMAIN );
 		setcookie( LOGGED_IN_COOKIE, ' ', time() - YEAR_IN_SECONDS, SITECOOKIEPATH, COOKIE_DOMAIN );
-		// Settings cookies
+		// Settings cookies.
 		setcookie( 'wp-settings-' . get_current_user_id(), ' ', time() - YEAR_IN_SECONDS, SITECOOKIEPATH );
 		setcookie( 'wp-settings-time-' . get_current_user_id(), ' ', time() - YEAR_IN_SECONDS, SITECOOKIEPATH );
-		// Old cookies
+		// Old cookies.
 		setcookie( AUTH_COOKIE, ' ', time() - YEAR_IN_SECONDS, COOKIEPATH, COOKIE_DOMAIN );
 		setcookie( AUTH_COOKIE, ' ', time() - YEAR_IN_SECONDS, SITECOOKIEPATH, COOKIE_DOMAIN );
 		setcookie( SECURE_AUTH_COOKIE, ' ', time() - YEAR_IN_SECONDS, COOKIEPATH, COOKIE_DOMAIN );
 		setcookie( SECURE_AUTH_COOKIE, ' ', time() - YEAR_IN_SECONDS, SITECOOKIEPATH, COOKIE_DOMAIN );
-		// Even older cookies
+		// Even older cookies.
 		setcookie( USER_COOKIE, ' ', time() - YEAR_IN_SECONDS, COOKIEPATH, COOKIE_DOMAIN );
 		setcookie( PASS_COOKIE, ' ', time() - YEAR_IN_SECONDS, COOKIEPATH, COOKIE_DOMAIN );
 		setcookie( USER_COOKIE, ' ', time() - YEAR_IN_SECONDS, SITECOOKIEPATH, COOKIE_DOMAIN );
 		setcookie( PASS_COOKIE, ' ', time() - YEAR_IN_SECONDS, SITECOOKIEPATH, COOKIE_DOMAIN );
-		// Post password cookie
+		// Post password cookie.
 		setcookie( 'wp-postpass_' . COOKIEHASH, ' ', time() - YEAR_IN_SECONDS, COOKIEPATH, COOKIE_DOMAIN );
 	}
 endif;
 if ( ! function_exists( 'is_user_logged_in' ) ) :
 if ( ! function_exists( 'auth_redirect' ) ) :
 	/**
 	 * Checks if a user is logged in, if not it redirects them to the login page.
 	 *
+	 * When this code is called from a page, it checks to see if the user viewing the page is logged in.
+	 * If the user is not logged in, they are redirected to the login page. The user is redirected
+	 * in such a way that, upon logging in, they will be sent directly to the page they were originally
+	 * trying to access.
+	 *
 	 * @since 1.5.0
 	 */
 	function auth_redirect() {
-		// Checks if a user is logged in, if not redirects them to the login page
 		$secure = ( is_ssl() || force_ssl_admin() );
 		/**
 		 * Filters whether to use a secure authentication redirect.
 		 *
 		 *
 		 * @param bool $secure Whether to use a secure authentication redirect. Default false.
 		 */
 		$secure = apply_filters( 'secure_auth_redirect', $secure );
-		// If https is required and request is http, redirect
+		// If https is required and request is http, redirect.
 		if ( $secure && ! is_ssl() && false !== strpos( $_SERVER['REQUEST_URI'], 'wp-admin' ) ) {
 			if ( 0 === strpos( $_SERVER['REQUEST_URI'], 'http' ) ) {
 				wp_redirect( set_url_scheme( $_SERVER['REQUEST_URI'], 'https' ) );
-				exit();
+				exit;
 			} else {
 				wp_redirect( 'https://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'] );
-				exit();
+				exit;
 			}
 		}
 		/**
 		 * Filters the authentication redirect scheme.
 		 *
 		 * @param string $scheme Authentication redirect scheme. Default empty.
 		 */
 		$scheme = apply_filters( 'auth_redirect_scheme', '' );
-		if ( $user_id = wp_validate_auth_cookie( '', $scheme ) ) {
+		$user_id = wp_validate_auth_cookie( '', $scheme );
+		if ( $user_id ) {
 			/**
 			 * Fires before the authentication redirect.
 			 *
 			 * @since 2.8.0
 			 *
 			// If the user wants ssl but the session is not ssl, redirect.
 			if ( ! $secure && get_user_option( 'use_ssl', $user_id ) && false !== strpos( $_SERVER['REQUEST_URI'], 'wp-admin' ) ) {
 				if ( 0 === strpos( $_SERVER['REQUEST_URI'], 'http' ) ) {
 					wp_redirect( set_url_scheme( $_SERVER['REQUEST_URI'], 'https' ) );
-					exit();
+					exit;
 				} else {
 					wp_redirect( 'https://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'] );
-					exit();
+					exit;
 				}
 			}
-			return;  // The cookie is good so we're done
+			return; // The cookie is good, so we're done.
 		}
-		// The cookie is no good so force login
+		// The cookie is no good, so force login.
 		nocache_headers();
 		$redirect = ( strpos( $_SERVER['REQUEST_URI'], '/options.php' ) && wp_get_referer() ) ? wp_get_referer() : set_url_scheme( 'http://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'] );
 		$login_url = wp_login_url( $redirect, true );
 		wp_redirect( $login_url );
-		exit();
+		exit;
 	}
 endif;
 if ( ! function_exists( 'check_admin_referer' ) ) :
 	/**
-	 * Makes sure that a user was referred from another admin page.
+	 * Ensures intent by verifying that a user was referred from another admin page with the correct security nonce.
 	 *
-	 * To avoid security exploits.
+	 * This function ensures the user intends to perform a given action, which helps protect against clickjacking style
+	 * attacks. It verifies intent, not authorisation, therefore it does not verify the user's capabilities. This should
+	 * be performed with `current_user_can()` or similar.
+	 *
+	 * If the nonce value is invalid, the function will exit with an "Are You Sure?" style message.
 	 *
 	 * @since 1.2.0
-	 *
+	 * @since 2.5.0 The `$query_arg` parameter was added.
-	 * @param int|string $action    Action nonce.
+	 *
-	 * @param string     $query_arg Optional. Key to check for nonce in `$_REQUEST` (since 2.5).
+	 * @param int|string $action    The nonce action.
-	 *                              Default '_wpnonce'.
+	 * @param string     $query_arg Optional. Key to check for nonce in `$_REQUEST`. Default '_wpnonce'.
-	 * @return false|int False if the nonce is invalid, 1 if the nonce is valid and generated between
+	 * @return int|false 1 if the nonce is valid and generated between 0-12 hours ago,
-	 *                   0-12 hours ago, 2 if the nonce is valid and generated between 12-24 hours ago.
+	 *                   2 if the nonce is valid and generated between 12-24 hours ago.
+	 *                   False if the nonce is invalid.
 	 */
 	function check_admin_referer( $action = -1, $query_arg = '_wpnonce' ) {
 		if ( -1 === $action ) {
 			_doing_it_wrong( __FUNCTION__, __( 'You should specify a nonce action to be verified by using the first parameter.' ), '3.2.0' );
 		}
 	 * @param false|string $query_arg Optional. Key to check for the nonce in `$_REQUEST` (since 2.5). If false,
 	 *                                `$_REQUEST` values will be evaluated for '_ajax_nonce', and '_wpnonce'
 	 *                                (in that order). Default false.
 	 * @param bool         $die       Optional. Whether to die early when the nonce cannot be verified.
 	 *                                Default true.
-	 * @return false|int False if the nonce is invalid, 1 if the nonce is valid and generated between
+	 * @return int|false 1 if the nonce is valid and generated between 0-12 hours ago,
-	 *                   0-12 hours ago, 2 if the nonce is valid and generated between 12-24 hours ago.
+	 *                   2 if the nonce is valid and generated between 12-24 hours ago.
+	 *                   False if the nonce is invalid.
 	 */
 	function check_ajax_referer( $action = -1, $query_arg = false, $die = true ) {
 		if ( -1 == $action ) {
 			_doing_it_wrong( __FUNCTION__, __( 'You should specify a nonce action to be verified by using the first parameter.' ), '4.7' );
 		}
 	 *         exit;
 	 *     }
 	 *
 	 * @since 1.5.1
 	 * @since 5.1.0 The `$x_redirect_by` parameter was added.
+	 * @since 5.4.0 On invalid status codes, wp_die() is called.
 	 *
 	 * @global bool $is_IIS
 	 *
 	 * @param string $location      The path or URL to redirect to.
 	 * @param int    $status        Optional. HTTP response status code to use. Default '302' (Moved Temporarily).
 		if ( ! $location ) {
 			return false;
 		}
+		if ( $status < 300 || 399 < $status ) {
+			wp_die( __( 'HTTP redirect status code must be a redirection code, 3xx.' ) );
+		}
 		$location = wp_sanitize_redirect( $location );
-		if ( ! $is_IIS && PHP_SAPI != 'cgi-fcgi' ) {
+		if ( ! $is_IIS && 'cgi-fcgi' !== PHP_SAPI ) {
-			status_header( $status ); // This causes problems on IIS and some FastCGI setups
+			status_header( $status ); // This causes problems on IIS and some FastCGI setups.
 		}
 		/**
 		 * Filters the X-Redirect-By header.
 		 *
 	 *
 	 * @param string $location The path to redirect to.
 	 * @return string Redirect-sanitized URL.
 	 */
 	function wp_sanitize_redirect( $location ) {
+		// Encode spaces.
+		$location = str_replace( ' ', '%20', $location );
 		$regex    = '/
 		(
 			(?: [\xC2-\xDF][\x80-\xBF]        # double-byte sequences   110xxxxx 10xxxxxx
 			|   \xE0[\xA0-\xBF][\x80-\xBF]    # triple-byte sequences   1110xxxx 10xxxxxx * 2
 			|   [\xE1-\xEC][\x80-\xBF]{2}
 		)/x';
 		$location = preg_replace_callback( $regex, '_wp_sanitize_utf8_in_redirect', $location );
 		$location = preg_replace( '|[^a-z0-9-~+_.?#=&;,/:%!*\[\]()@]|i', '', $location );
 		$location = wp_kses_no_null( $location );
-		// remove %0d and %0a from location
+		// Remove %0D and %0A from location.
 		$strip = array( '%0d', '%0a', '%0D', '%0A' );
 		return _deep_replace( $strip, $location );
 	}
 	/**
 	 * @since 5.1.0 The return value from wp_redirect() is now passed on, and the `$x_redirect_by` parameter was added.
 	 *
 	 * @param string $location      The path or URL to redirect to.
 	 * @param int    $status        Optional. HTTP response status code to use. Default '302' (Moved Temporarily).
 	 * @param string $x_redirect_by Optional. The application doing the redirect. Default 'WordPress'.
-	 * @return bool  $redirect False if the redirect was cancelled, true otherwise.
+	 * @return bool False if the redirect was cancelled, true otherwise.
 	 */
 	function wp_safe_redirect( $location, $status = 302, $x_redirect_by = 'WordPress' ) {
-		// Need to look at the URL the way it will end up in wp_redirect()
+		// Need to look at the URL the way it will end up in wp_redirect().
 		$location = wp_sanitize_redirect( $location );
 		/**
 		 * Filters the redirect fallback URL for when the provided redirect is not safe (local).
 		 *
 	 * @param string $location The redirect to validate
 	 * @param string $default  The value to return if $location is not allowed
 	 * @return string redirect-sanitized URL
 	 */
 	function wp_validate_redirect( $location, $default = '' ) {
-		$location = trim( $location, " \t\n\r\0\x08\x0B" );
+		$location = wp_sanitize_redirect( trim( $location, " \t\n\r\0\x08\x0B" ) );
-		// browsers will assume 'http' is your protocol, and will obey a redirect to a URL starting with '//'
+		// Browsers will assume 'http' is your protocol, and will obey a redirect to a URL starting with '//'.
-		if ( substr( $location, 0, 2 ) == '//' ) {
+		if ( '//' === substr( $location, 0, 2 ) ) {
 			$location = 'http:' . $location;
 		}
-		// In php 5 parse_url may fail if the URL query part contains http://, bug #38143
+		// In PHP 5 parse_url() may fail if the URL query part contains 'http://'.
-		$test = ( $cut = strpos( $location, '?' ) ) ? substr( $location, 0, $cut ) : $location;
+		// See https://bugs.php.net/bug.php?id=38143
+		$cut  = strpos( $location, '?' );
-		// @-operator is used to prevent possible warnings in PHP < 5.3.3.
+		$test = $cut ? substr( $location, 0, $cut ) : $location;
-		$lp = @parse_url( $test );
+		$lp = parse_url( $test );
-		// Give up if malformed URL
+		// Give up if malformed URL.
 		if ( false === $lp ) {
 			return $default;
 		}
-		// Allow only http and https schemes. No data:, etc.
+		// Allow only 'http' and 'https' schemes. No 'data:', etc.
-		if ( isset( $lp['scheme'] ) && ! ( 'http' == $lp['scheme'] || 'https' == $lp['scheme'] ) ) {
+		if ( isset( $lp['scheme'] ) && ! ( 'http' === $lp['scheme'] || 'https' === $lp['scheme'] ) ) {
 			return $default;
 		}
 		if ( ! isset( $lp['host'] ) && ! empty( $lp['path'] ) && '/' !== $lp['path'][0] ) {
 			$path = '';
 				$path = wp_normalize_path( $path );
 			}
 			$location = '/' . ltrim( $path . '/', '/' ) . $location;
 		}
-		// Reject if certain components are set but host is not. This catches urls like https:host.com for which parse_url does not set the host field.
+		// Reject if certain components are set but host is not.
+		// This catches URLs like https:host.com for which parse_url() does not set the host field.
 		if ( ! isset( $lp['host'] ) && ( isset( $lp['scheme'] ) || isset( $lp['user'] ) || isset( $lp['pass'] ) || isset( $lp['port'] ) ) ) {
 			return $default;
 		}
 		// Reject malformed components parse_url() can return on odd inputs.
 		}
 		$wpp = parse_url( home_url() );
 		/**
-		 * Filters the whitelist of hosts to redirect to.
+		 * Filters the list of allowed hosts to redirect to.
 		 *
 		 * @since 2.3.0
 		 *
-		 * @param array       $hosts An array of allowed hosts.
+		 * @param string[] $hosts An array of allowed host names.
-		 * @param bool|string $host  The parsed host; empty if not isset.
+		 * @param string   $host  The host name of the redirect destination; empty string if not set.
 		 */
 		$allowed_hosts = (array) apply_filters( 'allowed_redirect_hosts', array( $wpp['host'] ), isset( $lp['host'] ) ? $lp['host'] : '' );
-		if ( isset( $lp['host'] ) && ( ! in_array( $lp['host'], $allowed_hosts ) && $lp['host'] != strtolower( $wpp['host'] ) ) ) {
+		if ( isset( $lp['host'] ) && ( ! in_array( $lp['host'], $allowed_hosts, true ) && strtolower( $wpp['host'] ) !== $lp['host'] ) ) {
 			$location = $default;
 		}
 		return $location;
 	}
 	/**
 	 * Notify an author (and/or others) of a comment/trackback/pingback on a post.
 	 *
 	 * @since 1.0.0
 	 *
-	 * @param int|WP_Comment  $comment_id Comment ID or WP_Comment object.
+	 * @param int|WP_Comment $comment_id Comment ID or WP_Comment object.
-	 * @param string          $deprecated Not used
+	 * @param string         $deprecated Not used
 	 * @return bool True on completion. False if no email addresses were specified.
 	 */
 	function wp_notify_postauthor( $comment_id, $deprecated = null ) {
 		if ( null !== $deprecated ) {
 			_deprecated_argument( __FUNCTION__, '3.8.0' );
 		 * By default, only post authors are notified of comments. This filter allows
 		 * others to be added.
 		 *
 		 * @since 3.7.0
 		 *
-		 * @param array $emails     An array of email addresses to receive a comment notification.
+		 * @param string[] $emails     An array of email addresses to receive a comment notification.
-		 * @param int   $comment_id The comment ID.
+		 * @param int      $comment_id The comment ID.
 		 */
 		$emails = apply_filters( 'comment_notification_recipients', $emails, $comment->comment_ID );
 		$emails = array_filter( $emails );
 		// If there are no addresses to send the comment to, bail.
 		 *                         Default false.
 		 * @param int  $comment_id The comment ID.
 		 */
 		$notify_author = apply_filters( 'comment_notification_notify_author', false, $comment->comment_ID );
-		// The comment was left by the author
+		// The comment was left by the author.
 		if ( $author && ! $notify_author && $comment->user_id == $post->post_author ) {
 			unset( $emails[ $author->user_email ] );
 		}
-		// The author moderated a comment on their own post
+		// The author moderated a comment on their own post.
-		if ( $author && ! $notify_author && $post->post_author == get_current_user_id() ) {
+		if ( $author && ! $notify_author && get_current_user_id() == $post->post_author ) {
 			unset( $emails[ $author->user_email ] );
 		}
-		// The post author is no longer a member of the blog
+		// The post author is no longer a member of the blog.
 		if ( $author && ! $notify_author && ! user_can( $post->post_author, 'read_post', $post->ID ) ) {
 			unset( $emails[ $author->user_email ] );
 		}
-		// If there's no email to send the comment to, bail, otherwise flip array back around for use below
+		// If there's no email to send the comment to, bail, otherwise flip array back around for use below.
 		if ( ! count( $emails ) ) {
 			return false;
 		} else {
 			$emails = array_flip( $emails );
 		}
 		$switched_locale = switch_to_locale( get_locale() );
-		$comment_author_domain = @gethostbyaddr( $comment->comment_author_IP );
+		$comment_author_domain = '';
+		if ( WP_Http::is_ip_address( $comment->comment_author_IP ) ) {
-		// The blogname option is escaped with esc_html on the way into the database in sanitize_option
+			$comment_author_domain = gethostbyaddr( $comment->comment_author_IP );
-		// we want to reverse this for the plain text arena of emails.
+		}
+		// The blogname option is escaped with esc_html() on the way into the database in sanitize_option().
+		// We want to reverse this for the plain text arena of emails.
 		$blogname        = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES );
 		$comment_content = wp_specialchars_decode( $comment->comment_content );
 		switch ( $comment->comment_type ) {
 			case 'trackback':
-				/* translators: %s: post title */
+				/* translators: %s: Post title. */
 				$notify_message = sprintf( __( 'New trackback on your post "%s"' ), $post->post_title ) . "\r\n";
-				/* translators: 1: trackback/pingback website name, 2: website IP address, 3: website hostname */
+				/* translators: 1: Trackback/pingback website name, 2: Website IP address, 3: Website hostname. */
 				$notify_message .= sprintf( __( 'Website: %1$s (IP address: %2$s, %3$s)' ), $comment->comment_author, $comment->comment_author_IP, $comment_author_domain ) . "\r\n";
-				/* translators: %s: trackback/pingback/comment author URL */
+				/* translators: %s: Trackback/pingback/comment author URL. */
 				$notify_message .= sprintf( __( 'URL: %s' ), $comment->comment_author_url ) . "\r\n";
-				/* translators: %s: comment text */
+				/* translators: %s: Comment text. */
 				$notify_message .= sprintf( __( 'Comment: %s' ), "\r\n" . $comment_content ) . "\r\n\r\n";
 				$notify_message .= __( 'You can see all trackbacks on this post here:' ) . "\r\n";
-				/* translators: Trackback notification email subject. 1: Site title, 2: Post title */
+				/* translators: Trackback notification email subject. 1: Site title, 2: Post title. */
 				$subject = sprintf( __( '[%1$s] Trackback: "%2$s"' ), $blogname, $post->post_title );
 				break;
 			case 'pingback':
-				/* translators: %s: post title */
+				/* translators: %s: Post title. */
 				$notify_message = sprintf( __( 'New pingback on your post "%s"' ), $post->post_title ) . "\r\n";
-				/* translators: 1: trackback/pingback website name, 2: website IP address, 3: website hostname */
+				/* translators: 1: Trackback/pingback website name, 2: Website IP address, 3: Website hostname. */
 				$notify_message .= sprintf( __( 'Website: %1$s (IP address: %2$s, %3$s)' ), $comment->comment_author, $comment->comment_author_IP, $comment_author_domain ) . "\r\n";
-				/* translators: %s: trackback/pingback/comment author URL */
+				/* translators: %s: Trackback/pingback/comment author URL. */
 				$notify_message .= sprintf( __( 'URL: %s' ), $comment->comment_author_url ) . "\r\n";
-				/* translators: %s: comment text */
+				/* translators: %s: Comment text. */
 				$notify_message .= sprintf( __( 'Comment: %s' ), "\r\n" . $comment_content ) . "\r\n\r\n";
 				$notify_message .= __( 'You can see all pingbacks on this post here:' ) . "\r\n";
-				/* translators: Pingback notification email subject. 1: Site title, 2: Post title */
+				/* translators: Pingback notification email subject. 1: Site title, 2: Post title. */
 				$subject = sprintf( __( '[%1$s] Pingback: "%2$s"' ), $blogname, $post->post_title );
 				break;
-			default: // Comments
-				/* translators: %s: post title */
+			default: // Comments.
+				/* translators: %s: Post title. */
 				$notify_message = sprintf( __( 'New comment on your post "%s"' ), $post->post_title ) . "\r\n";
-				/* translators: 1: comment author's name, 2: comment author's IP address, 3: comment author's hostname */
+				/* translators: 1: Comment author's name, 2: Comment author's IP address, 3: Comment author's hostname. */
 				$notify_message .= sprintf( __( 'Author: %1$s (IP address: %2$s, %3$s)' ), $comment->comment_author, $comment->comment_author_IP, $comment_author_domain ) . "\r\n";
-				/* translators: %s: comment author email */
+				/* translators: %s: Comment author email. */
 				$notify_message .= sprintf( __( 'Email: %s' ), $comment->comment_author_email ) . "\r\n";
-				/* translators: %s: trackback/pingback/comment author URL */
+				/* translators: %s: Trackback/pingback/comment author URL. */
 				$notify_message .= sprintf( __( 'URL: %s' ), $comment->comment_author_url ) . "\r\n";
-				/* translators: %s: comment text */
+				if ( $comment->comment_parent && user_can( $post->post_author, 'edit_comment', $comment->comment_parent ) ) {
+					/* translators: Comment moderation. %s: Parent comment edit URL. */
+					$notify_message .= sprintf( __( 'In reply to: %s' ), admin_url( "comment.php?action=editcomment&c={$comment->comment_parent}#wpbody-content" ) ) . "\r\n";
+				}
+				/* translators: %s: Comment text. */
 				$notify_message .= sprintf( __( 'Comment: %s' ), "\r\n" . $comment_content ) . "\r\n\r\n";
 				$notify_message .= __( 'You can see all comments on this post here:' ) . "\r\n";
-				/* translators: Comment notification email subject. 1: Site title, 2: Post title */
+				/* translators: Comment notification email subject. 1: Site title, 2: Post title. */
 				$subject = sprintf( __( '[%1$s] Comment: "%2$s"' ), $blogname, $post->post_title );
 				break;
 		}
 		$notify_message .= get_permalink( $comment->comment_post_ID ) . "#comments\r\n\r\n";
+		/* translators: %s: Comment URL. */
 		$notify_message .= sprintf( __( 'Permalink: %s' ), get_comment_link( $comment ) ) . "\r\n";
 		if ( user_can( $post->post_author, 'edit_comment', $comment->comment_ID ) ) {
 			if ( EMPTY_TRASH_DAYS ) {
-				/* translators: Comment moderation. %s: Comment action URL */
+				/* translators: Comment moderation. %s: Comment action URL. */
 				$notify_message .= sprintf( __( 'Trash it: %s' ), admin_url( "comment.php?action=trash&c={$comment->comment_ID}#wpbody-content" ) ) . "\r\n";
 			} else {
-				/* translators: Comment moderation. %s: Comment action URL */
+				/* translators: Comment moderation. %s: Comment action URL. */
 				$notify_message .= sprintf( __( 'Delete it: %s' ), admin_url( "comment.php?action=delete&c={$comment->comment_ID}#wpbody-content" ) ) . "\r\n";
 			}
-			/* translators: Comment moderation. %s: Comment action URL */
+			/* translators: Comment moderation. %s: Comment action URL. */
 			$notify_message .= sprintf( __( 'Spam it: %s' ), admin_url( "comment.php?action=spam&c={$comment->comment_ID}#wpbody-content" ) ) . "\r\n";
 		}
-		$wp_email = 'wordpress@' . preg_replace( '#^www\.#', '', strtolower( $_SERVER['SERVER_NAME'] ) );
+		$wp_email = 'wordpress@' . preg_replace( '#^www\.#', '', wp_parse_url( network_home_url(), PHP_URL_HOST ) );
-		if ( '' == $comment->comment_author ) {
+		if ( '' === $comment->comment_author ) {
 			$from = "From: \"$blogname\" <$wp_email>";
-			if ( '' != $comment->comment_author_email ) {
+			if ( '' !== $comment->comment_author_email ) {
 				$reply_to = "Reply-To: $comment->comment_author_email";
 			}
 		} else {
 			$from = "From: \"$comment->comment_author\" <$wp_email>";
-			if ( '' != $comment->comment_author_email ) {
+			if ( '' !== $comment->comment_author_email ) {
 				$reply_to = "Reply-To: \"$comment->comment_author_email\" <$comment->comment_author_email>";
 			}
 		}
 		$message_headers = "$from\n"
 		 * @param int    $comment_id      Comment ID.
 		 */
 		$message_headers = apply_filters( 'comment_notification_headers', $message_headers, $comment->comment_ID );
 		foreach ( $emails as $email ) {
-			@wp_mail( $email, wp_specialchars_decode( $subject ), $notify_message, $message_headers );
+			wp_mail( $email, wp_specialchars_decode( $subject ), $notify_message, $message_headers );
 		}
 		if ( $switched_locale ) {
 			restore_previous_locale();
 		}
 			}
 		}
 		$switched_locale = switch_to_locale( get_locale() );
-		$comment_author_domain = @gethostbyaddr( $comment->comment_author_IP );
+		$comment_author_domain = '';
-		$comments_waiting      = $wpdb->get_var( "SELECT count(comment_ID) FROM $wpdb->comments WHERE comment_approved = '0'" );
+		if ( WP_Http::is_ip_address( $comment->comment_author_IP ) ) {
+			$comment_author_domain = gethostbyaddr( $comment->comment_author_IP );
-		// The blogname option is escaped with esc_html on the way into the database in sanitize_option
+		}
-		// we want to reverse this for the plain text arena of emails.
+		$comments_waiting = $wpdb->get_var( "SELECT COUNT(*) FROM $wpdb->comments WHERE comment_approved = '0'" );
+		// The blogname option is escaped with esc_html() on the way into the database in sanitize_option().
+		// We want to reverse this for the plain text arena of emails.
 		$blogname        = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES );
 		$comment_content = wp_specialchars_decode( $comment->comment_content );
 		switch ( $comment->comment_type ) {
 			case 'trackback':
-				/* translators: %s: post title */
+				/* translators: %s: Post title. */
 				$notify_message  = sprintf( __( 'A new trackback on the post "%s" is waiting for your approval' ), $post->post_title ) . "\r\n";
 				$notify_message .= get_permalink( $comment->comment_post_ID ) . "\r\n\r\n";
-				/* translators: 1: trackback/pingback website name, 2: website IP address, 3: website hostname */
+				/* translators: 1: Trackback/pingback website name, 2: Website IP address, 3: Website hostname. */
 				$notify_message .= sprintf( __( 'Website: %1$s (IP address: %2$s, %3$s)' ), $comment->comment_author, $comment->comment_author_IP, $comment_author_domain ) . "\r\n";
-				/* translators: %s: trackback/pingback/comment author URL */
+				/* translators: %s: Trackback/pingback/comment author URL. */
 				$notify_message .= sprintf( __( 'URL: %s' ), $comment->comment_author_url ) . "\r\n";
 				$notify_message .= __( 'Trackback excerpt: ' ) . "\r\n" . $comment_content . "\r\n\r\n";
 				break;
 			case 'pingback':
-				/* translators: %s: post title */
+				/* translators: %s: Post title. */
 				$notify_message  = sprintf( __( 'A new pingback on the post "%s" is waiting for your approval' ), $post->post_title ) . "\r\n";
 				$notify_message .= get_permalink( $comment->comment_post_ID ) . "\r\n\r\n";
-				/* translators: 1: trackback/pingback website name, 2: website IP address, 3: website hostname */
+				/* translators: 1: Trackback/pingback website name, 2: Website IP address, 3: Website hostname. */
 				$notify_message .= sprintf( __( 'Website: %1$s (IP address: %2$s, %3$s)' ), $comment->comment_author, $comment->comment_author_IP, $comment_author_domain ) . "\r\n";
-				/* translators: %s: trackback/pingback/comment author URL */
+				/* translators: %s: Trackback/pingback/comment author URL. */
 				$notify_message .= sprintf( __( 'URL: %s' ), $comment->comment_author_url ) . "\r\n";
 				$notify_message .= __( 'Pingback excerpt: ' ) . "\r\n" . $comment_content . "\r\n\r\n";
 				break;
-			default: // Comments
-				/* translators: %s: post title */
+			default: // Comments.
+				/* translators: %s: Post title. */
 				$notify_message  = sprintf( __( 'A new comment on the post "%s" is waiting for your approval' ), $post->post_title ) . "\r\n";
 				$notify_message .= get_permalink( $comment->comment_post_ID ) . "\r\n\r\n";
-				/* translators: 1: comment author's name, 2: comment author's IP address, 3: comment author's hostname */
+				/* translators: 1: Comment author's name, 2: Comment author's IP address, 3: Comment author's hostname. */
 				$notify_message .= sprintf( __( 'Author: %1$s (IP address: %2$s, %3$s)' ), $comment->comment_author, $comment->comment_author_IP, $comment_author_domain ) . "\r\n";
-				/* translators: %s: comment author email */
+				/* translators: %s: Comment author email. */
 				$notify_message .= sprintf( __( 'Email: %s' ), $comment->comment_author_email ) . "\r\n";
-				/* translators: %s: trackback/pingback/comment author URL */
+				/* translators: %s: Trackback/pingback/comment author URL. */
 				$notify_message .= sprintf( __( 'URL: %s' ), $comment->comment_author_url ) . "\r\n";
-				/* translators: %s: comment text */
+				if ( $comment->comment_parent ) {
+					/* translators: Comment moderation. %s: Parent comment edit URL. */
+					$notify_message .= sprintf( __( 'In reply to: %s' ), admin_url( "comment.php?action=editcomment&c={$comment->comment_parent}#wpbody-content" ) ) . "\r\n";
+				}
+				/* translators: %s: Comment text. */
 				$notify_message .= sprintf( __( 'Comment: %s' ), "\r\n" . $comment_content ) . "\r\n\r\n";
 				break;
 		}
-		/* translators: Comment moderation. %s: Comment action URL */
+		/* translators: Comment moderation. %s: Comment action URL. */
 		$notify_message .= sprintf( __( 'Approve it: %s' ), admin_url( "comment.php?action=approve&c={$comment_id}#wpbody-content" ) ) . "\r\n";
 		if ( EMPTY_TRASH_DAYS ) {
-			/* translators: Comment moderation. %s: Comment action URL */
+			/* translators: Comment moderation. %s: Comment action URL. */
 			$notify_message .= sprintf( __( 'Trash it: %s' ), admin_url( "comment.php?action=trash&c={$comment_id}#wpbody-content" ) ) . "\r\n";
 		} else {
-			/* translators: Comment moderation. %s: Comment action URL */
+			/* translators: Comment moderation. %s: Comment action URL. */
 			$notify_message .= sprintf( __( 'Delete it: %s' ), admin_url( "comment.php?action=delete&c={$comment_id}#wpbody-content" ) ) . "\r\n";
 		}
-		/* translators: Comment moderation. %s: Comment action URL */
+		/* translators: Comment moderation. %s: Comment action URL. */
 		$notify_message .= sprintf( __( 'Spam it: %s' ), admin_url( "comment.php?action=spam&c={$comment_id}#wpbody-content" ) ) . "\r\n";
-		/* translators: Comment moderation. %s: Number of comments awaiting approval */
 		$notify_message .= sprintf(
+			/* translators: Comment moderation. %s: Number of comments awaiting approval. */
 			_n(
 				'Currently %s comment is waiting for approval. Please visit the moderation panel:',
 				'Currently %s comments are waiting for approval. Please visit the moderation panel:',
 				$comments_waiting
 			),
 			number_format_i18n( $comments_waiting )
 		) . "\r\n";
 		$notify_message .= admin_url( 'edit-comments.php?comment_status=moderated#wpbody-content' ) . "\r\n";
-		/* translators: Comment moderation notification email subject. 1: Site name, 2: Post title */
+		/* translators: Comment moderation notification email subject. 1: Site title, 2: Post title. */
 		$subject         = sprintf( __( '[%1$s] Please moderate: "%2$s"' ), $blogname, $post->post_title );
 		$message_headers = '';
 		/**
 		 * Filters the list of recipients for comment moderation emails.
 		 *
 		 * @since 3.7.0
 		 *
-		 * @param array $emails     List of email addresses to notify for comment moderation.
+		 * @param string[] $emails     List of email addresses to notify for comment moderation.
-		 * @param int   $comment_id Comment ID.
+		 * @param int      $comment_id Comment ID.
 		 */
 		$emails = apply_filters( 'comment_moderation_recipients', $emails, $comment_id );
 		/**
 		 * Filters the comment moderation email text.
 		 * @param int    $comment_id      Comment ID.
 		 */
 		$message_headers = apply_filters( 'comment_moderation_headers', $message_headers, $comment_id );
 		foreach ( $emails as $email ) {
-			@wp_mail( $email, wp_specialchars_decode( $subject ), $notify_message, $message_headers );
+			wp_mail( $email, wp_specialchars_decode( $subject ), $notify_message, $message_headers );
 		}
 		if ( $switched_locale ) {
 			restore_previous_locale();
 		}
 	 * @since 2.7.0
 	 *
 	 * @param WP_User $user User object.
 	 */
 	function wp_password_change_notification( $user ) {
-		// send a copy of password change notification to the admin
+		// Send a copy of password change notification to the admin,
-		// but check to see if it's the admin whose password we're changing, and skip this
+		// but check to see if it's the admin whose password we're changing, and skip this.
 		if ( 0 !== strcasecmp( $user->user_email, get_option( 'admin_email' ) ) ) {
-			/* translators: %s: user name */
+			/* translators: %s: User name. */
 			$message = sprintf( __( 'Password changed for user: %s' ), $user->user_login ) . "\r\n";
-			// The blogname option is escaped with esc_html on the way into the database in sanitize_option
+			// The blogname option is escaped with esc_html() on the way into the database in sanitize_option().
-			// we want to reverse this for the plain text arena of emails.
+			// We want to reverse this for the plain text arena of emails.
 			$blogname = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES );
 			$wp_password_change_notification_email = array(
 				'to'      => get_option( 'admin_email' ),
-				/* translators: Password change notification email subject. %s: Site title */
+				/* translators: Password change notification email subject. %s: Site title. */
 				'subject' => __( '[%s] Password Changed' ),
 				'message' => $message,
 				'headers' => '',
 			);
 	 * @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.
 	 * @since 4.6.0 The `$notify` parameter accepts 'user' for sending notification only to the user created.
 	 *
-	 * @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 null   $deprecated Not used (argument deprecated).
 	 * @param string $notify     Optional. Type of notification that should happen. Accepts 'admin' or an empty
 	 *                           string (admin only), 'user', or 'both' (admin and user). Default empty.
 	 */
 	function wp_new_user_notification( $user_id, $deprecated = null, $notify = '' ) {
-		if ( $deprecated !== null ) {
+		if ( null !== $deprecated ) {
 			_deprecated_argument( __FUNCTION__, '4.3.1' );
 		}
-		// Accepts only 'user', 'admin' , 'both' or default '' as $notify
+		// Accepts only 'user', 'admin' , 'both' or default '' as $notify.
 		if ( ! in_array( $notify, array( 'user', 'admin', 'both', '' ), true ) ) {
 			return;
 		}
-		global $wpdb, $wp_hasher;
 		$user = get_userdata( $user_id );
-		// The blogname option is escaped with esc_html on the way into the database in sanitize_option
+		// The blogname option is escaped with esc_html() on the way into the database in sanitize_option().
-		// we want to reverse this for the plain text arena of emails.
+		// We want to reverse this for the plain text arena of emails.
 		$blogname = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES );
 		if ( 'user' !== $notify ) {
 			$switched_locale = switch_to_locale( get_locale() );
-			/* translators: %s: site title */
+			/* translators: %s: Site title. */
 			$message = sprintf( __( 'New user registration on your site %s:' ), $blogname ) . "\r\n\r\n";
-			/* translators: %s: user login */
+			/* translators: %s: User login. */
 			$message .= sprintf( __( 'Username: %s' ), $user->user_login ) . "\r\n\r\n";
-			/* translators: %s: user email address */
+			/* translators: %s: User email address. */
 			$message .= sprintf( __( 'Email: %s' ), $user->user_email ) . "\r\n";
 			$wp_new_user_notification_email_admin = array(
 				'to'      => get_option( 'admin_email' ),
-				/* translators: New user registration notification email subject. %s: Site title */
+				/* translators: New user registration notification email subject. %s: Site title. */
 				'subject' => __( '[%s] New User Registration' ),
 				'message' => $message,
 				'headers' => '',
 			);
 			/**
 			 * Filters the contents of the new user notification email sent to the site admin.
 			 *
 			 * @since 4.9.0
 			 *
-			 * @param array   $wp_new_user_notification_email {
+			 * @param array   $wp_new_user_notification_email_admin {
 			 *     Used to build wp_mail().
 			 *
 			 *     @type string $to      The intended recipient - site admin email address.
 			 *     @type string $subject The subject of the email.
 			 *     @type string $message The body of the email.
 			 * @param WP_User $user     User object for new user.
 			 * @param string  $blogname The site title.
 			 */
 			$wp_new_user_notification_email_admin = apply_filters( 'wp_new_user_notification_email_admin', $wp_new_user_notification_email_admin, $user, $blogname );
-			@wp_mail(
+			wp_mail(
 				$wp_new_user_notification_email_admin['to'],
 				wp_specialchars_decode( sprintf( $wp_new_user_notification_email_admin['subject'], $blogname ) ),
 				$wp_new_user_notification_email_admin['message'],
 				$wp_new_user_notification_email_admin['headers']
 			);
 			if ( $switched_locale ) {
 				restore_previous_locale();
 			}
 		}
-		// `$deprecated was pre-4.3 `$plaintext_pass`. An empty `$plaintext_pass` didn't sent a user notification.
+		// `$deprecated` was pre-4.3 `$plaintext_pass`. An empty `$plaintext_pass` didn't sent a user notification.
 		if ( 'admin' === $notify || ( empty( $deprecated ) && empty( $notify ) ) ) {
 			return;
 		}
-		// Generate something random for a password reset key.
+		$key = get_password_reset_key( $user );
-		$key = wp_generate_password( 20, false );
+		if ( is_wp_error( $key ) ) {
+			return;
-		/** This action is documented in wp-login.php */
+		}
-		do_action( 'retrieve_password_key', $user->user_login, $key );
-		// Now insert the key, hashed, into the DB.
-		if ( empty( $wp_hasher ) ) {
-			require_once ABSPATH . WPINC . '/class-phpass.php';
-			$wp_hasher = new PasswordHash( 8, true );
-		}
-		$hashed = time() . ':' . $wp_hasher->HashPassword( $key );
-		$wpdb->update( $wpdb->users, array( 'user_activation_key' => $hashed ), array( 'user_login' => $user->user_login ) );
 		$switched_locale = switch_to_locale( get_user_locale( $user ) );
-		/* translators: %s: user login */
+		/* translators: %s: User login. */
 		$message  = sprintf( __( 'Username: %s' ), $user->user_login ) . "\r\n\r\n";
 		$message .= __( 'To set your password, visit the following address:' ) . "\r\n\r\n";
-		$message .= '<' . network_site_url( "wp-login.php?action=rp&key=$key&login=" . rawurlencode( $user->user_login ), 'login' ) . ">\r\n\r\n";
+		$message .= network_site_url( "wp-login.php?action=rp&key=$key&login=" . rawurlencode( $user->user_login ), 'login' ) . "\r\n\r\n";
 		$message .= wp_login_url() . "\r\n";
 		$wp_new_user_notification_email = array(
 			'to'      => $user->user_email,
-			/* translators: Login details notification email subject. %s: Site title */
+			/* translators: Login details notification email subject. %s: Site title. */
 			'subject' => __( '[%s] Login Details' ),
 			'message' => $message,
 			'headers' => '',
 		);
 	}
 endif;
 if ( ! function_exists( 'wp_nonce_tick' ) ) :
 	/**
-	 * Get the time-dependent variable for nonce creation.
+	 * Returns the time-dependent variable for nonce creation.
 	 *
 	 * A nonce has a lifespan of two ticks. Nonces in their second tick may be
 	 * updated, e.g. by autosave.
 	 *
 	 * @since 2.5.0
 	}
 endif;
 if ( ! function_exists( 'wp_verify_nonce' ) ) :
 	/**
-	 * Verify that correct nonce was used with time limit.
+	 * Verifies that a correct security nonce was used with time limit.
 	 *
-	 * The user is given an amount of time to use the token, so therefore, since the
+	 * A nonce is valid for 24 hours (by default).
-	 * UID and $action remain the same, the independent variable is the time.
 	 *
 	 * @since 2.0.3
 	 *
-	 * @param string     $nonce  Nonce that was used in the form to verify
+	 * @param string     $nonce  Nonce value that was used for verification, usually via a form field.
 	 * @param string|int $action Should give context to what is taking place and be the same when nonce was created.
-	 * @return false|int False if the nonce is invalid, 1 if the nonce is valid and generated between
+	 * @return int|false 1 if the nonce is valid and generated between 0-12 hours ago,
-	 *                   0-12 hours ago, 2 if the nonce is valid and generated between 12-24 hours ago.
+	 *                   2 if the nonce is valid and generated between 12-24 hours ago.
+	 *                   False if the nonce is invalid.
 	 */
 	function wp_verify_nonce( $nonce, $action = -1 ) {
 		$nonce = (string) $nonce;
 		$user  = wp_get_current_user();
 		$uid   = (int) $user->ID;
 		}
 		$token = wp_get_session_token();
 		$i     = wp_nonce_tick();
-		// Nonce generated 0-12 hours ago
+		// Nonce generated 0-12 hours ago.
 		$expected = substr( wp_hash( $i . '|' . $action . '|' . $uid . '|' . $token, 'nonce' ), -12, 10 );
 		if ( hash_equals( $expected, $nonce ) ) {
 			return 1;
 		}
-		// Nonce generated 12-24 hours ago
+		// Nonce generated 12-24 hours ago.
 		$expected = substr( wp_hash( ( $i - 1 ) . '|' . $action . '|' . $uid . '|' . $token, 'nonce' ), -12, 10 );
 		if ( hash_equals( $expected, $nonce ) ) {
 			return 2;
 		}
 		 * @param WP_User    $user   The current user object.
 		 * @param string     $token  The user's session token.
 		 */
 		do_action( 'wp_verify_nonce_failed', $nonce, $action, $user, $token );
-		// Invalid nonce
+		// Invalid nonce.
 		return false;
 	}
 endif;
 if ( ! function_exists( 'wp_create_nonce' ) ) :
 	}
 endif;
 if ( ! function_exists( 'wp_salt' ) ) :
 	/**
-	 * Get salt to add to hashes.
+	 * Returns a salt to add to hashes.
 	 *
 	 * Salts are created using secret keys. Secret keys are located in two places:
 	 * in the database and in the wp-config.php file. The secret key in the database
 	 * is randomly generated and will be appended to the secret keys in wp-config.php.
 	 *
 	 * common dictionary strings. The added values makes it harder to crack.
 	 *
 	 * @since 2.5.0
 	 *
 	 * @link https://api.wordpress.org/secret-key/1.1/salt/ Create secrets for wp-config.php
-	 *
-	 * @staticvar array $cached_salts
-	 * @staticvar array $duplicated_keys
 	 *
 	 * @param string $scheme Authentication scheme (auth, secure_auth, logged_in, nonce)
 	 * @return string Salt value
 	 */
 	function wp_salt( $scheme = 'auth' ) {
 			'salt' => '',
 		);
 		if ( defined( 'SECRET_KEY' ) && SECRET_KEY && empty( $duplicated_keys[ SECRET_KEY ] ) ) {
 			$values['key'] = SECRET_KEY;
 		}
-		if ( 'auth' == $scheme && defined( 'SECRET_SALT' ) && SECRET_SALT && empty( $duplicated_keys[ SECRET_SALT ] ) ) {
+		if ( 'auth' === $scheme && defined( 'SECRET_SALT' ) && SECRET_SALT && empty( $duplicated_keys[ SECRET_SALT ] ) ) {
 			$values['salt'] = SECRET_SALT;
 		}
-		if ( in_array( $scheme, array( 'auth', 'secure_auth', 'logged_in', 'nonce' ) ) ) {
+		if ( in_array( $scheme, array( 'auth', 'secure_auth', 'logged_in', 'nonce' ), true ) ) {
 			foreach ( array( 'key', 'salt' ) as $type ) {
 				$const = strtoupper( "{$scheme}_{$type}" );
 				if ( defined( $const ) && constant( $const ) && empty( $duplicated_keys[ constant( $const ) ] ) ) {
 					$values[ $type ] = constant( $const );
 				} elseif ( ! $values[ $type ] ) {
 	 */
 	function wp_hash_password( $password ) {
 		global $wp_hasher;
 		if ( empty( $wp_hasher ) ) {
-			require_once( ABSPATH . WPINC . '/class-phpass.php' );
+			require_once ABSPATH . WPINC . '/class-phpass.php';
-			// By default, use the portable hash from phpass
+			// By default, use the portable hash from phpass.
 			$wp_hasher = new PasswordHash( 8, true );
 		}
 		return $wp_hasher->HashPassword( trim( $password ) );
 	}
 	 * instead use the other package password checking algorithm.
 	 *
 	 * @since 2.5.0
 	 *
 	 * @global PasswordHash $wp_hasher PHPass object used for checking the password
-	 *  against the $hash + $password
+	 *                                 against the $hash + $password
 	 * @uses PasswordHash::CheckPassword
 	 *
 	 * @param string     $password Plaintext user's password
 	 * @param string     $hash     Hash of the user's password to check against.
 	 * @param string|int $user_id  Optional. User ID.
 			 * @param string|int $user_id  User ID. Can be empty.
 			 */
 			return apply_filters( 'check_password', $check, $password, $hash, $user_id );
 		}
-		// If the stored hash is longer than an MD5, presume the
+		// If the stored hash is longer than an MD5,
-		// new style phpass portable hash.
+		// presume the new style phpass portable hash.
 		if ( empty( $wp_hasher ) ) {
-			require_once( ABSPATH . WPINC . '/class-phpass.php' );
+			require_once ABSPATH . WPINC . '/class-phpass.php';
-			// By default, use the portable hash from phpass
+			// By default, use the portable hash from phpass.
 			$wp_hasher = new PasswordHash( 8, true );
 		}
 		$check = $wp_hasher->CheckPassword( $password, $hash );
 		/**
 		 * Filters the randomly-generated password.
 		 *
 		 * @since 3.0.0
-		 *
+		 * @since 5.3.0 Added the `$length`, `$special_chars`, and `$extra_special_chars` parameters.
-		 * @param string $password The generated password.
+		 *
-		 */
+		 * @param string $password            The generated password.
-		return apply_filters( 'random_password', $password );
+		 * @param int    $length              The length of password to generate.
+		 * @param bool   $special_chars       Whether to include standard special characters.
+		 * @param bool   $extra_special_chars Whether to include other special characters.
+		 */
+		return apply_filters( 'random_password', $password, $length, $special_chars, $extra_special_chars );
 	}
 endif;
 if ( ! function_exists( 'wp_rand' ) ) :
 	/**
 	 *
 	 * @since 2.6.2
 	 * @since 4.4.0 Uses PHP7 random_int() or the random_compat library if available.
 	 *
 	 * @global string $rnd_value
-	 * @staticvar string $seed
-	 * @staticvar bool $use_random_int_functionality
 	 *
 	 * @param int $min Lower limit for the generated number
 	 * @param int $max Upper limit for the generated number
 	 * @return int A random number between min and max
 	 */
 	function wp_rand( $min = 0, $max = 0 ) {
 		global $rnd_value;
-		// Some misconfigured 32bit environments (Entropy PHP, for example) truncate integers larger than PHP_INT_MAX to PHP_INT_MAX rather than overflowing them to floats.
+		// Some misconfigured 32-bit environments (Entropy PHP, for example)
+		// truncate integers larger than PHP_INT_MAX to PHP_INT_MAX rather than overflowing them to floats.
 		$max_random_number = 3000000000 === 2147483647 ? (float) '4294967295' : 4294967295; // 4294967295 = 0xffffffff
-		// We only handle Ints, floats are truncated to their integer value.
+		// We only handle ints, floats are truncated to their integer value.
 		$min = (int) $min;
 		$max = (int) $max;
-		// Use PHP's CSPRNG, or a compatible method
+		// Use PHP's CSPRNG, or a compatible method.
 		static $use_random_int_functionality = true;
 		if ( $use_random_int_functionality ) {
 			try {
 				$_max = ( 0 != $max ) ? $max : $max_random_number;
 				// wp_rand() can accept arguments in either order, PHP cannot.
 			} catch ( Exception $e ) {
 				$use_random_int_functionality = false;
 			}
 		}
-		// Reset $rnd_value after 14 uses
+		// Reset $rnd_value after 14 uses.
-		// 32(md5) + 40(sha1) + 40(sha1) / 8 = 14 random numbers from $rnd_value
+		// 32 (md5) + 40 (sha1) + 40 (sha1) / 8 = 14 random numbers from $rnd_value.
 		if ( strlen( $rnd_value ) < 8 ) {
 			if ( defined( 'WP_SETUP_CONFIG' ) ) {
 				static $seed = '';
 			} else {
 				$seed = get_transient( 'random_seed' );
 			if ( ! defined( 'WP_SETUP_CONFIG' ) && ! defined( 'WP_INSTALLING' ) ) {
 				set_transient( 'random_seed', $seed );
 			}
 		}
-		// Take the first 8 digits for our value
+		// Take the first 8 digits for our value.
 		$value = substr( $rnd_value, 0, 8 );
 		// Strip the first eight, leaving the remainder for the next call to wp_rand().
 		$rnd_value = substr( $rnd_value, 8 );
 		$value = abs( hexdec( $value ) );
-		// Reduce the value to be within the min - max range
+		// Reduce the value to be within the min - max range.
-		if ( $max != 0 ) {
+		if ( 0 != $max ) {
 			$value = $min + ( $max - $min + 1 ) * $value / ( $max_random_number + 1 );
 		}
 		return abs( intval( $value ) );
 	}
 				'user_activation_key' => '',
 			),
 			array( 'ID' => $user_id )
 		);
-		wp_cache_delete( $user_id, 'users' );
+		clean_user_cache( $user_id );
 	}
 endif;
 if ( ! function_exists( 'get_avatar' ) ) :
 	/**
 	 * Retrieve the avatar `<img>` tag for a user, email address, MD5 hash, comment, or post.
 	 *
 	 * @since 2.5.0
 	 * @since 4.2.0 Optional `$args` parameter added.
 	 *
-	 * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
+	 * @param mixed  $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
-	 *                           user email, WP_User object, WP_Post object, or WP_Comment object.
+	 *                            user email, WP_User object, WP_Post object, or WP_Comment object.
-	 * @param int    $size       Optional. Height and width of the avatar image file in pixels. Default 96.
+	 * @param int    $size        Optional. Height and width of the avatar image file in pixels. Default 96.
-	 * @param string $default    Optional. URL for the default image or a default type. Accepts '404'
+	 * @param string $default     Optional. URL for the default image or a default type. Accepts '404'
-	 *                           (return a 404 instead of a default image), 'retro' (8bit), 'monsterid'
+	 *                            (return a 404 instead of a default image), 'retro' (8bit), 'monsterid'
-	 *                           (monster), 'wavatar' (cartoon face), 'indenticon' (the "quilt"),
+	 *                            (monster), 'wavatar' (cartoon face), 'indenticon' (the "quilt"),
-	 *                           'mystery', 'mm', or 'mysteryman' (The Oyster Man), 'blank' (transparent GIF),
+	 *                            'mystery', 'mm', or 'mysteryman' (The Oyster Man), 'blank' (transparent GIF),
-	 *                           or 'gravatar_default' (the Gravatar logo). Default is the value of the
+	 *                            or 'gravatar_default' (the Gravatar logo). Default is the value of the
-	 *                           'avatar_default' option, with a fallback of 'mystery'.
+	 *                            'avatar_default' option, with a fallback of 'mystery'.
-	 * @param string $alt        Optional. Alternative text to use in &lt;img&gt; tag. Default empty.
+	 * @param string $alt         Optional. Alternative text to use in img tag. Default empty.
-	 * @param array  $args       {
+	 * @param array  $args {
 	 *     Optional. Extra arguments to retrieve the avatar.
 	 *
 	 *     @type int          $height        Display height of the avatar in pixels. Defaults to $size.
 	 *     @type int          $width         Display width of the avatar in pixels. Defaults to $size.
 	 *     @type bool         $force_default Whether to always show the default image, never the Gravatar. Default false.
 	 *     @type string       $rating        What rating to display avatars up to. Accepts 'G', 'PG', 'R', 'X', and are
 	 *                                       judged in that order. Default is the value of the 'avatar_rating' option.
 	 *     @type string       $scheme        URL scheme to use. See set_url_scheme() for accepted values.
 	 *                                       Default null.
-	 *     @type array|string $class         Array or string of additional classes to add to the &lt;img&gt; element.
+	 *     @type array|string $class         Array or string of additional classes to add to the img element.
 	 *                                       Default null.
 	 *     @type bool         $force_display Whether to always show the avatar - ignores the show_avatars option.
 	 *                                       Default false.
+	 *     @type string       $loading       Value for the `loading` attribute.
+	 *                                       Default null.
 	 *     @type string       $extra_attr    HTML attributes to insert in the IMG element. Is not sanitized. Default empty.
 	 * }
-	 * @return false|string `<img>` tag for the user's avatar. False on failure.
+	 * @return string|false `<img>` tag for the user's avatar. False on failure.
 	 */
 	function get_avatar( $id_or_email, $size = 96, $default = '', $alt = '', $args = null ) {
 		$defaults = array(
 			// get_avatar_data() args.
 			'size'          => 96,
 			'rating'        => get_option( 'avatar_rating' ),
 			'scheme'        => null,
 			'alt'           => '',
 			'class'         => null,
 			'force_display' => false,
+			'loading'       => null,
 			'extra_attr'    => '',
 		);
+		if ( wp_lazy_loading_enabled( 'img', 'get_avatar' ) ) {
+			$defaults['loading'] = 'lazy';
+		}
 		if ( empty( $args ) ) {
 			$args = array();
 		}
 		if ( is_object( $id_or_email ) && isset( $id_or_email->comment_ID ) ) {
 			$id_or_email = get_comment( $id_or_email );
 		}
 		/**
-		 * Filters whether to retrieve the avatar URL early.
+		 * Allows the HTML for a user's avatar to be returned early.
 		 *
 		 * Passing a non-null value will effectively short-circuit get_avatar(), passing
 		 * the value through the {@see 'get_avatar'} filter and returning early.
 		 *
 		 * @since 4.2.0
 		 *
-		 * @param string $avatar      HTML for the user's avatar. Default null.
+		 * @param string|null $avatar      HTML for the user's avatar. Default null.
-		 * @param mixed  $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
+		 * @param mixed       $id_or_email The avatar to retrieve. Accepts a user_id, Gravatar MD5 hash,
-		 *                            user email, WP_User object, WP_Post object, or WP_Comment object.
+		 *                                 user email, WP_User object, WP_Post object, or WP_Comment object.
-		 * @param array  $args        Arguments passed to get_avatar_url(), after processing.
+		 * @param array       $args        Arguments passed to get_avatar_url(), after processing.
 		 */
 		$avatar = apply_filters( 'pre_get_avatar', null, $id_or_email, $args );
 		if ( ! is_null( $avatar ) ) {
 			/** This filter is documented in wp-includes/pluggable.php */
 			if ( is_array( $args['class'] ) ) {
 				$class = array_merge( $class, $args['class'] );
 			} else {
 				$class[] = $args['class'];
 			}
+		}
+		// Add `loading` attribute.
+		$extra_attr = $args['extra_attr'];
+		$loading    = $args['loading'];
+		if ( in_array( $loading, array( 'lazy', 'eager' ), true ) && ! preg_match( '/\bloading\s*=/', $extra_attr ) ) {
+			if ( ! empty( $extra_attr ) ) {
+				$extra_attr .= ' ';
+			}
+			$extra_attr .= "loading='{$loading}'";
 		}
 		$avatar = sprintf(
 			"<img alt='%s' src='%s' srcset='%s' class='%s' height='%d' width='%d' %s/>",
 			esc_attr( $args['alt'] ),
 			esc_url( $url ),
 			esc_url( $url2x ) . ' 2x',
 			esc_attr( join( ' ', $class ) ),
 			(int) $args['height'],
 			(int) $args['width'],
-			$args['extra_attr']
+			$extra_attr
 		);
 		/**
-		 * Filters the avatar to retrieve.
+		 * Filters the HTML for a user's avatar.
 		 *
 		 * @since 2.5.0
 		 * @since 4.2.0 The `$args` parameter was added.
 		 *
-		 * @param string $avatar      &lt;img&gt; tag for the user's avatar.
+		 * @param string $avatar      HTML for the user's avatar.
-		 * @param mixed  $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
+		 * @param mixed  $id_or_email The avatar to retrieve. Accepts a user_id, Gravatar MD5 hash,
 		 *                            user email, WP_User object, WP_Post object, or WP_Comment object.
 		 * @param int    $size        Square avatar width and height in pixels to retrieve.
 		 * @param string $default     URL for the default image or a default type. Accepts '404', 'retro', 'monsterid',
-		 *                            'wavatar', 'indenticon','mystery' (or 'mm', or 'mysteryman'), 'blank', or 'gravatar_default'.
+		 *                            'wavatar', 'indenticon', 'mystery', 'mm', 'mysteryman', 'blank', or 'gravatar_default'.
 		 *                            Default is the value of the 'avatar_default' option, with a fallback of 'mystery'.
 		 * @param string $alt         Alternative text to use in the avatar image tag. Default empty.
 		 * @param array  $args        Arguments passed to get_avatar_data(), after processing.
 		 */
 		return apply_filters( 'get_avatar', $avatar, $id_or_email, $args['size'], $args['default'], $args['alt'], $args );
 	 *
 	 * The Diff is available for getting the changes between versions. The output is
 	 * HTML, so the primary use is for displaying the changes. If the two strings
 	 * are equivalent, then an empty string will be returned.
 	 *
-	 * The arguments supported and can be changed are listed below.
-	 *
-	 * 'title' : Default is an empty string. Titles the diff in a manner compatible
-	 *      with the output.
-	 * 'title_left' : Default is an empty string. Change the HTML to the left of the
-	 *      title.
-	 * 'title_right' : Default is an empty string. Change the HTML to the right of
-	 *      the title.
-	 *
 	 * @since 2.6.0
 	 *
 	 * @see wp_parse_args() Used to change defaults to user defined settings.
 	 * @uses Text_Diff
 	 * @uses WP_Text_Diff_Renderer_Table
 	 *
 	 * @param string       $left_string  "old" (left) version of string
 	 * @param string       $right_string "new" (right) version of string
-	 * @param string|array $args         Optional. Change 'title', 'title_left', and 'title_right' defaults.
+	 * @param string|array $args {
+	 *     Associative array of options to pass to WP_Text_Diff_Renderer_Table().
+	 *
+	 *     @type string $title           Titles the diff in a manner compatible
+	 *                                   with the output. Default empty.
+	 *     @type string $title_left      Change the HTML to the left of the title.
+	 *                                   Default empty.
+	 *     @type string $title_right     Change the HTML to the right of the title.
+	 *                                   Default empty.
+	 *     @type bool   $show_split_view True for split view (two columns), false for
+	 *                                   un-split view (single column). Default true.
+	 * }
 	 * @return string Empty string if strings are equivalent or HTML with differences.
 	 */
 	function wp_text_diff( $left_string, $right_string, $args = null ) {
 		$defaults = array(
-			'title'       => '',
+			'title'           => '',
-			'title_left'  => '',
+			'title_left'      => '',
-			'title_right' => '',
+			'title_right'     => '',
+			'show_split_view' => true,
 		);
 		$args     = wp_parse_args( $args, $defaults );
 		if ( ! class_exists( 'WP_Text_Diff_Renderer_Table', false ) ) {
-			require( ABSPATH . WPINC . '/wp-diff.php' );
+			require ABSPATH . WPINC . '/wp-diff.php';
 		}
 		$left_string  = normalize_whitespace( $left_string );
 		$right_string = normalize_whitespace( $right_string );
 		$r .= '</table>';
 		return $r;
 	}
 endif;

changeset 16	a86126ab1dd4
parent 13	d255fe9cd479
child 18	be944660c56a