Home / / How to Map Custom Search Form Fields to Query Parameters

How to Map Custom Search Form Fields to Query Parameters

58 views

Filter: wpestate_query_2026_search_params

This filter fires after the Query 2026 engine has finished parsing a search form submission
into a canonical parameter array. When a visitor uses the advanced search form on your site, the
browser sends raw $_GET parameters (like ?property_city=new-york&price_low=100000).
The engine parses these raw values into a clean, structured $params array that the main
query function understands. This filter lets you modify that array before it is passed to the query.

This is the dedicated filter for custom search form fields. If you have added custom
inputs to your search form (for example, a “year built” slider, a “building type” dropdown, or a
“has parking” checkbox), the engine will not recognize those fields by default. This filter is where
you read those custom values from the raw request and convert them into the appropriate query
parameters (taxonomy filters, meta query clauses, etc.).

When Does This Filter Fire?

This filter fires inside the function wpestate_query_2026_prepare_search_arguments(),
after the main parsing loop has processed all recognized fields (taxonomies, prices, keywords,
geolocation, generic meta fields) and the meta_query clauses have been attached to
the params array.

Important: This filter only fires when
wpestate_query_2026_prepare_search_arguments() is called, which happens during
search form submissions and AJAX search requests. It does not fire
when wpestate_query_2026_property() is called directly with manually assembled params
(for example, from a page template or shortcode). For those cases, use the
wpestate_query_2026_params filter instead.

Source file: libs/query/query2026/wpestate_query_2026_prepare_search_arguments.php

Filter Signature

$params = apply_filters( 'wpestate_query_2026_search_params', $params, $request, $options );

Parameters

Parameter Type Description
$params array The parsed canonical parameter array. This is the value you must return from your
callback function. It will be passed to
wpestate_query_2026_property() as the $params argument.
$request array The raw request data, typically $_GET. This contains all
URL parameters from the search form, including custom fields that the engine did not
recognize. Use this to read your custom form field values. Always sanitize
values before using them.
$options array Caller options. May contain ‘adv_search_what’ and
‘adv_search_how’ override arrays when the search form is rendered by
an Elementor widget (which can have its own field configuration).

What the $params Array Contains at This Point

After the engine has parsed the search form data, the $params array contains the
recognized and validated values, organized into these groups:

Category Keys Format
Taxonomies property_category, property_city, property_area, property_county_state, property_action_category, property_status Arrays of sanitized slug or name strings
Features property_features Array of feature term slugs
Text search keyword, location Sanitized strings
Geolocation geo_lat, geo_long, geo_rad Float values
Pagination/sort order, paged Integer values
Meta clauses meta_query Array of WP_Query meta_query clause arrays (built from price, beds/baths, and generic meta fields)

The $request array (the second parameter) is the original raw $_GET data.
It contains everything the browser sent, including custom fields that the engine
skipped. This is where you read your custom form field values.

Child Theme Examples

Example 1: Add a “Year Built” Range Slider to the Search Form

If you have added two custom fields to your search form — year_built_min and
year_built_max — that let visitors filter properties by construction year, you
need to read those values from the raw request and convert them into meta_query clauses: 

<?php
/**
 * Convert the year_built_min and year_built_max search form fields into
 * meta_query clauses that filter by the 'year_built' custom field.
 *
 * This assumes your search form contains inputs like:
 *   <input type="number" name="year_built_min" placeholder="From year">
 *   <input type="number" name="year_built_max" placeholder="To year">
 *
 * And your properties have a custom field with meta key 'year_built'
 * storing a numeric year value (e.g. 2015, 2020).
 *
 * Add this code to your child theme's functions.php file.
 */
add_filter( 'wpestate_query_2026_search_params', 'my_child_year_built_search', 10, 3 );
function my_child_year_built_search( $params, $request, $options ) {
    // Read the raw values from the search form submission.
    $min = isset( $request['year_built_min'] ) ? intval( $request['year_built_min'] ) : 0;
    $max = isset( $request['year_built_max'] ) ? intval( $request['year_built_max'] ) : 0;

    // If neither value was provided, there is nothing to filter.
    if ( $min <= 0 && $max <= 0 ) {
        return $params;
    }

    // Make sure the meta_query array exists in the params.
    if ( ! isset( $params['meta_query'] ) || ! is_array( $params['meta_query'] ) ) {
        $params['meta_query'] = array();
    }

    // Build the appropriate meta clause based on which values were provided.
    if ( $min > 0 && $max > 0 ) {
        // Both min and max provided: use BETWEEN.
        $params['meta_query'][] = array(
            'key'     => 'year_built',
            'value'   => array( $min, $max ),
            'type'    => 'NUMERIC',
            'compare' => 'BETWEEN',
        );
    } elseif ( $min > 0 ) {
        // Only minimum provided: year must be >= min.
        $params['meta_query'][] = array(
            'key'     => 'year_built',
            'value'   => $min,
            'type'    => 'NUMERIC',
            'compare' => '>=',
        );
    } else {
        // Only maximum provided: year must be <= max.
        $params['meta_query'][] = array(
            'key'     => 'year_built',
            'value'   => $max,
            'type'    => 'NUMERIC',
            'compare' => '<=',
        );
    }

    return $params;
}

