Developer Guide & FAQ

Welcome to the AdFuz Developer Hub. AdFuz is architected with a modular, extensible object-oriented PHP foundation that exposes robust action hooks, filter hooks, a fluent QueryBuilder ORM, and customizable UI form registries.

---

Developer Guides

Action & Filter Hooks

Complete reference catalog of 22+ action hooks and 35+ filter hooks across AdFuz core and UI. View Hooks Catalog →

QueryBuilder & DB Layer

Learn how to use DB::get(TableName::X()) with automatic _meta handling and fluent querying. QueryBuilder Guide →

AJAX Controllers & Security

Conventions for creating AJAX endpoints with strict capability and nonce security checks. AJAX Conventions →

Extending Forms & UI

Extend Ad Space & Campaign forms, add settings tabs, and register custom ad formats. Extending UI Guide →

---

Developer FAQ (12 Questions & Solutions)

Q1: What action hooks does AdFuz expose?

AdFuz follows the standard naming convention: adfuz/ui/{entity}/{context}/{hook_name}.

// Lifecycle & Autoloading
adfuz/core/autoload:before        // Fires before Free plugin autoload
adfuz/core/autoload:after         // Fires after Free plugin autoload
adfuz/vendor/autoload:before      // Fires before vendor autoload
adfuz/vendor/autoload:after       // Fires after vendor autoload
adfuz/function/core:before        // Fires before adfuz() function returns
adfuz/function/core:after         // Fires after adfuz() function returns
adfuz/plugins_loaded              // Fires on plugins_loaded

// Enqueuing Scripts
adfuz/frontend/scripts:before     // Fires before enqueuing frontend scripts
adfuz/frontend/scripts:after      // Fires after enqueuing frontend scripts
adfuz/admin/scripts:before        // Fires before enqueuing admin scripts
adfuz/admin/scripts:after         // Fires after enqueuing admin scripts

// Template Loading
adfuz/before_template_load        // Fires before template is included
adfuz/after_template_load         // Fires after template is included

// Dashboard UI Sections
adfuz/ui/dashboard/before_welcome // Dashboard: before welcome section
adfuz/ui/dashboard/after_welcome  // Dashboard: after welcome section
adfuz/ui/dashboard/after_stats    // Dashboard: after stats cards
adfuz/ui/dashboard/after_widgets  // Dashboard: after recent widgets
adfuz/ui/dashboard/after_actions  // Dashboard: after quick actions
adfuz/ui/dashboard/additional_sections // Dashboard: for extensions

// Installation & Data Mutations
adfuz/install/all_tables          // Fires after Free plugin tables installed
adfuz/settings/save/{tab}         // Fires when saving a specific settings tab
adfuz/campaign/after_save         // Fires after campaign save (Pro uses this)
adfuz/campaign/after_delete       // Fires after campaign delete (Pro uses this)

AJAX actions follow the WordPress convention: wp_ajax_adfuz_{entity}_{action}

add_action('wp_ajax_adfuz_{entity}_{action}', [MyController::class, 'method']);
add_action('wp_ajax_nopriv_adfuz_{entity}_{action}', [MyController::class, 'method']);

---

Q2: What filter hooks does AdFuz expose?

AdFuz provides granular filters for extending core objects, templates, forms, and UI states:

// Core & Templates
adfuz/core                               // Filters the adfuz() core object
adfuz_template_name                      // Filters template name before load
adfuz_template_path                      // Filters full template path
adfuz_template_output                    // Filters the rendered template output
adfuz/admin/page/slugs                   // Filters AdFuz admin page slugs
adfuz/admin/menu/sub/menus               // Filters submenu items
adfuz/floating_sidebar/items             // Filters floating sidebar items
adfuz/floating_sidebar/enabled           // Controls floating sidebar visibility
adfuz/table_name/definitions             // Filters table name definitions

// Settings & Formats
adfuz/settings/tabs                      // Filters settings tabs
adfuz/settings/tab/data/{tab}            // Filters tab data before render
adfuz/settings/tab/template/dir          // Filters template directory for tabs
adfuz/ads/ad_format/formats              // Filters available ad formats
adfuz/ad_renderer/wrap_banner_html       // Filters banner wrapper HTML

