PHP 搜尋類封裝實作：基於 Xunsearch 的索引與查詢範例

PHP 搜尋類封裝實作：基於 Xunsearch 的索引與查詢範例

本文展示一個封裝良好的 PHP 搜尋類 SoClass，底層採用 Xunsearch 全文搜尋引擎，提供索引建立、關鍵字查詢、熱門搜尋、同義詞擴展等完整功能，適合快速整合至專案中。

核心類結構

<?php
/** 
 * SoClass.php - 索引與搜尋類封裝
 * 依賴：lib/XS.php (Xunsearch SDK)
 */
class SoClass {
    private $_xindex;   // 索引物件
    private $_xsearch;  // 搜尋物件
    private $_project;  // 專案名稱

    public function __construct($project) {
        require_once 'lib/XS.php';
        $xs = new XS($project);
        $this->_project = $project;
        $this->_xindex = $xs->index;
        $this->_xsearch = $xs->search;
        $this->_xsearch->setCharset('UTF-8');
    }

    /**
     * 關鍵字模糊搜尋，支援同義詞與分頁
     * @param string $keyWord  搜尋關鍵字
     * @param int    $row      每頁筆數 (預設 20)
     * @param int    $jnum     跳過筆數 (預設 0)
     * @return array ['data'=>[...], 'count'=>總數] 或空陣列
     */
    public function query($keyWord, $row = 20, $jnum = 0) {
        $xs = new XS($this->_project);
        $xs->search->setFuzzy();           // 模糊匹配
        $xs->search->setAutoSynonyms();    // 自動同義詞
        $xs->search->setQuery($keyWord);
        $xs->search->setLimit($row, $jnum); // 分頁
        
        $docs  = $xs->search->search();
        $count = $xs->search->count();
        
        if ($count) {
            $data = [];
            foreach ($docs as $key => $doc) {
                $data[$key] = [
                    'pid'      => $doc->pid,
                    'nid'      => $doc->nid,
                    'category' => $doc->category,
                    'url'      => $doc->url,
                    'name'     => $xs->search->highlight(htmlspecialchars($doc->name)),
                    'message'  => $xs->search->highlight(htmlspecialchars($doc->message)),
                ];
            }
            return ['data' => $data, 'count' => $count];
        }
        return [];
    }

    /** 取得熱門搜尋詞 */
    public function hotWord($num, $type = 'lastnum') {
        return $this->_xsearch->getHotQuery($num, $type);
    }

    /** 取得擴展查詢建議 (同義詞/相關詞) */
    public function expanded($keyWord) {
        return $this->_xsearch->getExpandedQuery($keyWord);
    }

    /** 取得上次搜尋總筆數 */
    public function lastCount() {
        return $this->_xsearch->getLastCount();
    }

    /** 索引文檔：新增或更新 */
    public function index($data, $update = 0) {
        $doc = new XSDocument;
        $doc->setFields($data);
        if (!$update) {
            $this->_xindex->add($doc);
        } else {
            $this->_xindex->update($doc);
        }
    }

    /** 刪除索引 (主鍵陣列) */
    public function delete($idArray) {
        $this->_xindex->del($idArray);
    }

    /** 新增同義詞 */
    public function addSynonym($word1, $word2) {
        $this->_xindex->addSynonym($word1, $word2);
    }

    /** 清空所有索引 */
    public function clearIndex() {
        $this->_xindex->clean();
    }
}
?>

使用情境與擴充建議

• 站內搜尋：文章、商品、使用者資料的全文檢索
• 自動完成：搭配 expanded() 做搜尋建議下拉
• 熱門關鍵字：hotWord() 產出熱搜排行榜
• 同義詞維護：addSynonym() 讓「手機」=「行動電話」同義搜尋

實際部署時，建議將 Xunsearch 服務獨立部署，配合 xs-ctl.sh 管理索引重建、備份與監控；PHP 端可做連線池或單例模式複用 XS 物件，降低建構開銷。