Add search_position parameter to WP_Query for more refined search control

This commit introduces the `search_position` parameter to the `WP_Query` class, allowing developers to specify search behavior for posts: finding terms at the start, end, or anywhere within fields. Corresponding functionality in `canonical.php` has also been updated, and comprehensive unit tests were added to ensure reliability of the new behavior.

Author: spacedmonkey

src/wp-includes/canonical.php

@@ -983,9 +983,9 @@ function redirect_guess_404_permalink() {
 		if ( $strict_guess ) {
 			$query_args['name'] = get_query_var( 'name' );
 		} else {
-			$query_args['s']              = get_query_var( 'name' );
-			$query_args['search_columns'] = array( 'post_name' );
-			$query_args['starts_with']    = true;
+			$query_args['s']               = get_query_var( 'name' );
+			$query_args['search_columns']  = array( 'post_name' );
+			$query_args['search_position'] = 'start';
 		}
 
 		// If any of post_type, year, monthnum, or day are set, use them to refine the query.

src/wp-includes/class-wp-query.php

@@ -687,8 +687,8 @@ public function fill_query_vars( $query_vars ) {
 	 *                                                   See WP_Date_Query::__construct().
 	 *     @type int             $day                    Day of the month. Default empty. Accepts numbers 1-31.
 	 *     @type bool            $exact                  Whether to search by exact keyword. Default false.
-	 *                                                   Cannot be used together with `$starts_with`.
-	 *     @type bool            $starts_with            Whether to search starts with keyword. Default false.
+	 *                                                   Cannot be used together with `$search_position`.
+	 *     @type bool            $search_position        Whether to search start, ends or is anywhere within keyword. Default anywhere.
 	 *                                                   Cannot be used together with `$exact`.
 	 *     @type string          $fields                 Post fields to query for. Accepts:
 	 *                                                   - '' Returns an array of complete post objects (`WP_Post[]`).
@@ -817,13 +817,13 @@ public function parse_query( $query = '' ) {
 		$query_vars               = &$this->query_vars;
 		$this->query_vars_changed = true;
 
-		if ( ! empty( $query_vars['exact'] ) && ! empty( $query_vars['starts_with'] ) ) {
+		if ( ! empty( $query_vars['exact'] ) && ! empty( $query_vars['search_position'] ) ) {
 			_doing_it_wrong(
 				__METHOD__,
-				__( 'The `exact` and `starts_with` query parameters are mutually exclusive and cannot be used together.' ),
+				__( 'The `exact` and `search_position` query parameters are mutually exclusive and cannot be used together.' ),
 				'7.0.0'
 			);
-			$query_vars['starts_with'] = false;
+			$query_vars['search_position'] = 'anywhere';
 		}
 
 		if ( ! empty( $query_vars['robots'] ) ) {
@@ -1466,8 +1466,13 @@ protected function parse_search( &$query_vars ) {
 		if ( ! empty( $query_vars['exact'] ) ) {
 			$start = '';
 			$end   = '';
-		} elseif ( ! empty( $query_vars['starts_with'] ) ) {
-			$start = '';
+		} elseif ( ! empty( $query_vars['search_position'] ) ) {
+			if ( 'start' === $query_vars['search_position'] ) {
+				$start = '';
+			}
+			if ( 'end' === $query_vars['search_position'] ) {
+				$end = '';
+			}
 		}
 
 		$searchand                          = '';
@@ -1983,6 +1988,10 @@ public function get_posts() {
 			}
 		}
 
+		if ( ! isset( $query_vars['search_position'] ) || ! in_array( $query_vars['search_position'], array( 'start', 'end', 'anywhere' ), true ) ) {
+			$query_vars['search_position'] = 'anywhere';
+		}
+
 		if ( ! isset( $query_vars['ignore_sticky_posts'] ) ) {
 			$query_vars['ignore_sticky_posts'] = false;
 		}