Download the PHP package itdocs/xunsearch without Composer

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.xunsearch.com/doc/

最简单使用方法就是下载全部源码压缩包，然后引入入口文件即可。 出现异常则抛出 \XSException 异常实例。

Composer 支持

自 v1.4.9 起，通过 subtree 功能将 xs-sdk-php 分离成为一个只读的子仓库， 以支持通过 composer 安装。我们的包名称为 itdocs/xunsearch，内含全部 PHP-SDK 的库文件，还包括支持 Yii 的扩展类。

安装

和绝大多数 composer 一样，你可以通过以下两种方法中的任意一种安装。

可以直接运行

或者将以下内容添加到您的项目根目录 composer.json 中的 require 章节， 然后运行 composer install

tip: 如果您打算用代码仓库中的最新版本，请将星号改为 dev-master。

命令行工具

普通用法

这和 xunsearch 指南中的用法完全一致，只不过引入开始文件的方法略有不同。 官方用法指南详见 http://www.xunsearch.com/doc/php

Yii-1.x 用法

这是对 xunsearch 的一个简单封装，使之更适合 yii-1.x 的用法习惯。首先， 在应用入口文件最开头引入 composer 的 autoload 文件，通常是 index.php。

在应用配置文件的 compnents 中添加以下代码，通常是 protected/config/main.php

然后就可以通过 Yii::app()->search 来访问 EXunSearch 对象，进行索引管理或检索。

添加、修改索引数据，使用方法参照 XSIndex。 对于 ActiveRecord 对象来讲，建议在相关的 afterSave 和 afterDelete 中进行索引同步。

使用检索功能时，可以将 Yii::app()->search 当作 XSSearch 对象一样直接使用它的全部方法。

Yii-2.x 用法

在 yii2 中，除了提供类似 yii-1.x 的调用方式外，我们还支持 ActiveRecord 方式来操作。首先， 请在应用配置文件的 components 中添加以下代码，通常是 config/web.php

接下来，你可以通过以下代码获取到 itdocs\xunsearch\Database 对象，该对像和 yii-1.x 的 EXunSearch 用法很相似，通过魔术方法，能够依次检索以下对象的方法列表而直接调用：

• XS 优先调用该对象方法，如有必要，可直接通过 itdocs\xunsearch\Database::$xs 属性访问。
• XSIndex 紧接着检查索引管理方法，如有必要，可直接通过 itdocs\xunsearch\Database::$index 属性访问。
• XSSearch 紧接着检查索引管理方法，如有必要，可直接通过 itdocs\xunsearch\Database::$search 属性访问。

具体用法不再赘述，下面重点讲讲如何通过 ActiveRecord 方法来检索和创建索引，由于遵循 yii2 的思想进行开发设计， 使用起来非常方便和简单。

创建 AR 对象

首先必须创建一个继承自 itdocs\xunsearch\ActiveRecord 的模型类，默认情况下会以全小写的类名字作为 ini 文件名。如需指定，请自行覆盖编写 itdocs\xunsearch\ActiveRecord::projectName()。通常代码如下：

由此可见，如果命名规范模型类几乎不需要任何额外代码，上述代码会自动采用 demo.ini 并自动装载字段配置。

添加或更新索引

为避免数据重复，底层统一通过 XSIndex::update() 方法进行提交的。

如需要做批量删除或更新，请参见以下代码文档：ActiveRecord::updateAll() 和 ActiveRecord::deleteAll()。

检索对象

重点先介绍一下 ActiveQuery::where() 系列搜索条件函数的用法，和 yii2 其它的 ActiveRecord 类似：

对于 itdocs\xunsearch\ActiveQuery 对象，主要支持以下几个方法获取和操作：

• asArray(): 以数组形式返回数据
• one(): 返回一行数据
• all(): 返回全部数据
• count(): 统计数据匹配数据，是估算的并不是完全准确
• exists(): 判断查询条件是否存在数据
• where(): 指定搜索条件
• orderBy(): 指定排序方式，默认为相关性排序
• limit(), offfset(): 指定获取数据量和偏移，用于分页检索
• with(), indexBy ...
• buildOther(function(\XSSearch $search){}) 可通过此方法定制检索选项

此外，ActiveQuery 还提供了一个名为 beforeSearch 的事件，可在执行搜索前再次对 ActiveQuery::getSearch() 所返回的 XSSearch 对象进行调整。

如果以 AR 对象获得数据，可通过以下几个方法获取搜索结果元数据，参照 XSDocument 相关用法。

ActiveRecord 对象实现了绝大多数据接口，完全可以像使用普通数据库模型一样使用它。如果需要 访问原始的 xunsearch 对象，请通过以下方式获取 Database 对象：

使用 xunsearch DebugPanel

为便于调试，还提供了一个 itdocs\xunsearch\DebugPanel 对象，可以集成到 debug 模块中， 可在调试工具条和面板中显示 xunsearch 有关的查询以及耗时情况。

要想启用这个很容易，只要在主配置文件中加入以下代码：

其它用法

TBD. 如关联等，参见其它 AR 用法即可。

note: 相关的 AR 索引操作均非实时的，如需实时更新索引，请通过 Database::getIndex()->flushIndex() 刷新。 关于查询日志有关的功能，也建议通过原生的 XSSearch 和 XSIndex 对象来操作。