ShopCMS 开发文档
HFramework 开发文档

4.3 框架模型基类提供的方法

模型基类提供的方法有(这里只展示public/protected方法的用法):
其中,setExtFields() 和 removeExtFields() 方法是1.6版本新增的方法,在ShopCMS二次开发时,可以不用重写CMS控制器和模型类,通过调用此方法直接扩充数据表字段。
<?php
 
/**
 * 模型基类
 * 本类是对数据库操作类的简单封装同时实现了数据验证的入口
 * 如果需要多表操作或者更复杂的查询等,可能还需要您手动编写SQL
 * 若类中提供的方法能实现的数据操作,尽量使用本类的方法,以简化程序以及防止SQL出错,加快开发速度
 * 如果不需要操作数据库和也不需要数据验证,您的模型类不需要继承此类
 * 重要:
 * 此类被定义为一个抽象类,只有被继承后才可以使用
 * 此类中有一个抽象方法 HModel::setTable();  因此,要求子类必须重写此方法
 * 子类中如果有构造函数,则必须在构造函数中调用此类的 setTable()方法
 * 如果您的数据表主键字段名不是“id”,您需要重写此类的setTableKey()方法,用以返回主键字段名字符串
 */
abstract class HModel{
	
	/**
	 * 设置当前Model默认操作的数据表
	 * 此方法在子类中必须被重写,否则程序会出错。
	 * 此方法会在初始化时调用
	 * @return string 默认操作的数据表的名字
	 */
	abstract protected function setTable();
	
	/**
	 * 设置表的主键
	 * 默认返回 字符串 id 如果表的主键不是id 则需要重写此方法
	 * @return string 主键名
	 */
	protected function setTableKey()

/**
	 * 获取默认操作的数据表
	 * @return string 默认操作的数据表的名字
	 */
	public function getTable(){
		return $this->_table;
	}
	
	/**
	 * 设置默认操作的数据库,用于数据库主从分离和多数据库的场景
	 * @param string $dbType 数据库类型,见数据库配置,可选值为 master、slave
	 * 如果您的配置文件中有其他类型,也可以设置
	 * @return void 无返回值
	 */
	public function setDbType($dbType){
		$this->_dbType = $dbType;
	}
	
	/**
	 * 追加扩展字段
	 * 追加的扩展字段仅在插入或者更新时,随原表数据一起写入数据表
	 * 该方法用于扩展时使用,在不重写原有模型类的情况下,快速扩展字段
	 * 注:此处添加的字段,不做数据格式检查,因此,您在添加前需自行检查数据的格式
	 * @param string $tableName 适用的数据表的表名,只有此表被插入时才会触发对应的回调函数
	 * @param string $scene 触发的场景,可选值有:INSERT/UPDATE,分别表示插入、更新
	 * @param array $data 一维关联数组,键名表示字段名,键值表示字段值
	 * @param string $dbType 当前操作的数据库类型,默认为 master ,可选值为master/slave,详情见数据库配置文件
	 * @return void 无返回值
	 * 注:此方法对本类中的execute方法无效
	 */
	public static function setExtFields($tableName, $scene, $data)
	
	/**
	 * 删除扩展字段
	 * @param string $tableName 仅限适用的数据表的表名
	 * @param string $scene 触发的场景,可选值有:INSERT/UPDATE,分别表示插入/更新 时触发
	 * @return void 无返回值
	 */
	public static function removeExtFields($tableName, $scene)
	
	/**
	 * 添加一条记录
	 * @param array $data  一维数组,其中键名表示字段名,键值表示字段值
	 * @param string $keys (可选)只插入指定的字段,英文逗号分割,如username,moible
	 * 如果不指定,默认插入$data中的所有字段
	 * @return boolen true = 执行成功,失败会抛出错误
	 */
	public function insertData($data, $keys='')
	
	/**
	 * 获取当前数据库连接的最后一次插入的记录ID(或者序列)
	 * @return int id 最后插入的记录的ID
	 */
	public function lastInsertId()
	
