Helper Functions: The Global hvnly Developer Reference

Havenlytics ships a large library of global helper functions — procedural PHP functions prefixed hvnly_ — that give theme and plugin developers a stable, public surface for reading property and agent data, rendering fields, resolving prices, generating avatars and wiring up the Contact Agent module. These helpers live in includes/Functions/ and are loaded early in the boot sequence, so they are available from theme templates, shortcodes, widgets and your own integrations. This Havenlytics developer guide documents the most useful helpers grouped by domain, with exact signatures, return types and runnable examples.

Note: Every helper on this page is prefixed hvnly_ and lives in the global namespace (they are procedural functions, not methods). They are the recommended, forward-compatible way to read Havenlytics data — prefer them over calling internal HvnlyNab\ classes directly. If a function name is not documented here or in the source, do not rely on it.

Why use the helpers instead of internal classes

Havenlytics follows a single-source-of-truth (SSOT) architecture: a small number of internal services own each concern (price resolution, avatar resolution, agent lookup, gallery loading), and the global helpers are thin, documented facades over those services. Calling a helper such as hvnly_resolve_property_price() means you automatically benefit from the plugin’s caching, fallbacks and future refactors. Calling the underlying class directly couples your code to internals that may change between releases.

• Stability — helper signatures are treated as public API.
• Caching — most helpers cache results (static request caches and/or the object cache group havenlytics).
• Fallbacks — helpers degrade gracefully (empty arrays, sensible defaults) rather than throwing.

Agent helpers

Defined in includes/Functions/agent-functions.php. These read the Agent custom post type (hvnly_agent), resolve property↔agent relationships and expose agency (taxonomy hvnly_agent_agency) data. Under the hood agent lookups route through hvnly_agent_repository(), which returns an implementation of AgentRepositoryInterface.

Tip: hvnly_get_agent() and its siblings always return an array, never null. Check for a truthy id (or empty()) rather than a null check — this keeps template code branch-free and safe.

Property, rendering, price and time helpers

The property helpers span includes/Functions/property-functions.php and the template loaders in includes/Functions/template-functions.php. They cover structured data access, field rendering, view counts, relative time, currency and price. Price and currency helpers ultimately resolve through the price SSOT, HvnlyNab\Services\Hvnly_Price_Resolver (documented below).

Data access & rendering

Views & relative time

Currency & price

Performance: hvnly_get_property_data() and hvnly_get_property_gallery_ids() keep a per-request static cache keyed by property ID. Calling them repeatedly inside a loop for the same property is effectively free after the first call — you do not need to memoize results yourself.

Avatar helpers (AvatarService-backed)

All avatar output flows through a single source of truth: HvnlyNab\Common\AvatarService (includes/Common/AvatarService.php). The resolution order is uploaded photo → Gravatar → Havenlytics placeholder. The global helpers hvnly_get_agent_avatar_url() and hvnly_get_user_avatar_url() are facades over this service; the service also filters WordPress core avatars via pre_get_avatar_data, so get_avatar() in a theme returns the correct Havenlytics avatar too.

The service exposes DEFAULT_SIZE = 96 and caches Gravatar checks under the prefix hvnly_has_gravatar_ (a per-user transient with a one-day TTL).

Common mistake: Do not build avatar URLs by reading the agent photo meta directly. That bypasses the Gravatar and placeholder fallbacks and will render broken images for agents without an uploaded photo. Always call hvnly_get_agent_avatar_url() or AvatarService::resolve_url().

Contact Agent helpers

Defined in includes/Functions/contact-agent-functions.php. These drive the Contact Agent inquiry module — rendering the button, checking feature flags, reading rate-limit configuration and localizing the front-end script. The module object is returned by hvnly_contact_agent_module().

Security: hvnly_render_contact_agent_button() echoes markup directly. Call it only inside a template output context, never in a REST or AJAX callback that returns JSON. The button and its modal already handle nonces, the honeypot and rate limiting — do not reimplement the submission flow yourself.

Field option helpers

Defined in includes/Functions/field-options.php. These supply the canonical option sets for select fields (heating, cooling, water, location, country) and provide the hydration utilities the builder uses to populate select controls.

The Helpers class (HvnlyNab\Helpers)

