Hooks and Filters - /llmtag.org

Hooks and Filters Overview

The LLMTAG plugin provides a comprehensive set of WordPress hooks and filters that allow developers to extend and customize the plugin’s functionality.

Developer Extensibility

Action Hooks • Filter Hooks • Custom Functions • Plugin Integration

Action Hooks

Core Plugin Actions

`llmtag_init`

Fired when the plugin is initialized.

add_action('llmtag_init', function() {
    // Plugin initialization code
    error_log('LLMTAG plugin initialized');
});

`llmtag_settings_saved`

Fired when plugin settings are saved.

add_action('llmtag_settings_saved', function($settings) {
    // Handle settings save
    error_log('LLMTAG settings saved: ' . print_r($settings, true));
});

`llmtag_agent_blocked`

Fired when an AI agent is blocked.

add_action('llmtag_agent_blocked', function($agent, $ip, $path) {
    // Log blocked agent
    error_log("Blocked AI agent: {$agent} from {$ip} accessing {$path}");
    
    // Send notification
    wp_mail('admin@example.com', 'AI Agent Blocked', 
        "Agent: {$agent}\nIP: {$ip}\nPath: {$path}");
});

`llmtag_llmtag_txt_generated`

Fired when the llmtag.txt file is generated.

add_action('llmtag_llmtag_txt_generated', function($content) {
    // Custom processing of generated content
    $custom_content = apply_filters('llmtag_custom_content', $content);
    
    // Save to custom location
    file_put_contents(ABSPATH . 'custom-llmtag.txt', $custom_content);
});

Analytics Actions

`llmtag_analytics_updated`

Fired when analytics data is updated.

add_action('llmtag_analytics_updated', function($data) {
    // Send analytics to external service
    wp_remote_post('https://analytics.example.com/llmtag', [
        'body' => json_encode($data),
        'headers' => ['Content-Type' => 'application/json']
    ]);
});

`llmtag_daily_report_generated`

Fired when daily analytics report is generated.

add_action('llmtag_daily_report_generated', function($report) {
    // Send daily report to stakeholders
    $email_content = $this->format_report_for_email($report);
    wp_mail('stakeholders@example.com', 'Daily LLMTAG Report', $email_content);
});

Filter Hooks

Content Generation Filters

`llmtag_txt_content`

Filter the content of the generated llmtag.txt file.

add_filter('llmtag_txt_content', function($content, $context) {
    // Add custom directives
    $custom_directives = "\n# Custom directive\nai_license: creative-commons\n";
    
    return $content . $custom_directives;
}, 10, 2);

`llmtag_global_policies`

Filter global AI policies before they are applied.

add_filter('llmtag_global_policies', function($policies) {
    // Modify policies based on custom logic
    if (is_user_logged_in() && current_user_can('manage_options')) {
        $policies['ai_training_data'] = 'allow';
    }
    
    return $policies;
});

`llmtag_path_policies`

Filter path-specific policies.

add_filter('llmtag_path_policies', function($policies, $path) {
    // Custom path-based logic
    if (strpos($path, '/premium/') !== false) {
        $policies['ai_training_data'] = 'disallow';
        $policies['ai_use'] = ['search_indexing'];
    }
    
    return $policies;
}, 10, 2);

Agent Blocking Filters

`llmtag_blocked_agents`

Filter the list of blocked AI agents.

add_filter('llmtag_blocked_agents', function($agents) {
    // Add custom agents to block
    $custom_agents = ['CustomAI-Bot', 'AnotherAI-Crawler'];
    
    return array_merge($agents, $custom_agents);
});

`llmtag_agent_blocking_decision`

Filter the decision to block or allow an AI agent.

add_filter('llmtag_agent_blocking_decision', function($should_block, $agent, $ip, $path) {
    // Custom blocking logic
    if ($agent === 'ResearchBot' && strpos($path, '/research/') !== false) {
        return false; // Allow research bots on research pages
    }
    
    return $should_block;
}, 10, 3);

`llmtag_user_agent_detection`

Filter user agent detection logic.

add_filter('llmtag_user_agent_detection', function($is_ai_agent, $user_agent) {
    // Custom AI agent detection
    $custom_patterns = ['/CustomAI/i', '/MyBot/i'];
    
    foreach ($custom_patterns as $pattern) {
        if (preg_match($pattern, $user_agent)) {
            return true;
        }
    }
    
    return $is_ai_agent;
}, 10, 2);

