<?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='')
}