编辑“使用XOOPS应用程序接口”

__NOTOC__
<span style="text-align:center; border:1px solid #000; float:right; padding:6px;"><strong>导航:</strong> [[Xoops模块开发指南|上一页]] | {{Template:Xoops导航}}</span>
<div style="clear:both;"></div>

===基于XoopsObject 的数据存取类===
'''XOOPS ORM的使用指南'''

*通过继承XoopsObject创建模块类

:Object类

在/modules/foo/class/目录下创建文件myclass.php，并在该文件中创建一个由XoopsObject扩展得来的模块类，用于持有对应的数据。类的命名格式
<pre>
<Dirname>Myclass：

class FooMyclass extends XoopsObject
{
    /**
     * Constructor
     */
	function __construct()	// 构造函数
	{
		//初始化成员变量 (变量名，变量类型，初始值，是否必须，最大长度，选项数组)
		$this->initVar('my_variable', XOBJ_DTYPE_INT, NULL);
	}
}
</pre>

该类里声明的初始变量建议与对应的数据表字段一一对应。

:ObjectHandler类

在该文件中同时创建一个由XoopsObjectHandler扩展得到的数据处理类，命名格式<Module>MyclassHandler：
<pre>
class FooMyclassHandler extends XoopsObjectHandler
{ … }
</pre>

:PersistableObjectHandler类

XoopsObjectHandler是一个抽象类，由其继承得到的类需要创建自己的方法。同时[[XOOPS]] 2.3以后提供了XoopsPersistableObjectHandler类，提供了常用的数据处理方法。建议模块开发者通过继承该类创建自己的数据处理类：
<pre>
class FooMyclassHandler extends XoopsPersistableObjectHandler
{
    public function __construct (&$db)
{
	// 父类构造函数（数据库，数据表名，对应的object类名，主键名称，标识字段名）
	parent::__construct($db, $table, $className, $keyName, $identifierName);
}
}
</pre>

*XoopsObject类的实例化和应用

:创建当前模块数据类的句柄类实例
<pre>
In /modules/foo/index.php:
$myclassHandler =& xoops_getmodulehandler('MyClass');
</pre>

*调用其他模块数据对象

如果调用其他模块的数据，则需要在xoops_getmodulehandler中明确指定要调用的模块的目录名，比如要做foo模块中调用newbb模块的forum句柄：
<pre>
In /modules/foo/index.php:
$forumHandler =& xoops_getmodulehandler('forum', ‘newbb’);
</pre>

*调用系统数据对象

XOOPS系统内部的数据对象句柄可以通过xoops_gethandler('<class>')获得。例如创建模块数据对象实例：
<pre>
$moduleHandler =& xoops_gethandler(“module”);
$xoopsModule = $moduleHandler->getByDirname (“foo”);
</pre>


'''Criteria类使用和ObjectHandler常用方法介绍'''

XOOPS提供了Criteria类用于创建[[数据库]]的条件查询语法。为保证数据查询库的效率和安全性，建议模块开发者采用XOOPS系统提供的PersistableObjectHandler类并结合Criteria类实现对数据库的操作。

*Criteria类

:Criteria用于创建单一查询条件语句
<pre>
<?php
$criteria = new Criteria(“foo_id”, 100);
// 查询条件解析，一般在XoopsObjectHandler里调用
$criteria->render();
该实例将生成如下条件语句
“[… where] foo_id=100”;
?>
</pre>

:CriteriaCompo用于创建多条件组合查询语句
<pre>
<?php
$criteria = new CriteriaCompo();
$criteria_foo_id = new Criteria(“foo_id”, 100);
$criteria->add($criteria_foo_id);
//通过 AND 操作添加一个条件
$criteria->add(new Criteria(“foo_status”, 1, “=”), “AND”);
或
$criteria->add(new Criteria(“foo_status”, 1));
//通过 OR 操作添加一个条件
$criteria->add(new Criteria(“foo_level”, 100, “>”), “OR”);
//添加另一个组合查询条件
$criteria_another = new CriteriaCompo(new Criteria(“foo_category”, “test”));
$criteria_another->add(new Criteria(“foo_owner”, “administrator”));
$criteria->add($criteria_another, “OR”);
// 查询条件解析，一般在XoopsObjectHandler里调用
$criteria->render();

该实例将生成如下条件语句
“[… where] (foo_id = 100 AND foo_status = 1 OR foo_levl > 100) OR (foo_category = ’test’ AND foo_owner = ’administrator’)”;
?>
</pre>

*PersistableObjectHandler常用方法

:* create()：创建一个新对象
:* get()：从数据库读取数据并实例化一个对象
:* insert()：将当前对象数据插入或更新到数据库。系统通过该方法自动对数据进行验证和转义，以验证查询语法的正确性和对数据库操作的安全性；强烈建议模块开发者采用该方法或是继承该方法对数据库进行写操作。
:* delete()：从数据库中删除当前对象的数据
:* deleteAll()：从数据库中删除满足$criteria所描述条件的所有对象的数据
:* updateAll()：更新数据库中满足$criteria所描述条件的所有对象的字段数据
:* getObjects()：从数据库中读取满足$criteria所描述条件的所有数据并实例化为对象
:* getAll()：从数据库中读取满足$criteria所描述条件的所有数据并实例化为对象或返回数组
:* getList()：从数据库中读取满足$criteria所描述条件的所有数据，返回数组
:* getIds()：从数据库中读取满足$criteria所描述条件的所有数据，返回对应的主键值数组
:* getCount()：从数据库中读取满足$criteria所描述条件的数据量
:* getCounts()：从数据库中读取满足$criteria所描述条件的数据量的数组
:* getByLink()：联表查询，从数据库中读取满足$criteria所描述条件的所有数据并实例化为对象或返回数组
:* getCountByLink()：联表查询，从数据库中读取满足$criteria所描述条件的数据量
:* getCountsByLink()：联表查询，从数据库中读取满足$criteria所描述条件的数据量数组
:* updateByLink()：联表方式，更新数据库中满足$criteria所描述条件的所有对象的字段数据
:* deleteByLink()：联表方式，从数据库中删除满足$criteria所描述条件的所有对象的数据
:* cleanOrphan()：联表方式，清除数据表中的孤立数据
:* synchronization()：数据同步 


