Xunsearch PHP-SDK v1.4.9 API 参考文档

# XSDocument

包 | XS
继承关系 | class XSDocument
实现接口 | ArrayAccess, IteratorAggregate, Traversable
版本 | 1.0.0
源代码 | sdk/php/lib/XSDocument.class.php

文档用于描述检索/索引的基础对象, 包含一组字段及其值, 相当于常规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";
    }

如果有特殊需求, 可以自行扩展本类, 重写 beforeSubmit() 及 afterSubmit() 方法以定义在索引 提交前后的行为

## Public 方法

隐去继承来的方法

名称 | 描述 | 定义于
--- | --- | ---
__call() | 魔术方法 __call | XSDocument
__construct() | 构造函数 | XSDocument
__get() | 魔术方法 __get | XSDocument
__set() | 魔术方法 __set | XSDocument
addIndex() | 给字段增加索引文本 (仅限索引文档) | XSDocument
addTerm() | 给字段增加索引词 (仅限索引文档) | XSDocument
afterSubmit() | 重写接口, 在文档成功提交到索引服务器后调用 | XSDocument
beforeSubmit() | 重写接口, 在文档提交到索引服务器前调用 | XSDocument
f() | 获取文档字段的值 | XSDocument
getAddIndex() | 获取字段的附加索引文本 (仅限索引文档) | XSDocument
getAddTerms() | 获取字段的附加索引词列表 (仅限索引文档) | XSDocument
getCharset() | 获取文档字符集 | XSDocument
getFields() | 获取字段值 | XSDocument
getIterator() | IteratorAggregate 接口, 以支持 foreach 遍历访问字段列表 | XSDocument
offsetExists() | ArrayAccess 接口, 判断字段是否存在, 勿直接调用 | XSDocument
offsetGet() | ArrayAccess 接口, 取得字段值, 勿直接调用 | XSDocument
offsetSet() | ArrayAccess 接口, 设置字段值, 勿直接调用 | XSDocument
offsetUnset() | ArrayAccess 接口, 删除字段值, 勿直接调用 | XSDocument
setCharset() | 设置文档字符集 | XSDocument
setField() | 设置某个字段的值 | XSDocument
setFields() | 批量设置字段值 | XSDocument

## 方法明细

__call() 方法

public void __call(string $name, array $args)
$name | string | 方法名称
$args | array | 调用时的参数列表 (此处无用)

