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

equal deleted inserted replaced

-:be944660c56a
+:3d72ae0968f4
 	 *
 	 * @since 2.0.3
 	 *
 	 * @global WP_User $current_user The current user object which holds the user data.
 	 *
-	 * @param int    $id   User ID
+	 * @param int|null $id   User ID.
-	 * @param string $name User's username
+	 * @param string   $name User's username.
-	 * @return WP_User Current user User object
+	 * @return WP_User Current user User object.
 	 */
 	function wp_set_current_user( $id, $name = '' ) {
 		global $current_user;
 		// If `$id` matches the current user, there is nothing to do.
 	 *
 	 * @since 3.0.0
 	 *
 	 * @global wpdb $wpdb WordPress database abstraction object.
 	 *
-	 * @param array $user_ids User ID numbers list
+	 * @param int[] $user_ids User ID numbers list
 	 */
 	function cache_users( $user_ids ) {
 		global $wpdb;
 		$clean = _get_non_cached_ids( $user_ids, 'users' );
 		 * 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 = wp_parse_url( network_home_url(), PHP_URL_HOST );
+			$sitename   = wp_parse_url( network_home_url(), PHP_URL_HOST );
-			if ( 'www.' === substr( $sitename, 0, 4 ) ) {
+			$from_email = 'wordpress@';
-				$sitename = substr( $sitename, 4 );
+			if ( null !== $sitename ) {
+				if ( 'www.' === substr( $sitename, 0, 4 ) ) {
+					$sitename = substr( $sitename, 4 );
+				}
+				$from_email .= $sitename;
 			}
-			$from_email = 'wordpress@' . $sitename;
 		}
 		/**
 		 * Filters the email address to send from.
 		 *
 		 *
 		 * @param PHPMailer $phpmailer The PHPMailer instance (passed by reference).
 		 */
 		do_action_ref_array( 'phpmailer_init', array( &$phpmailer ) );
+		$mail_data = compact( 'to', 'subject', 'message', 'headers', 'attachments' );
 		// Send!
 		try {
-			return $phpmailer->send();
+			$send = $phpmailer->send();
+			/**
+			 * Fires after PHPMailer has successfully sent an email.
+			 *
+			 * The firing of this action does not necessarily mean that the recipient(s) received the
+			 * email successfully. It only means that the `send` method above was able to
+			 * process the request without any errors.
+			 *
+			 * @since 5.9.0
+			 *
+			 * @param array $mail_data {
+			 *     An array containing the email recipient(s), subject, message, headers, and attachments.
+			 *
+			 *     @type string[] $to          Email addresses to send message.
+			 *     @type string   $subject     Email subject.
+			 *     @type string   $message     Message contents.
+			 *     @type string[] $headers     Additional headers.
+			 *     @type string[] $attachments Paths to files to attach.
+			 * }
+			 */
+			do_action( 'wp_mail_succeeded', $mail_data );
+			return $send;
 		} catch ( PHPMailer\PHPMailer\Exception $e ) {
+			$mail_data['phpmailer_exception_code'] = $e->getCode();
-			$mail_error_data                             = compact( 'to', 'subject', 'message', 'headers', 'attachments' );
-			$mail_error_data['phpmailer_exception_code'] = $e->getCode();
 			/**
 			 * Fires after a PHPMailer\PHPMailer\Exception is caught.
 			 *
 			 * @since 4.4.0
 			 *
 			 * @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 ) );
+			do_action( 'wp_mail_failed', new WP_Error( 'wp_mail_failed', $e->getMessage(), $mail_data ) );
 			return false;
 		}
 	}
 endif;
 			/**
 			 * Fires once an authentication cookie has expired.
 			 *
 			 * @since 2.7.0
 			 *
-			 * @param string[] $cookie_elements An array of data for the authentication cookie.
+			 * @param string[] $cookie_elements {
+			 *     Authentication cookie components. None of the components should be assumed
+			 *     to be valid as they come directly from a client-provided cookie value.
+			 *
+			 *     @type string $username   User's username.
+			 *     @type string $expiration The time the cookie expires as a UNIX timestamp.
+			 *     @type string $token      User's session token used.
+			 *     @type string $hmac       The security hash for the cookie.
+			 *     @type string $scheme     The cookie scheme to use.
+			 * }
 			 */
 			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 string[] $cookie_elements An array of data for the authentication cookie.
+			 * @param string[] $cookie_elements {
+			 *     Authentication cookie components. None of the components should be assumed
+			 *     to be valid as they come directly from a client-provided cookie value.
+			 *
+			 *     @type string $username   User's username.
+			 *     @type string $expiration The time the cookie expires as a UNIX timestamp.
+			 *     @type string $token      User's session token used.
+			 *     @type string $hmac       The security hash for the cookie.
+			 *     @type string $scheme     The cookie scheme to use.
+			 * }
 			 */
 			do_action( 'auth_cookie_bad_username', $cookie_elements );
 			return false;
 		}
 			/**
 			 * Fires if a bad authentication cookie hash is encountered.
 			 *
 			 * @since 2.7.0
 			 *
-			 * @param string[] $cookie_elements An array of data for the authentication cookie.
+			 * @param string[] $cookie_elements {
+			 *     Authentication cookie components. None of the components should be assumed
+			 *     to be valid as they come directly from a client-provided cookie value.
+			 *
+			 *     @type string $username   User's username.
+			 *     @type string $expiration The time the cookie expires as a UNIX timestamp.
+			 *     @type string $token      User's session token used.
+			 *     @type string $hmac       The security hash for the cookie.
+			 *     @type string $scheme     The cookie scheme to use.
+			 * }
 			 */
 			do_action( 'auth_cookie_bad_hash', $cookie_elements );
 			return false;
 		}
 			/**
 			 * Fires if a bad session token is encountered.
 			 *
 			 * @since 4.0.0
 			 *
-			 * @param string[] $cookie_elements An array of data for the authentication cookie.
+			 * @param string[] $cookie_elements {
+			 *     Authentication cookie components. None of the components should be assumed
+			 *     to be valid as they come directly from a client-provided cookie value.
+			 *
+			 *     @type string $username   User's username.
+			 *     @type string $expiration The time the cookie expires as a UNIX timestamp.
+			 *     @type string $token      User's session token used.
+			 *     @type string $hmac       The security hash for the cookie.
+			 *     @type string $scheme     The cookie scheme to use.
+			 * }
 			 */
 			do_action( 'auth_cookie_bad_session_token', $cookie_elements );
 			return false;
 		}
 		/**
 		 * Fires once an authentication cookie has been validated.
 		 *
 		 * @since 2.7.0
 		 *
-		 * @param string[] $cookie_elements An array of data for the authentication cookie.
+		 * @param string[] $cookie_elements {
+		 *     Authentication cookie components.
+		 *
+		 *     @type string $username   User's username.
+		 *     @type string $expiration The time the cookie expires as a UNIX timestamp.
+		 *     @type string $token      User's session token used.
+		 *     @type string $hmac       The security hash for the cookie.
+		 *     @type string $scheme     The cookie scheme to use.
+		 * }
 		 * @param WP_User  $user            User object.
 		 */
 		do_action( 'auth_cookie_valid', $cookie_elements, $user );
 		return $user->ID;
 	 *
 	 * @since 2.7.0
 	 *
 	 * @param string $cookie Authentication cookie.
 	 * @param string $scheme Optional. The cookie scheme to use: 'auth', 'secure_auth', or 'logged_in'.
