Filter Hooks

Filter hooks are the primary extension seam of the Havenlytics real-estate plugin. Every filter lets you intercept a value the plugin is about to use — a query argument array, a block of property data, a template path, an email subject, a capability string — modify it, and hand it back. This reference documents every apply_filters() hook that ships in Havenlytics 3.3.1, grouped by subsystem, with the exact hook name, the file that fires it, the value you are expected to return, and the parameters your callback receives.

This page is part of the Havenlytics developer documentation. If you are looking for side-effect hooks (registration, notifications, lifecycle events) rather than value transformers, see the companion Action Hooks Reference. Together they cover the roughly 185 hooks Havenlytics exposes.

How Havenlytics filters work

A filter is registered with the core WordPress function add_filter(). Havenlytics calls apply_filters() at strategic points and passes the current value as the first argument, optionally followed by contextual arguments (a property ID, a data array, a context string). Your callback must return a value — that returned value replaces the original and flows on to the next filter and ultimately to the plugin.

<?php
add_filter( 'hvnly_empty_price_text', function ( $text ) {
    // Always return the (possibly modified) value.
    return __( 'Contact for pricing', 'my-theme' );
} );

Warning: The single most common mistake with filters is forgetting to return the value. A callback that ends without returning effectively returns null, wiping out the data Havenlytics was about to render. If your prices, images, or agent cards disappear after adding a filter, check that every code path in your callback returns a value.

Argument count and priority

The 3rd and 4th parameters of add_filter() are the priority (default 10; lower runs earlier) and the accepted argument count (default 1). Many Havenlytics filters pass more than one argument — for example hvnly_property_data passes both the data array and the property ID. To receive the extra context you must declare the argument count explicitly.

<?php
// The 4th argument, 2, tells WordPress to pass BOTH $data and $property_id.
add_filter( 'hvnly_property_data', function ( $data, $property_id ) {
    $data['is_new'] = ( time() - get_post_time( 'U', true, $property_id ) ) < WEEK_IN_SECONDS;
    return $data;
}, 10, 2 );

Note: Nearly every Havenlytics hook uses the hvnly_ prefix. There is exactly one exception in the filter set: the REST controller class map filter hvnlynab_rest_api_class_map, which uses the hvnlynab_ prefix. Watch the spelling.

Settings & Configuration

These filters govern capability checks, service registration, and admin-facing configuration. The most important is hvnly_admin_capability, which controls which WordPress capability is required to reach Havenlytics admin screens and REST endpoints — it defaults to manage_options.

Security: Raising hvnly_admin_capability to a stricter capability tightens who can reach Havenlytics settings and builder REST routes. Lowering it below manage_options exposes plugin configuration to non-administrators — do so only for a deliberate role-based access model, and never below a capability you fully trust.

Cache

The search subsystem is cache-heavy. These filters let you customize cache keys, short-circuit a lookup with a precomputed result, and tune how long results and sidebar terms are stored.

Performance: Increasing hvnly_search_cache_duration reduces database load on high-traffic archives but delays how quickly newly published listings appear in filtered results. Balance the TTL against how often your inventory changes.

Property Query & Search

These are among the most useful filters in Havenlytics. hvnly_property_query_args is the canonical seam for injecting meta_query, tax_query, ordering, or pagination into the property loop — for archives, shortcodes, and Elementor widgets alike.

Worked example: add a meta_query with hvnly_property_query_args

Suppose properties store a featured meta flag and you want every archive and shortcode loop to show featured listings first, then filter to a specific city passed in your own data array.

<?php
add_filter( 'hvnly_property_query_args', function ( $query_args, $data = array() ) {
    // Order featured listings ahead of the rest.
    $query_args['meta_key'] = 'featured';
    $query_args['orderby']  = array( 'meta_value_num' => 'DESC', 'date' => 'DESC' );

    // Restrict to properties that have a price set.
    $meta_query   = isset( $query_args['meta_query'] ) ? $query_args['meta_query'] : array();
    $meta_query[] = array(
        'key'     => 'price',
        'value'   => '',
        'compare' => '!=',
    );
    $query_args['meta_query'] = $meta_query;

    return $query_args;
}, 10, 2 );

Tip: Always merge into the existing meta_query/tax_query arrays instead of overwriting them. Other extensions — and Havenlytics’ own search facets — may have already added clauses that you would silently discard.

Property Data, Images & Pricing

