文檔說明

Xunsearch SDK for PHP

$Id$

這是采用 PHP 語言編寫的 xunsearch 開發包,在此基礎上開發您自己的全文檢索。

在此簡要介紹以下幾個文件:

- lib/XS.php             入口文件,所有搜索功能必須包含此文件
- lib/XS.class.php       未合并帶注釋的入口文件,會自動加載其它 .class.php 文件
- util/RequireCheck.php  命令行運行,用于檢測您的 PHP 環境是否符合運行條件
- util/IniWizzaard.php   命令行運行,用于幫助您編寫 xunsearch 項目配置文件
- util/Quest.php         命令行運行,搜索測試工具
- util/Indexer.php       命令行運行,索引管理工具
- util/SearchSkel.php    命令行運行,根據配置文件生成搜索骨架代碼
- util/xs                命令行工具統一入口

在開始編寫您的代碼前強烈建議執行 util/RequireCheck.php 以檢查環境。

具體各項文檔內容請參閱子目錄: doc/ 強烈推薦在線閱讀我們的文檔:http://www.482075.live/doc/

最簡單使用方法就是下載全部源碼壓縮包,然后引入入口文件即可。 出現異常則拋出 \XSException 異常實例。

Composer 支持

自 v1.4.9 起,通過 subtree 功能將 xs-sdk-php 分離成為一個只讀的子倉庫, 以支持通過 composer 安裝。我們的包名稱為 hightman/xunsearch,內含全部 PHP-SDK 的庫文件,還包括支持 Yii 的擴展類。

安裝

和絕大多數 composer 一樣,你可以通過以下兩種方法中的任意一種安裝。

可以直接運行

composer require --prefer-dist hightman/xunsearch "*@beta"

或者將以下內容添加到您的項目根目錄 composer.json 中的 require 章節, 然后運行 composer install

"hightman/xunsearch": "*@beta"

Tip: 如果您打算用代碼倉庫中的最新版本,請將星號改為 dev-master。

命令行工具

vendor/bin/xs help

普通用法

這和 xunsearch 指南中的用法完全一致,只不過引入開始文件的方法略有不同。 官方用法指南詳見 http://www.482075.live/doc/php

// 加載 vendor 的 autoload 文件
require_once 'vendor/autoload.php';
 
// 默認的 xunsearch 應用配置文件目錄為 vendor/hightman/xunsearch/app
// 如有必要,請通過常量 XS_APP_ROOT 定義
define ('XS_APP_ROOT', '/path/to/ini')
 
// 創建 XS 對象,關于項目配置文件請參見官網
$xs = new \XS('demo');
 
// 后面的代碼就和官網上的指南一致了

Yii-1.x 用法

這是對 xunsearch 的一個簡單封裝,使之更適合 yii-1.x 的用法習慣。首先, 在應用入口文件最開頭引入 composer 的 autoload 文件,通常是 index.php。

require_once 'vendor/autoload.php';
// 如有必要請定義常量 XS_APP_ROOT 表示項目文件存放路徑
//define ('XS_APP_ROOT', dirname(__FILE__) . '/protected/data');

在應用配置文件的 compnents 中添加以下代碼,通常是 protected/config/main.php

// application components
    'components' => array(
        // ... other components ... 
        'search' => array(
            'class' => 'EXunSearch',
            'project' => 'demo', // 搜索項目名稱或對應的 ini 文件路徑
            'charset' => 'utf-8', // 您當前使用的字符集(索引、搜索結果)
        ),  
    ),

然后就可以通過 Yii::app()->search 來訪問 EXunSearch 對象,進行索引管理或檢索。

添加、修改索引數據,使用方法參照 XSIndex。 對于 ActiveRecord 對象來講,建議在相關的 afterSaveafterDelete 中進行索引同步。

$data = array('pid' => 1234, 'subject' => '標題', 'message' => '內容');
Yii::app()->search->add($data); // 添加文檔
Yii::app()->search->update($data);  // 更新文檔
Yii::app()->search->del('1234');    // 刪除文檔

使用檢索功能時,可以將 Yii::app()->search 當作 XSSearch 對象一樣直接使用它的全部方法。

