Xunsearch PHP-SDK v1.4.9 权威指南

# 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\n";
    }

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

## 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);

$Id$
« XSException 异常
XSIndex 索引管理 »
Copyright © 2008-2011 by 杭州云圣网络科技有限公司
All Rights Reserved.