// Ad Space Form & List UI
adfuz/ui/adspace/form/sections           // Filters ad space form sections
adfuz/ui/adspace/form/sidebar_actions    // Filters ad space sidebar actions
adfuz/ui/adspace/form/sidebar_meta       // Filters ad space sidebar meta
adfuz/ui/adspace/form/sidebar_delete     // Filters ad space delete button
adfuz/ui/adspace/list/page_actions       // Filters ad space list page actions
adfuz/ui/adspace/list/empty_state        // Filters ad space empty state
adfuz/ui/adspace/list/stats_display      // Filters ad space stats display
adfuz/ui/adspace/list/card_fields        // Filters ad space card fields
adfuz/ui/adspace/list/campaign_columns   // Filters ad space campaign columns
adfuz/ui/adspace/list/campaign_empty_state // Filters campaign empty state

// Ads Form & List UI
adfuz/ui/ads/list/columns                // Filters ad list columns
adfuz/ui/ads/list/stats_display          // Filters ad list stats display
adfuz/ui/ads/list/page_actions           // Filters ad list page actions
adfuz/ui/ads/list/empty_state            // Filters ad list empty state
adfuz/ui/ads/list/status_config          // Filters ad status badge config
adfuz/ui/ads/common/fields               // Filters common ad fields
adfuz/ui/ads/image/fields                // Filters image ad fields
adfuz/ui/ads/video/fields                // Filters video ad fields
adfuz/ui/ads/script/fields               // Filters script ad fields
adfuz/ui/ads/form/section                // Filters ad form sections
adfuz/ui/ads/form/page_meta              // Filters ad form page meta
adfuz/ui/ads/menu/ad_types               // Filters ad type menu items

// Campaign Form & List UI
adfuz/ui/campaign/form/sections          // Filters campaign form sections
adfuz/ui/campaign/list/columns           // Filters campaign list columns
adfuz/ui/campaign/list/empty_state       // Filters campaign empty state
adfuz/ui/campaign/list/stats_display     // Filters campaign stats display
adfuz/campaign/form_data                 // Filters campaign form data

// Dashboard & Utilities
adfuz/ui/dashboard/layout_config         // Filters dashboard layout config
adfuz/ui/dashboard/stat_cards            // Filters dashboard stat cards
adfuz/ui/dashboard/quick_actions         // Filters dashboard quick actions
adfuz/ui/dashboard/base_data             // Filters dashboard base data
adfuz/ui/dashboard/recent_widgets        // Filters dashboard recent widgets
adfuz/ui/dashboard/sections              // Filters dashboard sections
adfuz/wpkses_allowed_html                // Filters allowed HTML for wp_kses
adfuz/faq/items                          // Filters FAQ items (Pro adds categories)
adfuz/ad_space_meta/meta_schema          // Filters ad space meta schema
adfuz/ad_rotator/select_ad/campaigns_data // Filters campaigns data before ad selection
adfuz_show_upgrade_button                // Controls upgrade/Donate button visibility

---

Q3: How do I extend or override AdFuz templates?

1. Find the template you want to override inside adfuz/templates/.
2. Copy it into your active theme directory at your-theme/adfuz/, preserving the sub-directory structure.
3. Edit the copied file — AdFuz checks the theme folder first before falling back to plugin defaults.

add_filter('adfuz_template_path', function($path, $template_name, $args) {
    if ($template_name === 'admin/adz-space/form') {
        return get_stylesheet_directory() . '/adfuz/custom-form.php';
    }
    return $path;
}, 10, 3);

---

Q4: How do I use the QueryBuilder to query AdFuz tables?

Always use DB::get(TableName::X()) — never write raw $wpdb queries directly:

$ads = DB::get(TableName::ADFUZ_ADS())
    ->where('status', 'active')
    ->orderBy('created_at', 'DESC')
    ->limit(10)
    ->get();

• Filtering: where, orWhere, whereIn, whereNotIn
• Selecting: select, orderBy, limit, groupBy, having
• Joining: join, leftJoin, rightJoin, alias
• Results: get, first, find($id), findWithMeta($id), paginate($perPage, $page), exists, count
• Aggregates: sum, avg, max, min
• Writing: insert, update, softDelete, hardDelete, delete

Automatic Meta Storage

When calling insert() or update(), any keys not present in the main table schema are automatically stored in the associated _meta table.

---

Q5: How do I add a new AJAX controller action?

1. Create or update an entity file in src/Hooks/Action/ and register the hook:

   add_action('wp_ajax_adfuz_my_entity_save', [MyController::class, 'save']);

2. Inside the controller method, run security checks in this exact order:

   // In src/Controllers/AdsController.php
   public static function save(): void {
       Common::checkCapability(static::getCapabilities());
       Common::verifyNonce();
   
       $request = static::request()->input('field', 'post', $default);
       // ... business logic
   
       wp_send_json_success(['message' => 'Ad saved successfully']);
   }