Analytics Filters

`llmtag_analytics_data`

Filter analytics data before it’s stored.

add_filter('llmtag_analytics_data', function($data) {
    // Anonymize IP addresses
    if (isset($data['ip_address'])) {
        $data['ip_address'] = wp_privacy_anonymize_ip($data['ip_address']);
    }
    
    // Add custom metadata
    $data['custom_field'] = 'custom_value';
    
    return $data;
});

`llmtag_analytics_query`

Filter analytics database queries.

add_filter('llmtag_analytics_query', function($query, $args) {
    // Add custom WHERE conditions
    if (isset($args['custom_filter'])) {
        $query .= " AND custom_field = '" . esc_sql($args['custom_filter']) . "'";
    }
    
    return $query;
}, 10, 2);

Custom Functions

Utility Functions

`llmtag_is_ai_agent()`

Check if a user agent is an AI agent.

function my_custom_ai_detection($user_agent) {
    if (llmtag_is_ai_agent($user_agent)) {
        // Handle AI agent
        return true;
    }
    
    return false;
}

`llmtag_get_policies()`

Get current LLMTAG policies.

function my_custom_policy_check($path) {
    $policies = llmtag_get_policies($path);
    
    if ($policies['ai_training_data'] === 'disallow') {
        // Handle training data restriction
        return false;
    }
    
    return true;
}

`llmtag_log_activity()`

Log custom activity to LLMTAG analytics.

function my_custom_activity_log($action, $data) {
    llmtag_log_activity([
        'action' => $action,
        'data' => $data,
        'timestamp' => current_time('mysql'),
        'user_id' => get_current_user_id()
    ]);
}

Integration Examples

Custom Post Type Integration

// Add LLMTAG support to custom post types
add_action('init', function() {
    add_post_type_support('my_custom_post_type', 'llmtag');
});

// Custom policies for post types
add_filter('llmtag_post_type_policies', function($policies, $post_type) {
    if ($post_type === 'my_custom_post_type') {
        $policies['ai_training_data'] = 'disallow';
        $policies['ai_use'] = ['search_indexing'];
    }
    
    return $policies;
}, 10, 2);

WooCommerce Integration

// Different policies for product pages
add_filter('llmtag_path_policies', function($policies, $path) {
    if (is_shop() || is_product()) {
        $policies['ai_training_data'] = 'allow'; // Allow for product discovery
        $policies['ai_use'] = ['search_indexing', 'generative_synthesis'];
    }
    
    return $policies;
}, 10, 2);

// Block AI agents from checkout pages
add_filter('llmtag_agent_blocking_decision', function($should_block, $agent, $ip, $path) {
    if (is_checkout() || is_cart()) {
        return true; // Block all AI agents from checkout
    }
    
    return $should_block;
}, 10, 3);

Membership Plugin Integration

// Different policies for members vs. non-members
add_filter('llmtag_global_policies', function($policies) {
    if (function_exists('pmpro_hasMembershipLevel')) {
        if (pmpro_hasMembershipLevel()) {
            // Members get more permissive policies
            $policies['ai_training_data'] = 'allow';
            $policies['ai_use'] = ['search_indexing', 'generative_synthesis', 'research'];
        } else {
            // Non-members get restrictive policies
            $policies['ai_training_data'] = 'disallow';
            $policies['ai_use'] = ['search_indexing'];
        }
    }
    
    return $policies;
});

Advanced Customization

Custom Admin Pages

// Add custom admin page
add_action('admin_menu', function() {
    add_submenu_page(
        'llmtag',
        'Custom Settings',
        'Custom Settings',
        'manage_options',
        'llmtag-custom',
        'llmtag_custom_admin_page'
    );
});

function llmtag_custom_admin_page() {
    // Custom admin page content
    echo '<div class="wrap">';
    echo '<h1>Custom LLMTAG Settings</h1>';
    echo '<p>Your custom settings page content here.</p>';
    echo '</div>';
}

Custom API Endpoints

// Add custom REST API endpoint
add_action('rest_api_init', function() {
    register_rest_route('llmtag/v1', '/custom-endpoint', [
        'methods' => 'GET',
        'callback' => 'llmtag_custom_endpoint_callback',
        'permission_callback' => function() {
            return current_user_can('manage_options');
        }
    ]);
});

function llmtag_custom_endpoint_callback($request) {
    return [
        'status' => 'success',
        'data' => [
            'custom_field' => 'custom_value',
            'timestamp' => current_time('mysql')
        ]
    ];
}