These filters expose the resolved data for a single property: its full data array, individual meta, gallery images, and the price string. hvnly_property_data is the workhorse for injecting or overriding fields before templates render them; the pricing filters let you localize and reshape how prices display.

Worked example: inject a computed field with hvnly_property_data

Add a price-per-square-foot value to every property so your card and single templates (or a child filter) can display it, computed from the existing price and area meta.

<?php
add_filter( 'hvnly_property_data', function ( $property_data, $property_id ) {
    $price = isset( $property_data['price'] ) ? (float) $property_data['price'] : 0;
    $area  = isset( $property_data['area'] )  ? (float) $property_data['area']  : 0;

    if ( $price > 0 && $area > 0 ) {
        $property_data['price_per_sqft'] = round( $price / $area, 2 );
    }

    return $property_data;
}, 10, 2 );

Worked example: remap a field template with hvnly_field_template_mapping

Havenlytics chooses a template per field type from a mapping array. To render your energy_rating field with a custom template instead of the default text renderer, remap it.

<?php
add_filter( 'hvnly_field_template_mapping', function ( $mapping ) {
    // Route the 'energy_rating' field to a template your theme provides.
    $mapping['energy_rating'] = 'fields/energy-rating';
    return $mapping;
} );

Note: The template name you return is resolved through the Havenlytics template loader, so a matching file placed in havenlytics/fields/energy-rating.php inside your active or child theme will override the plugin default. See Template Overriding for the full resolution order.

Template Rendering & Paths

These filters control which template file Havenlytics loads and where it searches. They are the programmatic counterpart to dropping override files into your theme, and they let you redirect, replace, or relocate templates without shipping physical files.

Layout

Layout filters expose the CSS class strings and structural decisions Havenlytics makes for the grid, main content column, and sidebar — plus whether a sidebar is shown at all in a given context.

Shortcodes, Archive & Card Rendering

These filters cover default shortcode attributes, legacy attribute conversion, and card-level rendering.

Note: For the shortcode markup itself and available attributes, see Shortcodes. The default-atts filters above run before the user’s shortcode attributes are merged, so user-supplied values still take precedence.

Agents & Agencies

Havenlytics resolves agents for properties, builds agent/agency archives, and renders agent cards. These filters let you change the rewrite slug, swap the repository class, adjust per-page counts, and reshape the resolved agent/agency data and card metadata.

Maps

The map subsystem supports multiple providers. hvnly_map_provider selects the active provider, and the remaining filters supply provider-specific credentials and tile configuration.

Worked example: switch the map provider with hvnly_map_provider

Force OpenStreetMap everywhere (avoiding Google Maps billing) and point tiles at your own cached tile server.

<?php
add_filter( 'hvnly_map_provider', function ( $provider ) {
    return 'osm';
} );

add_filter( 'hvnly_osm_tile_url', function ( $tile_url ) {
    return 'https://tiles.example.com/{z}/{x}/{y}.png';
} );

add_filter( 'hvnly_osm_attribution', function ( $attribution ) {
    return '&copy; OpenStreetMap contributors';
} );

Security: Do not hard-code a production Google Maps API key in a public repository via hvnly_google_maps_api_key. Return the value from a constant defined in wp-config.php or an environment variable instead, and restrict the key by HTTP referrer in the Google Cloud console.

Import & Media

The import wizard uses these filters when resolving bundled or placeholder media and deciding whether remote media fetching is permitted.

Note: The demo-import engine lives in PropertyImportWizard.php; these filters only tune media resolution, not the import flow itself. See Import & Export for the wizard architecture.

Avatar

Avatars route through a single service (uploaded photo → Gravatar → Havenlytics placeholder). These filters let you change the placeholder, override Gravatar detection, and rewrite the final resolved URL.

REST / AJAX

Havenlytics registers its REST controllers from a class-map array. The filter below is the seam for registering your own controller classes into the hvnlynab/v1 admin namespace — note it uses the hvnlynab_ prefix.

Note: Havenlytics exposes two REST namespaces — hvnlynab/v1 for admin/settings/builders and hvnly/v1 for the Agent Workspace SPA. The hvnlynab_rest_api_class_map filter registers controllers into the admin namespace. See the REST API guide for route details.

Workspace

The Agent Workspace is a front-end SPA (namespace hvnly/v1). These filters govern its shortcode output, template resolution, settings, routing, registration behavior, redirects, localization, and the shape of API responses.

Workspace Auth, Identity & Provisioning

