Changeset 47122 for trunk/src/wp-includes/pluggable.php

Timestamp:

01/29/2020 12:43:23 AM (5 years ago)

Author:

SergeyBiryukov

Message:

Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.

File:

• trunk/src/wp-includes/pluggable.php (modified) (46 diffs)

trunk/src/wp-includes/pluggable.php

@@ -169 +169 @@
      */
     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.
 
         /**
@@ -210 +210 @@
         global $phpmailer;
 
-        // (Re)create it, if it's gone missing
+        // (Re)create it, if it's gone missing.
         if ( ! ( $phpmailer instanceof PHPMailer ) ) {
             require_once ABSPATH . WPINC . '/class-phpmailer.php';
@@ -217 +217 @@
         }
 
-        // Headers
+        // Headers.
         $cc       = array();
         $bcc      = array();
@@ -226 +226 @@
         } else {
             if ( ! is_array( $headers ) ) {
-                // Explode the headers out, so this function can take both
-                // string headers and an array of headers.
+                // Explode the headers out, so this function can take
+                // both string headers and an array of headers.
                 $tempheaders = explode( "\n", str_replace( "\r\n", "\n", $headers ) );
             } else {
@@ -234 +234 @@
             $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 ) {
@@ -245 +245 @@
                         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, '<' );
@@ -299 +299 @@
                             break;
                         default:
-                            // Add it to our grand headers array
+                            // Add it to our grand headers array.
                             $headers[ trim( $name ) ] = trim( $content );
                             break;
@@ -307 +307 @@
         }
 
-        // Empty out the values that may be set
+        // Empty out the values that may be set.
         $phpmailer->clearAllRecipients();
         $phpmailer->clearAttachments();
@@ -313 +313 @@
         $phpmailer->clearReplyTos();
 
-        // From email and name
-        // If we don't have a name from the input headers
+        // Set "From" name and email.
+
+        // 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
-         * there's no easy alternative. Defaulting to admin_email might appear to be another
-         * option but some hosts may refuse to relay mail from an unknown domain. See
-         * https://core.trac.wordpress.org/ticket/5007.
-         */
-
+        /*
+         * 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 there's no easy alternative. Defaulting to admin_email might appear to be
+         * 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.
@@ -366 +367 @@
         }
 
-        // 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' );
 
@@ -380 +381 @@
             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 = '';
 
@@ -410 +411 @@
         }
 
-        // Set to use PHP's mail()
+        // Set to use PHP's mail().
         $phpmailer->isMail();
 
-        // Set Content-Type and charset
-        // If we don't have a content-type from the input headers
+        // Set Content-Type and charset.
+
+        // If we don't have a content-type from the input headers.
         if ( ! isset( $content_type ) ) {
             $content_type = 'text/plain';
@@ -430 +432 @@
         $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 ) {
             $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' );
@@ -538 +540 @@
 
         if ( $user == null ) {
-            // 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.' ) );
@@ -626 +628 @@
         $expiration = $cookie_elements['expiration'];
 
-        // Allow a grace period for POST and Ajax requests
+        // 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() ) {
             /**
@@ -690 +692 @@
         }
 
-        // Ajax/POST grace period set above
+        // Ajax/POST grace period set above.
         if ( $expiration < time() ) {
             $GLOBALS['login_grace_period'] = 1;
@@ -967 +969 @@
         }
 
-        // 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 );
@@ -975 +977 @@
         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 );
@@ -985 +987 @@
         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 );
@@ -991 +993 @@
         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 );
     }
@@ -1027 +1029 @@
      */
     function auth_redirect() {
-        // Checks if a user is logged in, if not redirects them to the login page
-
         $secure = ( is_ssl() || force_ssl_admin() );
 
@@ -1040 +1040 @@
         $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' ) ) {
@@ -1082 +1082 @@
             }
 
-            return;  // The cookie is good so we're done
-        }
-
-        // The cookie is no good so force login
+            return; // The cookie is good, so we're done.
+        }
+
+        // The cookie is no good, so force login.
         nocache_headers();
 
@@ -1263 +1263 @@
 
         if ( ! $is_IIS && PHP_SAPI != 'cgi-fcgi' ) {
-            status_header( $status ); // This causes problems on IIS and some FastCGI setups
+            status_header( $status ); // This causes problems on IIS and some FastCGI setups.
         }
 
@@ -1374 +1374 @@
     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 );
 
@@ -1409 +1409 @@
     function wp_validate_redirect( $location, $default = '' ) {
         $location = 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 ) == '//' ) {
             $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://'.
+        // See https://bugs.php.net/bug.php?id=38143
         $cut  = strpos( $location, '?' );
         $test = $cut ? substr( $location, 0, $cut ) : $location;
@@ -1421 +1422 @@
         $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'] ) ) {
             return $default;
@@ -1440 +1441 @@
         }
 
-        // 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;
@@ -1537 +1539 @@
         $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() ) {
             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;
@@ -1566 +1568 @@
         }
 
-        // 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.
+        // 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 );
@@ -1600 +1602 @@
                 break;
 
-            default: // Comments
+            default: // Comments.
                 /* translators: %s: Post title. */
                 $notify_message = sprintf( __( 'New comment on your post "%s"' ), $post->post_title ) . "\r\n";
@@ -1755 +1757 @@
         $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.
+        // 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 );
@@ -1783 +1785 @@
                 break;
 
-            default: // Comments
+            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";
@@ -1894 +1896 @@
      */
     function wp_password_change_notification( $user ) {
-        // 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
+        // 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.
         if ( 0 !== strcasecmp( $user->user_email, get_option( 'admin_email' ) ) ) {
             /* 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
-            // 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 );
 
@@ -1960 +1962 @@
         }
 
-        // 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;
@@ -1967 +1969 @@
         $user = get_userdata( $user_id );
 
-        // 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.
+        // 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 );
 
@@ -2019 +2021 @@
         }
 
-        // `$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;
@@ -2139 +2141 @@
         $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 ) ) {
@@ -2145 +2147 @@
         }
 
-        // 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 ) ) {
@@ -2163 +2165 @@
         do_action( 'wp_verify_nonce_failed', $nonce, $action, $user, $token );
 
-        // Invalid nonce
+        // Invalid nonce.
         return false;
     }
@@ -2337 +2339 @@
         if ( empty( $wp_hasher ) ) {
             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 );
         }
@@ -2393 +2395 @@
         }
 
-        // If the stored hash is longer than an MD5, presume the
-        // new style phpass portable hash.
+        // If the stored hash is longer than an MD5,
+        // presume the new style phpass portable hash.
         if ( empty( $wp_hasher ) ) {
             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 );
         }
@@ -2471 +2473 @@
         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 ) {
@@ -2499 +2502 @@
         }
 
-        // Reset $rnd_value after 14 uses
-        // 32(md5) + 40(sha1) + 40(sha1) / 8 = 14 random numbers from $rnd_value
+        // Reset $rnd_value after 14 uses.
+        // 32 (md5) + 40 (sha1) + 40 (sha1) / 8 = 14 random numbers from $rnd_value.
         if ( strlen( $rnd_value ) < 8 ) {
             if ( defined( 'WP_SETUP_CONFIG' ) ) {
@@ -2516 +2519 @@
         }
 
-        // Take the first 8 digits for our value
+        // Take the first 8 digits for our value.
         $value = substr( $rnd_value, 0, 8 );
 
@@ -2524 +2527 @@
         $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 ) {
             $value = $min + ( $max - $min + 1 ) * $value / ( $max_random_number + 1 );