Yii::app()->search->setQuery('subject:標題');
$docs = Yii::app()->search->setLimit(5, 10)->search();  // 取得搜索結果文檔集

Yii-2.x 用法

在 yii2 中,除了提供類似 yii-1.x 的調用方式外,我們還支持 ActiveRecord 方式來操作。首先, 請在應用配置文件的 components 中添加以下代碼,通常是 config/web.php

// application components
    'components => [
        // ... other components ...
        'xunsearch' => [
            'class' => 'hightman\xunsearch\Connection', // 此行必須
            'iniDirectory' => '@app/config',    // 搜索 ini 文件目錄,默認:@vendor/hightman/xunsearch/app
            'charset' => 'utf-8',   // 指定項目使用的默認編碼,默認即時 utf-8,可不指定
        ],
    ],

接下來,你可以通過以下代碼獲取到 hightman\xunsearch\Database 對象,該對像和 yii-1.x 的 EXunSearch 用法很相似,通過魔術方法,能夠依次檢索以下對象的方法列表而直接調用:

$db = \Yii::$app->xunsearch->getDatabase('demo');
$db = (\Yii::$app->xunsearch)('demo');
$xs = $db->xs;
$search = $db->getSearch();
$index = $db->getIndex();
  • XS 優先調用該對象方法,如有必要,可直接通過 hightman\xunsearch\Database::$xs 屬性訪問。
  • XSIndex 緊接著檢查索引管理方法,如有必要,可直接通過 hightman\xunsearch\Database::$index 屬性訪問。
  • XSSearch 緊接著檢查索引管理方法,如有必要,可直接通過 hightman\xunsearch\Database::$search 屬性訪問。

具體用法不再贅述,下面重點講講如何通過 ActiveRecord 方法來檢索和創建索引,由于遵循 yii2 的思想進行開發設計, 使用起來非常方便和簡單。

創建 AR 對象

首先必須創建一個繼承自 hightman\xunsearch\ActiveRecord 的模型類,默認情況下會以全小寫的類名字作為 ini 文件名。如需指定,請自行覆蓋編寫 hightman\xunsearch\ActiveRecord::projectName()。通常代碼如下:

class Demo extends \hightman\xunsearch\ActiveRecord
{
    /*public static function projectName() {
        return 'another_name';  // 這將使用 @app/config/another_name.ini 作為項目名
    }*/
}

由此可見,如果命名規范模型類幾乎不需要任何額外代碼,上述代碼會自動采用 demo.ini 并自動裝載字段配置。

添加或更新索引

為避免數據重復,底層統一通過 XSIndex::update() 方法進行提交的。

// 添加索引,也可以通過 $model->setAttributes([...]) 批量賦值
$model = new Demo;
$model->pid = 321;
$model->subject = 'hello world';
$model->message = 'just for testing...';
$model->save();
 
// 更新索引
$model = Demo::findOne(321);
$model->message .= ' + updated';
$model->save();
 
 
// 添加或更新索引還支持以方法添加索引詞或文本
// 這樣做的目的是使得可以通過這些關鍵詞檢索到數據,但并非數據的字段值
// 用法與 XSDocument::addTerm() 和 XSDocument::addIndex() 等同
// 通常在 ActiveRecord::beforeSave() 中做這些操作
$model->addTerm('subject', 'hi');
$model->addIndex('subject', '你好,世界');
 
// 如需刪除數據則可直接
$model->delete();

如需要做批量刪除或更新,請參見以下代碼文檔:ActiveRecord::updateAll()ActiveRecord::deleteAll()。

檢索對象

重點先介紹一下 ActiveQuery::where() 系列搜索條件函數的用法,和 yii2 其它的 ActiveRecord 類似:

