Developer Reference

This page is the technical reference for developers who want to extend, customize, or integrate with Local Directory. It covers the plugin architecture, public API surface, database schema, hook system, and asset pipeline.

Architecture

Local Directory uses a singleton + PSR-4-style autoloader pattern. The main plugin file local-directory.php defines the ld_plugin() function, which returns the single instance of LD_Plugin. All subsystems are instantiated during the plugins_loaded hook.

Bootstrap Flow

local-directory.php  →  ld_plugin()  →  LD_Plugin::instance()

Inside LD_Plugin::instance(), the following subsystems are created:

new LD_Admin();
new LD_Shortcodes();
new LD_Badges();
new LD_Favorites();
new LD_Claim_Listing();
new LD_Report();
new LD_Email_Manager();
new LD_Schema();
new LD_Open_Graph();
new LD_Analytics_Tracker();
new LD_Search_Query();
new LD_Compare_Controller();
new LD_Blocks();

Autoloader

Classes follow the class-ld-{name}.php naming convention. The autoloader resolves classes from these directories:

• includes/
• includes/admin/
• includes/frontend/
• includes/models/
• includes/features/
• includes/search/
• includes/maps/
• includes/seo/
• includes/blocks/
• includes/elementor/
• includes/elementor/widgets/

Controller Pattern

Shortcode controllers follow a consistent render pipeline:

render($atts)  →  get_atts()  →  WP_Query  →  LD_Template_Loader::load()

Each controller normalizes shortcode attributes via get_atts(), builds a WP_Query for listing data, and passes results to the template loader which supports child-theme overrides.

Constants

These constants are defined in local-directory.php and available globally after the plugin loads.

Custom Post Type

The plugin registers the ld_listing custom post type during init.

Querying Listings

$listings = new WP_Query([
    'post_type'      => 'ld_listing',
    'posts_per_page' => 10,
    'orderby'        => 'date',
    'order'          => 'DESC',
]);

Taxonomies

Three custom taxonomies are registered for the ld_listing post type.

Database Tables

Local Directory creates 9 custom tables on activation. All table names are prefixed with $wpdb->prefix (typically wp_).

Key Models

Models wrap database records and provide a clean API for reading and writing data. All models are in includes/models/.

LD_Listing

Wraps a WP_Post of type ld_listing. The primary model used throughout the plugin for listing display, search results, and data export.

// All public getters on LD_Listing

$listing->get_id()
$listing->get_title()
$listing->get_permalink()
$listing->get_phone()
$listing->get_website()
$listing->get_opening_hours()
$listing->get_location_data()
$listing->get_lat()
$listing->get_lng()
$listing->get_address()
$listing->get_overall_rating()
$listing->get_criteria_ratings()
$listing->get_price_level()
$listing->get_badges()
$listing->is_featured()
$listing->is_verified()
$listing->is_new()
$listing->to_marker_data()
$listing->to_card_data()
$listing->to_compare_data()

LD_Location_Data

Manages the ld_locations_data table. Stores latitude, longitude, formatted address, and Google Place ID per listing.

// Static methods
LD_Location_Data::get_by_listing( $listing_id )  // Returns location row or null
LD_Location_Data::save( $listing_id, $data )      // Upserts location data

LD_Claim

Manages ownership claims in the ld_claims table.

LD_Claim::create( $listing_id, $user_data )
LD_Claim::get( $claim_id )
LD_Claim::verify_code( $claim_id, $code )
LD_Claim::approve( $claim_id )
LD_Claim::reject( $claim_id )
LD_Claim::get_approved_for_listing( $listing_id )

LD_Review

Handles multi-criteria ratings linked to WordPress comments.

LD_Review::get_criteria_for_listing( $listing_id )
LD_Review::get_ratings_for_comment( $comment_id )
LD_Review::save_ratings( $comment_id, $ratings )
LD_Review::recalculate_summary( $listing_id )

LD_Recaptcha

