Cache Management: A Developer's Guide

Havenlytics cache management spans several layers — a central transient facade, an engine cache, and multiple object-cache groups — all gated behind a single “is caching enabled” switch. This guide explains each layer, the key and TTL conventions, where caches are invalidated, the cache-related hooks, and the API you use to clear caches programmatically.

Note: Caching is globally controlled by hvnly_is_cache_enabled() (the single source of truth, reading the hvnly_cache_enabled option). When it returns false, the facade’s read/write short-circuit and nothing is cached.

Cache layers

1. CacheManager — the transient facade

HvnlyNab\Core\CacheManager (includes/Core/CacheManager.php) is the centralized transient cache. All keys are prefixed _transient_hvnly_ and passed through sanitize_key(). Optional GZIP compression is gated by the hvnly_cache_compression option. Purges use a direct SQL DELETE against option_name LIKE '_transient_hvnly_%'.

2. HvnlyEngine — engine cache

The engine (includes/HvnlyEngine.php) provides an engine-level cache (set_cache(), get_cache(), clear_all_cache(), cleanup_expired_cache()) with hit/miss tracking. It is reached through the facade functions hvnly_clear_cache(), hvnly_get_cache_stats(), and hvnly_transients_available().

3. Object-cache groups (wp_cache_*)

Transient key & TTL reference

Invalidation points

• HvnlyNab\Core\CacheInvalidator — invalidate() is hooked to save_post_hvnly_property and deleted_post_meta, clearing the search, sidebar, and property-query caches when a property changes.
• Frontend\AjaxHandler — hooks save_post_hvnly_property, deleted_post_meta, and the created_term/edited_term/delete_term events to clear property and taxonomy caches.
• View models — SidebarSearchFilters and SearchFilters expose clear_*_cache() methods; both also delete hvnly_unique_property_ids.
• hvnly_clear_all_cache() — clears all search caches and fires hvnly_cache_cleared.

Cache hooks

The clear-cache API

<?php
// Programmatic clears:
HVNLY_NAB()->clear_cache();   // clears the engine cache
hvnly_clear_all_cache();      // clears all search/plugin caches + fires hvnly_cache_cleared

// Guard your own cache work behind the SSOT switch:
if ( hvnly_is_cache_enabled() ) {
    \HvnlyNab\Core\CacheManager::set_transient( 'my_addon_data', $data, 10 * MINUTE_IN_SECONDS );
}

The admin UI clears caches over AJAX via the hvnly_clear_cache action, protected by the hvnly_cache_nonce nonce and the manage_options capability.

Filter the query cache TTL

<?php
add_filter( 'hvnly_property_query_cache_ttl', function ( $ttl ) {
    return 5 * MINUTE_IN_SECONDS; // shorter cache for very dynamic listings
} );

Invalidate your own cache in sync with Havenlytics

<?php
add_action( 'hvnly_cache_cleared', function () {
    delete_transient( 'my_addon_derived_cache' );
} );

Best practices

• Always guard writes with hvnly_is_cache_enabled() so your add-on respects the site’s caching setting.
• Use the CacheManager facade (keys auto-prefixed and sanitized) rather than raw set_transient(), so your entries are purged by the plugin’s clear routines.
• Hook hvnly_cache_cleared / hvnly_property_query_cache_invalidated to keep derived caches consistent.

Performance recommendations

Performance: The property query cache (hvnly_property_queries) is the highest-leverage layer — leave it enabled in production. Random-order queries (orderby=rand) bypass it by design, so avoid random ordering on high-traffic archives.

Common mistakes

• Writing to caches without checking hvnly_is_cache_enabled(), so data is cached even when the admin disabled caching.
• Using raw transient keys that the plugin’s purge routines don’t match, leaving stale data after a clear.
• Expecting query results to update instantly — they are cached for up to 15 minutes unless a property save invalidates them.