$query = Demo::find(); // 返回 ActiveQuery 對象
$condition = 'hello world'; // 字符串原樣保持,可包含 subject:xxx 這種形式
$condition = ['WILD', 'key1', 'key2' ... ]; // 通過空格將多個查詢條件連接
$condition = ['AND', 'key1', 'key2' ... ]; // 通過 AND 連接,轉換為:key1 AND key2
$condition = ['OR', 'key1', 'key2' ... ]; // 通過 OR 連接
$condition = ['XOR', 'key1', 'key2' ... ]; // 通過  XOR 連接
$condition = ['NOT', 'key']; // 排除匹配 key 的結果
$condition = ['pid' => '123', 'subject' => 'hello']; // 轉換為:pid:123 subject:hello
$condition = ['pid' => ['123', '456']]; // 相當于 IN,轉換為:pid:123 OR pid:456
$condition = ['IN', 'pid', ['123', '456']]; // 轉換結果同上
$condition = ['NOT IN', 'pid', ['123', '456']]; // 轉換為:NOT (pid:123 OR pid:456)
$condition = ['BETWEEN', 'chrono', 14918161631, 15918161631]; // 相當于 XSSearch::addRange(...)
$condition = ['WEIGHT', 'subject', 'hello', 0.5]; // 相當于額外調用 XSSearch::addWeight('subject', 'hello', 0.5);
$query->where($condition);

對于 hightman\xunsearch\ActiveQuery 對象,主要支持以下幾個方法獲取和操作:

  • asArray(): 以數組形式返回數據
  • one(): 返回一行數據
  • all(): 返回全部數據
  • count(): 統計數據匹配數據,是估算的并不是完全準確
  • exists(): 判斷查詢條件是否存在數據
  • where(): 指定搜索條件
  • orderBy(): 指定排序方式,默認為相關性排序
  • limit(), offfset(): 指定獲取數據量和偏移,用于分頁檢索
  • with(), indexBy ...
  • buildOther(function(\XSSearch $search){}) 可通過此方法定制檢索選項

此外,ActiveQuery 還提供了一個名為 beforeSearch 的事件,可在執行搜索前再次對 ActiveQuery::getSearch() 所返回的 XSSearch 對象進行調整。

如果以 AR 對象獲得數據,可通過以下幾個方法獲取搜索結果元數據,參照 XSDocument 相關用法。

$model = Demo::findOne(321);
$model->docid(); //Xapian數據 ID
$model->rank(); //序號
$model->percent(); //匹配百分比
$model->ccount(); //折疊數量,須在 XSSearch::setCollapse() 指定后才有效
$model->matched(); //獲得匹配詞匯

ActiveRecord 對象實現了絕大多數據接口,完全可以像使用普通數據庫模型一樣使用它。如果需要 訪問原始的 xunsearch 對象,請通過以下方式獲取 Database 對象:

$db = Demo::getDb();
$search = $db->getSearch();
$index = $db->getIndex();
// 如有必要,還可以獲得 scws 分詞對象
$scws = $db->getScws();

使用 xunsearch DebugPanel

為便于調試,還提供了一個 hightman\xunsearch\DebugPanel 對象,可以集成到 debug 模塊中, 可在調試工具條和面板中顯示 xunsearch 有關的查詢以及耗時情況。

要想啟用這個很容易,只要在主配置文件中加入以下代碼:

// ...
    'bootstrap' => ['debug'],
    'modules' => [
        'debug' => [
            'class' => 'yii\\debug\\Module',
            'panels' => [
                'xunsearch' => [
                    'class' => 'hightman\\xunsearch\\DebugPanel',
                ],
            ],
        ],
    ],
    // ...

其它用法

TBD. 如關聯等,參見其它 AR 用法即可。

Note: 相關的 AR 索引操作均非實時的,如需實時更新索引,請通過 Database::getIndex()->flushIndex() 刷新。 關于查詢日志有關的功能,也建議通過原生的 XSSearchXSIndex 對象來操作。

2條評論!

#94 報告
johnzhang361 at 2016-11-01 22:23:13
666很適合入門

配置好就能用,很適合入門

#75 報告
sjedufei at 2016-05-23 10:38:46
666

66666

請到論壇 登錄 后刷新本頁面!

青海快三开奖走势图_ 通配资 吉林快3计划 十一选五开奖结果浙 上海天天彩选4第320期开奖号码 p62连线走势图 2007上证指数 11选5近期中奖号码河南 河北十一选五走势图 江苏快三app免费下载最新版 股票配资推荐ˉ杨方配资靠谱