	/**
	 * 获取当前数据库连接的最后一次更新操作影响的行数
	 * @return int 行数
	 */
	public function lastUpdateRows()
	
	/**
	 * 删除记录
	 * @param mixed $condition 更新条件,类型可以是条件数组,或者HDbCondition的实例
	 * 若为数组,则键名表示字段名,键值表示字段值 ,如果不指定比较规则,则默认按照相等匹配
	 * 如:array('username'=>'user1'),表示删除所有 username=user1 的记录
	 * 构造查询查询条件数组,请参考关键
	 * @return boolen true = 执行成功,失败会抛出错误
	 * 注:执行成功未必更新了数据,足条件的记录不存在时仍然返回true
	 * 若要要获取更新的行数,可在调用此方法后,再调用lastUpdateRows方法判断
	 */
	public function deleteData($condition)
	
	/**
	 * 根据主键删除一条记录
	 * @param string $key 主键值
	 * @return boolen true = 执行成功,失败会抛出错误
	 * 注:执行成功未必更新了数据,足条件的记录不存在时返回true
	 */
	public function deleteByKey($key)
	
	/**
	 * 更新记录
	 * @param array $data 更新的值  键值型一位数组 键名表示字段名,键值表示字段值
	 * @param mixed $condition 查询条件,类型可以是查询条件数组,或者HDbCondition的实例
	 * @param string $keys 只更新指定的项目,英文逗号分割,如username,moible
	 * @return boolen true=成功;失败会抛出错误
	 * 注:执行成功未必更新了数据,足条件的记录不存在时返回true
	 */
	public function updateData($data, $condition=null, $keys='')
	
	/**
	 * 根据主键更新记录
	 * @param array $data  键值型一位数组 键名表示字段名,键值表示字段值
	 * @param mixed $key  主键值 
	 * @param string $keys 只更新指定的项目,英文逗号分割,如username,moible
	 * @return boolen true=成功;失败会抛出错误
	 * 注:执行成功未必更新了数据,足条件的记录不存在时仍返回true
	 */
	public function updateByKey($data, $key, $keys='')
	
	/**
	 * 根据主键值序列,批量更新某几个字段
	 * @param string $ids 英文逗号分隔的主键序列
	 * @param array $args 一维数组 如 array('is_delete'=>1)
	 * @return int 成功更新的记录数
	 */
	public function batchUpdateData($ids, $args)
	
	/**
	 * 根据主键序列,批量删除记录
	 * @param $ids string 英文逗号分隔的主键序列
	 * @return int 成功删除的记录数
	 */
	public function batchDeleteData($ids)
	
	/**
	 * 获取一条记录
	 * @param mixed $condition  查询或者更新条件,类型可以是关联数组,或者HDbCondition的实例
	 * @param string $orderby 查询时的排序规则   如 id desc, name asc
	 * @return mixed 成功返回一维关联数组 否则返回 boolen false
	 */
	public function getRow($condition, $orderby='')
	
	/**
	 * 根据主键获取一条记录
	 * @param $key  mixed 主键值 
	 * @return $mixed 成功返回一维数组 否则返回 boolen false
	 */
	public function getRowByKey($key)
	
	/**
	 * 根据SQL语句获取一条记录
	 * @param string $sql SQL语句
	 * @param array $params 参数绑定
	 * @return array 返回二维数组
	 * 注:SQL语句尽量用参数绑定的形式,以避免被SQL注入
	 */
	public function getRowBySql($sql, $params=array())
	
	/**
	 * 获取多条记录
	 * @param mixed $condition  查询或者更新条件,类型可以是关联数组,或者HDbCondition的实例
	 * 若为数组,则键名表示字段名,键值表示字段值 ,所有字段条件按照相等匹配查询
	 * @param $orderby string 查询时的排序规则   如 id desc, name asc
	 * @param int $rows 最多查询的记录数 默认为0,表示全部满足条件的记录
	 * @return array 成功返回二维数组 否则返回空数组:array()
	 */
	public function getRows($condition=null, $orderby='', $rows=0)
	
