Search Exclude provides a powerful set of hooks and filters that allow developers to extend and customize the plugin’s behavior. Whether you need to programmatically exclude content, create custom rules, or integrate with other systems, this guide has you covered.

Table of Contents

• Available Actions
• Available Filters
• Code Examples
• Helper Functions
• Advanced Use Cases
• Best Practices

Available Actions

searchexclude_hide_from_search

Programmatically hide or show posts, pages, or custom post types from search results.

Parameters

Parameter	Type	Description
$post_ids	Array of post IDs to hide or show
$hide	boolean	true to hide from search, false to show in search

Basic Usage

// Hide posts with IDs 10, 20, and 30 from search
do_action('searchexclude_hide_from_search', array(10, 20, 30), true);

// Show post with ID 15 in search results
do_action('searchexclude_hide_from_search', array(15), false);

🔧 Available Filters

searchexclude_filter_search

Dynamically control whether search filtering should be applied based on custom conditions.

Parameters

Parameter	Type	Description
$exclude	Current search filtering state
$query	WP_Query	Current WordPress query object

Return Value

Return true to enable search filtering, or false to disable it.

Basic Usage

searchexclude_filter_permissions

Control who can exclude content from search results based on user capabilities.

Parameters

Parameter	Type	Description
$capability	string	Required capability (default: ‘edit_post’)

Basic Usage

add_filter('searchexclude_filter_permissions', 'my_custom_permissions');
  
function my_custom_permissions($capability) {
      // Only allow administrators
      return 'manage_options';
}

Code Examples

Example 1: Auto-Exclude New Posts by Default

Automatically check the “Exclude from Search Results” checkbox for all newly created posts (but not pages).

add_filter('default_content', 'exclude_new_posts_by_default', 10, 2);
  
function exclude_new_posts_by_default($content, $post) {
     if ('post' === $post->post_type) {
         do_action('searchexclude_hide_from_search', array($post->ID), true);
     }
     return $content;
}

Example 2: Disable Filtering for Specific Post Types

Never apply search exclusion to WooCommerce products, even if they’re marked as excluded.

add_filter('searchexclude_filter_search', 'disable_filter_for_products', 10, 2);
  
function disable_filter_for_products($exclude, $query) {
      // Don't filter if searching for products
      if ('product' === $query->get('post_type')) {
          return false;
      }
      return $exclude;
}

Example 3: Exclude Posts from Specific Categories

Automatically exclude all posts from the “Private” category from search results.

add_action('save_post', 'exclude_private_category_posts');
  
function exclude_private_category_posts($post_id) {
   // Avoid infinite loops and check post type
   if (wp_is_post_revision($post_id) || get_post_type($post_id) !== 'post') {
          return;
   }

   // Check if post is in "Private" category (ID: 5)
   if (has_category(5, $post_id)) {
          do_action('searchexclude_hide_from_search', array($post_id), true);
   } else {
          // Show in search if removed from Private category
       do_action('searchexclude_hide_from_search', array($post_id), false);
      }
}

Example 4: Disable Exclusion for Logged-In Administrators

Show all content in search results when an administrator is logged in, regardless of exclusion settings.

add_filter('searchexclude_filter_search', 'show_all_for_admins', 10, 2);

function show_all_for_admins($exclude, $query) {
      // Don't apply exclusions for administrators
      if (current_user_can('manage_options')) {
          return false;
      }
      return $exclude;
}

Example 5: Exclude Old Posts Automatically

Automatically hide posts older than 2 years from search results.

add_action('init', 'exclude_old_posts_from_search');

function exclude_old_posts_from_search() {
      // Run once daily
      if (!wp_next_scheduled('exclude_old_posts_cron')) {
          wp_schedule_event(time(), 'daily', 'exclude_old_posts_cron');
      }
}

add_action('exclude_old_posts_cron', 'process_old_posts_exclusion');
  
function process_old_posts_exclusion() {
      $two_years_ago = date('Y-m-d', strtotime('-2 years'));

      $old_posts = get_posts(array(
          'post_type' => 'post',
          'posts_per_page' => -1,
          'date_query' => array(
              array(
                  'before' => $two_years_ago,
              ),
          ),
          'fields' => 'ids',
      ));

      if (!empty($old_posts)) {
          do_action('searchexclude_hide_from_search', $old_posts, true);
      }
}