Alongside the procedural helpers, Havenlytics has an internal Helpers singleton at includes/Helpers.php. It is reachable via HvnlyNab\Helpers::get_instance() or through the plugin accessor HVNLY_NAB()->get_helper(). Its instance methods back some of the global functions (image sizing, gallery images, property IDs, ratings, currency) and use the object cache group havenlytics. Prefer the global hvnly_* helpers in application code; reach for the class only when you are extending the plugin internally.

Note: HvnlyNab\Helpers is a singleton — never instantiate it with new. Always call HvnlyNab\Helpers::get_instance() (or HVNLY_NAB()->get_helper()) so you share the same cached state as the rest of the plugin.

The price SSOT: Hvnly_Price_Resolver

HvnlyNab\Services\Hvnly_Price_Resolver (includes/Services/Hvnly_Price_Resolver.php) is the single source of truth for property price resolution. The global helper hvnly_resolve_property_price() delegates to it. It exposes a static resolve( $property_id ) method and a get_mortgage_mode() helper for pricing display mode. Because every price surface (cards, single view, search, Workspace) routes through this resolver, using the helper guarantees consistent output across the site.

Code examples

Read structured property data and its gallery

<?php
// Inside a single-property template (get_the_ID() resolves the current post).
$property_id = get_the_ID();

$data = hvnly_get_property_data( $property_id );
if ( ! empty( $data ) ) {
    printf(
        '<h2>%s</h2><p class="price">%s</p>',
        esc_html( $data['title'] ),
        esc_html( hvnly_resolve_property_price( $property_id ) )
    );
}

// Canonical gallery attachment IDs (SSOT loader).
$gallery_ids = hvnly_get_property_gallery_ids( $property_id );
foreach ( $gallery_ids as $attachment_id ) {
    echo wp_get_attachment_image( $attachment_id, 'large' );
}

Render the Contact Agent button for a property

<?php
// Only render when the module is active.
if ( hvnly_is_contact_agent_enabled() ) {
    hvnly_render_contact_agent_button( get_the_ID(), array(
        'label' => __( 'Contact this agent', 'my-theme' ),
    ) );
}

Resolve an agent and its avatar

<?php
$agent = hvnly_get_agent( $agent_id );

if ( ! empty( $agent['id'] ) ) {
    $avatar = hvnly_get_agent_avatar_url( $agent['id'], 0, 128, 'medium' );

    printf(
        '<div class="agent"><img src="%s" width="128" height="128" alt="%s" /><span>%s</span></div>',
        esc_url( $avatar ),
        esc_attr( $agent['name'] ?? '' ),
        esc_html( $agent['name'] ?? '' )
    );
}

Resolve an avatar through the SSOT service directly

<?php
use HvnlyNab\Common\AvatarService;

// uploaded photo -> Gravatar -> Havenlytics placeholder
$url = AvatarService::resolve_url( $agent_id, 0, AvatarService::DEFAULT_SIZE, 'medium' );
echo esc_url( $url );

Best practices

• Guard optional features. Wrap Contact Agent output in hvnly_is_contact_agent_enabled() so disabling the module cleanly removes the button.
• Escape on output. Helpers return raw data (URLs, strings, numbers). Escape with esc_url(), esc_html(), esc_attr() at the point of output.
• Prefer helpers over meta reads. Reading get_post_meta() directly for price, gallery or avatar data bypasses the SSOT services and their caching/fallbacks.
• Pass explicit IDs in loops. Most helpers default to the current post; passing the ID explicitly avoids surprises inside nested or custom queries.

Performance recommendations

• Lean on the built-in static request caches in hvnly_get_property_data() and hvnly_get_property_gallery_ids() instead of duplicating your own arrays.
• Avatar Gravatar checks are day-cached per user; avoid clearing that cache in hot paths.
• The Helpers class caches ratings and max-price lookups in the havenlytics object cache group — persistent object caching (Redis/Memcached) makes these effectively free across requests.

Security notes

• Helpers do not sanitize output for you — always escape at output time.
• The Contact Agent flow includes nonces, a honeypot and rate limiting; never bypass hvnly_render_contact_agent_button() with a hand-rolled form.
• Avatar URLs may resolve to remote Gravatar images; treat them as untrusted URLs and pass through esc_url().

Common mistakes

• Instantiating HvnlyNab\Helpers with new instead of get_instance().
• Assuming a helper returns null — agent/property helpers return empty arrays; test with empty().
• Building price strings manually instead of calling hvnly_resolve_property_price(), which caus