These filters drive workspace authentication, the identity resolution pipeline, permission calculation, and the pluggable verification-factor system. The most important extension seam is hvnly_identity_factors, which lets you register a VerificationFactorInterface implementation into the identity-verification pipeline.

Note: hvnly_identity_factors is the designed seam for the email-verification architecture — register a class implementing VerificationFactorInterface and the identity service will run it as part of verification. See Authentication for the factor interface and the workspace auth flow.

Security: hvnly_verification_client_ip feeds the verification rate limiter. If you sit behind a reverse proxy or CDN, return the real client IP from a trusted forwarded header — but only trust that header when the request genuinely originates from your proxy, or an attacker can spoof it to bypass rate limits.

Email Verification

These filters control whether email verification is enforced, its token lifetime, and the subject and body of the verification email.

Email Pipeline & Notifiers

The core email pipeline exposes filters for render context, final HTML, headers, merge tags, template registration, and branding — plus per-notifier filters for property-workflow, import-success, workspace-account, and registration emails.

Worked example: rebrand outgoing email with hvnly_email_from_header

<?php
add_filter( 'hvnly_email_from_header', function ( $from_header ) {
    return 'From: My Agency <listings@myagency.example>';
} );

add_filter( 'hvnly_email_logo_url', function ( $url ) {
    return 'https://myagency.example/wp-content/uploads/brand/logo.png';
} );

Contact Agent (Inquiries)

The Contact Agent module powers property inquiry forms, spam protection, rate limiting, agent resolution, and reply email. These filters cover the entire inquiry lifecycle from button rendering through validation, notification, and admin reply.

Security: When you return true from hvnly_contact_agent_spam_verify to accept a submission, you are overriding Havenlytics’ built-in spam checks. Never blanket-approve inquiries; run your own validation (reCAPTCHA, Akismet) inside the callback and return its verdict.

Best practices

• Always return a value. Every branch of a filter callback must return — returning nothing returns null and erases the data.
• Declare the correct argument count. If a filter passes extra parameters (like $property_id), pass 10, 2 (or the right count) to add_filter(), or your callback silently receives only the first argument.
• Do not change the type. Return the same type the filter provides — an array stays an array, a bool stays a bool, a string stays a string. Returning the wrong type breaks downstream code that does not re-check.
• Merge, do not overwrite. For array filters like hvnly_property_query_args and hvnly_field_template_mapping, add your keys to the incoming array rather than replacing it wholesale.
• Namespace your logic. Guard expensive work with context checks so your callback only runs where it should (e.g. is_singular( 'hvnly_property' )).
• Prefer the documented seams. For identity, use hvnly_identity_factors; for query changes, use hvnly_property_query_args; for template swaps, use the template loader filters plus theme overrides.

Performance

• Filters such as hvnly_property_data, hvnly_property_agents, and the layout class filters run inside loops — once per property or per card. Keep their callbacks cheap and avoid database queries inside them; if you must query, cache the result outside the loop.
• Use the cache-key and TTL filters (hvnly_search_cache_key, hvnly_search_cache_duration, hvnly_property_query_cache_ttl) to tune the trade-off between freshness and database load rather than disabling caching.
• Return early. If your modification only applies to a specific view or post type, check context first and return the unmodified value immediately otherwise.

Security

• Escape on output, not inside data filters — but if a filter feeds directly into markup (email HTML, class strings, URLs), sanitize with the appropriate function (esc_url, esc_attr, wp_kses_post) before returning.
• Treat capability and access filters (hvnly_admin_capability, hvnly_workspace_permissions, hvnly_workspace_soft_portal_access, hvnly_inquiry_reply_capability) as security boundaries — never loosen them without a deliberate, audited access model.
• IP-derived filters (hvnly_verification_client_ip, hvnly_contact_agent_client_ip) feed rate limiters; only trust forwarded headers from infrastructure you control.

Common mistakes

• Forgetting to return the value. The number-one filter bug. If content vanishes after you add a filter, you almost certainly missed a return.
• Wrong argument count. Expecting $property_id in hvnly_property_data but omitting , 10, 2 — the parameter arrives as null.
• Confusing filters with actions. A filter must return; an action must not. Do not hook side-effect logic to a filter and forget the return, and do not try to modify-and-return from an action.
• Misspelling the prefix. All but one filter use hvnly_; only hvnlynab_rest_api_class_map uses hvnlynab_.
• Overwriting arrays. Replacing an incoming meta_query or template mapping instead of merging into it, silently dropping other extensions’ contributions.