XSDocument 文档

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