-	 * @return string[]|false Authentication cookie components.
+	 * @return string[]|false {
+	 *     Authentication cookie components. None of the components should be assumed
+	 *     to be valid as they come directly from a client-provided cookie value. If
+	 *     the cookie value is malformed, false is returned.
+	 *
+	 *     @type string $username   User's username.
+	 *     @type string $expiration The time the cookie expires as a UNIX timestamp.
+	 *     @type string $token      User's session token used.
+	 *     @type string $hmac       The security hash for the cookie.
+	 *     @type string $scheme     The cookie scheme to use.
+	 * }
 	 */
 	function wp_parse_auth_cookie( $cookie = '', $scheme = '' ) {
 		if ( empty( $cookie ) ) {
 			switch ( $scheme ) {
 				case 'auth':
 		 * others to be added.
 		 *
 		 * @since 3.7.0
 		 *
 		 * @param string[] $emails     An array of email addresses to receive a comment notification.
-		 * @param int      $comment_id The comment ID.
+		 * @param string   $comment_id The comment ID as a numeric string.
 		 */
 		$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.
 		 * By default, comment authors aren't notified of their comments on their own
 		 * posts. This filter allows you to override that.
 		 *
 		 * @since 3.8.0
 		 *
-		 * @param bool $notify     Whether to notify the post author of their own comment.
+		 * @param bool   $notify     Whether to notify the post author of their own comment.
-		 *                         Default false.
+		 *                           Default false.
-		 * @param int  $comment_id The comment ID.
+		 * @param string $comment_id The comment ID as a numeric string.
 		 */
 		$notify_author = apply_filters( 'comment_notification_notify_author', false, $comment->comment_ID );
 		// The comment was left by the author.
 		if ( $author && ! $notify_author && $comment->user_id == $post->post_author ) {
 		 * Filters the comment notification email text.
 		 *
 		 * @since 1.5.2
 		 *
 		 * @param string $notify_message The comment notification email text.
-		 * @param int    $comment_id     Comment ID.
+		 * @param string $comment_id     Comment ID as a numeric string.
 		 */
 		$notify_message = apply_filters( 'comment_notification_text', $notify_message, $comment->comment_ID );
 		/**
 		 * Filters the comment notification email subject.
 		 *
 		 * @since 1.5.2
 		 *
 		 * @param string $subject    The comment notification email subject.
-		 * @param int    $comment_id Comment ID.
+		 * @param string $comment_id Comment ID as a numeric string.
 		 */
 		$subject = apply_filters( 'comment_notification_subject', $subject, $comment->comment_ID );
 		/**
 		 * Filters the comment notification email headers.
 		 *
 		 * @since 1.5.2
 		 *
 		 * @param string $message_headers Headers for the comment notification email.
-		 * @param int    $comment_id      Comment ID.
+		 * @param string $comment_id      Comment ID as a numeric string.
 		 */
 		$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 );
 			'loading'       => null,
 			'extra_attr'    => '',
 		);
 		if ( wp_lazy_loading_enabled( 'img', 'get_avatar' ) ) {
-			$defaults['loading'] = 'lazy';
+			$defaults['loading'] = wp_get_loading_attr_default( 'get_avatar' );
 		}
 		if ( empty( $args ) ) {
 			$args = array();
 		}
 		}
 		/**
 		 * Allows the HTML for a user's avatar to be returned early.
 		 *
-		 * Passing a non-null value will effectively short-circuit get_avatar(), passing
+		 * Returning 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|null $avatar      HTML for the user's avatar. Default null.
 		 * @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', '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.
-		 * @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 );
 	}
 endif;

changeset 19	3d72ae0968f4
parent 18	be944660c56a
child 21	48c4eec2b7e6