Wraps Google reCAPTCHA v3 verification for contact, claim, and report forms.

LD_Recaptcha::is_enabled()             // bool
LD_Recaptcha::get_site_key()           // string
LD_Recaptcha::verify( $token, $action ) // bool

Hooks Reference

Local Directory fires custom actions and filters that let you extend every major feature. Use these hooks from your theme's functions.php or a custom plugin.

Actions

Example: Sync After Import

add_action( 'ld_after_import_listing', function( $listing_id, $raw_data ) {
    // Push new listing to external CRM
    my_crm_sync( $listing_id, $raw_data['name'] );
}, 10, 2 );

Filters

Example: Add a Custom Badge

add_filter( 'ld_badge_types', function( $types ) {
    $types['eco_friendly'] = [
        'label'    => 'Eco-Friendly',
        'color'    => '#16a34a',
        'bg_color' => '#f0fdf4',
        'icon'     => 'leaf',
        'meta_key' => '_ld_eco_friendly',
    ];
    return $types;
} );

AJAX Endpoints

AJAX handlers are registered in LD_Ajax for both authenticated (wp_ajax_) and public (wp_ajax_nopriv_) requests. All requests use admin-ajax.php and require a valid nonce unless noted otherwise.

REST API

Local Directory registers 8 REST endpoints under the local-directory/v1 namespace. All endpoints support standard WordPress REST authentication (cookie, Application Password, or OAuth).

Example: Fetch Listings

// JavaScript (fetch)
const res = await fetch('/wp-json/local-directory/v1/listings?per_page=10&category=restaurants');
const data = await res.json();

// PHP (internal)
$request  = new WP_REST_Request( 'GET', '/local-directory/v1/listings' );
$request->set_param( 'per_page', 10 );
$response = rest_do_request( $request );

Gutenberg Blocks

All shortcodes have matching Gutenberg block equivalents registered under the local-directory/ namespace. Block registration is handled in LD_Blocks.

Elementor Widgets

When Elementor is active, Local Directory registers 7 widgets in a dedicated "Local Directory" category. Widget files are in includes/elementor/widgets/.

Frontend Assets

All frontend scripts and styles are conditionally enqueued only on pages where directory content is rendered. Handles are prefixed with ld-.

Scripts

Styles

Localized Data: window.ldData

The ld-frontend script receives a localized JavaScript object via wp_localize_script(). This object is available globally as window.ldData.

window.ldData = {
    ajaxUrl:       '/wp-admin/admin-ajax.php',
    restUrl:       '/wp-json/local-directory/v1/',
    nonce:         'abc123...',
    mapProvider:   'leaflet',           // 'leaflet' or 'google'
    googleApiKey:  '',                  // Google Maps API key (if set)
    mapStyle:      'default',           // Map style preset name
    defaultLat:    40.7128,             // Default map center latitude
    defaultLng:    -74.0060,            // Default map center longitude
    defaultZoom:   12,                  // Default map zoom level
    clustering:    true,                // Whether marker clustering is enabled
    directoryPage: '/directory/',       // Main directory page URL
    comparePage:   '/compare/',         // Compare page URL
    i18n: {
        search:        'Search',
        noResults:     'No listings found.',
        loading:       'Loading...',
        viewOnMap:     'View on Map',
        addToCompare:  'Add to Compare',
        removeCompare: 'Remove from Compare',
        directions:    'Get Directions',
        openNow:       'Open Now',
        closed:        'Closed',
        featured:      'Featured',
        verified:      'Verified',
        claimListing:  'Claim this listing',
        reportListing: 'Report this listing'
    }
};

Plugin File Structure

Full directory tree of the Local Directory plugin:

local-directory/
├── local-directory.php          # Main plugin file, bootstrap
├── uninstall.php                # Cleanup on uninstall
│
├── includes/
│   ├── class-ld-plugin.php          # Singleton, subsystem init
│   ├── class-ld-activator.php       # Activation: tables, defaults
│   ├── class-ld-deactivator.php     # Deactivation cleanup
│   ├── class-ld-autoloader.php      # PSR-4 style autoloader
│   ├── class-ld-shortcodes.php      # Shortcode registration
│   ├── class-ld-template-loader.php # Template resolution + overrides
│   ├── class-ld-ajax.php            # AJAX handler registration
│   ├── class-ld-rest-api.php        # REST endpoint registration
│   ├── class-ld-email-manager.php   # 9 email notification types
│   ├── class-ld-badges.php          # Badge system (featured, verified, new, price)
│   ├── class-ld-favorites.php       # Favorites (cookie + user meta)
│   ├── class-ld-compare-controller.php
│   │
│   ├── admin/
│   │   ├── class-ld-admin.php           # Admin menus, metaboxes
│   │   ├── class-ld-admin-settings.php  # Settings page (tabs)
│   │   ├── class-ld-admin-import.php    # Import UI + processor
│   │   └── class-ld-admin-analytics.php # Analytics dashboard
│   │
│   ├── frontend/
│   │   ├── class-ld-directory-controller.php   # [local-directory]
│   │   ├── class-ld-listings-controller.php    # [ld-listings]
│   │   ├── class-ld-map-controller.php         # [ld-map]
│   │   ├── class-ld-search-controller.php      # [ld-search]
│   │   ├── class-ld-categories-controller.php  # [ld-categories]
│   │   ├── class-ld-single-controller.php      # [ld-listing-page]
│   │   ├── class-ld-compare-controller.php     # [ld-compare]
│   │   └── class-ld-recently-viewed-controller.php
│   │
│   ├── models/
│   │   ├── class-ld-listing.php
│   │   ├── class-ld-location-data.php
│   │   ├── class-ld-claim.php
│   │   ├── class-ld-review.php
│   │   └── class-ld-report.php
│   │
│   ├── features/
│   │   ├── class-ld-claim-listing.php
│   │   ├── class-ld-report.php
│   │   ├── class-ld-recaptcha.php
│   │   └── class-ld-analytics-tracker.php
│   │
│   ├── search/
│   │   └── class-ld-search-query.php
│   │
│   ├── maps/
│   │   └── class-ld-map-provider.php
│   │
│   ├── seo/
│   │   ├── class-ld-schema.php
│   │   └── class-ld-open-graph.php
│   │
│   ├── blocks/
│   │   └── class-ld-blocks.php
│   │
│   └── elementor/
│       ├── class-ld-elementor.php
│       └── widgets/
│           ├── class-ld-elementor-directory.php
│           ├── class-ld-elementor-listings.php
│           ├── class-ld-elementor-map.php
│           ├── class-ld-elementor-search.php
│           ├── class-ld-elementor-categories.php
│           ├── class-ld-elementor-compare.php
│           └── class-ld-elementor-recently-viewed.php
│
├── templates/
│   ├── directory.php
│   ├── listings/
│   │   ├── card-grid.php
│   │   ├── card-list.php
│   │   └── pagination.php
│   ├── single/
│   │   ├── single-listing.php
│   │   ├── gallery.php
│   │   ├── tabs.php
│   │   ├── reviews.php
│   │   ├── contact-form.php
│   │   └── sidebar.php
│   ├── search/
│   │   └── search-form.php
│   ├── map/
│   │   └── map-canvas.php
│   ├── categories/
│   │   └── category-grid.php
│   ├── compare/
│   │   └── compare-table.php
│   └── recently-viewed/
│       └── recently-viewed.php
│
├── assets/
│   ├── css/
│   │   ├── frontend.css
│   │   └── admin.css
│   ├── js/
│   │   ├── frontend.js
│   │   ├── search.js
│   │   ├── map-leaflet.js
│   │   ├── map-google.js
│   │   ├── compare.js
│   │   ├── single.js
│   │   └── admin.js
│   └── images/
│       ├── marker-default.svg
│       └── no-image.svg
│
└── languages/
    └── local-directory.pot