Developer documentation for the matching engine in the WPResidence real estate CRM. The engine lives in libs/matching-functions.php and matches buyer preference fields stored on contacts against estate_property posts.
Core Function
wpestate_crm_match_properties( $contact_id, $args = [] )
$args supports per_page, paged, agent_only. Returns {post_ids: int[], count: int}.
Input Fields Used
Read from the contacts table: pref_property_type, pref_property_status, pref_locations, pref_min_price, pref_max_price, pref_min_beds, pref_max_beds, pref_min_baths, pref_max_baths, pref_min_area, pref_max_area.
Query Construction
A WP_Query is built against post_type=estate_property with:
- tax_query: relation AND. property_category + property_status filters. Location is a nested OR matching city or area taxonomy terms.
- meta_query: relation AND. BETWEEN filters on property_price, property_bedrooms, property_bathrooms, property_size.
- post_status=publish.
Missing preference fields are skipped (no filter added). A contact with no preferences returns an empty result rather than all listings.
AJAX Endpoints
| Action | Nonce | Purpose |
|---|---|---|
| wpestate_crm_match_properties | wpestate_crm_nonce (security param) | Run match; returns post data |
| wpestate_crm_email_matches | wpestate_crm_nonce | Email matched listings to contact |
| wpestate_crm_get_viewed_listings | wpestate_crm_nonce | Fetch viewed-listings history (related feature) |
Email Dispatcher
wpestate_crm_ajax_email_matches() builds an HTML email with one property card per listing (thumbnail, title, price, beds, baths, area) and sends it via wpestate_send_emails() (or wp_mail() fallback).
Settings
- wp_estate_crm_matching_email_subject — default Properties matching your preferences.
- wp_estate_crm_matching_email_header — HTML above the listing cards.
- wp_estate_crm_matching_email_footer — HTML below the listing cards.
- wp_estate_crm_matching_email_max_listings — per-email cap, default 20.
Placeholders
Supports the 20-placeholder set from wpestate_crm_resolve_placeholders(). Common ones: {contact_name}, {site_name}, {agent_name}.
Activity Record
Each email records a listing_email_sent activity with meta JSON containing listing_count and listing_ids.
New-Listing Trigger
Hooked to publish_estate_property. When a listing is published for the first time, a one-time cron wpestate_crm_match_new_listing is scheduled 60 seconds later. The handler runs match queries against all active contacts with buyer preferences and emails them the new listing if it is a fit.
Automation Action
The action type run_matching (in libs/automations.php) calls wpestate_crm_match_properties() and optionally emails the agent if matches are found. Used by default rules 24, 25, 26.
Scoring
Matching is currently binary — a listing is either within the preference ranges or it is not. There is no numerical score. Extend by adding a custom filter that ranks the returned post IDs by some proximity metric (for example, distance from midpoint price).
Extending
- Add custom meta filters by extending the query builder in a child plugin and hooking a filter on the returned WP_Query arguments.
- Store additional preference fields on the contact row as custom meta or in a dedicated extension table; the engine reads from the contacts table by column name.
- For very large inventories, consider switching the engine to use a dedicated search index table (the theme has an in-progress wpestate_26_search_index module for this purpose).