Hướng dẫn sử dụng các filter trong Init Live Search

1. init_plugin_suite_live_search_enable_fallback

Cho phép bật hoặc tắt cơ chế fallback (gợi ý bằng cách cắt bớt hoặc tạo bigram) nếu kết quả tìm kiếm ban đầu quá ít.

• Tham số: (bool $enable, string $term, array $args)
• Mặc định: Bật fallback nếu số kết quả ban đầu nhỏ hơn một nửa max_results.

add_filter('init_plugin_suite_live_search_enable_fallback', function($enable, $term, $request) {
    // Vô hiệu hóa fallback nếu từ khóa chứa số
    return !preg_match('/\d/', $term);
}, 10, 3);

2. init_plugin_suite_live_search_post_ids

Cho phép thay đổi danh sách ID bài viết được truy vấn từ DB (sau khi tìm kiếm và fallback nếu có).

• Tham số: (array $post_ids, string $term, array $args)

add_filter('init_plugin_suite_live_search_post_ids', function($post_ids, $term, $args) {
    return array_filter($post_ids, function($post_id) {
        return !has_category(5, $post_id);
    });
}, 10, 3);

3. init_plugin_suite_live_search_result_item

Cho phép tùy biến từng phần tử kết quả trước khi trả về frontend.

• Tham số: (array $item, int $post_id, string $term, array $args)

add_filter('init_plugin_suite_live_search_result_item', function($item, $post_id, $term, $args) {
    $item['author'] = get_post_meta($post_id, 'author_name', true);
    return $item;
}, 10, 4);

4. init_plugin_suite_live_search_results

Tùy chỉnh mảng kết quả cuối cùng trước khi trả về qua REST API.

• Tham số: (array $results, array $post_ids, string $term, array $args)

add_filter('init_plugin_suite_live_search_results', function($results, $post_ids, $term, $args) {
    $results[] = [
        'title' => 'Tổng kết',
        'type'  => 'Thông báo',
        'url'   => '#',
        'thumb' => '',
        'date'  => '',
        'note'  => 'Có tổng cộng ' . count($post_ids) . ' kết quả.'
    ];
    return $results;
}, 10, 4);

5. init_plugin_suite_live_search_category

Tùy biến tên danh mục hiển thị trên kết quả tìm kiếm.

• Tham số: (string $category_name, int $post_id)

add_filter('init_plugin_suite_live_search_category', function($cat, $post_id) {
    return strtoupper($cat);
}, 10, 2);

6. init_plugin_suite_live_search_default_thumb

Thay đổi ảnh thumbnail mặc định nếu bài viết không có ảnh đại diện.

• Tham số: (string $thumb_url)

add_filter('init_plugin_suite_live_search_default_thumb', function($url) {
    return get_stylesheet_directory_uri() . '/img/default-thumb.jpg';
});

7. init_plugin_suite_live_search_query_args

Tùy chỉnh tham số WP_Query cho các command như /recent, /date, /tax, /product, /random.

• Tham số: (array $args, string $type, WP_REST_Request $request)

add_filter('init_plugin_suite_live_search_query_args', function($args, $type, $request) {
    if ($type === 'recent') {
        $args['meta_query'][] = [
            'key' => '_custom_flag',
            'value' => 'yes'
        ];
    }
    return $args;
}, 10, 3);

8. init_plugin_suite_live_search_taxonomy_cache_ttl

Tùy chỉnh thời gian lưu cache (tính bằng giây) của endpoint /taxonomies. Trả về 0 nếu muốn tắt cache hoàn toàn.

• Tham số: (int $ttl, string $taxonomy, int $limit)
• Mặc định: 300 giây (5 phút).

add_filter('init_plugin_suite_live_search_taxonomy_cache_ttl', function($ttl, $taxonomy, $limit) {
    // Tắt cache cho taxonomy 'post_tag'
    if ($taxonomy === 'post_tag') return 0;
    // Rút ngắn TTL cho các taxonomy khác nếu limit nhỏ
    if ($limit <= 5) return 60;
    return $ttl;
}, 10, 3);

9. init_plugin_suite_live_search_stop_single_words

Loại bỏ các từ đơn vô nghĩa trước khi phân tích tiêu đề và tạo bigram.

• Tham số: (array $stop_words, string $locale)

add_filter('init_plugin_suite_live_search_stop_single_words', function($words, $locale) {
    if (strpos($locale, 'vi') === 0) {
        $words[] = 'tèo';  // thêm từ cần loại bỏ
    }
    return $words;
}, 10, 2);

