Filter: wpestate_query_2026_args

This filter gives you access to the complete, final WP_Query arguments array right
before the database query is executed. At this point, the entire pipeline has finished its work:
pagination is set, sort order is resolved, taxonomy clauses are built, meta clauses are assembled,
geolocation filters are applied, and identity filters (post IDs, authors) are in place.

This is the last chance to modify anything before the query runs. It is the most
powerful filter because you can change any WP_Query argument, including ones that the Query 2026
pipeline does not natively support (such as date_query, comment_count,
or post_parent).

This filter follows the same pattern used elsewhere in the WP Residence theme, such as
apply_filters( 'wpresidence_agents_query_args', $args ) for agent queries. If you are
already familiar with that pattern, this filter works exactly the same way.

---

When Does This Filter Fire?

This filter fires inside the main orchestrator function wpestate_query_2026_property(),
after Step 14 (identity and targeting filters) and before Step 15 (query execution via
new WP_Query( $args )). The built-in error_log debug output fires
immediately after this filter, which means it will capture any changes your callback makes —
useful for verifying your filter is working correctly.

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

---

Filter Signature

$args = apply_filters( 'wpestate_query_2026_args', $args, $params, $context, $options );

Parameters

Parameter	Type	Description
$args	array	The complete WP_Query arguments array. This is the value you must return from your callback function. This array will be passed directly to new WP_Query( $args ).
$params	array	The normalized parameter array that was used to build the args. Provided as a read-only reference so you can check what the caller requested.
$context	string	The query context: ‘directory’, ‘map’, ‘dashboard’, or ‘featured’.
$options	array	The caller’s options array (read-only). Contains flags like respect_custom_order_zero.

---

What the $args Array Looks Like

At this point, $args is a fully assembled WP_Query arguments array. It always includes
'post_type' => 'estate_property' and typically looks like this:

array(
    'post_type'      => 'estate_property',
    'post_status'    => 'publish',
    'posts_per_page' => 12,
    'paged'          => 1,
    'orderby'        => 'date',
    'order'          => 'DESC',
    'no_found_rows'  => false,
    'tax_query'      => array(
        array(
            'taxonomy' => 'property_city',
            'field'    => 'term_id',
            'terms'    => array( 42 ),
        ),
    ),
    'meta_query'     => array(
        'relation' => 'AND',
        array(
            'key'     => 'property_price',
            'value'   => array( 100000, 500000 ),
            'type'    => 'NUMERIC',
            'compare' => 'BETWEEN',
        ),
    ),
)

The exact keys present depend on what filters the user applied. If no taxonomy or meta filters were
used, the tax_query and meta_query keys may not exist in the array.

---

Child Theme Examples

Example 1: Only Show Properties Published in the Last 30 Days

The WP_Query date_query argument is not natively supported by the Query 2026 pipeline
parameters, but you can add it through this filter. This example limits directory listing pages to
properties published within the last 30 days:

<?php
/**
 * Only show properties published in the last 30 days on directory listing pages.
 *
 * This uses the WP_Query date_query argument, which is not available through
 * the Query 2026 params but can be added directly to the args array here.
 *
 * Add this code to your child theme's functions.php file.
 */
add_filter( 'wpestate_query_2026_args', 'my_child_recent_properties_only', 10, 4 );
function my_child_recent_properties_only( $args, $params, $context, $options ) {
    // Only apply on directory listing pages.
    if ( 'directory' !== $context ) {
        return $args;
    }

    $args['date_query'] = array(
        array(
            'after'     => '30 days ago',
            'inclusive' => true,
        ),
    );

    return $args;
}

Example 2: Show Draft Properties on the Dashboard

By default, all queries use post_status => 'publish'. On the dashboard, agents may
need to see their draft (unpublished) properties as well. This example changes the dashboard to
show both published and draft properties:

<?php
/**
 * Show both published and draft properties on the dashboard.
 *
 * This allows agents to see their unpublished listings alongside published ones
 * in their dashboard property list.
 *
 * Add this code to your child theme's functions.php file.
 */
add_filter( 'wpestate_query_2026_args', 'my_child_dashboard_show_drafts', 10, 4 );
function my_child_dashboard_show_drafts( $args, $params, $context, $options ) {
    if ( 'dashboard' !== $context ) {
        return $args;
    }

    $args['post_status'] = array( 'publish', 'draft' );

    return $args;
}

Example 3: Inject Property IDs From an External Recommendation API

