diff --git a/wp-includes/general-template.php b/wp-includes/general-template.php index aa9f5d7eef..ae207d2715 100644 --- a/wp-includes/general-template.php +++ b/wp-includes/general-template.php @@ -175,11 +175,19 @@ function get_template_part( $slug, $name = null ) { * search. To give a few examples of what it can be used for. * * @since 2.7.0 + * @since 5.2.0 The $args array parameter was added in place of an $echo boolean flag. * - * @param bool $echo Default to echo and not return the form. - * @return string|void String when $echo is false. + * @param array $args { + * Optional. Array of display arguments. + * + * @type bool $echo Whether to echo or return the form. Default true. + * @type string $aria_label ARIA label for the search form. Useful to distinguish + * multiple search forms on the same page and improve + * accessibility. Default empty. + * } + * @return string|void String when the $echo param is false. */ -function get_search_form( $echo = true ) { +function get_search_form( $args = array() ) { /** * Fires before the search form is retrieved, at the start of get_search_form(). * @@ -192,6 +200,38 @@ function get_search_form( $echo = true ) { $format = current_theme_supports( 'html5', 'search-form' ) ? 'html5' : 'xhtml'; + /* + * Back compat: to ensure previous uses of get_search_form continue to + * function as expected, we handle a value for the boolean $echo param removed + * in 5.2.0. Then we deal with the $args array and cast its defaults. + */ + $echo = true; + if ( false === $args ) { + $echo = false; + } + + if ( ! is_array( $args ) ) { + // Set an empty array and allow default arguments to take over. + $args = array(); + } + + // Defaults are to echo and to output no custom label on the form. + $defaults = array( + 'echo' => $echo, + 'aria_label' => '', + ); + + $args = wp_parse_args( $args, $defaults ); + + /** + * Filters the array of arguments used when generating the search form. + * + * @since 5.2.0 + * + * @param array $args The array of arguments for building the search form. + */ + $args = apply_filters( 'search_form_args', $args ); + /** * Filters the HTML format of the search form. * @@ -208,8 +248,18 @@ function get_search_form( $echo = true ) { require( $search_form_template ); $form = ob_get_clean(); } else { + // Build a string containing an aria-label to use for the search form. + if ( isset( $args['aria_label'] ) && $args['aria_label'] ) { + $aria_label = 'aria-label="' . esc_attr( $args['aria_label'] ) . '" '; + } else { + /* + * If there's no custom aria-label, we can set a default here. At the + * moment it's empty as there's uncertainty about what the default should be. + */ + $aria_label = ''; + } if ( 'html5' == $format ) { - $form = '
'; } else { - $form = '