10. init_plugin_suite_live_search_stop_words

Loại bỏ các cụm từ 2 từ (bigrams) vô nghĩa khỏi danh sách từ khóa được tạo từ tiêu đề.

• Tham số: (array $stop_phrases, string $locale)

add_filter('init_plugin_suite_live_search_stop_words', function($phrases, $locale) {
    if ($locale === 'vi') {
        $phrases[] = 'đây là';
    }
    return $phrases;
}, 10, 2);

11. init_plugin_suite_live_search_filter_lang

Lọc lại danh sách post ID theo ngôn ngữ hiện tại, hỗ trợ WPML hoặc Polylang.

• Tham số: (array $post_ids, string $term, array $args)

// Polylang
add_filter('init_plugin_suite_live_search_filter_lang', function($post_ids, $term, $args) {
    if (!function_exists('pll_get_post_language')) return $post_ids;
    $lang = $args['lang'] ?? null;
    if (!$lang) return $post_ids;

    return array_filter($post_ids, fn($id) => pll_get_post_language($id) === $lang);
}, 10, 3);

// WPML
add_filter('init_plugin_suite_live_search_filter_lang', function($post_ids, $term, $args) {
    if (!function_exists('icl_object_id')) return $post_ids;
    $lang = $args['lang'] ?? null;
    if (!$lang || empty($post_ids)) return $post_ids;

    global $wpdb;
    $ids_in_lang = $wpdb->get_col($wpdb->prepare(
        "
        SELECT element_id FROM {$wpdb->prefix}icl_translations
        WHERE element_type LIKE 'post%%'
        AND language_code = %s
        AND element_id IN (" . implode(',', array_map('absint', $post_ids)) . ")
        ",
        $lang
    ));

    return array_map('absint', $ids_in_lang);
}, 10, 3);

12. init_plugin_suite_live_search_category_taxonomy

Tùy chỉnh taxonomy dùng để hiển thị tên danh mục trong kết quả tìm kiếm.

• Tham số: (string $taxonomy, int $post_id)
• Mặc định: category

add_filter('init_plugin_suite_live_search_category_taxonomy', function($taxonomy, $post_id) {
    if (get_post_type($post_id) === 'product') {
        return 'product_cat';
    }
    return $taxonomy;
}, 10, 2);

13. init_plugin_suite_live_search_seo_meta_keys

Tùy chỉnh danh sách các meta key dùng để tìm kiếm trong tiêu đề SEO và mô tả SEO.

• Tham số: (array $meta_keys)
• Mặc định: Bao gồm các meta key của Yoast, Rank Math, AIOSEO, TSF, SEOPress

add_filter('init_plugin_suite_live_search_seo_meta_keys', function($keys) {
    // Thêm meta key tùy chỉnh
    $keys[] = '_custom_seo_title';
    $keys[] = '_custom_seo_description';
    return $keys;
});

14. init_plugin_suite_live_search_weights

Tùy chỉnh trọng số của từng nguồn dữ liệu (tiêu đề, mô tả SEO, tag, v.v.) khi gộp và sắp xếp kết quả tìm kiếm.

• Tham số: (array $weights, string $search_mode)
• Mặc định: Tùy theo chế độ tìm kiếm:
  • title: [3, 2] (tiêu đề > SEO)
  • title_excerpt: [3, 2] (tiêu đề/mô tả > SEO)
  • title_tag: [3, 2, 1, 1] (tiêu đề > SEO > tag > tag từng từ)

add_filter('init_plugin_suite_live_search_weights', function($weights, $mode) {
    if ($mode === 'title_tag') {
        // Ưu tiên cực mạnh cho tiêu đề, giảm SEO và tag
        return [5, 2, 1, 1];
    }
    return $weights;
}, 10, 2);

15. init_plugin_suite_live_search_commands

Cho phép đăng ký thêm slash command tùy chỉnh, để hiển thị trong danh sách lệnh và xử lý bằng JavaScript hoặc REST API riêng.

• Tham số: (array $commands, array $options)

add_filter('init_plugin_suite_live_search_commands', function($commands) {
    $commands['vip'] = __('Show VIP-only posts', 'my-theme');
    $commands['my'] = __('Show my posts', 'my-theme');
    return $commands;
});