	/**
	 * 根据SQL语句获取多条记录
	 * @param string $sql slq语句
	 * @param array $params 参数绑定
	 * @return array 取到数据返回二维关联数组  否则返回空数组:array()
	 * 注:SQL语句尽量用参数绑定的形式,以避免被SQL注入
	 */
	public function getRowsBySql($sql, $params=array())
	
	/**
	 * 统计满足查询条件的记录数
	 * @param mixed $condition  查询或者更新条件,类型可以是关联数组,或者HDbCondition的实例
	 * @return int 满足条件的记录数
	 * 注:如果$sql中包含多个SQL语句(英文分号分隔的SQL语句),则获取更新行数时,返回第一个SQL语句的影响行数
	 */
	public function countRows($condition='')

	/**
	 * @param mexied $condition 查询或者更新条件,类型可以是关联数组,或者HDbCondition的实例
	 * @param int $page  查询的页码 从1开始
	 * @param int $rows 每页显示的行数
	 * @param strint $orderby 排序字段 如 id DESC
	 * @return array 格式如下:
	 * array(
	 * 	'total'=>8,//满足条件的总记录数
	 * 	'rows'=>array(
	 * 		0=>row0,
	 * 		1=>row1,
	 * 		......
	 * 	)
	 * )
	 * 期中 total表示满足条件的总记录数,  rows表示查询到的数据
	 */
	public function getPage($condition, $page=1, $rows=16, $orderby='')
	
	/**
	 * @param string $selectSql 查询语句,语句中不能有limit 关键词(有则忽略),翻页和排序通过后续参数传入
	 * @param int $page  查询的页码 从1开始
	 * @param int $rows 每页显示的行数
	 * @param array $params 参数绑定
	 * @return array 格式如下:
	 * array(
	 * 	'total'=>int
	 * 	'rows'=>array(
	 * 		0=>row0,
	 * 		1=>row1,
	 * 		......
	 * 	)
	 * )
	 * 期中 total表示满足条件的总记录数,  rows表示查询到的数据
	 */
	public function getPageBySql($selectSql, $page, $rows, $params=array())
	
	/**
	 * 执行SQL语句
	 * @param string $sql SQL语句
	 * @param array $params 绑定参数,格式为 array(':column1'=>'data1', ':column2'=>'data2'...)
	 * @return boolen true=成功;失败返回false,异常会抛出错误
	 * 注:执行成功未必更新了数据(如执行后前后记录未变化,或者没有满足条件的记录)
	 * 若要严格验证更新行数,需调用 $this->lastUpdateRows()
	 */
	public function execute($sql, $params=array())
	
	 /**
	 * 获取多条记录
	 * @param mixed $condition  查询或者更新条件,类型可以是关联数组,或者HDbCondition的实例
	 * 若为数组,则键名表示字段名,键值表示字段值 ,所有字段条件按照相等匹配查询
	 * @return boolen true=存在
	 */
	public function isExist($condition)
	
	/**
	 *  启动事务
	 * @return boolen 成功返回 true, 或者在失败时返回 false
	 */
	public function transBegin()
	
	/**
	 * 提交事务
	 * @return boolen 成功返回 true, 或者在失败时返回 false
	 */
	public function transCommit()
	
	/**
	 * 回滚事务,同时还可以添加错误信息,以便调用者捕获
	 * @param string $errorMsg 错误信息(如果为空则不添加错信息)
	 * @param int $errorCode 错误代码
	 * @return boolen 成功返回 true, 或者在失败时返回 false
	 */
	public function transRollback($errorMsg='', $errorCode='')
	
	
	
