diff -r 7b1b88e27a20 -r 48c4eec2b7e6 wp/wp-includes/link-template.php --- a/wp/wp-includes/link-template.php Thu Sep 29 08:06:27 2022 +0200 +++ b/wp/wp-includes/link-template.php Fri Sep 05 18:40:08 2025 +0200 @@ -39,17 +39,17 @@ * * @global WP_Rewrite $wp_rewrite WordPress rewrite component. * - * @param string $string URL with or without a trailing slash. + * @param string $url URL with or without a trailing slash. * @param string $type_of_url Optional. The type of URL being considered (e.g. single, category, etc) * for use in the filter. Default empty string. * @return string The URL with the trailing slash appended or stripped. */ -function user_trailingslashit( $string, $type_of_url = '' ) { +function user_trailingslashit( $url, $type_of_url = '' ) { global $wp_rewrite; if ( $wp_rewrite->use_trailing_slashes ) { - $string = trailingslashit( $string ); + $url = trailingslashit( $url ); } else { - $string = untrailingslashit( $string ); + $url = untrailingslashit( $url ); } /** @@ -57,12 +57,12 @@ * * @since 2.2.0 * - * @param string $string URL with or without a trailing slash. + * @param string $url URL with or without a trailing slash. * @param string $type_of_url The type of URL being considered. Accepts 'single', 'single_trackback', * 'single_feed', 'single_paged', 'commentpaged', 'paged', 'home', 'feed', * 'category', 'page', 'year', 'month', 'day', 'post_type_archive'. */ - return apply_filters( 'user_trailingslashit', $string, $type_of_url ); + return apply_filters( 'user_trailingslashit', $url, $type_of_url ); } /** @@ -152,7 +152,7 @@ * * @param int|WP_Post $post Optional. Post ID or post object. Default is the global `$post`. * @param bool $leavename Optional. Whether to keep post name or page name. Default false. - * @return string|false The permalink URL or false if post does not exist. + * @return string|false The permalink URL. False if the post does not exist. */ function get_the_permalink( $post = 0, $leavename = false ) { return get_permalink( $post, $leavename ); @@ -165,7 +165,7 @@ * * @param int|WP_Post $post Optional. Post ID or post object. Default is the global `$post`. * @param bool $leavename Optional. Whether to keep post name or page name. Default false. - * @return string|false The permalink URL or false if post does not exist. + * @return string|false The permalink URL. False if the post does not exist. */ function get_permalink( $post = 0, $leavename = false ) { $rewritecode = array( @@ -222,7 +222,7 @@ ) { $category = ''; - if ( strpos( $permalink, '%category%' ) !== false ) { + if ( str_contains( $permalink, '%category%' ) ) { $cats = get_the_category( $post->ID ); if ( $cats ) { $cats = wp_list_sort( @@ -249,8 +249,10 @@ $category = get_category_parents( $category_object->parent, false, '/', true ) . $category; } } - // Show default category in permalinks, - // without having to assign it explicitly. + /* + * Show default category in permalinks, + * without having to assign it explicitly. + */ if ( empty( $category ) ) { $default_category = get_term( get_option( 'default_category' ), 'category' ); if ( $default_category && ! is_wp_error( $default_category ) ) { @@ -260,13 +262,15 @@ } $author = ''; - if ( strpos( $permalink, '%author%' ) !== false ) { + if ( str_contains( $permalink, '%author%' ) ) { $authordata = get_userdata( $post->post_author ); $author = $authordata->user_nicename; } - // This is not an API call because the permalink is based on the stored post_date value, - // which should be parsed as local time regardless of the default PHP timezone. + /* + * This is not an API call because the permalink is based on the stored post_date value, + * which should be parsed as local time regardless of the default PHP timezone. + */ $date = explode( ' ', str_replace( array( '-', ':' ), ' ', $post->post_date ) ); $rewritereplace = array( @@ -308,21 +312,22 @@ * Retrieves the permalink for a post of a custom post type. * * @since 3.0.0 + * @since 6.1.0 Returns false if the post does not exist. * * @global WP_Rewrite $wp_rewrite WordPress rewrite component. * - * @param int|WP_Post $id Optional. Post ID or post object. Default is the global `$post`. + * @param int|WP_Post $post Optional. Post ID or post object. Default is the global `$post`. * @param bool $leavename Optional. Whether to keep post name. Default false. * @param bool $sample Optional. Is it a sample permalink. Default false. - * @return string|WP_Error The post permalink. + * @return string|false The post permalink URL. False if the post does not exist. */ -function get_post_permalink( $id = 0, $leavename = false, $sample = false ) { +function get_post_permalink( $post = 0, $leavename = false, $sample = false ) { global $wp_rewrite; - $post = get_post( $id ); - - if ( is_wp_error( $post ) ) { - return $post; + $post = get_post( $post ); + + if ( ! $post ) { + return false; } $post_link = $wp_rewrite->get_extra_permastruct( $post->post_type ); @@ -386,7 +391,7 @@ function get_page_link( $post = false, $leavename = false, $sample = false ) { $post = get_post( $post ); - if ( 'page' === get_option( 'show_on_front' ) && get_option( 'page_on_front' ) == $post->ID ) { + if ( 'page' === get_option( 'show_on_front' ) && (int) get_option( 'page_on_front' ) === $post->ID ) { $link = home_url( '/' ); } else { $link = _get_page_link( $post, $leavename, $sample ); @@ -460,8 +465,8 @@ * * @global WP_Rewrite $wp_rewrite WordPress rewrite component. * - * @param int|object $post Optional. Post ID or object. Default uses the global `$post`. - * @param bool $leavename Optional. Whether to keep the page name. Default false. + * @param int|WP_Post $post Optional. Post ID or object. Default uses the global `$post`. + * @param bool $leavename Optional. Whether to keep the page name. Default false. * @return string The attachment permalink. */ function get_attachment_link( $post = null, $leavename = false ) { @@ -495,13 +500,13 @@ $parentlink = get_permalink( $post->post_parent ); } - if ( is_numeric( $post->post_name ) || false !== strpos( get_option( 'permalink_structure' ), '%category%' ) ) { + if ( is_numeric( $post->post_name ) || str_contains( get_option( 'permalink_structure' ), '%category%' ) ) { $name = 'attachment/' . $post->post_name; // // is paged so we use the explicit attachment marker. } else { $name = $post->post_name; } - if ( strpos( $parentlink, '?' ) === false ) { + if ( ! str_contains( $parentlink, '?' ) ) { $link = user_trailingslashit( trailingslashit( $parentlink ) . '%postname%' ); } @@ -691,12 +696,12 @@ $permalink = $wp_rewrite->get_feed_permastruct(); if ( $permalink ) { - if ( false !== strpos( $feed, 'comments_' ) ) { + if ( str_contains( $feed, 'comments_' ) ) { $feed = str_replace( 'comments_', '', $feed ); $permalink = $wp_rewrite->get_comment_feed_permastruct(); } - if ( get_default_feed() == $feed ) { + if ( get_default_feed() === $feed ) { $feed = ''; } @@ -708,7 +713,7 @@ $feed = get_default_feed(); } - if ( false !== strpos( $feed, 'comments_' ) ) { + if ( str_contains( $feed, 'comments_' ) ) { $feed = str_replace( 'comments_', 'comments-', $feed ); } @@ -758,7 +763,7 @@ $unattached = 'attachment' === $post->post_type && 0 === (int) $post->post_parent; if ( get_option( 'permalink_structure' ) ) { - if ( 'page' === get_option( 'show_on_front' ) && get_option( 'page_on_front' ) == $post_id ) { + if ( 'page' === get_option( 'show_on_front' ) && (int) get_option( 'page_on_front' ) === $post_id ) { $url = _get_page_link( $post_id ); } else { $url = get_permalink( $post_id ); @@ -772,7 +777,7 @@ $url = add_query_arg( 'attachment_id', $post_id, $url ); } else { $url = trailingslashit( $url ) . 'feed'; - if ( get_default_feed() != $feed ) { + if ( get_default_feed() !== $feed ) { $url .= "/$feed"; } $url = user_trailingslashit( $url, 'single_feed' ); @@ -874,7 +879,7 @@ $link = home_url( "?feed=$feed&author=" . $author_id ); } else { $link = get_author_posts_url( $author_id ); - if ( get_default_feed() == $feed ) { + if ( get_default_feed() === $feed ) { $feed_link = 'feed'; } else { $feed_link = "feed/$feed"; @@ -957,7 +962,7 @@ } } else { $link = get_term_link( $term, $term->taxonomy ); - if ( get_default_feed() == $feed ) { + if ( get_default_feed() === $feed ) { $feed_link = 'feed'; } else { $feed_link = "feed/$feed"; @@ -1121,14 +1126,14 @@ * * @since 3.1.0 * - * @param string $link Optional. Anchor text. If empty, default is 'Edit This'. Default empty. - * @param string $before Optional. Display before edit link. Default empty. - * @param string $after Optional. Display after edit link. Default empty. - * @param int|WP_Term|null $term Optional. Term ID or object. If null, the queried object will be inspected. Default null. - * @param bool $echo Optional. Whether or not to echo the return. Default true. + * @param string $link Optional. Anchor text. If empty, default is 'Edit This'. Default empty. + * @param string $before Optional. Display before edit link. Default empty. + * @param string $after Optional. Display after edit link. Default empty. + * @param int|WP_Term|null $term Optional. Term ID or object. If null, the queried object will be inspected. Default null. + * @param bool $display Optional. Whether or not to echo the return. Default true. * @return string|void HTML content. */ -function edit_term_link( $link = '', $before = '', $after = '', $term = null, $echo = true ) { +function edit_term_link( $link = '', $before = '', $after = '', $term = null, $display = true ) { if ( is_null( $term ) ) { $term = get_queried_object(); } else { @@ -1160,7 +1165,7 @@ */ $link = $before . apply_filters( 'edit_term_link', $link, $term->term_id ) . $after; - if ( $echo ) { + if ( $display ) { echo $link; } else { return $link; @@ -1298,6 +1303,7 @@ global $wp_rewrite; $post_type_obj = get_post_type_object( $post_type ); + if ( ! $post_type_obj ) { return false; } @@ -1368,7 +1374,7 @@ if ( get_option( 'permalink_structure' ) && is_array( $post_type_obj->rewrite ) && $post_type_obj->rewrite['feeds'] ) { $link = trailingslashit( $link ); $link .= 'feed/'; - if ( $feed != $default_feed ) { + if ( $feed !== $default_feed ) { $link .= "$feed/"; } } else { @@ -1402,6 +1408,7 @@ */ function get_preview_post_link( $post = null, $query_args = array(), $preview_link = '' ) { $post = get_post( $post ); + if ( ! $post ) { return; } @@ -1432,17 +1439,20 @@ * Retrieves the edit post link for post. * * Can be used within the WordPress loop or outside of it. Can be used with - * pages, posts, attachments, and revisions. + * pages, posts, attachments, revisions, global styles, templates, and template parts. * * @since 2.3.0 - * - * @param int|WP_Post $id Optional. Post ID or post object. Default is the global `$post`. + * @since 6.3.0 Adds custom link for wp_navigation post types. + * Adds custom links for wp_template_part and wp_template post types. + * + * @param int|WP_Post $post Optional. Post ID or post object. Default is the global `$post`. * @param string $context Optional. How to output the '&' character. Default '&'. * @return string|null The edit post link for the given post. Null if the post type does not exist * or does not allow an editing UI. */ -function get_edit_post_link( $id = 0, $context = 'display' ) { - $post = get_post( $id ); +function get_edit_post_link( $post = 0, $context = 'display' ) { + $post = get_post( $post ); + if ( ! $post ) { return; } @@ -1456,6 +1466,7 @@ } $post_type_object = get_post_type_object( $post->post_type ); + if ( ! $post_type_object ) { return; } @@ -1464,10 +1475,15 @@ return; } - if ( $post_type_object->_edit_link ) { + $link = ''; + + if ( 'wp_template' === $post->post_type || 'wp_template_part' === $post->post_type ) { + $slug = urlencode( get_stylesheet() . '//' . $post->post_name ); + $link = admin_url( sprintf( $post_type_object->_edit_link, $post->post_type, $slug ) ); + } elseif ( 'wp_navigation' === $post->post_type ) { + $link = admin_url( sprintf( $post_type_object->_edit_link, (string) $post->ID ) ); + } elseif ( $post_type_object->_edit_link ) { $link = admin_url( sprintf( $post_type_object->_edit_link . $action, $post->ID ) ); - } else { - $link = ''; } /** @@ -1487,21 +1503,23 @@ * Displays the edit post link for post. * * @since 1.0.0 - * @since 4.4.0 The `$class` argument was added. - * - * @param string $text Optional. Anchor text. If null, default is 'Edit This'. Default null. - * @param string $before Optional. Display before edit link. Default empty. - * @param string $after Optional. Display after edit link. Default empty. - * @param int|WP_Post $id Optional. Post ID or post object. Default is the global `$post`. - * @param string $class Optional. Add custom class to link. Default 'post-edit-link'. + * @since 4.4.0 The `$css_class` argument was added. + * + * @param string $text Optional. Anchor text. If null, default is 'Edit This'. Default null. + * @param string $before Optional. Display before edit link. Default empty. + * @param string $after Optional. Display after edit link. Default empty. + * @param int|WP_Post $post Optional. Post ID or post object. Default is the global `$post`. + * @param string $css_class Optional. Add custom class to link. Default 'post-edit-link'. */ -function edit_post_link( $text = null, $before = '', $after = '', $id = 0, $class = 'post-edit-link' ) { - $post = get_post( $id ); +function edit_post_link( $text = null, $before = '', $after = '', $post = 0, $css_class = 'post-edit-link' ) { + $post = get_post( $post ); + if ( ! $post ) { return; } $url = get_edit_post_link( $post->ID ); + if ( ! $url ) { return; } @@ -1510,7 +1528,7 @@ $text = __( 'Edit This' ); } - $link = '' . $text . ''; + $link = '' . $text . ''; /** * Filters the post edit link anchor tag. @@ -1531,22 +1549,24 @@ * * @since 2.9.0 * - * @param int|WP_Post $id Optional. Post ID or post object. Default is the global `$post`. + * @param int|WP_Post $post Optional. Post ID or post object. Default is the global `$post`. * @param string $deprecated Not used. * @param bool $force_delete Optional. Whether to bypass Trash and force deletion. Default false. * @return string|void The delete post link URL for the given post. */ -function get_delete_post_link( $id = 0, $deprecated = '', $force_delete = false ) { +function get_delete_post_link( $post = 0, $deprecated = '', $force_delete = false ) { if ( ! empty( $deprecated ) ) { _deprecated_argument( __FUNCTION__, '3.0.0' ); } - $post = get_post( $id ); + $post = get_post( $post ); + if ( ! $post ) { return; } $post_type_object = get_post_type_object( $post->post_type ); + if ( ! $post_type_object ) { return; } @@ -1717,7 +1737,7 @@ return ''; } - if ( get_current_user_id() == $user->ID ) { + if ( get_current_user_id() === $user->ID ) { $link = get_edit_profile_url( $user->ID ); } else { $link = add_query_arg( 'user_id', $user->ID, self_admin_url( 'user-edit.php' ) ); @@ -1743,11 +1763,13 @@ * * @since 1.5.0 * - * @param bool $in_same_term Optional. Whether post should be in a same taxonomy term. Default false. - * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty. - * @param string $taxonomy Optional. Taxonomy, if $in_same_term is true. Default 'category'. - * @return WP_Post|null|string Post object if successful. Null if global $post is not set. Empty string if no - * corresponding post exists. + * @param bool $in_same_term Optional. Whether post should be in the same taxonomy term. + * Default false. + * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. + * Default empty. + * @param string $taxonomy Optional. Taxonomy, if `$in_same_term` is true. Default 'category'. + * @return WP_Post|null|string Post object if successful. Null if global `$post` is not set. + * Empty string if no corresponding post exists. */ function get_previous_post( $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) { return get_adjacent_post( $in_same_term, $excluded_terms, true, $taxonomy ); @@ -1758,11 +1780,13 @@ * * @since 1.5.0 * - * @param bool $in_same_term Optional. Whether post should be in a same taxonomy term. Default false. - * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty. - * @param string $taxonomy Optional. Taxonomy, if $in_same_term is true. Default 'category'. - * @return WP_Post|null|string Post object if successful. Null if global $post is not set. Empty string if no - * corresponding post exists. + * @param bool $in_same_term Optional. Whether post should be in the same taxonomy term. + * Default false. + * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. + * Default empty. + * @param string $taxonomy Optional. Taxonomy, if `$in_same_term` is true. Default 'category'. + * @return WP_Post|null|string Post object if successful. Null if global `$post` is not set. + * Empty string if no corresponding post exists. */ function get_next_post( $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) { return get_adjacent_post( $in_same_term, $excluded_terms, false, $taxonomy ); @@ -1777,17 +1801,21 @@ * * @global wpdb $wpdb WordPress database abstraction object. * - * @param bool $in_same_term Optional. Whether post should be in a same taxonomy term. Default false. - * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty string. - * @param bool $previous Optional. Whether to retrieve previous post. Default true - * @param string $taxonomy Optional. Taxonomy, if $in_same_term is true. Default 'category'. - * @return WP_Post|null|string Post object if successful. Null if global $post is not set. Empty string if no - * corresponding post exists. + * @param bool $in_same_term Optional. Whether post should be in the same taxonomy term. + * Default false. + * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. + * Default empty string. + * @param bool $previous Optional. Whether to retrieve previous post. + * Default true. + * @param string $taxonomy Optional. Taxonomy, if `$in_same_term` is true. Default 'category'. + * @return WP_Post|null|string Post object if successful. Null if global `$post` is not set. + * Empty string if no corresponding post exists. */ function get_adjacent_post( $in_same_term = false, $excluded_terms = '', $previous = true, $taxonomy = 'category' ) { global $wpdb; $post = get_post(); + if ( ! $post || ! taxonomy_exists( $taxonomy ) ) { return null; } @@ -1800,7 +1828,7 @@ if ( ! empty( $excluded_terms ) && ! is_array( $excluded_terms ) ) { // Back-compat, $excluded_terms used to be $excluded_categories with IDs separated by " and ". - if ( false !== strpos( $excluded_terms, ' and ' ) ) { + if ( str_contains( $excluded_terms, ' and ' ) ) { _deprecated_argument( __FUNCTION__, '3.3.0', @@ -1831,7 +1859,7 @@ * * @since 4.4.0 * - * @param array|string $excluded_terms Array of excluded term IDs. Empty string if none were provided. + * @param int[]|string $excluded_terms Array of excluded term IDs. Empty string if none were provided. */ $excluded_terms = apply_filters( "get_{$adjacent}_post_excluded_terms", $excluded_terms ); @@ -1908,11 +1936,11 @@ * @since 2.5.0 * @since 4.4.0 Added the `$taxonomy` and `$post` parameters. * - * @param string $join The JOIN clause in the SQL. - * @param bool $in_same_term Whether post should be in a same taxonomy term. - * @param array $excluded_terms Array of excluded term IDs. - * @param string $taxonomy Taxonomy. Used to identify the term used when `$in_same_term` is true. - * @param WP_Post $post WP_Post object. + * @param string $join The JOIN clause in the SQL. + * @param bool $in_same_term Whether post should be in the same taxonomy term. + * @param int[]|string $excluded_terms Array of excluded term IDs. Empty string if none were provided. + * @param string $taxonomy Taxonomy. Used to identify the term used when `$in_same_term` is true. + * @param WP_Post $post WP_Post object. */ $join = apply_filters( "get_{$adjacent}_post_join", $join, $in_same_term, $excluded_terms, $taxonomy, $post ); @@ -1930,11 +1958,11 @@ * @since 2.5.0 * @since 4.4.0 Added the `$taxonomy` and `$post` parameters. * - * @param string $where The `WHERE` clause in the SQL. - * @param bool $in_same_term Whether post should be in a same taxonomy term. - * @param array $excluded_terms Array of excluded term IDs. - * @param string $taxonomy Taxonomy. Used to identify the term used when `$in_same_term` is true. - * @param WP_Post $post WP_Post object. + * @param string $where The `WHERE` clause in the SQL. + * @param bool $in_same_term Whether post should be in the same taxonomy term. + * @param int[]|string $excluded_terms Array of excluded term IDs. Empty string if none were provided. + * @param string $taxonomy Taxonomy. Used to identify the term used when `$in_same_term` is true. + * @param WP_Post $post WP_Post object. */ $where = apply_filters( "get_{$adjacent}_post_where", $wpdb->prepare( "WHERE p.post_date $op %s AND p.post_type = %s $where", $current_post_date, $post->post_type ), $in_same_term, $excluded_terms, $taxonomy, $post ); @@ -1959,9 +1987,15 @@ */ $sort = apply_filters( "get_{$adjacent}_post_sort", "ORDER BY p.post_date $order LIMIT 1", $post, $order ); - $query = "SELECT p.ID FROM $wpdb->posts AS p $join $where $sort"; - $query_key = 'adjacent_post_' . md5( $query ); - $result = wp_cache_get( $query_key, 'counts' ); + $query = "SELECT p.ID FROM $wpdb->posts AS p $join $where $sort"; + $key = md5( $query ); + $last_changed = wp_cache_get_last_changed( 'posts' ); + if ( $in_same_term || ! empty( $excluded_terms ) ) { + $last_changed .= wp_cache_get_last_changed( 'terms' ); + } + $cache_key = "adjacent_post:$key:$last_changed"; + + $result = wp_cache_get( $cache_key, 'post-queries' ); if ( false !== $result ) { if ( $result ) { $result = get_post( $result ); @@ -1974,7 +2008,7 @@ $result = ''; } - wp_cache_set( $query_key, $result, 'counts' ); + wp_cache_set( $cache_key, $result, 'post-queries' ); if ( $result ) { $result = get_post( $result ); @@ -1991,10 +2025,13 @@ * @since 2.8.0 * * @param string $title Optional. Link title format. Default '%title'. - * @param bool $in_same_term Optional. Whether link should be in a same taxonomy term. Default false. - * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty. - * @param bool $previous Optional. Whether to display link to previous or next post. Default true. - * @param string $taxonomy Optional. Taxonomy, if $in_same_term is true. Default 'category'. + * @param bool $in_same_term Optional. Whether link should be in the same taxonomy term. + * Default false. + * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. + * Default empty. + * @param bool $previous Optional. Whether to display link to previous or next post. + * Default true. + * @param string $taxonomy Optional. Taxonomy, if `$in_same_term` is true. Default 'category'. * @return string|void The adjacent post relational link URL. */ function get_adjacent_post_rel_link( $title = '%title', $in_same_term = false, $excluded_terms = '', $previous = true, $taxonomy = 'category' ) { @@ -2055,9 +2092,11 @@ * @since 2.8.0 * * @param string $title Optional. Link title format. Default '%title'. - * @param bool $in_same_term Optional. Whether link should be in a same taxonomy term. Default false. - * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty. - * @param string $taxonomy Optional. Taxonomy, if $in_same_term is true. Default 'category'. + * @param bool $in_same_term Optional. Whether link should be in the same taxonomy term. + * Default false. + * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. + * Default empty. + * @param string $taxonomy Optional. Taxonomy, if `$in_same_term` is true. Default 'category'. */ function adjacent_posts_rel_link( $title = '%title', $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) { echo get_adjacent_post_rel_link( $title, $in_same_term, $excluded_terms, true, $taxonomy ); @@ -2090,9 +2129,11 @@ * @see get_adjacent_post_rel_link() * * @param string $title Optional. Link title format. Default '%title'. - * @param bool $in_same_term Optional. Whether link should be in a same taxonomy term. Default false. - * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty. - * @param string $taxonomy Optional. Taxonomy, if $in_same_term is true. Default 'category'. + * @param bool $in_same_term Optional. Whether link should be in the same taxonomy term. + * Default false. + * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. + * Default empty. + * @param string $taxonomy Optional. Taxonomy, if `$in_same_term` is true. Default 'category'. */ function next_post_rel_link( $title = '%title', $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) { echo get_adjacent_post_rel_link( $title, $in_same_term, $excluded_terms, false, $taxonomy ); @@ -2106,9 +2147,11 @@ * @see get_adjacent_post_rel_link() * * @param string $title Optional. Link title format. Default '%title'. - * @param bool $in_same_term Optional. Whether link should be in a same taxonomy term. Default false. - * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default true. - * @param string $taxonomy Optional. Taxonomy, if $in_same_term is true. Default 'category'. + * @param bool $in_same_term Optional. Whether link should be in the same taxonomy term. + * Default false. + * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. + * Default true. + * @param string $taxonomy Optional. Taxonomy, if `$in_same_term` is true. Default 'category'. */ function prev_post_rel_link( $title = '%title', $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) { echo get_adjacent_post_rel_link( $title, $in_same_term, $excluded_terms, true, $taxonomy ); @@ -2118,20 +2161,22 @@ * Retrieves the boundary post. * * Boundary being either the first or last post by publish date within the constraints specified - * by $in_same_term or $excluded_terms. + * by `$in_same_term` or `$excluded_terms`. * * @since 2.8.0 * - * @param bool $in_same_term Optional. Whether returned post should be in a same taxonomy term. + * @param bool $in_same_term Optional. Whether returned post should be in the same taxonomy term. * Default false. * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. * Default empty. - * @param bool $start Optional. Whether to retrieve first or last post. Default true - * @param string $taxonomy Optional. Taxonomy, if $in_same_term is true. Default 'category'. - * @return null|array Array containing the boundary post object if successful, null otherwise. + * @param bool $start Optional. Whether to retrieve first or last post. + * Default true. + * @param string $taxonomy Optional. Taxonomy, if `$in_same_term` is true. Default 'category'. + * @return array|null Array containing the boundary post object if successful, null otherwise. */ function get_boundary_post( $in_same_term = false, $excluded_terms = '', $start = true, $taxonomy = 'category' ) { $post = get_post(); + if ( ! $post || ! is_single() || is_attachment() || ! taxonomy_exists( $taxonomy ) ) { return null; } @@ -2187,9 +2232,11 @@ * * @param string $format Optional. Link anchor format. Default '« %link'. * @param string $link Optional. Link permalink format. Default '%title'. - * @param bool $in_same_term Optional. Whether link should be in a same taxonomy term. Default false. - * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty. - * @param string $taxonomy Optional. Taxonomy, if $in_same_term is true. Default 'category'. + * @param bool $in_same_term Optional. Whether link should be in the same taxonomy term. + * Default false. + * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. + * Default empty. + * @param string $taxonomy Optional. Taxonomy, if `$in_same_term` is true. Default 'category'. * @return string The link URL of the previous post in relation to the current post. */ function get_previous_post_link( $format = '« %link', $link = '%title', $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) { @@ -2205,9 +2252,11 @@ * * @param string $format Optional. Link anchor format. Default '« %link'. * @param string $link Optional. Link permalink format. Default '%title'. - * @param bool $in_same_term Optional. Whether link should be in a same taxonomy term. Default false. - * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty. - * @param string $taxonomy Optional. Taxonomy, if $in_same_term is true. Default 'category'. + * @param bool $in_same_term Optional. Whether link should be in the same taxonomy term. + * Default false. + * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. + * Default empty. + * @param string $taxonomy Optional. Taxonomy, if `$in_same_term` is true. Default 'category'. */ function previous_post_link( $format = '« %link', $link = '%title', $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) { echo get_previous_post_link( $format, $link, $in_same_term, $excluded_terms, $taxonomy ); @@ -2220,9 +2269,11 @@ * * @param string $format Optional. Link anchor format. Default '« %link'. * @param string $link Optional. Link permalink format. Default '%title'. - * @param bool $in_same_term Optional. Whether link should be in a same taxonomy term. Default false. - * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty. - * @param string $taxonomy Optional. Taxonomy, if $in_same_term is true. Default 'category'. + * @param bool $in_same_term Optional. Whether link should be in the same taxonomy term. + * Default false. + * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. + * Default empty. + * @param string $taxonomy Optional. Taxonomy, if `$in_same_term` is true. Default 'category'. * @return string The link URL of the next post in relation to the current post. */ function get_next_post_link( $format = '%link »', $link = '%title', $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) { @@ -2237,10 +2288,12 @@ * @see get_next_post_link() * * @param string $format Optional. Link anchor format. Default '« %link'. - * @param string $link Optional. Link permalink format. Default '%title' - * @param bool $in_same_term Optional. Whether link should be in a same taxonomy term. Default false. - * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. Default empty. - * @param string $taxonomy Optional. Taxonomy, if $in_same_term is true. Default 'category'. + * @param string $link Optional. Link permalink format. Default '%title'. + * @param bool $in_same_term Optional. Whether link should be in the same taxonomy term. + * Default false. + * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded term IDs. + * Default empty. + * @param string $taxonomy Optional. Taxonomy, if `$in_same_term` is true. Default 'category'. */ function next_post_link( $format = '%link »', $link = '%title', $in_same_term = false, $excluded_terms = '', $taxonomy = 'category' ) { echo get_next_post_link( $format, $link, $in_same_term, $excluded_terms, $taxonomy ); @@ -2255,10 +2308,13 @@ * * @param string $format Link anchor format. * @param string $link Link permalink format. - * @param bool $in_same_term Optional. Whether link should be in a same taxonomy term. Default false. - * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded terms IDs. Default empty. - * @param bool $previous Optional. Whether to display link to previous or next post. Default true. - * @param string $taxonomy Optional. Taxonomy, if $in_same_term is true. Default 'category'. + * @param bool $in_same_term Optional. Whether link should be in the same taxonomy term. + * Default false. + * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded terms IDs. + * Default empty. + * @param bool $previous Optional. Whether to display link to previous or next post. + * Default true. + * @param string $taxonomy Optional. Taxonomy, if `$in_same_term` is true. Default 'category'. * @return string The link URL of the previous or next post in relation to the current post. */ function get_adjacent_post_link( $format, $link, $in_same_term = false, $excluded_terms = '', $previous = true, $taxonomy = 'category' ) { @@ -2307,11 +2363,11 @@ * @since 2.6.0 * @since 4.2.0 Added the `$adjacent` parameter. * - * @param string $output The adjacent post link. - * @param string $format Link anchor format. - * @param string $link Link permalink format. - * @param WP_Post $post The adjacent post. - * @param string $adjacent Whether the post is previous or next. + * @param string $output The adjacent post link. + * @param string $format Link anchor format. + * @param string $link Link permalink format. + * @param WP_Post|string $post The adjacent post. Empty string if no corresponding post exists. + * @param string $adjacent Whether the post is previous or next. */ return apply_filters( "{$adjacent}_post_link", $output, $format, $link, $post, $adjacent ); } @@ -2325,10 +2381,13 @@ * * @param string $format Link anchor format. * @param string $link Link permalink format. - * @param bool $in_same_term Optional. Whether link should be in a same taxonomy term. Default false. - * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded category IDs. Default empty. - * @param bool $previous Optional. Whether to display link to previous or next post. Default true. - * @param string $taxonomy Optional. Taxonomy, if $in_same_term is true. Default 'category'. + * @param bool $in_same_term Optional. Whether link should be in the same taxonomy term. + * Default false. + * @param int[]|string $excluded_terms Optional. Array or comma-separated list of excluded category IDs. + * Default empty. + * @param bool $previous Optional. Whether to display link to previous or next post. + * Default true. + * @param string $taxonomy Optional. Taxonomy, if `$in_same_term` is true. Default 'category'. */ function adjacent_post_link( $format, $link, $in_same_term = false, $excluded_terms = '', $previous = true, $taxonomy = 'category' ) { echo get_adjacent_post_link( $format, $link, $in_same_term, $excluded_terms, $previous, $taxonomy ); @@ -2342,8 +2401,8 @@ * @global WP_Rewrite $wp_rewrite WordPress rewrite component. * * @param int $pagenum Optional. Page number. Default 1. - * @param bool $escape Optional. Whether to escape the URL for display, with esc_url(). Defaults to true. - * Otherwise, prepares the URL with esc_url_raw(). + * @param bool $escape Optional. Whether to escape the URL for display, with esc_url(). + * If set to false, prepares the URL with sanitize_url(). Default true. * @return string The link URL for the given page number. */ function get_pagenum_link( $pagenum = 1, $escape = true ) { @@ -2372,6 +2431,9 @@ $qs_regex = '|\?.*?$|'; preg_match( $qs_regex, $request, $qs_match ); + $parts = array(); + $parts[] = untrailingslashit( get_bloginfo( 'url' ) ); + if ( ! empty( $qs_match[0] ) ) { $query_string = $qs_match[0]; $request = preg_replace( $qs_regex, '', $request ); @@ -2383,17 +2445,21 @@ $request = preg_replace( '|^' . preg_quote( $wp_rewrite->index, '|' ) . '|i', '', $request ); $request = ltrim( $request, '/' ); - $base = trailingslashit( get_bloginfo( 'url' ) ); - if ( $wp_rewrite->using_index_permalinks() && ( $pagenum > 1 || '' !== $request ) ) { - $base .= $wp_rewrite->index . '/'; + $parts[] = $wp_rewrite->index; } + $parts[] = untrailingslashit( $request ); + if ( $pagenum > 1 ) { - $request = ( ( ! empty( $request ) ) ? trailingslashit( $request ) : $request ) . user_trailingslashit( $wp_rewrite->pagination_base . '/' . $pagenum, 'paged' ); + $parts[] = $wp_rewrite->pagination_base; + $parts[] = $pagenum; } - $result = $base . $request . $query_string; + $result = user_trailingslashit( implode( '/', array_filter( $parts ) ), 'paged' ); + if ( ! empty( $query_string ) ) { + $result .= $query_string; + } } /** @@ -2410,7 +2476,7 @@ if ( $escape ) { return esc_url( $result ); } else { - return esc_url_raw( $result ); + return sanitize_url( $result ); } } @@ -2433,9 +2499,11 @@ if ( ! $paged ) { $paged = 1; } - $nextpage = (int) $paged + 1; - if ( ! $max_page || $max_page >= $nextpage ) { - return get_pagenum_link( $nextpage ); + + $next_page = (int) $paged + 1; + + if ( ! $max_page || $max_page >= $next_page ) { + return get_pagenum_link( $next_page ); } } } @@ -2446,13 +2514,14 @@ * @since 0.71 * * @param int $max_page Optional. Max pages. Default 0. - * @param bool $echo Optional. Whether to echo the link. Default true. - * @return string|void The link URL for next posts page if `$echo = false`. + * @param bool $display Optional. Whether to echo the link. Default true. + * @return string|void The link URL for next posts page if `$display = false`. */ -function next_posts( $max_page = 0, $echo = true ) { - $output = esc_url( get_next_posts_page_link( $max_page ) ); - - if ( $echo ) { +function next_posts( $max_page = 0, $display = true ) { + $link = get_next_posts_page_link( $max_page ); + $output = $link ? esc_url( $link ) : ''; + + if ( $display ) { echo $output; } else { return $output; @@ -2482,13 +2551,13 @@ $paged = 1; } - $nextpage = (int) $paged + 1; + $next_page = (int) $paged + 1; if ( null === $label ) { $label = __( 'Next Page »' ); } - if ( ! is_single() && ( $nextpage <= $max_page ) ) { + if ( ! is_single() && ( $next_page <= $max_page ) ) { /** * Filters the anchor tag attributes for the next posts page link. * @@ -2498,7 +2567,12 @@ */ $attr = apply_filters( 'next_posts_link_attributes', '' ); - return '" . preg_replace( '/&([^#])(?![a-z]{1,8};)/i', '&$1', $label ) . ''; + return sprintf( + '%3$s', + next_posts( $max_page, false ), + $attr, + preg_replace( '/&([^#])(?![a-z]{1,8};)/i', '&$1', $label ) + ); } } @@ -2531,11 +2605,13 @@ global $paged; if ( ! is_single() ) { - $nextpage = (int) $paged - 1; - if ( $nextpage < 1 ) { - $nextpage = 1; + $previous_page = (int) $paged - 1; + + if ( $previous_page < 1 ) { + $previous_page = 1; } - return get_pagenum_link( $nextpage ); + + return get_pagenum_link( $previous_page ); } } @@ -2544,13 +2620,13 @@ * * @since 0.71 * - * @param bool $echo Optional. Whether to echo the link. Default true. - * @return string|void The previous posts page link if `$echo = false`. + * @param bool $display Optional. Whether to echo the link. Default true. + * @return string|void The previous posts page link if `$display = false`. */ -function previous_posts( $echo = true ) { +function previous_posts( $display = true ) { $output = esc_url( get_previous_posts_page_link() ); - if ( $echo ) { + if ( $display ) { echo $output; } else { return $output; @@ -2583,7 +2659,13 @@ * @param string $attributes Attributes for the anchor tag. */ $attr = apply_filters( 'previous_posts_link_attributes', '' ); - return '" . preg_replace( '/&([^#])(?![a-z]{1,8};)/i', '&$1', $label ) . ''; + + return sprintf( + '%3$s', + previous_posts( false ), + $attr, + preg_replace( '/&([^#])(?![a-z]{1,8};)/i', '&$1', $label ) + ); } } @@ -2644,7 +2726,6 @@ } } return $return; - } /** @@ -2672,12 +2753,17 @@ * @param array $args { * Optional. Default post navigation arguments. Default empty array. * - * @type string $prev_text Anchor text to display in the previous post link. Default '%title'. - * @type string $next_text Anchor text to display in the next post link. Default '%title'. - * @type bool $in_same_term Whether link should be in a same taxonomy term. Default false. - * @type int[]|string $excluded_terms Array or comma-separated list of excluded term IDs. Default empty. + * @type string $prev_text Anchor text to display in the previous post link. + * Default '%title'. + * @type string $next_text Anchor text to display in the next post link. + * Default '%title'. + * @type bool $in_same_term Whether link should be in the same taxonomy term. + * Default false. + * @type int[]|string $excluded_terms Array or comma-separated list of excluded term IDs. + * Default empty. * @type string $taxonomy Taxonomy, if `$in_same_term` is true. Default 'category'. - * @type string $screen_reader_text Screen reader text for the nav element. Default 'Post navigation'. + * @type string $screen_reader_text Screen reader text for the nav element. + * Default 'Post navigation'. * @type string $aria_label ARIA label text for the nav element. Default 'Posts'. * @type string $class Custom class for the nav element. Default 'post-navigation'. * } @@ -2765,10 +2851,12 @@ * @return string Markup for posts links. */ function get_the_posts_navigation( $args = array() ) { + global $wp_query; + $navigation = ''; // Don't print empty markup if there's only one page. - if ( $GLOBALS['wp_query']->max_num_pages > 1 ) { + if ( $wp_query->max_num_pages > 1 ) { // Make sure the nav element has an aria-label attribute: fallback to the screen reader text. if ( ! empty( $args['screen_reader_text'] ) && empty( $args['aria_label'] ) ) { $args['aria_label'] = $args['screen_reader_text']; @@ -2821,6 +2909,8 @@ * @since 5.3.0 Added the `aria_label` parameter. * @since 5.5.0 Added the `class` parameter. * + * @global WP_Query $wp_query WordPress Query object. + * * @param array $args { * Optional. Default pagination arguments, see paginate_links(). * @@ -2832,10 +2922,12 @@ * @return string Markup for pagination links. */ function get_the_posts_pagination( $args = array() ) { + global $wp_query; + $navigation = ''; // Don't print empty markup if there's only one page. - if ( $GLOBALS['wp_query']->max_num_pages > 1 ) { + if ( $wp_query->max_num_pages > 1 ) { // Make sure the nav element has an aria-label attribute: fallback to the screen reader text. if ( ! empty( $args['screen_reader_text'] ) && empty( $args['aria_label'] ) ) { $args['aria_label'] = $args['screen_reader_text']; @@ -2853,6 +2945,22 @@ ) ); + /** + * Filters the arguments for posts pagination links. + * + * @since 6.1.0 + * + * @param array $args { + * Optional. Default pagination arguments, see paginate_links(). + * + * @type string $screen_reader_text Screen reader text for navigation element. + * Default 'Posts navigation'. + * @type string $aria_label ARIA label text for the nav element. Default 'Posts'. + * @type string $class Custom class for the nav element. Default 'pagination'. + * } + */ + $args = apply_filters( 'the_posts_pagination_args', $args ); + // Make sure we get a string back. Plain is the next best thing. if ( isset( $args['type'] ) && 'array' === $args['type'] ) { $args['type'] = 'plain'; @@ -2889,7 +2997,7 @@ * @access private * * @param string $links Navigational links. - * @param string $class Optional. Custom class for the nav element. + * @param string $css_class Optional. Custom class for the nav element. * Default 'posts-navigation'. * @param string $screen_reader_text Optional. Screen reader text for the nav element. * Default 'Posts navigation'. @@ -2897,9 +3005,9 @@ * Defaults to the value of `$screen_reader_text`. * @return string Navigation template tag. */ -function _navigation_markup( $links, $class = 'posts-navigation', $screen_reader_text = '', $aria_label = '' ) { +function _navigation_markup( $links, $css_class = 'posts-navigation', $screen_reader_text = '', $aria_label = '' ) { if ( empty( $screen_reader_text ) ) { - $screen_reader_text = __( 'Posts navigation' ); + $screen_reader_text = /* translators: Hidden accessibility text. */ __( 'Posts navigation' ); } if ( empty( $aria_label ) ) { $aria_label = $screen_reader_text; @@ -2925,13 +3033,13 @@ * * @since 4.4.0 * - * @param string $template The default template. - * @param string $class The class passed by the calling function. + * @param string $template The default template. + * @param string $css_class The class passed by the calling function. * @return string Navigation template. */ - $template = apply_filters( 'navigation_markup_template', $template, $class ); - - return sprintf( $template, sanitize_html_class( $class ), esc_html( $screen_reader_text ), $links, esc_html( $aria_label ) ); + $template = apply_filters( 'navigation_markup_template', $template, $css_class ); + + return sprintf( $template, sanitize_html_class( $css_class ), esc_html( $screen_reader_text ), $links, esc_attr( $aria_label ) ); } /** @@ -2948,12 +3056,13 @@ function get_comments_pagenum_link( $pagenum = 1, $max_page = 0 ) { global $wp_rewrite; - $pagenum = (int) $pagenum; + $pagenum = (int) $pagenum; + $max_page = (int) $max_page; $result = get_permalink(); if ( 'newest' === get_option( 'default_comments_page' ) ) { - if ( $pagenum != $max_page ) { + if ( $pagenum !== $max_page ) { if ( $wp_rewrite->using_permalinks() ) { $result = user_trailingslashit( trailingslashit( $result ) . $wp_rewrite->comments_pagination_base . '-' . $pagenum, 'commentpaged' ); } else { @@ -3004,7 +3113,7 @@ $page = 1; } - $nextpage = (int) $page + 1; + $next_page = (int) $page + 1; if ( empty( $max_page ) ) { $max_page = $wp_query->max_num_comment_pages; @@ -3014,7 +3123,7 @@ $max_page = get_comment_pages_count(); } - if ( $nextpage > $max_page ) { + if ( $next_page > $max_page ) { return; } @@ -3029,7 +3138,14 @@ * * @param string $attributes Attributes for the anchor tag. */ - return '' . preg_replace( '/&([^#])(?![a-z]{1,8};)/i', '&$1', $label ) . ''; + $attr = apply_filters( 'next_comments_link_attributes', '' ); + + return sprintf( + '%3$s', + esc_url( get_comments_pagenum_link( $next_page, $max_page ) ), + $attr, + preg_replace( '/&([^#])(?![a-z]{1,8};)/i', '&$1', $label ) + ); } /** @@ -3063,7 +3179,7 @@ return; } - $prevpage = (int) $page - 1; + $previous_page = (int) $page - 1; if ( empty( $label ) ) { $label = __( '« Older Comments' ); @@ -3076,7 +3192,14 @@ * * @param string $attributes Attributes for the anchor tag. */ - return '' . preg_replace( '/&([^#])(?![a-z]{1,8};)/i', '&$1', $label ) . ''; + $attr = apply_filters( 'previous_comments_link_attributes', '' ); + + return sprintf( + '%3$s', + esc_url( get_comments_pagenum_link( $previous_page ) ), + $attr, + preg_replace( '/&([^#])(?![a-z]{1,8};)/i', '&$1', $label ) + ); } /** @@ -3410,7 +3533,7 @@ * * @since 2.6.0 * - * @param string $path Optional. Path relative to the admin URL. Default 'admin'. + * @param string $path Optional. Path relative to the admin URL. Default empty. * @param string $scheme The scheme to use. Default is 'admin', which obeys force_ssl_admin() and is_ssl(). * 'http' or 'https' can be passed to force those schemes. * @return string Admin URL link with optional path appended. @@ -3532,7 +3655,7 @@ $plugin = wp_normalize_path( $plugin ); $mu_plugin_dir = wp_normalize_path( WPMU_PLUGIN_DIR ); - if ( ! empty( $plugin ) && 0 === strpos( $plugin, $mu_plugin_dir ) ) { + if ( ! empty( $plugin ) && str_starts_with( $plugin, $mu_plugin_dir ) ) { $url = WPMU_PLUGIN_URL; } else { $url = WP_PLUGIN_URL; @@ -3784,7 +3907,7 @@ } $url = trim( $url ); - if ( substr( $url, 0, 2 ) === '//' ) { + if ( str_starts_with( $url, '//' ) ) { $url = 'http:' . $url; } @@ -3907,8 +4030,8 @@ * @since 4.6.0 * * @param int|WP_Post $post Optional. Post ID or object. Default is global `$post`. - * @return string|false The canonical URL, or false if the post does not exist or has not - * been published yet. + * @return string|false The canonical URL. False if the post does not exist + * or has not been published yet. */ function wp_get_canonical_url( $post = null ) { $post = get_post( $post ); @@ -3999,7 +4122,7 @@ /** * Filters whether to preempt generating a shortlink for the given post. * - * Returning a truthy value from the filter will effectively short-circuit + * Returning a value other than false from the filter will short-circuit * the shortlink generation process, returning that value instead. * * @since 3.0.0 @@ -4032,7 +4155,9 @@ if ( ! empty( $post_id ) ) { $post_type = get_post_type_object( $post->post_type ); - if ( 'page' === $post->post_type && get_option( 'page_on_front' ) == $post->ID && 'page' === get_option( 'show_on_front' ) ) { + if ( 'page' === $post->post_type + && 'page' === get_option( 'show_on_front' ) && (int) get_option( 'page_on_front' ) === $post->ID + ) { $shortlink = home_url( '/' ); } elseif ( $post_type && $post_type->public ) { $shortlink = home_url( '?p=' . $post_id ); @@ -4135,27 +4260,37 @@ } } - /** * Retrieves the avatar URL. * * @since 4.2.0 * - * @param mixed $id_or_email The Gravatar to retrieve a URL for. Accepts a user_id, gravatar md5 hash, + * @param mixed $id_or_email The avatar to retrieve a URL for. Accepts a user ID, Gravatar MD5 hash, * user email, WP_User object, WP_Post object, or WP_Comment object. * @param array $args { - * Optional. Arguments to return instead of the default arguments. + * Optional. Arguments to use instead of the default arguments. * * @type int $size Height and width of the avatar in pixels. Default 96. - * @type string $default URL for the default image or a default type. Accepts '404' (return - * a 404 instead of a default image), 'retro' (8bit), 'monsterid' (monster), - * 'wavatar' (cartoon face), 'indenticon' (the "quilt"), 'mystery', 'mm', - * or 'mysteryman' (The Oyster Man), 'blank' (transparent GIF), or - * 'gravatar_default' (the Gravatar logo). Default is the value of the - * 'avatar_default' option, with a fallback of 'mystery'. - * @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 $default URL for the default image or a default type. Accepts: + * - '404' (return a 404 instead of a default image) + * - 'retro' (a 8-bit arcade-style pixelated face) + * - 'robohash' (a robot) + * - 'monsterid' (a monster) + * - 'wavatar' (a cartoon face) + * - 'identicon' (the "quilt", a geometric pattern) + * - 'mystery', 'mm', or 'mysteryman' (The Oyster Man) + * - 'blank' (transparent GIF) + * - 'gravatar_default' (the Gravatar logo) + * Default is the value of the 'avatar_default' option, + * with a fallback of 'mystery'. + * @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' (suitable for all audiences) + * - 'PG' (possibly offensive, usually for audiences 13 and above) + * - 'R' (intended for adult audiences above 17) + * - 'X' (even more mature than above) + * 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 $processed_args When the function returns, the value will be the processed/sanitized $args @@ -4168,7 +4303,6 @@ return $args['url']; } - /** * Check if this comment type allows avatars to be retrieved. * @@ -4190,41 +4324,52 @@ return in_array( $comment_type, (array) $allowed_comment_types, true ); } - /** * Retrieves default data about the avatar. * * @since 4.2.0 * - * @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 array $args { - * Optional. Arguments to return instead of the default arguments. - * - * @type int $size Height and width of the avatar image file in pixels. Default 96. + * Optional. Arguments to use instead of the default arguments. + * + * @type int $size Height and width of the avatar in pixels. Default 96. * @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 string $default URL for the default image or a default type. Accepts '404' (return - * a 404 instead of a default image), 'retro' (8bit), 'monsterid' (monster), - * 'wavatar' (cartoon face), 'indenticon' (the "quilt"), 'mystery', 'mm', - * or 'mysteryman' (The Oyster Man), 'blank' (transparent GIF), or - * 'gravatar_default' (the Gravatar logo). Default is the value of the - * 'avatar_default' option, with a fallback of 'mystery'. - * @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 $default URL for the default image or a default type. Accepts: + * - '404' (return a 404 instead of a default image) + * - 'retro' (a 8-bit arcade-style pixelated face) + * - 'robohash' (a robot) + * - 'monsterid' (a monster) + * - 'wavatar' (a cartoon face) + * - 'identicon' (the "quilt", a geometric pattern) + * - 'mystery', 'mm', or 'mysteryman' (The Oyster Man) + * - 'blank' (transparent GIF) + * - 'gravatar_default' (the Gravatar logo) + * Default is the value of the 'avatar_default' option, + * with a fallback of 'mystery'. + * @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' (suitable for all audiences) + * - 'PG' (possibly offensive, usually for audiences 13 and above) + * - 'R' (intended for adult audiences above 17) + * - 'X' (even more mature than above) + * 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 $processed_args When the function returns, the value will be the processed/sanitized $args * plus a "found_avatar" guess. Pass as a reference. Default null. - * @type string $extra_attr HTML attributes to insert in the IMG element. Is not sanitized. Default empty. + * @type string $extra_attr HTML attributes to insert in the IMG element. Is not sanitized. + * Default empty. * } * @return array { * Along with the arguments passed in `$args`, this will contain a couple of extra arguments. * - * @type bool $found_avatar True if we were able to find an avatar for this user, - * false or not set if we couldn't. - * @type string $url The URL of the avatar we found. + * @type bool $found_avatar True if an avatar was found for this user, + * false or not set if none was found. + * @type string|false $url The URL of the avatar that was found, or false. * } */ function get_avatar_data( $id_or_email, $args = null ) { @@ -4301,7 +4446,7 @@ * @since 4.2.0 * * @param array $args Arguments passed to get_avatar_data(), after processing. - * @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. */ $args = apply_filters( 'pre_get_avatar_data', $args, $id_or_email ); @@ -4323,7 +4468,7 @@ if ( is_numeric( $id_or_email ) ) { $user = get_user_by( 'id', absint( $id_or_email ) ); } elseif ( is_string( $id_or_email ) ) { - if ( strpos( $id_or_email, '@md5.gravatar.com' ) ) { + if ( str_contains( $id_or_email, '@md5.gravatar.com' ) ) { // MD5 hash. list( $email_hash ) = explode( '@', $id_or_email ); } else { @@ -4392,7 +4537,7 @@ * @since 4.2.0 * * @param string $url The URL of the 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 array $args Arguments passed to get_avatar_data(), after processing. */ @@ -4404,7 +4549,7 @@ * @since 4.2.0 * * @param array $args Arguments passed to get_avatar_data(), after processing. - * @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. */ return apply_filters( 'get_avatar_data', $args, $id_or_email ); @@ -4424,9 +4569,11 @@ function get_theme_file_uri( $file = '' ) { $file = ltrim( $file, '/' ); + $stylesheet_directory = get_stylesheet_directory(); + if ( empty( $file ) ) { $url = get_stylesheet_directory_uri(); - } elseif ( file_exists( get_stylesheet_directory() . '/' . $file ) ) { + } elseif ( get_template_directory() !== $stylesheet_directory && file_exists( $stylesheet_directory . '/' . $file ) ) { $url = get_stylesheet_directory_uri() . '/' . $file; } else { $url = get_template_directory_uri() . '/' . $file; @@ -4485,12 +4632,15 @@ function get_theme_file_path( $file = '' ) { $file = ltrim( $file, '/' ); + $stylesheet_directory = get_stylesheet_directory(); + $template_directory = get_template_directory(); + if ( empty( $file ) ) { - $path = get_stylesheet_directory(); - } elseif ( file_exists( get_stylesheet_directory() . '/' . $file ) ) { - $path = get_stylesheet_directory() . '/' . $file; + $path = $stylesheet_directory; + } elseif ( $stylesheet_directory !== $template_directory && file_exists( $stylesheet_directory . '/' . $file ) ) { + $path = $stylesheet_directory . '/' . $file; } else { - $path = get_template_directory() . '/' . $file; + $path = $template_directory . '/' . $file; } /** @@ -4575,6 +4725,7 @@ * Returns the privacy policy link with formatting, when applicable. * * @since 4.9.6 + * @since 6.2.0 Added 'privacy-policy' rel attribute. * * @param string $before Optional. Display before privacy policy link. Default empty. * @param string $after Optional. Display after privacy policy link. Default empty. @@ -4589,7 +4740,7 @@ if ( $privacy_policy_url && $page_title ) { $link = sprintf( - '%s', + '%s', esc_url( $privacy_policy_url ), esc_html( $page_title ) ); @@ -4613,3 +4764,63 @@ return ''; } + +/** + * Returns an array of URL hosts which are considered to be internal hosts. + * + * By default the list of internal hosts is comprised of the host name of + * the site's home_url() (as parsed by wp_parse_url()). + * + * This list is used when determining if a specified URL is a link to a page on + * the site itself or a link offsite (to an external host). This is used, for + * example, when determining if the "nofollow" attribute should be applied to a + * link. + * + * @see wp_is_internal_link + * + * @since 6.2.0 + * + * @return string[] An array of URL hosts. + */ +function wp_internal_hosts() { + static $internal_hosts; + + if ( empty( $internal_hosts ) ) { + /** + * Filters the array of URL hosts which are considered internal. + * + * @since 6.2.0 + * + * @param string[] $internal_hosts An array of internal URL hostnames. + */ + $internal_hosts = apply_filters( + 'wp_internal_hosts', + array( + wp_parse_url( home_url(), PHP_URL_HOST ), + ) + ); + $internal_hosts = array_unique( + array_map( 'strtolower', (array) $internal_hosts ) + ); + } + + return $internal_hosts; +} + +/** + * Determines whether or not the specified URL is of a host included in the internal hosts list. + * + * @see wp_internal_hosts() + * + * @since 6.2.0 + * + * @param string $link The URL to test. + * @return bool Returns true for internal URLs and false for all other URLs. + */ +function wp_is_internal_link( $link ) { + $link = strtolower( $link ); + if ( in_array( wp_parse_url( $link, PHP_URL_SCHEME ), wp_allowed_protocols(), true ) ) { + return in_array( wp_parse_url( $link, PHP_URL_HOST ), wp_internal_hosts(), true ); + } + return false; +}