Example 2: Add a Custom “Building Type” Dropdown to the Search Form

If you have registered a custom taxonomy called property_building_type and added a
dropdown to your search form with the name building_type, the engine will not recognize
this field automatically. You need to read the selected value and add a taxonomy filter: 

<?php
/**
 * Convert the 'building_type' search form dropdown into a taxonomy query.
 *
 * This assumes your search form contains a select like:
 *   <select name="building_type">
 *       <option value="all">All Types</option>
 *       <option value="condo">Condo</option>
 *       <option value="townhouse">Townhouse</option>
 *       <option value="single-family">Single Family</option>
 *   </select>
 *
 * And you have registered a taxonomy 'property_building_type' in your child theme.
 *
 * Add this code to your child theme's functions.php file.
 */
add_filter( 'wpestate_query_2026_search_params', 'my_child_building_type_search', 10, 3 );
function my_child_building_type_search( $params, $request, $options ) {
    // Check if the building_type field was submitted.
    if ( empty( $request['building_type'] ) ) {
        return $params;
    }

    // Sanitize the raw value from the form.
    $value = sanitize_text_field( wp_unslash( $request['building_type'] ) );

    // Skip "all" or empty values (the default/placeholder option).
    if ( '' === $value || 'all' === strtolower( $value ) ) {
        return $params;
    }

    // Make sure the tax_query array exists in the params.
    if ( ! isset( $params['tax_query'] ) || ! is_array( $params['tax_query'] ) ) {
        $params['tax_query'] = array();
    }

    // Add a taxonomy clause for the custom building type.
    $params['tax_query'][] = array(
        'taxonomy' => 'property_building_type',
        'field'    => 'slug',
        'terms'    => array( $value ),
    );

    return $params;
}

Example 3: Override the Geolocation Radius From a Custom Dropdown

If you have added a custom radius dropdown to your search form (in addition to or instead of the
built-in radius control), you can read the selected value and set it as the geolocation radius: 

<?php
/**
 * Read a custom 'custom_radius' dropdown from the search form and use it
 * as the geolocation search radius.
 *
 * This assumes your search form contains a select like:
 *   <select name="custom_radius">
 *       <option value="5">5 km</option>
 *       <option value="10">10 km</option>
 *       <option value="25">25 km</option>
 *       <option value="50">50 km</option>
 *   </select>
 *
 * Add this code to your child theme's functions.php file.
 */
add_filter( 'wpestate_query_2026_search_params', 'my_child_custom_radius', 10, 3 );
function my_child_custom_radius( $params, $request, $options ) {
    if ( empty( $request['custom_radius'] ) ) {
        return $params;
    }

    $radius = floatval( $request['custom_radius'] );
    if ( $radius > 0 ) {
        $params['geo_rad'] = $radius;
    }

    return $params;
}

Example 4: Make Keyword Search Include Post Content

By default, the Query 2026 engine’s keyword search only matches property titles. If you want the
search to also look inside the property description (post content), you can set the WordPress
native 's' parameter alongside the keyword: 

<?php
/**
 * When a keyword is provided via the search form, also set the WordPress
 * native 's' parameter so WordPress searches post_content in addition
 * to the title-only filter provided by the theme.
 *
 * This gives visitors broader search results that match keywords in the
 * property description, not just the title.
 *
 * Add this code to your child theme's functions.php file.
 */
add_filter( 'wpestate_query_2026_search_params', 'my_child_keyword_full_search', 10, 3 );
function my_child_keyword_full_search( $params, $request, $options ) {
    if ( ! empty( $params['keyword'] ) ) {
        $params['s'] = $params['keyword'];
    }
    return $params;
}

Important Notes

  • This filter only fires during search form submissions. It is called by
    wpestate_query_2026_prepare_search_arguments(), which parses raw
    $_GET data from search forms. It does not fire when
    wpestate_query_2026_property() is called directly with manually assembled params.
    If you need to modify params in all cases (not just search forms), use the
    wpestate_query_2026_params filter instead.
  • After this filter, the output goes into the main query pipeline. The
    $params array returned by this filter is passed to
    wpestate_query_2026_property(), where filters #1 through #6 will also fire.
    This means your search params modifications will also be subject to the params filter (#2),
    tax_query filter (#3), meta_query filter (#4), etc.
  • Always sanitize values from $request. The $request
    array contains raw user input from the URL. Always use WordPress sanitization functions like
    sanitize_text_field(), intval(), floatval(), or
    wp_unslash() before using any value in a query parameter or meta clause.
  • The $options array may contain Elementor overrides. When the search
    form is rendered by an Elementor widget, the widget may pass its own field configuration through
    $options['adv_search_what'] and $options['adv_search_how']. This is
    provided for reference in case your custom field handling needs to be aware of the form
    configuration.
  • Always return the $params array. Even if you do not modify it,
    you must return the array from your callback function. Failing to return it will prevent the
    search from working.