> ## Documentation Index
> Fetch the complete documentation index at: https://docs.llmtag.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks and Filters

> Extend LLMTAG plugin functionality with WordPress hooks and filters

## 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.

<Card title="Developer Extensibility" icon="code" horizontal>
  **Action Hooks** • **Filter Hooks** • **Custom Functions** • **Plugin Integration**
</Card>

## Action Hooks

### Core Plugin Actions

#### `llmtag_init`

Fired when the plugin is initialized.

```php theme={null}
add_action('llmtag_init', function() {
    // Plugin initialization code
    error_log('LLMTAG plugin initialized');
});
```

#### `llmtag_settings_saved`

Fired when plugin settings are saved.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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

```php theme={null}
// 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

```php theme={null}
// 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

```php theme={null}
// 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

```php theme={null}
// 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

```php theme={null}
// 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

```php theme={null}
// 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

<Columns cols={2}>
  <Card title="Use Appropriate Hooks" icon="link">
    Choose the right hook for your use case to avoid conflicts.
  </Card>

  <Card title="Set Proper Priorities" icon="sort">
    Use appropriate priority values to control execution order.
  </Card>

  <Card title="Clean Up Hooks" icon="broom">
    Remove hooks when plugins are deactivated to prevent conflicts.
  </Card>

  <Card title="Document Customizations" icon="file-text">
    Document all custom hooks and filters for future reference.
  </Card>
</Columns>

### Performance Considerations

<Note>
  Follow these tips to optimize hook performance:
</Note>

* **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

<Warning>
  Always follow security best practices when using hooks:
</Warning>

* **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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>