===XOOPS ORM应用实例===
以newbb[[论坛]]模块为例，描述数据操作的常用方法和范例。示例中涉及的类声明，按出现顺序：

*Forum类的定义
<pre>
class Forum extends XoopsObject
{ … }
class NewbbForumHandler extends XoopsPersistableObjectHandler
{ … }
</pre>
*Moderate类的定义
<pre>
class Moderate extends XoopsObject
{ … }
class NewbbModerateHandler extends XoopsPersistableObjectHandler
{ … }
</pre>
*Category类的定义
<pre>
class Category extends XoopsObject
{ … }
class NewbbCategoryHandler extends XoopsPersistableObjectHandler
{ … }
</pre>
*Post类的定义
<pre>
class Post extends XoopsObject
{ … }
class NewbbPostHandler extends XoopsPersistableObjectHandler
{ … }
</pre>
*Post类的定义
<pre>
class Topic extends XoopsObject
{ … }
class NewbbTopicHandler extends XoopsPersistableObjectHandler
{ … }
</pre>

*获取单个对象实例的数据
<pre>
/modules/newbb/viewforum.php
// 获取forum ID
$forum_id = intval($_GET['forum']);
// 创建NewbbForumObjectHandler
$forum_handler =& xoops_getmodulehandler('forum', 'newbb');
// 实例化NewbbForumObject
$forum_obj =& $forum_handler->get($forum_id);
</pre>

*按条件获取多个对象实例的数据
<pre>
/modules/newbb/moderate.php
//确定forum_id需满足的条件
$criteria = new Criteria("forum_id", "(0, {$forum_id})", "IN");
//确定要读取的数据量上限
$criteria->setLimit($xoopsModuleConfig['topics_per_page']);
//要读取的数据初始位置
$criteria->setStart($start);
//排序所依据的规则，即字段名
$criteria->setSort($sort);
//正序或倒序
$criteria->setOrder($order);
//读取满足条件的数据并实例化到$moderate_objs
$moderate_objs = $moderate_handler->getObjects($criteria);
</pre>

*新建对象实例并保存到数据库
<pre>
/modules/newbb/admin/admin_cat_manager.php
//创建category新对象
$category_obj =& $category_handler->create();
...
//从POST提交的数据赋值
$category_obj->setVar('cat_title', @$_POST['title']);
$category_obj->setVar('cat_image', @$_POST['cat_image']);
$category_obj->setVar('cat_order', $_POST['cat_order']);
$category_obj->setVar('cat_description', @$_POST['cat_description']);
$category_obj->setVar('cat_url', @$_POST['cat_url']);
...
//将对象数据插入到数据库中
if (!$category_handler->insert($category_obj)) {
...
}
</pre>

*更新单个对象实例的数据
<pre>
/modules/newbb/admin/admin_cat_manager.php
//创建category对象并从数据库读取数据
$category_obj =& $category_handler->get($cat_id);
...
//从POST提交的数据赋值
$category_obj->setVar('cat_title', @$_POST['title']);
$category_obj->setVar('cat_image', @$_POST['cat_image']);
$category_obj->setVar('cat_order', $_POST['cat_order']);
$category_obj->setVar('cat_description', @$_POST['cat_description']);
$category_obj->setVar('cat_url', @$_POST['cat_url']);
...
//更新对象在数据库中的数据
if (!$category_handler->insert($category_obj)) {
...
}
</pre>

*按条件更新多个对象实例的数据
<pre>
/modules/newbb/admin/topicmanager.php
//建立条件查询类
$criteria_topic = new Criteria("topic_id", $topic_id);
$criteria = new CriteriaCompo($criteria_topic);
$criteria->add(new Criteria('pid', 0));
//更新所有满足条件的post对象的pid值
$post_handler->updateAll("pid", $topic_handler->getTopPostId($newtopic), $criteria, true);
//更新所有满足条件的post对象的topic_id值
$post_handler->updateAll("topic_id", $newtopic, $criteria_topic, true);
</pre>

*删除单个对象实例的数据
<pre>
/modules/newbb/admin/admin_forum_manager.php
//创建forum对象并从数据库读取数据
$forum_obj =& $forum_handler->get($_POST['forum']);
//从数据库中删除该对象的数据
$forum_handler->delete($forum_obj);

*按条件删除多个对象实例的数据
<pre>
/modules/newbb/admin/admin_forum_manager.php
// forum类的delete方法 
function delete(&$forum)
{
	…
    // Get list of all topics in forum, to delete them too
$topic_handler =& xoops_getmodulehandler('topic', 'newbb');
//删除forum_id等于当前forum ID的所有主题
$topic_handler->deleteAll(new Criteria("forum_id", $forum->getVar('forum_id')), true, true);
…
//调用父类删除当前论坛版面的数据
    return parent::delete($forum);
}
</pre>












[[category:Xoops模块开发指南]]