| | 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 | */ |
| | 29 | function 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 | /** |