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