---

Q6: How do I add a new hook for an existing entity?

1. Check if an entity file already exists in src/Hooks/Action/ or src/Hooks/Filter/ (e.g. AdSpace.php, Campaigns.php).
2. If it exists: Add the new add_action() or add_filter() call inside its constructor.
3. If it does not exist: Create the file using the singleton pattern, then register it via get_instance() in the parent Action.php or Filter.php.

// In src/Hooks/Filter/AdRenderer.php
class AdRenderer {
    public function __construct() {
        add_filter('adfuz/ad_renderer/wrap_banner_html', [$this, 'sticky_ad_wrapper'], 10, 4);
    }

    public function sticky_ad_wrapper($html, $inner, $ad, $ad_space) {
        // ... business logic
        return $html;
    }
}

---

Q7: How do I add a new settings tab?

// 1. Register Tab
add_filter('adfuz/settings/tabs', function($tabs) {
    $tabs['geolite'] = ['label' => 'GeoLite2', 'icon' => 'dashicons-location-alt'];
    return $tabs;
});

// 2. Inject Data
add_filter('adfuz/settings/tab/data/geolite', function($data) {
    $data['geolite'] = get_option('adfuz_geolite', []);
    return $data;
});

// 3. Point to Template Directory
add_filter('adfuz/settings/tab/template/dir', function($dir, $tab) {
    if ($tab === 'geolite') return ADFUZ_PRO_TEMPLATE_DIR;
    return $dir;
}, 10, 2);

// 4. Handle Saving
add_action('adfuz/settings/save/geolite', function() {
    // Save logic
    wp_send_json_success(['message' => 'GeoLite2 settings saved.']);
});

---

Q8: How do I add new ad formats?

add_filter('adfuz/ads/ad_format/formats', function($formats) {
    $formats['popup'] = [
        'name'           => 'Popup',
        'description'    => 'Shows a popup ad on page load.',
        'status'         => 'active',
        'placement_type' => 'global',
        'max_spaces'     => 1,
        'settings'       => [
            'delay' => ['label' => 'Trigger Delay', 'type' => 'number', 'default' => 3],
        ],
    ];
    return $formats;
});

---

Q9: How do I add Pro-specific FAQ categories?

add_filter('adfuz/faq/items', function($faqs) {
    $faqs['Pro Features'] = [
        'priority' => 5,
        'icon'     => '⭐',
        'items'    => [
            [
                'q' => 'What Pro features are available?',
                'a' => [
                    ['text', 'AdFuz Pro includes advanced features like:'],
                    ['list', ['Global Ads', 'Advanced targeting', 'Real-time statistics']],
                ],
            ],
        ],
    ];
    return $faqs;
});

---

Q10: How do I extend the Ad Space form with Pro fields?

add_filter('adfuz/ui/adspace/form/sections', function($sections) {
    $sections['display']['fields']['inline_position'] = [
        'order'     => 11,
        'label'     => 'Inline Position',
        'row_class' => 'adfuz-inline-only',
        'render'    => fn() => self::renderInlinePosition(),
    ];
    return $sections;
});

---

Q11: How do I extend the Campaign form with Pro targeting?

// Add targeting sections
add_filter('adfuz/ui/campaign/form/sections', function($sections, $args) {
    $sections['geo_targeting'] = [
        'label'   => 'Country Targeting',
        'order'   => 60,
        'visible' => true,
        'render'  => fn() => CampaignTargetingFormController::render_countries($args['campaign']),
    ];
    return $sections;
}, 10, 2);

// Inject targeting data
add_filter('adfuz/campaign/form_data', function($data, $id, $campaign) {
    $data['target_countries'] = $id ? CampaignTargetCountry::byCampaign($id) : [];
    $data['available_countries'] = Common::countries();
    return $data;
}, 10, 3);

---

Q12: How do I add new dashboard stat cards?

add_filter('adfuz/ui/dashboard/stat_cards', function($cards) {
    $cards['global_ads_configured'] = [
        'id'           => 'adfuz-dashboard-global-configured',
        'order'        => 40,
        'label'        => 'Global Ads - Configured',
        'value'        => 5,
        'href'         => admin_url('admin.php?page=adfuz-global-ads'),
        'icon'         => 'dashicons-globe',
        'icon_color'   => 'text-emerald-600',
        'bg_color'     => 'bg-emerald-50',
        'border_color' => 'border-emerald-200',
        'size'         => 'compact',
    ];
    return $cards;
});