Các lệnh được thêm vào sẽ tự động hiển thị trong hộp gợi ý khi gõ /, nhưng không được xử lý bởi plugin gốc. Bạn cần tự lắng nghe sự kiện JavaScript (ils:search-started, ils:results-loaded) hoặc triển khai endpoint riêng nếu cần.

16. init_plugin_suite_live_search_synonym_map

Tuỳ chỉnh hoặc mở rộng danh sách từ đồng nghĩa được dùng để mở rộng kết quả tìm kiếm khi không có kết quả trực tiếp.

• Tham số: (array $synonym_map)
• Mặc định: Lấy từ phần cài đặt Synonyms trong admin — ví dụ: { "reaction": ["tương tác", "phản hồi"] }

add_filter('init_plugin_suite_live_search_synonym_map', function($map) {
    $map['speed'] = ['velocity', 'momentum'];
    $map['ai'] = ['trí tuệ nhân tạo', 'máy học'];
    return $map;
});

17. init_plugin_suite_live_search_smart_post_thumbnail_alt

Tuỳ chỉnh văn bản alt được tạo tự động cho thumbnail nếu không có mô tả sẵn từ Media Library — đảm bảo SEO và accessibility tốt hơn.

• Tham số: (string $alt, int $post_id)
• Mặc định: Dùng mô tả từ Media Library nếu có, nếu không thì tạo từ tiêu đề bài viết.

add_filter('init_plugin_suite_live_search_smart_post_thumbnail_alt', function($alt, $post_id) {
    return 'Ảnh minh hoạ cho bài viết #' . $post_id;
}, 10, 2);

18. init_plugin_suite_live_search_auto_insert_enabled

Filter cho phép bật/tắt tự động chèn shortcode bài viết liên quan vào nội dung bài viết hoặc khu vực bình luận – dựa trên vị trí và loại bài viết hiện tại.

• Tham số: (bool $enabled, string $position, string $post_type)
• Mặc định: true nếu tất cả điều kiện đều phù hợp (bài viết đơn, đúng post type, đúng vị trí cấu hình)

add_filter('init_plugin_suite_live_search_auto_insert_enabled', function($enabled, $position, $post_type) {
    // Vô hiệu hoá tự động chèn đối với các bài viết thuộc post type "page"
    return $post_type === 'page' ? false : $enabled;
}, 10, 3);

19. init_plugin_suite_live_search_default_related_shortcode

Filter để tuỳ biến shortcode được chèn tự động khi bật tính năng auto-insert related posts (sau nội dung, trước/sau bình luận).

• Tham số: (string $shortcode)
• Mặc định: [init_live_search_related_posts count="10"]

add_filter('init_plugin_suite_live_search_default_related_shortcode', function($shortcode) {
    return '[init_live_search_related_posts count="5" template="grid"]';
});

20. init_plugin_suite_live_search_ai_candidates

Tuỳ chỉnh hoặc thay thế danh sách bài viết ứng viên cho hệ thống AI Related Posts.

• Tham số: (array $candidates, int $post_id, string $post_type)
• Mặc định: Lấy từ nhiều nguồn (bài viết mới, cùng series, cùng same_keyword nếu có).

add_filter('init_plugin_suite_live_search_ai_candidates', function($candidates, $post_id, $post_type) {
    // Thêm các bài viết nổi bật (sticky) vào pool ứng viên
    $sticky = get_option('sticky_posts');
    return array_unique(array_merge($candidates, $sticky));
}, 10, 3);

21. init_plugin_suite_live_search_ai_signals

Bổ sung hoặc ghi đè các tín hiệu (signals) dùng trong tính điểm AI (tag, series, same_keyword, v.v.).

• Tham số: (array $signals, int $post_id, int $candidate_id)

add_filter('init_plugin_suite_live_search_ai_signals', function($signals, $post_id, $candidate_id) {
    // Tăng điểm nếu 2 bài cùng tác giả
    if (get_post_field('post_author', $post_id) === get_post_field('post_author', $candidate_id)) {
        $signals['author'] = 1;
    }
    return $signals;
}, 10, 3);

22. init_plugin_suite_live_search_ai_weights

Điều chỉnh trọng số mặc định của từng tín hiệu trong AI ranking.

• Tham số: (array $weights)
• Mặc định: tag=0.25, series=0.20, title_bigrams=0.20, same_keyword=0.15, category=0.08, views=0.07, comment=0.05, freshness=0.05

add_filter('init_plugin_suite_live_search_ai_weights', function($weights) {
    // Tăng sức nặng cho "same_keyword"
    $weights['same_keyword'] = 0.25;
    return $weights;
});

