WordPress.org

Make WordPress Core

Ticket #32071: 32071.01.patch

File 32071.01.patch, 2.7 KB (added by johnjamesjacoby, 7 years ago)

Introduce wp_generate_url()

  • src/wp-includes/link-template.php

     
    77 */
    88
    99/**
     10 * Generate a URL by provding a set of query parameters to add or remove. Also
     11 * accepts a few other optional arguments for escaping and echoing the results
     12 *
     13 * @see build_query()
     14 * @see _html_build_query()
     15 *
     16 * @since 4.3.0
     17 *
     18 * @param array $args {
     19 *     Optional. Default URL arguments. Default empty array.
     20 *
     21 *     @type array   $add_query_args    'key' => 'value' array of arguments to add
     22 *     @type array   $remove_query_args 'key' => 'value' array of arguments to remove
     23 *     @type string  $url                Original URL to generate new URL from
     24 *     @type boolean $escape             True|False. Will run `esc_url()` on generated URL
     25 *     @type boolean $echo               True|False. Will echo *escaped* generated URL before returning
     26 * }
     27 * @return string The generated URL based on arguments passed into $args param
     28 */
     29function wp_generate_url( $args = array() ) {
     30
     31        // Grab the `home_url()` to use as the default URL if none is passed
     32        $home_url = home_url();
     33
     34        // Parse passed arguments with default arguments
     35        $r = wp_parse_args( $args, array(
     36                'add_query_args'    => array(),
     37                'remove_query_args' => array(),
     38                'url'               => $home_url,
     39                'escape'            => true,
     40                'echo'              => false
     41        ) );
     42
     43        // URL has not been escaped yet
     44        $escaped = false;
     45
     46        // Ensure there is always a URL, even if it's not exactly what was intended
     47        // by the developer using this function. This is intended to guarantee a
     48        // somewhat sane and anticipated URL is returned.
     49        $generated_url = ! empty( $r['url'] )
     50                ? $r['url']
     51                : $home_url;
     52
     53        // Add any query arguments
     54        if ( ! empty( $r['add_query_args'] ) ) {
     55                $generated_url = add_query_arg( $r['add_query_args'], $generated_url );
     56        }
     57
     58        // Remove any query arguments
     59        if ( ! empty( $r['remove_query_args'] ) ) {
     60                $generated_url = remove_query_arg( $r['remove_query_args'], $generated_url );
     61        }
     62
     63        // Filter the generated result, and pass along all of our known variables
     64        $retval = apply_filters( 'wp_generate_url', $generated_url, $r, $args );
     65
     66        // Maybe prepare the results for output to the browser
     67        if ( true === $r['escape'] ) {
     68                $retval  = esc_url( $retval );
     69                $escaped = true;
     70        }
     71
     72        // Maybe echo the result to the browser
     73        if ( true === $r['echo'] ) {
     74
     75                // Always escape URLs before echo'ing
     76                if ( false === $escaped ) {
     77                        $retval  = esc_url( $retval );
     78                        $escaped = true;
     79                }
     80
     81                // Echo *escaped* URL to the browser
     82                echo $retval;
     83        }
     84
     85        // Return the generated result
     86        return $retval;
     87}
     88
     89/**
    1090 * Display the permalink for the current post.
    1191 *
    1292 * @since 1.2.0