Example 6: Exclude Posts with Specific Custom Field

Hide posts that have a custom field hide_from_search set to true.

add_action('save_post', 'check_custom_field_exclusion', 20);
  function check_custom_field_exclusion($post_id) {
      // Avoid autosaves and revisions
      if (wp_is_post_revision($post_id) || wp_is_post_autosave($post_id)) {
          return;
      }

      $hide_from_search = get_post_meta($post_id, 'hide_from_search', true);

      if ($hide_from_search === 'true' || $hide_from_search === '1') {
          do_action('searchexclude_hide_from_search', array($post_id), true);
      } else {
          do_action('searchexclude_hide_from_search', array($post_id), false);
      }
  }

🛠️ Helper Functions

Get All Excluded Post IDs

Retrieve an array of all post IDs that are currently excluded from search.

$excluded_ids = get_option('sep_exclude', array());

// Example: Check if specific post is excluded
$post_id = 123;
if (in_array($post_id, $excluded_ids)) {
     echo 'This post is excluded from search';
}

Check if Post is Excluded

Create a helper function to check if a specific post is excluded from search.

function is_post_excluded_from_search($post_id) {
      $excluded_ids = get_option('sep_exclude', array());
      return in_array($post_id, $excluded_ids);
}

// Usage
if (is_post_excluded_from_search(123)) {
      // Do something
}

Advanced Use Cases

Integration with Custom Search Forms

If you’re using a custom search form or plugin, you can manually apply exclusions:

function custom_search_query($args) {
      if (isset($args['s']) && !empty($args['s'])) {
          // Get excluded post IDs
          $excluded_ids = get_option('sep_exclude', array());

          // Add to query args
          if (!empty($excluded_ids)) {
              $args['post__not_in'] = $excluded_ids;
          }
      }
      return $args;
}
add_filter('my_custom_search_args', 'custom_search_query');

REST API Integration

Expose exclusion status in WordPress REST API responses:

add_action('rest_api_init', 'register_search_exclude_field');
  function register_search_exclude_field() {
      register_rest_field('post', 'excluded_from_search', array(
          'get_callback' => function($post) {
              $excluded_ids = get_option('sep_exclude', array());
              return in_array($post['id'], $excluded_ids);
          },
          'schema' => array(
              'description' => 'Whether post is excluded from search',
              'type' => 'boolean',
          ),
      ));
  }

Multisite Support

Manage search exclusions across multiple sites in a network:

function exclude_from_all_sites($post_ids, $hide = true) {
      if (!is_multisite()) {
          do_action('searchexclude_hide_from_search', $post_ids, $hide);
          return;
      }

      $sites = get_sites();
      foreach ($sites as $site) {
          switch_to_blog($site->blog_id);
          do_action('searchexclude_hide_from_search', $post_ids, $hide);
          restore_current_blog();
      }
}

// Usage
exclude_from_all_sites(array(10, 20, 30), true);

Best Practices

1. Always Check for Autosaves and Revisions

When hooking into save_post, always verify you’re not processing autosaves or revisions:

if (wp_is_post_revision($post_id) || wp_is_post_autosave($post_id)) {
      return;
}

2. Use Priority When Adding Filters

Set appropriate priority to ensure your filters run at the right time:

// Run after other plugins (higher priority)
add_filter('searchexclude_filter_search', 'my_function', 20, 2);

// Run before other plugins (lower priority)
add_filter('searchexclude_filter_search', 'my_function', 5, 2);

3. Cache Excluded IDs for Performance

If you’re checking exclusions frequently, cache the results:

function get_excluded_ids_cached() {
      $cache_key = 'search_exclude_ids';
      $excluded_ids = wp_cache_get($cache_key);

      if (false === $excluded_ids) {
          $excluded_ids = get_option('sep_exclude', array());
          wp_cache_set($cache_key, $excluded_ids, '', 3600); // 1 hour
      }

      return $excluded_ids;
}