If you have an external service that recommends property IDs (for example, a machine learning API
or a CRM system), you can inject those IDs into the query. This example replaces the featured widget
query with a set of recommended IDs:

<?php
/**
 * Replace the featured widget query with property IDs from an external recommendation API.
 *
 * The API returns a JSON array of property post IDs. The properties are then
 * displayed in the order returned by the API.
 *
 * Important: Be mindful of performance. This HTTP request runs on every featured
 * widget query. Consider caching the API response using WordPress transients.
 *
 * Add this code to your child theme's functions.php file.
 */
add_filter( 'wpestate_query_2026_args', 'my_child_external_recommendations', 10, 4 );
function my_child_external_recommendations( $args, $params, $context, $options ) {
    // Only apply to featured widget queries.
    if ( 'featured' !== $context ) {
        return $args;
    }

    // Check for a cached response first (cached for 1 hour).
    $cached_ids = get_transient( 'my_recommended_property_ids' );
    if ( false !== $cached_ids ) {
        $ids = $cached_ids;
    } else {
        // Fetch recommended property IDs from the external API.
        $response = wp_remote_get( 'https://api.example.com/recommendations' );
        if ( is_wp_error( $response ) ) {
            return $args;
        }
        $ids = json_decode( wp_remote_retrieve_body( $response ), true );
        if ( empty( $ids ) || ! is_array( $ids ) ) {
            return $args;
        }
        // Cache the result for 1 hour.
        set_transient( 'my_recommended_property_ids', $ids, HOUR_IN_SECONDS );
    }

    // Set post__in to only query these specific IDs.
    $args['post__in'] = array_map( 'intval', $ids );

    // Preserve the API's ordering.
    $args['orderby'] = 'post__in';

    return $args;
}

Example 4: Log All Query Arguments for Debugging

During development, you may want to log the complete WP_Query arguments to your PHP error log so
you can see exactly what the query engine is doing. This is a common debugging technique:

<?php
/**
 * Log all Query 2026 arguments to the PHP error log for debugging.
 *
 * This uses priority 99 to ensure it runs after all other filters,
 * so you see the final args including modifications from other callbacks.
 *
 * Only active when WP_DEBUG is enabled. Remove this filter in production.
 *
 * Add this code to your child theme's functions.php file.
 */
add_filter( 'wpestate_query_2026_args', 'my_child_debug_log_args', 99, 4 );
function my_child_debug_log_args( $args, $params, $context, $options ) {
    if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
        error_log( '[query2026-debug] context=' . $context . ' args=' . print_r( $args, true ) );
    }
    return $args;
}

Example 5: Restrict Queries to Specific Author IDs

If your site has multiple agents and you want to restrict property listings to only show properties
from a specific set of approved authors:

<?php
/**
 * Only show properties from approved author IDs (5, 12, 18, 25).
 *
 * This is useful for multi-agent sites where only certain agents'
 * listings should appear on the public-facing pages.
 *
 * Add this code to your child theme's functions.php file.
 */
add_filter( 'wpestate_query_2026_args', 'my_child_approved_authors_only', 10, 4 );
function my_child_approved_authors_only( $args, $params, $context, $options ) {
    // Only apply to public-facing contexts (not dashboard).
    if ( 'dashboard' === $context ) {
        return $args;
    }

    $args['author__in'] = array( 5, 12, 18, 25 );

    return $args;
}

---

Important Notes

• This is the most powerful filter. You can modify any WP_Query argument here,
  including arguments the Query 2026 pipeline does not natively support (such as
  date_query, comment_count, post_parent,
  post_name__in, etc.). Refer to the
  WordPress WP_Query documentation
  for the full list of available arguments.
• Avoid overwriting tax_query or meta_query entirely.
  If you need to add taxonomy or meta clauses, append to the existing array instead of replacing
  it. Better yet, use the dedicated wpestate_query_2026_tax_query or
  wpestate_query_2026_meta_query filters, which are specifically designed for that
  purpose.
• The debug error_log runs after this filter. The built-in debug
  logging in the pipeline fires immediately after this filter, which means any changes your
  callback makes will be visible in the PHP error log. This is helpful for verifying your filter
  is working correctly.
• Be careful with performance. This filter fires on every property query,
  including AJAX requests for map pins, property list pagination, and search results. Avoid running
  expensive operations (HTTP API calls, heavy database queries) inside your callback unless you
  have proper caching in place and are targeting a specific context.
• Do not change post_type. The Query 2026 engine is designed
  exclusively for estate_property queries. Changing the post_type
  argument will cause unpredictable behavior in the template rendering code.