Make WordPress Core


Ignore:
Timestamp:
01/29/2020 12:43:23 AM (7 years ago)
Author:
SergeyBiryukov
Message:

Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/canonical.php

    r47060 r47122  
    4848
    4949        // If we're not in wp-admin and the post has been published and preview nonce
    50         // is non-existent or invalid then no need for preview in query
     50        // is non-existent or invalid then no need for preview in query.
    5151        if ( is_preview() && get_query_var( 'p' ) && 'publish' == get_post_status( get_query_var( 'p' ) ) ) {
    5252                if ( ! isset( $_GET['preview_id'] )
    … …  
    6262
    6363        if ( ! $requested_url && isset( $_SERVER['HTTP_HOST'] ) ) {
    64                 // build the URL in the address bar
     64                // Build the URL in the address bar.
    6565                $requested_url  = is_ssl() ? 'https://' : 'http://';
    6666                $requested_url .= $_SERVER['HTTP_HOST'];
    … …  
    7676        $redirect_url = false;
    7777
    78         // Notice fixing
     78        // Notice fixing.
    7979        if ( ! isset( $redirect['path'] ) ) {
    8080                $redirect['path'] = '';
    … …  
    8484        }
    8585
    86         // If the original URL ended with non-breaking spaces, they were almost
    87         // certainly inserted by accident. Let's remove them, so the reader doesn't
    88         // see a 404 error with no obvious cause.
     86        /*
     87         * If the original URL ended with non-breaking spaces, they were almost
     88         * certainly inserted by accident. Let's remove them, so the reader doesn't
     89         * see a 404 error with no obvious cause.
     90         */
    8991        $redirect['path'] = preg_replace( '|(%C2%A0)+$|i', '', $redirect['path'] );
    9092
    91         // It's not a preview, so remove it from URL
     93        // It's not a preview, so remove it from URL.
    9294        if ( get_query_var( 'preview' ) ) {
    9395                $redirect['query'] = remove_query_arg( 'preview', $redirect['query'] );
    … …  
    121123        }
    122124
    123         // These tests give us a WP-generated permalink
     125        // These tests give us a WP-generated permalink.
    124126        if ( is_404() ) {
    125127
    126                 // Redirect ?page_id, ?p=, ?attachment_id= to their respective url's
     128                // Redirect ?page_id, ?p=, ?attachment_id= to their respective URLs.
    127129                $id            = max( get_query_var( 'p' ), get_query_var( 'page_id' ), get_query_var( 'attachment_id' ) );
    128130                $redirect_post = $id ? get_post( $id ) : false;
    … …  
    163165                }
    164166        } elseif ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) {
    165                 // rewriting of old ?p=X, ?m=2004, ?m=200401, ?m=20040101
     167                // Rewriting of old ?p=X, ?m=2004, ?m=200401, ?m=20040101.
    166168                if ( is_attachment() &&
    167169                        ! array_diff( array_keys( $wp->query_vars ), array( 'attachment', 'attachment_id' ) ) &&
    … …  
    200202                        $m = get_query_var( 'm' );
    201203                        switch ( strlen( $m ) ) {
    202                                 case 4: // Yearly
     204                                case 4: // Yearly.
    203205                                        $redirect_url = get_year_link( $m );
    204206                                        break;
    205                                 case 6: // Monthly
     207                                case 6: // Monthly.
    206208                                        $redirect_url = get_month_link( substr( $m, 0, 4 ), substr( $m, 4, 2 ) );
    207209                                        break;
    208                                 case 8: // Daily
     210                                case 8: // Daily.
    209211                                        $redirect_url = get_day_link( substr( $m, 0, 4 ), substr( $m, 4, 2 ), substr( $m, 6, 2 ) );
    210212                                        break;
    … …  
    213215                                $redirect['query'] = remove_query_arg( 'm', $redirect['query'] );
    214216                        }
    215                         // now moving on to non ?m=X year/month/day links
     217                        // Now moving on to non ?m=X year/month/day links.
    216218                } elseif ( is_day() && get_query_var( 'year' ) && get_query_var( 'monthnum' ) && ! empty( $_GET['day'] ) ) {
    217219                        $redirect_url = get_day_link( get_query_var( 'year' ), get_query_var( 'monthnum' ), get_query_var( 'day' ) );
    … …  
    237239                                }
    238240                        }
    239                 } elseif ( is_category() || is_tag() || is_tax() ) { // Terms (Tags/categories)
     241                } elseif ( is_category() || is_tag() || is_tax() ) { // Terms (tags/categories).
    240242
    241243                        $term_count = 0;
    … …  
    249251                                if ( $tax_url && ! is_wp_error( $tax_url ) ) {
    250252                                        if ( ! empty( $redirect['query'] ) ) {
    251                                                 // Strip taxonomy query vars off the url.
     253                                                // Strip taxonomy query vars off the URL.
    252254                                                $qv_remove = array( 'term', 'taxonomy' );
    253255                                                if ( is_category() ) {
    … …  
    257259                                                        $qv_remove[] = 'tag';
    258260                                                        $qv_remove[] = 'tag_id';
    259                                                 } else { // Custom taxonomies will have a custom query var, remove those too:
     261                                                } else {
     262                                                        // Custom taxonomies will have a custom query var, remove those too.
    260263                                                        $tax_obj = get_taxonomy( $obj->taxonomy );
    261264                                                        if ( false !== $tax_obj->query_var ) {
    … …  
    266269                                                $rewrite_vars = array_diff( array_keys( $wp_query->query ), array_keys( $_GET ) );
    267270
    268                                                 if ( ! array_diff( $rewrite_vars, array_keys( $_GET ) ) ) { // Check to see if all the Query vars are coming from the rewrite, none are set via $_GET
    269                                                         $redirect['query'] = remove_query_arg( $qv_remove, $redirect['query'] ); //Remove all of the per-tax qv's
    270 
    271                                                         // Create the destination url for this taxonomy
     271                                                // Check to see if all the query vars are coming from the rewrite, none are set via $_GET.
     272                                                if ( ! array_diff( $rewrite_vars, array_keys( $_GET ) ) ) {
     273                                                        // Remove all of the per-tax query vars.
     274                                                        $redirect['query'] = remove_query_arg( $qv_remove, $redirect['query'] );
     275
     276                                                        // Create the destination URL for this taxonomy.
    272277                                                        $tax_url = parse_url( $tax_url );
    273                                                         if ( ! empty( $tax_url['query'] ) ) { // Taxonomy accessible via ?taxonomy=..&term=.. or any custom qv..
     278                                                        if ( ! empty( $tax_url['query'] ) ) {
     279                                                                // Taxonomy accessible via ?taxonomy=...&term=... or any custom query var.
    274280                                                                parse_str( $tax_url['query'], $query_vars );
    275281                                                                $redirect['query'] = add_query_arg( $query_vars, $redirect['query'] );
    276                                                         } else { // Taxonomy is accessible via a "pretty-URL"
     282                                                        } else {
     283                                                                // Taxonomy is accessible via a "pretty URL".
    277284                                                                $redirect['path'] = $tax_url['path'];
    278285                                                        }
    279                                                 } else { // Some query vars are set via $_GET. Unset those from $_GET that exist via the rewrite
     286                                                } else {
     287                                                        // Some query vars are set via $_GET. Unset those from $_GET that exist via the rewrite.
    280288                                                        foreach ( $qv_remove as $_qv ) {
    281289                                                                if ( isset( $rewrite_vars[ $_qv ] ) ) {
    … …  
    297305                }
    298306
    299                         // Post Paging
     307                        // Post paging.
    300308                if ( is_singular() && get_query_var( 'page' ) ) {
    301309                        if ( ! $redirect_url ) {
    … …  
    314322                }
    315323
    316                         // paging and feeds
     324                        // Paging and feeds.
    317325                if ( get_query_var( 'paged' ) || is_feed() || get_query_var( 'cpage' ) ) {
    318326                        while ( preg_match( "#/$wp_rewrite->pagination_base/?[0-9]+?(/+)?$#", $redirect['path'] ) || preg_match( '#/(comments/?)?(feed|rss|rdf|atom|rss2)(/+)?$#', $redirect['path'] ) || preg_match( "#/{$wp_rewrite->comments_pagination_base}-[0-9]+(/+)?$#", $redirect['path'] ) ) {
    319                                 // Strip off paging and feed
    320                                 $redirect['path'] = preg_replace( "#/$wp_rewrite->pagination_base/?[0-9]+?(/+)?$#", '/', $redirect['path'] ); // strip off any existing paging
    321                                 $redirect['path'] = preg_replace( '#/(comments/?)?(feed|rss2?|rdf|atom)(/+|$)#', '/', $redirect['path'] ); // strip off feed endings
    322                                 $redirect['path'] = preg_replace( "#/{$wp_rewrite->comments_pagination_base}-[0-9]+?(/+)?$#", '/', $redirect['path'] ); // strip off any existing comment paging
     327                                // Strip off paging and feed.
     328                                $redirect['path'] = preg_replace( "#/$wp_rewrite->pagination_base/?[0-9]+?(/+)?$#", '/', $redirect['path'] ); // Strip off any existing paging.
     329                                $redirect['path'] = preg_replace( '#/(comments/?)?(feed|rss2?|rdf|atom)(/+|$)#', '/', $redirect['path'] ); // Strip off feed endings.
     330                                $redirect['path'] = preg_replace( "#/{$wp_rewrite->comments_pagination_base}-[0-9]+?(/+)?$#", '/', $redirect['path'] ); // Strip off any existing comment paging.
    323331                        }
    324332
    … …  
    373381                        }
    374382
    375                         $redirect['path'] = user_trailingslashit( preg_replace( '|/' . preg_quote( $wp_rewrite->index, '|' ) . '/?$|', '/', $redirect['path'] ) ); // strip off trailing /index.php/
     383                        $redirect['path'] = user_trailingslashit( preg_replace( '|/' . preg_quote( $wp_rewrite->index, '|' ) . '/?$|', '/', $redirect['path'] ) ); // Strip off trailing /index.php/.
    376384                        if ( ! empty( $addl_path ) && $wp_rewrite->using_index_permalinks() && strpos( $redirect['path'], '/' . $wp_rewrite->index . '/' ) === false ) {
    377385                                $redirect['path'] = trailingslashit( $redirect['path'] ) . $wp_rewrite->index . '/';
    … …  
    396404        }
    397405
    398         // tack on any additional query vars
     406        // Tack on any additional query vars.
    399407        $redirect['query'] = preg_replace( '#^\??&*?#', '', $redirect['query'] );
    400408        if ( $redirect_url && ! empty( $redirect['query'] ) ) {
    … …  
    421429        }
    422430
    423         // www.example.com vs example.com
     431        // www.example.com vs. example.com
    424432        $user_home = @parse_url( home_url() );
    425433        if ( ! empty( $user_home['host'] ) ) {
    … …  
    430438        }
    431439
    432         // Handle ports
     440        // Handle ports.
    433441        if ( ! empty( $user_home['port'] ) ) {
    434442                $redirect['port'] = $user_home['port'];
    … …  
    437445        }
    438446
    439         // trailing /index.php
     447        // Trailing /index.php.
    440448        $redirect['path'] = preg_replace( '|/' . preg_quote( $wp_rewrite->index, '|' ) . '/*?$|', '/', $redirect['path'] );
    441449
    … …  
    446454                        array(
    447455                                ' ',
    448                                 '%20',  // space
     456                                '%20',  // Space.
    449457                                '!',
    450                                 '%21',  // exclamation mark
     458                                '%21',  // Exclamation mark.
    451459                                '"',
    452                                 '%22',  // double quote
     460                                '%22',  // Double quote.
    453461                                "'",
    454                                 '%27',  // single quote
     462                                '%27',  // Single quote.
    455463                                '(',
    456                                 '%28',  // opening bracket
     464                                '%28',  // Opening bracket.
    457465                                ')',
    458                                 '%29',  // closing bracket
     466                                '%29',  // Closing bracket.
    459467                                ',',
    460                                 '%2C',  // comma
     468                                '%2C',  // Comma.
    461469                                '.',
    462                                 '%2E',  // period
     470                                '%2E',  // Period.
    463471                                ';',
    464                                 '%3B',  // semicolon
     472                                '%3B',  // Semicolon.
    465473                                '{',
    466                                 '%7B',  // opening curly bracket
     474                                '%7B',  // Opening curly bracket.
    467475                                '}',
    468                                 '%7D',  // closing curly bracket
    469                                 '%E2%80%9C', // opening curly quote
    470                                 '%E2%80%9D', // closing curly quote
     476                                '%7D',  // Closing curly bracket.
     477                                '%E2%80%9C', // Opening curly quote.
     478                                '%E2%80%9D', // Closing curly quote.
    471479                        )
    472480                )
    … …  
    480488                $redirect['query'] = preg_replace( "#((p|page_id|cat|tag)=[^&]*?)($punctuation_pattern)+$#", '$1', $redirect['query'] );
    481489
    482                 // Clean up empty query strings
     490                // Clean up empty query strings.
    483491                $redirect['query'] = trim( preg_replace( '#(^|&)(p|page_id|cat|tag)=?(&|$)#', '&', $redirect['query'] ), '&' );
    484492
    485                 // Redirect obsolete feeds
     493                // Redirect obsolete feeds.
    486494                $redirect['query'] = preg_replace( '#(^|&)feed=rss(&|$)#', '$1feed=rss2$2', $redirect['query'] );
    487495
    488                 // Remove redundant leading ampersands
     496                // Remove redundant leading ampersands.
    489497                $redirect['query'] = preg_replace( '#^\??&*?#', '', $redirect['query'] );
    490498        }
    491499
    492         // strip /index.php/ when we're not using PATHINFO permalinks
     500        // Strip /index.php/ when we're not using PATHINFO permalinks.
    493501        if ( ! $wp_rewrite->using_index_permalinks() ) {
    494502                $redirect['path'] = str_replace( '/' . $wp_rewrite->index . '/', '/', $redirect['path'] );
    495503        }
    496504
    497         // trailing slashes
     505        // Trailing slashes.
    498506        if ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() && ! is_404() && ( ! is_front_page() || ( is_front_page() && ( get_query_var( 'paged' ) > 1 ) ) ) ) {
    499507                $user_ts_type = '';
    … …  
    514522        }
    515523
    516         // Strip multiple slashes out of the URL
     524        // Strip multiple slashes out of the URL.
    517525        if ( strpos( $redirect['path'], '//' ) > -1 ) {
    518526                $redirect['path'] = preg_replace( '|/+|', '/', $redirect['path'] );
    519527        }
    520528
    521         // Always trailing slash the Front Page URL
     529        // Always trailing slash the Front Page URL.
    522530        if ( trailingslashit( $redirect['path'] ) == trailingslashit( $user_home['path'] ) ) {
    523531                $redirect['path'] = trailingslashit( $redirect['path'] );
    524532        }
    525533
    526         // Ignore differences in host capitalization, as this can lead to infinite redirects
    527         // Only redirect no-www <=> yes-www
     534        // Ignore differences in host capitalization, as this can lead to infinite redirects.
     535        // Only redirect no-www <=> yes-www.
    528536        if ( strtolower( $original['host'] ) == strtolower( $redirect['host'] ) ||
    529537                ( strtolower( $original['host'] ) != 'www.' . strtolower( $redirect['host'] ) && 'www.' . strtolower( $original['host'] ) != strtolower( $redirect['host'] ) ) ) {
    … …  
    597605        $redirect_url = apply_filters( 'redirect_canonical', $redirect_url, $requested_url );
    598606
    599         // yes, again -- in case the filter aborted the request
     607        // Yes, again -- in case the filter aborted the request.
    600608        if ( ! $redirect_url || strip_fragment_from_url( $redirect_url ) == strip_fragment_from_url( $requested_url ) ) {
    601609                return;
    … …  
    603611
    604612        if ( $do_redirect ) {
    605                 // protect against chained redirects
     613                // Protect against chained redirects.
    606614                if ( ! redirect_canonical( $redirect_url, false ) ) {
    607615                        wp_redirect( $redirect_url, 301 );
    608616                        exit();
    609617                } else {
    610                         // Debug
     618                        // Debug.
    611619                        // die("1: $redirect_url<br />2: " . redirect_canonical( $redirect_url, false ) );
    612620                        return;
    … …  
    688696                $where = $wpdb->prepare( 'post_name LIKE %s', $wpdb->esc_like( get_query_var( 'name' ) ) . '%' );
    689697
    690                 // if any of post_type, year, monthnum, or day are set, use them to refine the query
     698                // If any of post_type, year, monthnum, or day are set, use them to refine the query.
    691699                if ( get_query_var( 'post_type' ) ) {
    692700                        $where .= $wpdb->prepare( ' AND post_type = %s', get_query_var( 'post_type' ) );
Note: See TracChangeset for help on using the changeset viewer.