[Xunsearch PHP-SDK](http://www.xunsearch.com) v1.4.8 API 参考文档
# XSDocument
[All Packages](#)| [方法(函数)](#)
| 包 | [XS](#) |
|-----|-----|
| 继承关系 | class XSDocument |
| 实现接口 | ArrayAccess, IteratorAggregate, Traversable |
| 版本 | 1.0.0 |
| 源代码 | [sdk/php/lib/XSDocument.class.php](https://github.com/hightman/xunsearch/blob/master/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()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>__call</b>(string $name, array $args)</div></td></tr><tr><td class="paramNameCol">$name</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">方法名称</td></tr><tr><td class="paramNameCol">$args</td> <td class="paramTypeCol">array</td> <td class="paramDescCol">调用时的参数列表 (此处无用)</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L108](https://github.com/hightman/xunsearch/blob/master/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()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>__construct</b>(mixed $p=NULL, string $d=NULL)</div></td></tr><tr><td class="paramNameCol">$p</td> <td class="paramTypeCol">mixed</td> <td class="paramDescCol">字符串表示索引文档的编码或搜索结果文档的 meta 数据, 数组则表示或索引文档的初始字段数据</td></tr><tr><td class="paramNameCol">$d</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">可选参数, 当 $p 不为编码时, 本参数表示数据编码</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L56](https://github.com/hightman/xunsearch/blob/master/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()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public mixed <b>__get</b>(string $name)</div></td></tr><tr><td class="paramNameCol">$name</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">字段名称</td></tr><tr><td class="paramNameCol">{return}</td> <td class="paramTypeCol">mixed</td> <td class="paramDescCol">字段值, 若不存在返回 null</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L79](https://github.com/hightman/xunsearch/blob/master/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()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>__set</b>(string $name, mixed $value)</div></td></tr><tr><td class="paramNameCol">$name</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">字段名称</td></tr><tr><td class="paramNameCol">$value</td> <td class="paramTypeCol">mixed</td> <td class="paramDescCol">字段值</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L93](https://github.com/hightman/xunsearch/blob/master/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()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>addIndex</b>(string $field, string $text)</div></td></tr><tr><td class="paramNameCol">$field</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">文本所属的字段名称</td></tr><tr><td class="paramNameCol">$text</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">文本内容</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L256](https://github.com/hightman/xunsearch/blob/master/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()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>addTerm</b>(string $field, string $term, int $weight=1)</div></td></tr><tr><td class="paramNameCol">$field</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">词条所属字段名称</td></tr><tr><td class="paramNameCol">$term</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">词条内容, 不超过 255字节</td></tr><tr><td class="paramNameCol">$weight</td> <td class="paramTypeCol">int</td> <td class="paramDescCol">词重, 默认为 1</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L236](https://github.com/hightman/xunsearch/blob/master/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()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>afterSubmit</b>(<a href="XSIndex.html">XSIndex</a> $index)</div></td></tr><tr><td class="paramNameCol">$index</td> <td class="paramTypeCol"><a href="XSIndex.html">XSIndex</a></td> <td class="paramDescCol">索引操作对象</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L344](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSDocument.class.php#L344) (**[显示](#)**)
`public function afterSubmit($index)
{
}`
重写接口, 在文档成功提交到索引服务器后调用继承此类进行重写该方法时, 强烈建议要调用 parent::afterSave($index) 以确保完整.
beforeSubmit()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public bool <b>beforeSubmit</b>(<a href="XSIndex.html">XSIndex</a> $index)</div></td></tr><tr><td class="paramNameCol">$index</td> <td class="paramTypeCol"><a href="XSIndex.html">XSIndex</a></td> <td class="paramDescCol">索引操作对象</td></tr><tr><td class="paramNameCol">{return}</td> <td class="paramTypeCol">bool</td> <td class="paramDescCol">默认返回 true, 若返回 false 将阻止该文档提交到索引服务器</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L331](https://github.com/hightman/xunsearch/blob/master/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()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public mixed <b>f</b>(string $name)</div></td></tr><tr><td class="paramNameCol">$name</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">字段名称</td></tr><tr><td class="paramNameCol">{return}</td> <td class="paramTypeCol">mixed</td> <td class="paramDescCol">字段值, 若不存在则返回 null</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L192](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSDocument.class.php#L192) (**[显示](#)**)
`public function f($name)
{
return $this->__get(strval($name));
}`
获取文档字段的值
getAddIndex()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public string <b>getAddIndex</b>(string $field)</div></td></tr><tr><td class="paramNameCol">$field</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">字段名称</td></tr><tr><td class="paramNameCol">{return}</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">文本内容, 若无则返回 null</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L221](https://github.com/hightman/xunsearch/blob/master/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()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public array <b>getAddTerms</b>(string $field)</div></td></tr><tr><td class="paramNameCol">$field</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">字段名称</td></tr><tr><td class="paramNameCol">{return}</td> <td class="paramTypeCol">array</td> <td class="paramDescCol">索引词列表(词为键, 词重为值), 若无则返回 null</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L202](https://github.com/hightman/xunsearch/blob/master/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()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public string <b>getCharset</b>()</div></td></tr><tr><td class="paramNameCol">{return}</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">当前设定的字符集(已大写), 若未曾设置则返回 null</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L123](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSDocument.class.php#L123) (**[显示](#)**)
`public function getCharset()
{
return $this->_charset;
}`
获取文档字符集
getFields()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public array <b>getFields</b>()</div></td></tr><tr><td class="paramNameCol">{return}</td> <td class="paramTypeCol">array</td> <td class="paramDescCol">返回已设置的字段键值数组</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L144](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSDocument.class.php#L144) (**[显示](#)**)
`public function getFields()
{
return $this->_data;
}`
获取字段值
getIterator()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>getIterator</b>()</div></td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L272](https://github.com/hightman/xunsearch/blob/master/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()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public bool <b>offsetExists</b>(string $name)</div></td></tr><tr><td class="paramNameCol">$name</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">字段名称</td></tr><tr><td class="paramNameCol">{return}</td> <td class="paramTypeCol">bool</td> <td class="paramDescCol">存在返回 true, 若不存在返回 false</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L287](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSDocument.class.php#L287) (**[显示](#)**)
`public function offsetExists($name)
{
return isset($this->_data[$name]);
}`
ArrayAccess 接口, 判断字段是否存在, 勿直接调用
offsetGet()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public mixed <b>offsetGet</b>(string $name)</div></td></tr><tr><td class="paramNameCol">$name</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">字段名称</td></tr><tr><td class="paramNameCol">{return}</td> <td class="paramTypeCol">mixed</td> <td class="paramDescCol">字段值, 若不存在返回 null</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L298](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSDocument.class.php#L298) (**[显示](#)**)
`public function offsetGet($name)
{
return $this->__get($name);
}`
ArrayAccess 接口, 取得字段值, 勿直接调用
#### 参见
- [__get](#)
offsetSet()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>offsetSet</b>(string $name, mixed $value)</div></td></tr><tr><td class="paramNameCol">$name</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">字段名称</td></tr><tr><td class="paramNameCol">$value</td> <td class="paramTypeCol">mixed</td> <td class="paramDescCol">字段值</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L309](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSDocument.class.php#L309) (**[显示](#)**)
`public function offsetSet($name, $value)
{
if (!is_null($name)) {
$this->__set(strval($name), $value);
}
}`
ArrayAccess 接口, 设置字段值, 勿直接调用
#### 参见
- [__set](#)
offsetUnset()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>offsetUnset</b>(string $name)</div></td></tr><tr><td class="paramNameCol">$name</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">字段名称</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L320](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSDocument.class.php#L320) (**[显示](#)**)
`public function offsetUnset($name)
{
unset($this->_data[$name]);
}`
ArrayAccess 接口, 删除字段值, 勿直接调用
setCharset()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>setCharset</b>(string $charset)</div></td></tr><tr><td class="paramNameCol">$charset</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">设置文档字符集</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L132](https://github.com/hightman/xunsearch/blob/master/sdk/php/lib/XSDocument.class.php#L132) (**[显示](#)**)
`public function setCharset($charset)
{
$this->_charset = strtoupper($charset);
if ($this->_charset == 'UTF8') {
$this->_charset = 'UTF-8';
}
}`
设置文档字符集
setField()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>setField</b>(string $name, mixed $value, bool $isMeta=false)</div></td></tr><tr><td class="paramNameCol">$name</td> <td class="paramTypeCol">string</td> <td class="paramDescCol">字段名称</td></tr><tr><td class="paramNameCol">$value</td> <td class="paramTypeCol">mixed</td> <td class="paramDescCol">字段值</td></tr><tr><td class="paramNameCol">$isMeta</td> <td class="paramTypeCol">bool</td> <td class="paramDescCol">是否为元数据字段</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L170](https://github.com/hightman/xunsearch/blob/master/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()方法
<table class="summaryTable"><tr><td colspan="3"><div class="signature2">public void <b>setFields</b>(array $data)</div></td></tr><tr><td class="paramNameCol">$data</td> <td class="paramTypeCol">array</td> <td class="paramDescCol">字段名及其值组成的数组</td></tr></table>
**源码:**[sdk/php/lib/XSDocument.class.php#L154](https://github.com/hightman/xunsearch/blob/master/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 [杭州云圣网络科技有限公司](http://www.xunsearch.com)
All Rights Reserved.
- 权威指南
- 新手上路
- 最新主要变动
- 概述
- 关于 Xunsearch PHP-SDK
- 安装、升级
- 体验 demo 项目
- 开发规范
- 开发流程
- 了解基础对象
- 基础对象概述
- XS 项目
- XSException 异常
- XSDocument 文档
- XSIndex 索引管理
- XSSearch 搜索
- XSTokenizer 分词接口
- 编写项目配置文件
- 项目配置详解
- 自定义分词器
- 编写第一个配置文件
- 管理索引
- 索引概述
- 添加文档
- 更新、修改文档
- 删除文档
- 清空索引
- 平滑重建索引
- 使用索引缓冲区
- 自定义SCWS词库
- 使用搜索
- 搜索概述
- 构建搜索语句
- 获取搜索匹配结果
- 获取搜索匹配数量
- 获取热门搜索词
- 获取相关搜索词
- 搜索建议和纠错
- 按字段值分面搜索
- 使用辅助工具
- RequiredCheck 运行检测
- Indexer 索引管理器
- Quest 搜索测试工具
- SearchSkel 生成搜索代码
- IniWizzard 配置文件向导
- Logger 搜索日志管理
- 专题
- 同义词搜索功能
- 在SDK中使用SCWS分词
- API 指南
- XS
- XS
- XSCommand
- XSComponent
- XSDocument
- XSErrorException
- XSException
- XSFieldMeta
- XSFieldScheme
- XSIndex
- XSSearch
- XSServer
- XS.tokenizer
- XSTokenizer
- XSTokenizerFull
- XSTokenizerNone
- XSTokenizerScws
- XSTokenizerSplit
- XSTokenizerXlen
- XSTokenizerXstep
- XS.util
- XSCsvDataSource
- XSDataFilter
- XSDatabaseDataSource
- XSDebugFilter
- XSJsonDataSource
- XSUtil
- XS.util.db
- XSDatabase
- XSDatabaseMySQL
- XSDatabaseMySQLI
- XSDatabasePDO
- XSDatabasePDO_MySQL
- XSDatabasePDO_PgSQL
- XSDatabasePDO_SQLite
- XSDatabasePgSQL
- XSDatabaseSQLite
- XSDatabaseSQLite3
- XS.utilf
- XSDataSource
- 其它文档
- 关于 xunsearch
- 特色和优势
- Xunsearch 架构简图
- 下载 Xunsearch
- 商业服务与支持
- XunSearch 授权许可证