基础对象概述

Xunsearch PHP-SDK 全面采用面向对象（OOP）的开发方式。本章节将简单介绍开发过程中要接触到的几个重要对象（类）。

XS 搜索项目的总对象，所有操作均基于此对象或其属性。

XSException 所有操作中出现的异常、错误均抛出此类型的异常，搜索代码中应该尝试捕捉该异常以确定操作是否成功。

XSDocument 文档用于描述检索/索引的基础对象，包含一组字段及其值，相当于常规SQL数据表中的一行记录。

XSIndex 提供索引添加/删除/修改功能，通常以 XS 对象的属性方式出现，参见 XS::index。

XSSearch 提供各种搜索功能，通常以 XS 对象的属性方式出现，参见 XS::search。

XSTokenizer 自定义字段词法分析器接口。

类对象中的魔术属性

通过PHP对象中的__get和__set技巧，我们针对所有 XSComponent 的子类实现了对象的模拟属性。这类读取或写入属性值时实际上是隐含调用了相应的 getter/setter 方法，这类属性不区分大小写。

支持这类属性的对象主要包括以下几个（不全，仅挑重要的列出）：

XS::index 项目索引对象：$xs->index

XS::search 项目搜索对象：$xs->search

XS::defaultCharset 项目默认字符集：$xs->defaultCharset

XSSearch::dbTotal 搜索数据库内的数据总量：$xs->search->dbTotal

XSSearch::lastCount 最近一次搜索的结果匹配总数估算值：$xs->search->lastCount

XSSearch::query 搜索语句：$xs->search->query

---

XS 项目

XS 是搜索项目的总对象，所有操作均基于此对象或其属性，在此我们只挑最常用的一些属性、方法进行介绍。

1.创建 XS 对象

创建 XS 对象的唯一参数是项目配置文件的可访问路径，或者项目名，也可以是项目配置文件的内容。如果给出的参数是项目名则自动使用 $prefix/sdk/php/app/项目名.ini，例子代码如下：

2.重要属性

XS::defaultCharset 项目默认字符集 影响范围包括使用时的输入数据以及搜索结果的输出数据，该属性默认由配置文件中的 project.default_charset 指定，如有必要可以自行修改，但要确保在使用索引、搜索对象之前。

XS::index 索引管理对象 类型为 XSIndex，比如用下面代码可以清空项目索引内容：

$xs->index->clean();

XS::search 搜索对象 类型为 XSSearch，比如用下面代码可以快速检索包含 hightman 的结果

$docs = $xs->search->search('hightman');

print_r($docs);

---

XSException 异常

所有操作中出现的异常、错误均抛出此类型的异常，搜索代码中应该尝试捕捉该异常以确定操作是否成功。

已通过重载魔术方法 XSException::__toString 对出错信息作了简要的美化和修饰，您可以直接输出该对象，如需要查看堆栈追踪，通过继承来的 XSException::getTraceAsString 即可。

一段典型的处理代码应类似下面的方式：

require '/home/admin/xunsearch/sdk/php/lib/XS.php';
try{
  $xs = new XS('demo');
  $docs = $xs->search->setQuery('hightman')->setLimit(5)->search();
  foreach($docs as $doc){
    echo $doc->rank().' '.$doc->subject.' ['.$doc->percent().'%]'.PHP_EOL;
    echo $doc->message.PHP_EOL;
  }
}catch(XSException $e){
  echo $e; //直接输出异常描述
  if(defined('DEBUG')){
    echo PHP_EOL.$e->getTraceAsString().PHP_EOL; //如果是DEBUG模式，则输出堆栈情况
  }
}

---

XSDocument 文档

XSDocument 是用于描述检索/索引的基础对象，包含一组字段及其值。相当于常规SQL数据表中的一行记录。通过魔术方法，每个字段名都是文档的虚拟属性，可直接赋值或取值，也支持数组下标方式访问文档字段。

$doc=new XSDocument;
$doc->name='value'; //用对象属性方式进行赋值、取值
$doc['name']='value'; //用数组下标方式进行赋值、取值
$value=$doc->f('name'); //用函数方式进行取值
$doc->setField('name','value'); //用函数方式进行赋值
$doc->setFields(array('name'=>'value','name2'=>'value2')); //用数组进行批量赋值
//迭代方式取所有字段值
foreach($doc as $name=>$value){
  echo "$name: $value".PHP_EOL;  
}

用于索引更新的文档对象和搜索结果返回中略有不同，下面分开讲解。

1.搜索结果文档

搜索结果文档是指 XSSearch::search 返回值包含的文档，它由PHP-SDK内部代码创建。除了普通文档的功能外，还支持以下魔术方法来访问搜索结果的元数据：

docid() 取得搜索结果文档的 docid 值 (实际数据库内的 id，一般用不到)

rank() 取得搜索结果文档的序号值 (第X条结果)

percent() 取得搜索结果文档的匹配百分比 (结果匹配度，1~100)

weight() 取得搜索结果文档的权重值 (浮点数)

ccount() 取得搜索结果折叠的数量 (按字段折叠搜索时才有效)

访问结果文档的字符集默认是与 XSSearch::setCharset 所指定的字符集一致的，如未指定过则为 XS::defaultCharset。虽然您可以通过 XSDocument::setCharset 来强制修改文档的字符集，但不推荐这样做，也没必要这样做。

2.索引文档

索引文档是指由用户创建，并用于提交更新到索引库中的文档，创建文档时允许传入字符集作为构造函数的参数，如未传入，则自动视为项目的默认字符集 XS::defaultCharset，如果字符集不是UTF-8的系统内部会自动进行转换，但要求PHP带有中文转码扩展（iconv或mbstring）

$doc= new XSDocument; //使用默认字符集
$doc= new XSDocument('gbk'); //指定文档为GBK编码
$doc= new XSDocument($data); //数组$data为初始字段数据，编码则为默认编码
$doc= new XSDocument($data,'gbk'); //数组$data为字段数据，编码为GBK

//然后进行一系列赋值操作
//提交到索引中
$xs->index->add($doc);

如果您希望在 XSDocument 提交到索引前、后进行一系列必要的操作，您可以对 XSDocument 进行扩展，重写 XSDocument::beforeSubmit 和 XSDocument::afterSubmit 方法来实现，比如扩展代码为 $prefix/sdk/php/lib/MyDocument.class.php。

class MyDocument extends XSDocument
{
  public function beforeSubmit(XSIndex $index)
  {
    //在此编写您的代码，如需要中断添加请提前返回 false
    //......
    return parent::beforeSubmit($index);
  }
  public function afterSubmit(XSIndex $index)
  {
    //在此编写您的代码，只有加入索引成功后才会执行
    //......
  }
}
$doc= new MyDocument('gbk');
$doc->pid=123;
$doc->subject='Hello 测试';
$doc->message='测试的内容在此';
$xs->index->add($doc);

---

XSIndex 索引管理

通过 XSIndex 对象实现索引数据库的增、删、改等相关操作。实现使用过程中并不需要自行创建该对象，而是直接访问 XS::index 即可。

require '$prefix/sdk/php/lib/XS.php';
$xs = new XS('demo');
$index = $xs->index; //索引对象来自XS的属性