Beyond the property and agent helper functions, Havenlytics ships a set of low-level utility functions for reading settings, resolving design tokens, checking feature toggles, and — critically — deleting plugin data safely. This reference documents those utilities plus the plugin’s public interfaces and traits.
Settings access
Defined in includes/Functions/utility-functions.php. The canonical option is hvnly_plugin_settings.
| Function | Purpose |
|---|---|
hvnly_get_plugin_settings(): array | Return the full, normalized settings array. |
hvnly_settings_key_group_index(): array | Map each setting key to its group. |
hvnly_maybe_migrate_legacy_settings(): array | One-time migration of the legacy hvnly_settings option to hvnly_plugin_settings (runs on init, priority 1). |
Note: Read settings through
hvnly_get_plugin_settings()rather than callingget_option( 'hvnly_plugin_settings' )directly — the helper normalizes legacy shapes and applies defaults.
Design tokens
These resolve the site’s configured brand styling, used across templates and the dynamic stylesheet.
| Function | Returns |
|---|---|
hvnly_get_design_setting( $key, $default = null ) | A single design setting. |
hvnly_get_brand_color() / hvnly_get_secondary_color() | Primary / secondary brand colors. |
hvnly_get_link_color() / hvnly_get_title_color() / hvnly_get_body_color() | Text colors. |
hvnly_get_body_font_size() | Base font size. |
hvnly_get_default_badge_color() / hvnly_get_term_badge_background_color( $term_id ) | Badge colors. |
hvnly_get_marker_color_css() / hvnly_marker_color_is_custom() | Map marker color. |
Feature toggles
Boolean helpers that reflect the site’s configuration:
hvnly_is_ajax_load_more_enabled()hvnly_is_breadcrumb_enabled()hvnly_is_back_to_top_enabled()hvnly_is_print_button_enabled()hvnly_is_save_property_enabled()
Query & URL helpers
| Function | Purpose |
|---|---|
hvnly_get_unique_property_ids() | All published property IDs (12-hour transient hvnly_unique_property_ids). |
hvnly_get_terms( $taxonomy, $args = array() ) | Cached term list for a taxonomy. |
hvnly_get_search_page_url() | URL of the configured search page. |
hvnly_get_properties_per_page() | Configured listings-per-page value. |
hvnly_get_ajax_url() | The admin-ajax.php URL. |
Debug logging
<?php
// Writes only when debug logging is enabled in Havenlytics settings.
hvnly_debug_log( 'My add-on did something', 'MyAddon' );
if ( hvnly_is_debug_logging_enabled() ) {
// expensive diagnostics only when logging is on
}
The deletion-safety toolkit
Defined in includes/Functions/deletion-safety.php. Havenlytics stores builder configuration and property data under protected keys; these guards prevent accidental destruction of that data during cleanups and migrations.
| Function | Purpose |
|---|---|
hvnly_protected_meta_prefixes(): array | Meta-key prefixes that must never be bulk-deleted (e.g. _hvnly_, gallery_, map_). |
hvnly_protected_option_keys(): array | Options that must never be deleted (builder configs, DB version, snapshots). |
hvnly_is_protected_meta_key( string $key ): bool | Whether a meta key is protected. |
hvnly_safe_delete_post_meta( $post_id, $key, $context = '' ): bool | Delete post meta only if allowed by the guards. |
hvnly_safe_delete_option( $key, $context = '' ): bool | Delete an option only if not protected. |
hvnly_safe_add_post_meta( $post_id, $key, $value ): bool | Add meta safely. |
hvnly_deep_merge_settings( array $existing, array $incoming ): array | Recursively merge settings, preserving existing values. |
hvnly_rest_deletion_confirmed( bool $confirmed ): bool | Whether a destructive REST action carried explicit confirmation. |
Warning: Never run a raw bulk
delete_post_meta/delete_optionagainsthvnly_keys. Route destructive operations throughhvnly_safe_delete_post_meta()/hvnly_safe_delete_option(), or you risk wiping the property builder configuration and orphaning every property’s field data.
<?php
// Safe deletion respects the protected-key registry:
hvnly_safe_delete_post_meta( $property_id, '_my_addon_temp_flag', 'my-addon-cleanup' );
// This would be refused because the prefix is protected:
hvnly_safe_delete_post_meta( $property_id, '_hvnly_property_price' ); // returns false
Interfaces
| Interface | Contract | Implemented by |
|---|---|---|
VerificationFactorInterface | slug(), label(), is_required_for_access(), is_satisfied(), state() | EmailVerificationFactor |
Agent\Contracts\AgentRepositoryInterface | get(), is_valid_agent(), list_agents() | AgentRepository |
ContactAgent\Contracts\InquiryRepositoryInterface | create(), find(), list(), count(), update_status(), delete() | InquiryRepository |
ContactAgent\Contracts\InquiryNotifierInterface | send() | InquiryNotifier |
Core\Migration\Interfaces\MigrationInterface | get_version(), get_description(), is_needed(), up(), down() | All Version*Handler classes |
FieldTypeInterface | render(), save(), sanitize(), validate(), get_type(), requires_assets(), enqueue_assets() | BaseFieldType + 16 field types |
Traits
Core\Migration\Traits\MigrationTrait— shared migration helpers (backup/restore, safe meta/option writes, builder-config repair).Database\Traits\Taxonomy_Permalink_Manager— rewrites taxonomy term links to the property archive with query params.Database\Traits\Taxonomy_Fields\Hvnly_Advanced_Img_Manager— reusable term image upload.Database\Traits\Taxonomy_Fields\Hvnly_Advanced_Icon_Manager— Font Awesome icon picker for terms.
Namespace map
All classes live under HvnlyNab\ (PSR-4 → includes/): Admin, Agent, Analytics, Api, Common, ContactAgent, Core, Database, Email, Frontend, Functions (global hvnly_* helpers), Integrations, Services, Setup, and Workspace. The top-level HvnlyNab\Helpers and HvnlyNab\HvnlyEngine classes sit at the namespace root.
Best practices
- Read configuration through the settings/design/toggle helpers so your add-on honours the admin’s choices.
- Always use the deletion-safety helpers for any cleanup that touches
hvnly_data. - Program against the interfaces (e.g.
AgentRepositoryInterface) rather than concrete classes where possible.
Security notes
Security: Design-token values are configuration, not user HTML — still escape them on output with
esc_attr()when placing them into inline styles or attributes.
Common mistakes
- Bulk-deleting
hvnly_meta/options directly instead of using the safe-delete helpers. - Reading
hvnly_plugin_settingswithget_option()and missing the normalization/defaults. - Assuming
hvnly_get_unique_property_ids()is live — it is cached for 12 hours.