源码: sdk/php/lib/XSDocument.class.php#L108 (显示)
`public function __call($name, $args)
{
if ($this->_meta !== null) {
$name = strtolower($name);
if (isset($this->_meta[$name])) {
return $this->_meta[$name];
}
}
throw new XSException('Call to undefined method `' . get_class($this) . '::' . $name . '()\'');
}`

魔术方法 __call 实现以函数调用访问搜索结果元数据, 支持: docid, rank, percent, weight, ccount

__construct() 方法

public void __construct(mixed $p=NULL, string $d=NULL)
$p | mixed | 字符串表示索引文档的编码或搜索结果文档的 meta 数据, 数组则表示或索引文档的初始字段数据
$d | string | 可选参数, 当 $p 不为编码时, 本参数表示数据编码

源码: sdk/php/lib/XSDocument.class.php#L56 (显示)
`public function __construct($p = null, $d = null)
{
$this->_data = array();
if (is_array($p)) {
$this->_data = $p;
} elseif (is_string($p)) {
if (strlen($p) !== self::$_resSize) {
$this->setCharset($p);
return;
}
$this->_meta = unpack(self::$_resFormat, $p);
}
if ($d !== null && is_string($d)) {
$this->setCharset($d);
}
}`

构造函数

__get() 方法

public mixed __get(string $name)
$name | string | 字段名称
{return} | mixed | 字段值, 若不存在返回 null

源码: sdk/php/lib/XSDocument.class.php#L79 (显示)
`public function __get($name)
{
if (!isset($this->_data[$name])) {
return null;
}
return $this->autoConvert($this->_data[$name]);
}`

魔术方法 __get 实现以对象属性方式获取文档字段值

__set() 方法

public void __set(string $name, mixed $value)
$name | string | 字段名称
$value | mixed | 字段值

源码: sdk/php/lib/XSDocument.class.php#L93 (显示)
`public function __set($name, $value)
{
if ($this->_meta !== null) {
throw new XSException('Magick property of result document is read-only');
}
$this->setField($name, $value);
}`

魔术方法 __set 实现以对象属性方式设置文档字段值

addIndex() 方法

public void addIndex(string $field, string $text)
$field | string | 文本所属的字段名称
$text | string | 文本内容

源码: sdk/php/lib/XSDocument.class.php#L256 (显示)
`public function addIndex($field, $text)
{
$field = strval($field);
if (!is_array($this->_texts)) {
$this->_texts = array();
}
if (!isset($this->_texts[$field])) {
$this->_texts[$field] = strval($text);
} else {
$this->_texts[$field] .= "\n" . strval($text);
}
}`

给字段增加索引文本 (仅限索引文档)

addTerm() 方法

public void addTerm(string $field, string $term, int $weight=1)
$field | string | 词条所属字段名称
$term | string | 词条内容, 不超过 255字节
$weight | int | 词重, 默认为 1

源码: sdk/php/lib/XSDocument.class.php#L236 (显示)
`public function addTerm($field, $term, $weight = 1)
{
$field = strval($field);
if (!is_array($this->_terms)) {
$this->_terms = array();
}
if (!isset($this->_terms[$field])) {
$this->_terms[$field] = array($term => $weight);
} elseif (!isset($this->_terms[$field][$term])) {
$this->_terms[$field][$term] = $weight;
} else {
$this->_terms[$field][$term] += $weight;
}
}`

给字段增加索引词 (仅限索引文档)

afterSubmit() 方法

public void afterSubmit(XSIndex $index)
$index | XSIndex | 索引操作对象

源码: sdk/php/lib/XSDocument.class.php#L344 (显示)
`public function afterSubmit($index)
{
}`

重写接口, 在文档成功提交到索引服务器后调用 继承此类进行重写该方法时, 强烈建议要调用 parent::afterSave($index) 以确保完整.

beforeSubmit() 方法

public bool beforeSubmit(XSIndex $index)
$index | XSIndex | 索引操作对象
{return} | bool | 默认返回 true, 若返回 false 将阻止该文档提交到索引服务器

源码: sdk/php/lib/XSDocument.class.php#L331 (显示)
`public function beforeSubmit(XSIndex $index)
{
if ($this->_charset === null) {
$this->_charset = $index->xs->getDefaultCharset();
}
return true;
}`

重写接口, 在文档提交到索引服务器前调用 继承此类进行重写该方法时, 必须调用 parent::beforeSave($index) 以确保正确

f() 方法

public mixed f(string $name)
$name | string | 字段名称
{return} | mixed | 字段值, 若不存在则返回 null

源码: sdk/php/lib/XSDocument.class.php#L192 (显示)
`public function f($name)
{
return $this->__get(strval($name));
}`

获取文档字段的值

getAddIndex() 方法

public string getAddIndex(string $field)
$field | string | 字段名称
{return} | string | 文本内容, 若无则返回 null

源码: sdk/php/lib/XSDocument.class.php#L221 (显示)
`public function getAddIndex($field)
{
$field = strval($field);
if ($this->_texts === null || !isset($this->_texts[$field])) {
return null;
}
return $this->autoConvert($this->_texts[$field]);
}`

获取字段的附加索引文本 (仅限索引文档)

getAddTerms() 方法

public array getAddTerms(string $field)
$field | string | 字段名称
{return} | array | 索引词列表(词为键, 词重为值), 若无则返回 null

源码: sdk/php/lib/XSDocument.class.php#L202 (显示)
`public function getAddTerms($field)
{
$field = strval($field);
if ($this->_terms === null || !isset($this->_terms[$field])) {
return null;
}
$terms = array();
foreach ($this->_terms[$field] as $term => $weight) {
$term = $this->autoConvert($term);
$terms[$term] = $weight;
}
return $terms;
}`

获取字段的附加索引词列表 (仅限索引文档)

getCharset() 方法

public string getCharset()
{return} | string | 当前设定的字符集(已大写), 若未曾设置则返回 null

源码: sdk/php/lib/XSDocument.class.php#L123 (显示)
`public function getCharset()
{
return $this->_charset;
}`

获取文档字符集

getFields() 方法

public array getFields()
{return} | array | 返回已设置的字段键值数组

源码: sdk/php/lib/XSDocument.class.php#L144 (显示)
`public function getFields()
{
return $this->_data;
}`

获取字段值

getIterator() 方法

public void getIterator()

源码: sdk/php/lib/XSDocument.class.php#L272 (显示)
`public function getIterator()
{
if ($this->_charset !== null && $this->_charset !== 'UTF-8') {
$from = $this->_meta === null ? $this->_charset : 'UTF-8';
$to = $this->_meta === null ? 'UTF-8' : $this->_charset;
return new ArrayIterator(XS::convert($this->_data, $to, $from));
}
return new ArrayIterator($this->_data);
}`

IteratorAggregate 接口, 以支持 foreach 遍历访问字段列表

offsetExists() 方法

public bool offsetExists(string $name)
$name | string | 字段名称
{return} | bool | 存在返回 true, 若不存在返回 false

源码: sdk/php/lib/XSDocument.class.php#L287 (显示)
`public function offsetExists($name)
{
return isset($this->_data[$name]);
}`

ArrayAccess 接口, 判断字段是否存在, 勿直接调用

offsetGet() 方法

public mixed offsetGet(string $name)
$name | string | 字段名称
{return} | mixed | 字段值, 若不存在返回 null

源码: sdk/php/lib/XSDocument.class.php#L298 (显示)
`public function offsetGet($name)
{
return $this->__get($name);
}`

ArrayAccess 接口, 取得字段值, 勿直接调用

#### 参见

- __get

offsetSet() 方法

public void offsetSet(string $name, mixed $value)
$name | string | 字段名称
$value | mixed | 字段值

源码: sdk/php/lib/XSDocument.class.php#L309 (显示)
`public function offsetSet($name, $value)
{
if (!is_null($name)) {
$this->__set(strval($name), $value);
}
}`

ArrayAccess 接口, 设置字段值, 勿直接调用

#### 参见

- __set

offsetUnset() 方法

public void offsetUnset(string $name)
$name | string | 字段名称

源码: sdk/php/lib/XSDocument.class.php#L320 (显示)
`public function offsetUnset($name)
{
unset($this->_data[$name]);
}`

ArrayAccess 接口, 删除字段值, 勿直接调用

setCharset() 方法

public void setCharset(string $charset)
$charset | string | 设置文档字符集

源码: sdk/php/lib/XSDocument.class.php#L132 (显示)
`public function setCharset($charset)
{
$this->_charset = strtoupper($charset);
if ($this->_charset == 'UTF8') {
$this->_charset = 'UTF-8';
}
}`

设置文档字符集

setField() 方法

public void setField(string $name, mixed $value, bool $isMeta=false)
$name | string | 字段名称
$value | mixed | 字段值
$isMeta | bool | 是否为元数据字段

源码: sdk/php/lib/XSDocument.class.php#L170 (显示)
`public function setField($name, $value, $isMeta = false)
{
if ($value === null) {
if ($isMeta) {
unset($this->_meta[$name]);
} else {
unset($this->_data[$name]);
}
} else {
if ($isMeta) {
$this->_meta[$name] = $value;
} else {
$this->_data[$name] = $value;
}
}
}`

设置某个字段的值

setFields() 方法

public void setFields(array $data)
$data | array | 字段名及其值组成的数组

源码: sdk/php/lib/XSDocument.class.php#L154 (显示)
`public function setFields($data)
{
if ($data === null) {
$this->_data = array();
$this->_meta = $this->_terms = $this->_texts = null;
} else {
$this->_data = array_merge($this->_data, $data);
}
}`

批量设置字段值 这里是以合并方式赋值, 即不会清空已赋值并且不在参数中的字段.

Copyright © 2008-2011 by 杭州云圣网络科技有限公司
All Rights Reserved.