Custom Database Tables

// Create custom database table
add_action('llmtag_init', function() {
    global $wpdb;
    
    $table_name = $wpdb->prefix . 'llmtag_custom_data';
    
    $charset_collate = $wpdb->get_charset_collate();
    
    $sql = "CREATE TABLE $table_name (
        id mediumint(9) NOT NULL AUTO_INCREMENT,
        custom_field varchar(255) NOT NULL,
        created_at datetime DEFAULT CURRENT_TIMESTAMP,
        PRIMARY KEY (id)
    ) $charset_collate;";
    
    require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
    dbDelta($sql);
});

Best Practices

Hook Usage

Use Appropriate Hooks

Choose the right hook for your use case to avoid conflicts.

Set Proper Priorities

Use appropriate priority values to control execution order.

Clean Up Hooks

Remove hooks when plugins are deactivated to prevent conflicts.

Document Customizations

Document all custom hooks and filters for future reference.

Performance Considerations

Follow these tips to optimize hook performance:

Minimize hook usage to reduce overhead
Use efficient callbacks to avoid performance bottlenecks
Cache expensive operations in hook callbacks
Monitor hook performance and optimize as needed

Security Best Practices

Always follow security best practices when using hooks:

Validate all inputs in hook callbacks
Sanitize data before processing
Use proper capabilities for permission checks
Escape output to prevent XSS attacks

Troubleshooting

Common Issues

Hooks not firing

Possible causes:

Hook not properly registered
Priority conflicts
Plugin conflicts

Solutions:

Check hook registration
Adjust hook priorities
Test with other plugins deactivated

Unexpected behavior

Possible causes:

Hook callback errors
Filter return value issues
Logic errors in callbacks

Solutions:

Debug hook callbacks
Check return values
Review callback logic

Performance issues

Possible causes:

Too many hooks
Inefficient callbacks
Heavy operations in hooks

Solutions:

Optimize hook usage
Improve callback efficiency
Move heavy operations to background

​Hooks and Filters Overview

Developer Extensibility

​Action Hooks

​Core Plugin Actions

​llmtag_init

​llmtag_settings_saved

​llmtag_agent_blocked

​llmtag_llmtag_txt_generated

​Analytics Actions

​llmtag_analytics_updated

​llmtag_daily_report_generated

​Filter Hooks

​Content Generation Filters

​llmtag_txt_content

​llmtag_global_policies

​llmtag_path_policies

​Agent Blocking Filters

​llmtag_blocked_agents

​llmtag_agent_blocking_decision

​llmtag_user_agent_detection

​Analytics Filters

​llmtag_analytics_data

​llmtag_analytics_query

​Custom Functions

​Utility Functions

​llmtag_is_ai_agent()

​llmtag_get_policies()

​llmtag_log_activity()

​Integration Examples

​Custom Post Type Integration

​WooCommerce Integration

​Membership Plugin Integration

​Advanced Customization

​Custom Admin Pages

​Custom API Endpoints

​Custom Database Tables

​Best Practices

​Hook Usage

Use Appropriate Hooks

Set Proper Priorities

Clean Up Hooks

Document Customizations

​Performance Considerations

​Security Best Practices

​Troubleshooting

​Common Issues

Hooks and Filters Overview

Action Hooks

Core Plugin Actions

`llmtag_init`

`llmtag_settings_saved`

`llmtag_agent_blocked`

`llmtag_llmtag_txt_generated`

Analytics Actions

`llmtag_analytics_updated`

`llmtag_daily_report_generated`

Filter Hooks

Content Generation Filters

`llmtag_txt_content`

`llmtag_global_policies`

`llmtag_path_policies`

Agent Blocking Filters

`llmtag_blocked_agents`

`llmtag_agent_blocking_decision`

`llmtag_user_agent_detection`

Analytics Filters

`llmtag_analytics_data`

`llmtag_analytics_query`

Custom Functions

Utility Functions

`llmtag_is_ai_agent()`

`llmtag_get_policies()`

`llmtag_log_activity()`

Integration Examples

Custom Post Type Integration

WooCommerce Integration

Membership Plugin Integration

Advanced Customization

Custom Admin Pages

Custom API Endpoints

Custom Database Tables

Best Practices

Hook Usage

Performance Considerations

Security Best Practices

Troubleshooting

Common Issues