23. init_plugin_suite_live_search_ai_score

Tuỳ chỉnh điểm cuối cùng của mỗi ứng viên sau khi tính toán signals và weights.

• Tham số: (float $score, int $post_id, int $candidate_id, array $signals)

add_filter('init_plugin_suite_live_search_ai_score', function($score, $post_id, $candidate_id, $signals) {
    // Boost nhẹ nếu ứng viên có trên 1000 views
    $views = (int) get_post_meta($candidate_id, '_init_view_count', true);
    if ($views > 1000) $score *= 1.1;
    return $score;
}, 10, 4);

24. init_plugin_suite_live_search_ai_half_life_recency

Tuỳ chỉnh half-life (đơn vị: ngày) cho tín hiệu recency – mức độ “mới” so với thời điểm hiện tại.

• Tham số: (int $days)
• Mặc định: 60 ngày.

add_filter('init_plugin_suite_live_search_ai_half_life_recency', function($days) {
    // Blog kỹ thuật: nội dung “nguội” nhanh hơn
    return 45;
});

25. init_plugin_suite_live_search_ai_half_life_gap

Tuỳ chỉnh half-life (đơn vị: ngày) cho tín hiệu time_gap – độ gần về mốc thời gian với bài gốc.

• Tham số: (int $days)
• Mặc định: 90 ngày.

add_filter('init_plugin_suite_live_search_ai_half_life_gap', function($days) {
    // Giảm tầm quan trọng của khớp mốc thời gian
    return 75;
});

26. init_plugin_suite_live_search_ai_mmr_lambda

Điều chỉnh hệ số λ trong thuật toán MMR (Max Marginal Relevance) – cân bằng giữa liên quan và đa dạng.

• Tham số: (float $lambda)
• Mặc định: 0.75 (càng gần 1.0 ⇒ ưu tiên liên quan, càng gần 0.0 ⇒ ưu tiên đa dạng).

add_filter('init_plugin_suite_live_search_ai_mmr_lambda', function($lambda) {
    // Tăng đa dạng hơn một chút
    return 0.68;
});

27. init_plugin_suite_live_search_ai_selected

Can thiệp danh sách ID cuối cùng sau khi diversify bằng MMR (thêm/bớt/sắp xếp lại).

• Tham số: (array $selected_ids, array $scored_candidates, int $post_id)

add_filter('init_plugin_suite_live_search_ai_selected', function($selected, $scored, $post_id) {
    // Đưa bài có điểm cao nhất (nếu chưa ở đầu) lên vị trí đầu tiên
    if (!empty($scored)) {
        arsort($scored);
        $top = array_key_first($scored);
        $selected = array_values(array_unique(array_merge([$top], $selected)));
    }
    return $selected;
}, 10, 3);

28. init_plugin_suite_live_search_ai_cache_ttl

Tùy chỉnh thời gian cache (tính bằng giây) cho AI-powered related posts. Trả về 0 để tắt cache.

• Tham số: (int $ttl, int $post_id, string $post_type, int $limit)

add_filter('init_plugin_suite_live_search_ai_cache_ttl', function($ttl, $post_id, $post_type, $limit) {
    // Ví dụ: cache riêng cho product là 12 giờ, còn lại giữ mặc định
    if ($post_type === 'product') {
        return 12 * HOUR_IN_SECONDS;
    }
    return $ttl;
}, 10, 4);

29. init_plugin_suite_live_search_post_types

Cho phép theme hoặc plugin tuỳ chỉnh danh sách post_type được dùng để tìm kiếm.
Hữu ích khi bạn muốn mở rộng hoặc ép luôn một custom post type cụ thể vào kết quả tìm kiếm mà không ảnh hưởng tới cấu hình plugin.

• Tham số: (array $post_types, array $options, array $args)
• Mặc định: Dựa theo cài đặt plugin hoặc fallback ['post'].

add_filter('init_plugin_suite_live_search_post_types', function($types, $options, $args) {
    // Đảm bảo luôn có post type "manga"
    $types[] = 'manga';
    return array_values(array_unique($types));
}, 10, 3);

Tổng kết

Hệ thống filter mạnh mẽ giúp Init Live Search dễ dàng mở rộng và tích hợp sâu vào theme hoặc plugin tùy chỉnh. Từ việc thay đổi kết quả đến tối ưu UX/UI, bạn hoàn toàn làm chủ plugin mà không cần đụng vào core code.