	/**
	 * 验证表单字段
	 * @param array $data 待验证的数据,一维关联数组
	 * @param array $rules 验证规则表  二维数组
	 * @return boolen 是否全部验证成功  true =成功
	 * 如果验证失败,会写入一条错误信息,调用者可以通过getError方法捕获
	 * @link HValidate::testRule()
	 */
	public function testRule($data, $rules)
	
	/**
	 * 验证数据的有效性 
	 * @param mixed $val 待验证的数据,可以是数组或者字符串,如果为数组,则数组的每一项都必须通过验证才算通过验证
	 * @param string $method  验证方法,如:验证是否为email,此处填 email
	 * @param boolen $allowEmpey 是否允许为空
	 * @param array $extRule 扩展规则,规则数组,用于传递额外的条件,以用于复杂的校验,比如校验字符串长度 需要传入 max min
	 * @return boolen 是否验证通过 true=通过,如果不通过,可以使用getError方法获取原因
	 * @link HValidate::test()
	 */
	public function test($val, $method, $allowEmpty=false, $extRule=null)
	
	/**
	 * 判断当前Model实例是否发生过错误(是否调用过addError()方法)
	 * @return boolen  如果发生过错误则返回true,否则返回false
	 */
	public function isError()
	
	/**
	 * 获取最后一个错误信息
	 * @param boolen$returnArray 是否指返回错误信息 默认为 false
	 * @return mixed 错误信息,可能的类型有:
	 * 如果没有错误信息则返回boolen false
	 * 如果$returnArray = false,返回最后一个错误的错误描述  string
	 * 如果$returnArray = true,返回错误信息和错误代码 型如 array('code'=>'001', 'msg'=>'this is a error')
	 */
	public function getError($returnArray = false)
	
	/**
	 * 获取全部错误信息
	 * @return array 如果有错误,返回array 二维数组,否则返回空数组
	 */
	public function getErrorAll()
	
	/**
	 * 添加错误信息
	 * @param string $msg 错误信息
	 * @param string $code 错误代码
	 * @return void
	 */
	protected function addError($msg, $code=0)
	
	/**
	 * 转换数组,把二维数组转换为一维关联数组
	 * @param array $array 二维数组
	 * @param string $valueField 数组$array中的键名,此键名对应的值将作为新数组的值
	 * @param string $keyField 数组$array中的键名,此键名对应的值将作为新数组的键名,如果为空,则以数字键从0开始命名
	 * @return 一维数组
	 */
	public function convertArray($array, $valueField, $keyField='')
	
	/**
	 * 返回子数组
	 * @param array $data 原数组
	 * @param string $keys 键名
	 * @return array 子数组
	 */
	public function subArray($data, $keys)
	
	/**
	 * 填充数组的空项,如果不为空则不被填充,为空则被赋值为$val
	 * @param array $args 待填充的数组
	 * @param mixed $val 被赋的值
	 * @param string $keys 英文逗号分隔的键名序列
	 * @return array 被填充后的数组
	 */
	public function fillArray($args, $val, $keys)
	
	/**
	 * SQL调试
	 * @return void 无返回值  调用后程序会输出所有执行过的SQL语句和绑定参数,结束运行
	 * 注:此方法仅在调试模式下有效
	 */
	public function debugSql()
	
	/**
	 * 创建数据库查询条件
	 * @return object HDbCondition 的实例
	 */
	public function createCondition()
	
	/**
	 * 过滤数组,遍历所有的数组项,他通过匹配方法的字段重新组合为一个新数组,
	 * @param array $data 待过滤的数组,一维数组
	 * @param striing $method 验证规则
	 * @param string $key 指定的键名 ,为空表示全部键,多个key则用英文逗号分隔
	 * @return array()  返回满足条件的项目组成的数组,如果全都不满足条件,则返回空数组
	 */
	protected function filter($data, $method, $keys='')
}


关键词:php模型类重写 CMS添加字段 数据库增删改查 数据库面向对象
阅读:1076 | 发布时间:2018-12-29 18:24