From 4d71f9d64530108fc5ce2199504720fe4a27da2b Mon Sep 17 00:00:00 2001 From: wangchunsheng Date: Fri, 12 Nov 2010 09:10:04 +0000 Subject: [PATCH] * recomment it in english. --- lib/dao/dao.class.php | 729 +++++++++++++++++++++++++++++++++--------- 1 file changed, 570 insertions(+), 159 deletions(-) diff --git a/lib/dao/dao.class.php b/lib/dao/dao.class.php index a5295a82d8..ad47c8b6c0 100755 --- a/lib/dao/dao.class.php +++ b/lib/dao/dao.class.php @@ -11,13 +11,13 @@ */ /** - * DAO类。提供各种便利的数据库操作方法。 + * DAO, data access object. * * @package ZenTaoPHP */ class dao { - /* 解决autoCompany带来的sql关键字冲突的问题。*/ + /* Use these strang strings to avoid conflicting with these keywords in the sql body. */ const WHERE = 'wHeRe'; const GROUPBY = 'gRoUp bY'; const HAVING = 'hAvInG'; @@ -25,7 +25,7 @@ class dao const LIMIT = 'lImiT'; /** - * 全局的$app对象。 + * The global app object. * * @var object * @access protected @@ -33,7 +33,7 @@ class dao protected $app; /** - * 全局的$config对象。 + * The global config object. * * @var object * @access protected @@ -41,7 +41,7 @@ class dao protected $config; /** - * 全局的$lang对象。 + * The global lang object. * * @var object * @access protected @@ -49,7 +49,7 @@ class dao protected $lang; /** - * 全局的$dbh（数据库访问句柄）对象。 + * The global dbh(database handler) object. * * @var object * @access protected @@ -57,7 +57,15 @@ class dao protected $dbh; /** - * 当前查询所对应的主表。 + * The sql object, used to creat the query sql. + * + * @var object + * @access protected + */ + public $sqlobj; + + /** + * The table of current query. * * @var string * @access public @@ -65,7 +73,7 @@ class dao public $table; /** - * 主表所对应的alias + * The alias of $this->table. * * @var string * @access public @@ -73,7 +81,7 @@ class dao public $alias; /** - * 当前查询所返回的字段列表。 + * The fields will be returned. * * @var string * @access public @@ -81,9 +89,9 @@ class dao public $fields; /** - * 查询的模式，现在支持两种，一种是通过魔术方法，一种是直接拼写sql查询。 + * The query mode, raw or magic. * - * 主要用来区分dao::from()方法和sql::from()方法。 + * This var is used to diff dao::from() with sql::from(). * * @var string * @access public @@ -91,7 +99,7 @@ class dao public $mode; /** - * 查询的方法: insert, select, update, delete, replace + * The query method: insert, select, update, delete, replace. * * @var string * @access public @@ -99,17 +107,15 @@ class dao public $method; /** - * 执行的sql查询列表。 + * The queries executed. Every query will be saved in this array. * - * 用来记录当前页面所有的sql查询。 - * * @var array * @access public */ static public $querys = array(); /** - * 数据检查结果。 + * The errors. * * @var array * @access public @@ -117,15 +123,12 @@ class dao static public $errors = array(); /** - * 构造函数。 - * - * 设置当前model对应的表名，并引用全局的变量。 + * The construct method. * - * @param string $table 表名。 * @access public * @return void */ - public function __construct($table = '') + public function __construct() { global $app, $config, $lang, $dbh; $this->app = $app; @@ -137,9 +140,9 @@ class dao } /** - * 设置数据表。 + * Set the $table property. * - * @param string $table 表名。 + * @param string $table * @access private * @return void */ @@ -149,9 +152,9 @@ class dao } /** - * 设置当前查询主表的alias。 + * Set the $alias property. * - * @param string $alias 别名。 + * @param string $alias * @access private * @return void */ @@ -161,9 +164,9 @@ class dao } /** - * 设置返回的字段列表。 + * Set the $fields property. * - * @param string $fields 字段列表。 + * @param string $fields * @access private * @return void */ @@ -173,7 +176,7 @@ class dao } /** - * 重新设置table, field, mode。 + * Reset the vars. * * @access private * @return void @@ -187,12 +190,12 @@ class dao $this->setMethod(''); } - //-------------------- 根据查询方式的不同，调用SQL类的对应方法。--------------------// + //-------------------- According to the query method, call according method of sql class. --------------------// /** - * 设置查询模式。magic是通过findby之类的魔术方法进行查询的，而raw则直接拼装sql进行查询。 + * Set the query mode. If the method if like findByxxx, the mode is magic. Else, the mode is raw. * - * @param string mode 查询模式： empty|magic|raw + * @param string $mode magic|raw * @access private * @return void */ @@ -201,13 +204,25 @@ class dao $this->mode = $mode; } - /* 设置查询的方法。select|update|insert|delete|replace */ + /** + * Set the query method: select|update|insert|delete|replace + * + * @param string $method + * @access private + * @return void + */ private function setMethod($method = '') { $this->method = $method; } - /* select：调用SQL类的select方法。*/ + /** + * The select method, call sql::select(). + * + * @param string $fields + * @access public + * @return object the dao object self. + */ public function select($fields = '*') { $this->setMode('raw'); @@ -216,7 +231,13 @@ class dao return $this; } - /* update：调用SQL类的update方法。*/ + /** + * The select method, call sql::update(). + * + * @param string $table + * @access public + * @return object the dao object self. + */ public function update($table) { $this->setMode('raw'); @@ -226,7 +247,12 @@ class dao return $this; } - /* delete：调用SQL类的delete方法。*/ + /** + * The delete method, call sql::delete(). + * + * @access public + * @return object + */ public function delete() { $this->setMode('raw'); @@ -235,7 +261,13 @@ class dao return $this; } - /* insert：调用SQL类的insert方法。*/ + /** + * The insert method, call sql::insert(). + * + * @param string $table + * @access public + * @return object + */ public function insert($table) { $this->setMode('raw'); @@ -245,7 +277,13 @@ class dao return $this; } - /* replace：调用SQL类的replace方法。*/ + /** + * The replace method, call sql::replace(). + * + * @param string $table + * @access public + * @return object + */ public function replace($table) { $this->setMode('raw'); @@ -255,7 +293,13 @@ class dao return $this; } - /* from: 设定要查询的table name。*/ + /** + * Set the from table. + * + * @param string $table + * @access public + * @return object + */ public function from($table) { $this->setTable($table); @@ -263,14 +307,26 @@ class dao return $this; } - /* fields方法：设置要查询的字段列表。*/ + /** + * Set the fields. + * + * @param string $fields + * @access public + * @return object + */ public function fields($fields) { $this->setFields($fields); return $this; } - /* alias方法。*/ + /** + * Alias a table, equal the AS keyword. (Don't use AS, because it's a php keyword.) + * + * @param string $alias + * @access public + * @return object + */ public function alias($alias) { if(empty($this->alias)) $this->setAlias($alias); @@ -278,36 +334,58 @@ class dao return $this; } - /* data方法。*/ + /** + * Set the data to update or insert. + * + * @param object $data the data object or array + * @param bool $autoCompany auto append company field or not + * @access public + * @return object + */ public function data($data, $autoCompany = true) { - /* 如果当前模块不是company，都追加company字段。*/ if(!is_object($data)) $data = (object)$data; if($autoCompany and isset($this->app->company) and $this->table != TABLE_COMPANY and !isset($data->company)) $data->company = $this->app->company->id; $this->sqlobj->data($data); return $this; } - //-------------------- 拼装之后的SQL相关处理方法。--------------------// + //-------------------- The sql related method. --------------------// - /* 返回SQL语句。*/ + /** + * Get the sql string. + * + * @access public + * @return string + */ public function get() { return $this->processKeywords($this->processSQL()); } - /* 打印SQL语句。*/ + /** + * Print the sql string. + * + * @access public + * @return void + */ public function printSQL() { echo $this->processSQL(); } - /* 处理SQL，将table和fields字段替换成对应的值。*/ + /** + * Process the sql, replace the table, fields and add the company condition. + * + * @param bool $autoCompany + * @access private + * @return string + */ private function processSQL($autoCompany = true) { $sql = $this->sqlobj->get(); - /* 如果查询模式是magic，处理fields和table两个变量。*/ + /* If the mode is magic, process the $fields and $table. */ if($this->mode == 'magic') { if($this->fields == '') $this->fields = '*'; @@ -315,24 +393,24 @@ class dao $sql = sprintf($this->sqlobj->get(), $this->fields, $this->table); } - /* 如果处理的不是company表，并且查询方法不是insert和replace， 追加company的查询条件。*/ + /* If the method if select, update or delete, set the comapny condition. */ if(isset($this->app->company) and $autoCompany and $this->table != '' and $this->table != TABLE_COMPANY and $this->method != 'insert' and $this->method != 'replace') { - /* 获得where 和 order by的位置。*/ - $wherePOS = strrpos($sql, DAO::WHERE); - $groupPOS = strrpos($sql, DAO::GROUPBY); // group by的位置。 - $havingPOS = strrpos($sql, DAO::HAVING); // having的位置。 - $orderPOS = strrpos($sql, DAO::ORDERBY); // order by的位置。 - $limitPOS = strrpos($sql, DAO::LIMIT); // limit的位置。 - $splitPOS = $orderPOS ? $orderPOS : $limitPOS; // order比limit靠前。 - $splitPOS = $havingPOS? $havingPOS: $splitPOS; // having比orer靠前。 - $splitPOS = $groupPOS ? $groupPOS : $splitPOS; // group比having靠前。 + /* Get the position to insert company = ?. */ + $wherePOS = strrpos($sql, DAO::WHERE); // The position of WHERE keyword. + $groupPOS = strrpos($sql, DAO::GROUPBY); // The position of GROUP BY keyword. + $havingPOS = strrpos($sql, DAO::HAVING); // The position of HAVING keyword. + $orderPOS = strrpos($sql, DAO::ORDERBY); // The position of ORDERBY keyword. + $limitPOS = strrpos($sql, DAO::LIMIT); // The position of LIMIT keyword. + $splitPOS = $orderPOS ? $orderPOS : $limitPOS; // If $orderPOS, use it instead of $limitPOS. + $splitPOS = $havingPOS? $havingPOS: $splitPOS; // If $havingPOS, use it instead of $orderPOS. + $splitPOS = $groupPOS ? $groupPOS : $splitPOS; // If $groupPOS, use it instead of $havingPOS. - /* 要追加的条件语句。*/ + /* Set the conditon to be appened. */ $tableName = !empty($this->alias) ? $this->alias : $this->table; $companyCondition = " $tableName.company = '{$this->app->company->id}' "; - /* SQL语句中有order by。*/ + /* If $spliPOS > 0, split the sql at $splitPOS. */ if($splitPOS) { $firstPart = substr($sql, 0, $splitPOS); @@ -355,28 +433,46 @@ class dao return $sql; } - /* 处理SQL关键字。*/ + /** + * Process the sql keywords, replace the constants to normal. + * + * @param string $sql + * @access private + * @return string + */ private function processKeywords($sql) { return str_replace(array(DAO::WHERE, DAO::GROUPBY, DAO::HAVING, DAO::ORDERBY, DAO::LIMIT), array('WHERE', 'GROUP BY', 'HAVING', 'ORDER BY', 'LIMIT'), $sql); } - //-------------------- SQL查询相关的方法。--------------------// + //-------------------- Query related methods. --------------------// - /* 设置数据库访问句柄。*/ + /** + * Set the dbh. + * + * You can use like this: $this->dao->dbh($dbh), thus you can handle two database. + * + * @param object $dbh + * @access public + * @return object + */ public function dbh($dbh) { $this->dbh = $dbh; return $this; } - /* 执行sql查询，返回stmt对象。autoComapny设定是否自动追加company的查询条件。*/ + /** + * Query the sql, return the statement object. + * + * @param bool $autoCompany + * @access public + * @return object the PDOStatement object. + */ public function query($autoCompany = true) { - /* 如果dao::$errors不为空，返回一个空的stmt对象，这样后续的方法调用还可以继续。*/ - if(!empty(dao::$errors)) return new PDOStatement(); + if(!empty(dao::$errors)) return new PDOStatement(); // If any error, return an empty statement object to make sure the remain method to execute. - /* 处理一下SQL语句。*/ $sql = $this->processSQL($autoCompany); try { @@ -389,22 +485,28 @@ class dao } } - /* 执行分页。*/ + /** + * Page the records, set the limit part auto. + * + * @param object $pager + * @access public + * @return object + */ public function page($pager) { if(!is_object($pager)) return $this; - /* 没有传递recTotal，则自己进行计算。*/ + /* If the record total is 0, compute it. */ if($pager->recTotal == 0) { - /* 获得SELECT和FROM的位置，据此算出查询的字段，然后将其替换为count(*)。*/ + /* Get the SELECT, FROM position, thus get the fields, replace it by count(*). */ $sql = $this->get(); $selectPOS = strpos($sql, 'SELECT') + strlen('SELECT'); $fromPOS = strpos($sql, 'FROM'); $fields = substr($sql, $selectPOS, $fromPOS - $selectPOS ); $sql = str_replace($fields, ' COUNT(*) AS recTotal ', $sql); - /* 取得order 或者limit的位置，将后面的去掉。*/ + /* Remove the part after order and limit. */ $subLength = strlen($sql); $orderPOS = strripos($sql, 'order'); $limitPOS = strripos($sql , 'limit'); @@ -413,7 +515,7 @@ class dao $sql = substr($sql, 0, $subLength); self::$querys[] = $sql; - /* 获得记录总数。*/ + /* Get the records count. */ try { $row = $this->dbh->query($sql)->fetch(PDO::FETCH_OBJ); @@ -430,13 +532,17 @@ class dao return $this; } - /* 执行sql查询，返回受影响的记录数。autoComapny设定是否自动追加company的查询条件。*/ + /** + /* Execute the sql. It's different with query(), which return the stmt object. But this not. + * + * @param bool $autoCompany + * @access public + * @return int the modified or deleted records. + */ public function exec($autoCompany = true) { - /* 如果dao::$errors不为空，返回一个空的stmt对象，这样后续的方法调用还可以继续。*/ - if(!empty(dao::$errors)) return new PDOStatement(); + if(!empty(dao::$errors)) return new PDOStatement(); // If any error, return an empty statement object to make sure the remain method to execute. - /* 处理一下SQL语句。*/ $sql = $this->processSQL($autoCompany); try { @@ -451,7 +557,14 @@ class dao //-------------------- 数据获取相关的方法。--------------------// - /* 返回一条记录，如果指定了$field字段, 则直接返回该字段对应的值。*/ + /** + * Fetch one record. + * + * @param string $field if the field is set, only return the value of this field, else return this record + * @param bool $autoCompany + * @access public + * @return misc + */ public function fetch($field = '', $autoCompany = true) { if(empty($field)) return $this->query($autoCompany)->fetch(); @@ -460,7 +573,14 @@ class dao if($result) return $result->$field; } - /* 返回全部的结果。如果指定了$keyField，则以keyField的值作为key。*/ + /** + * Fetch all records. + * + * @param string $keyField the key field, thus the return records is keyed by this field + * @param bool $autoCompany + * @access public + * @return array + */ public function fetchAll($keyField = '', $autoCompany = true) { $stmt = $this->query($autoCompany); @@ -470,7 +590,15 @@ class dao return $rows; } - /* 返回结果并按照某个字段进行分组。*/ + /** + * Fetch all records and group them by one field. + * + * @param string $groupField the field to group by + * @param string $keyField the field of key + * @param bool $autoCompany + * @access public + * @return array + */ public function fetchGroup($groupField, $keyField = '', $autoCompany = true) { $stmt = $this->query($autoCompany); @@ -482,7 +610,17 @@ class dao return $rows; } - /* fetchPairs方法：如果没有指定key和value字段，则取行字段里面的第一个作为key，最后一个作为value。*/ + /** + * Fetch array like key=>value. + * + * If the keyFiled and valueField not set, use the first and last in the record. + * + * @param string $keyField + * @param string $valueField + * @param bool $autoCompany + * @access public + * @return array + */ public function fetchPairs($keyField = '', $valueField = '', $autoCompany = true) { $pairs = array(); @@ -506,28 +644,32 @@ class dao return $pairs; } - /* 获取最后插入的id。*/ + /** + * Return the last insert ID. + * + * @access public + * @return int + */ public function lastInsertID() { return $this->dbh->lastInsertID(); } - //-------------------- 各种魔术方法。--------------------// + //-------------------- Magic methods.--------------------// /** - * 魔术方法，籍此提供各种便利的查询方法。 + * Use it to do some convenient queries. * - * @param string $funcName 被调用的方法名。 - * @param array $funcArgs 传入的参数列表。 + * @param string $funcName the function name to be called + * @param array $funcArgs the params * @access public * @return void */ public function __call($funcName, $funcArgs) { - /* 将funcName转为小写。*/ $funcName = strtolower($funcName); - /* findBy类的方法。*/ + /* findByxxx, xxx as will be in the where. */ if(strpos($funcName, 'findby') !== false) { $this->setMode('magic'); @@ -542,16 +684,15 @@ class dao $operator = $funcArgs[0]; $value = $funcArgs[1]; } - $this->sqlobj = sql::select('%s')->from('%s')->where($field, $operator, $value); // 使用占位符，执行查询之前替换为相应的字段和表名。 + $this->sqlobj = sql::select('%s')->from('%s')->where($field, $operator, $value); return $this; } - /* fetch10方法，真正的数据查询。*/ + /* Fetch10. */ elseif(strpos($funcName, 'fetch') !== false) { $max = str_replace('fetch', '', $funcName); $stmt = $this->query(); - /* 设定了key字段。 */ $rows = array(); $key = isset($funcArgs[0]) ? $funcArgs[0] : ''; $i = 0; @@ -563,10 +704,10 @@ class dao } return $rows; } - /* 其余的都直接调用sql类里面的方法。*/ + /* Others, call the method in sql class. */ else { - /* 取SQL类方法中参数个数最大值，生成一个最大集合的参数列表。。*/ + /* Create the max counts of sql class methods, and then create $arg0, $arg1... */ for($i = 0; $i < SQL::MAX_ARGS; $i ++) { ${"arg$i"} = isset($funcArgs[$i]) ? $funcArgs[$i] : null; @@ -576,24 +717,32 @@ class dao } } - //-------------------- 数据检查相关的方法。--------------------// + //-------------------- Checking.--------------------// - /* 按照某个规则检查值是否符合要求。*/ + /** + * Check a filed is satisfied with the check rule. + * + * @param string $fieldName the field to check + * @param string $funcName the check rule + * @access public + * @return object + */ public function check($fieldName, $funcName) { - /* 如果data变量里面没有这个字段，直接返回。*/ + /* If no this field in the data, reuturn. */ if(!isset($this->sqlobj->data->$fieldName)) return $this; - /* 引用全局的config, lang。*/ + /* Set the field label and value. */ global $lang, $config, $app; - $table = strtolower(str_replace($config->db->prefix, '', $this->table)); + $table = strtolower(str_replace($config->db->prefix, '', $this->table)); $fieldLabel = isset($lang->$table->$fieldName) ? $lang->$table->$fieldName : $fieldName; $value = $this->sqlobj->data->$fieldName; + /* Check unique. */ if($funcName == 'unique') { - $args = func_get_args(); - $sql = "SELECT COUNT(*) AS count FROM $this->table WHERE `$fieldName` = " . $this->sqlobj->quote($value); + $args = func_get_args(); + $sql = "SELECT COUNT(*) AS count FROM $this->table WHERE `$fieldName` = " . $this->sqlobj->quote($value); if($this->table != TABLE_COMPANY) $sql .= " AND company = {$this->app->company->id} "; if(isset($args[2])) $sql .= ' AND ' . $args[2]; try @@ -608,7 +757,7 @@ class dao } else { - /* 取validate类方法中参数个数最大值，生成一个最大集合的参数列表。。*/ + /* Create the params. */ $funcArgs = func_get_args(); unset($funcArgs[0]); unset($funcArgs[1]); @@ -627,7 +776,15 @@ class dao return $this; } - /* 如果满足某一个条件，按照某个规则检查值是否符合要求。*/ + /** + * Check a field, if satisfied with the condition. + * + * @param string $condition + * @param string $fieldName + * @param string $funcName + * @access public + * @return object + */ public function checkIF($condition, $fieldName, $funcName) { if(!$condition) return $this; @@ -640,7 +797,14 @@ class dao return $this; } - /* 批量检查。*/ + /** + * Batch check some fileds. + * + * @param string $fields the fields to check, join with , + * @param string $funcName + * @access public + * @return object + */ public function batchCheck($fields, $funcName) { $fields = explode(',', str_replace(' ', '', $fields)); @@ -653,7 +817,15 @@ class dao return $this; } - /* 批量条件检查。*/ + /** + * Batch check fields on the condition is true. + * + * @param string $condition + * @param string $fields + * @param string $funcName + * @access public + * @return object + */ public function batchCheckIF($condition, $fields, $funcName) { if(!$condition) return $this; @@ -667,7 +839,13 @@ class dao return $this; } - /* 自动根据数据库中表的字段格式进行检查。*/ + /** + * Check the fields according the the database schema. + * + * @param string $skipFields fields to skip checking + * @access public + * @return object + */ public function autoCheck($skipFields = '') { $fields = $this->getFieldsType(); @@ -675,7 +853,7 @@ class dao foreach($fields as $fieldName => $validater) { - if(strpos($skipFields, $fieldName) !== false) continue; // 忽略。 + if(strpos($skipFields, $fieldName) !== false) continue; // skip it. if(!isset($this->sqlobj->data->$fieldName)) continue; if($validater['rule'] == 'skip') continue; $options = array(); @@ -689,27 +867,38 @@ class dao return $this; } - /* 记录错误。*/ + /** + * Log the error. + * + * For the error notice, see module/common/lang. + * + * @param string $checkType the check rule + * @param string $fieldName the field name + * @param string $fieldLabel the field label + * @param array $funcArgs the args + * @access public + * @return void + */ public function logError($checkType, $fieldName, $fieldLabel, $funcArgs = array()) { global $lang; $error = $lang->error->$checkType; - $replaces = array_merge(array($fieldLabel), $funcArgs); + $replaces = array_merge(array($fieldLabel), $funcArgs); // the replace values. - /* 如果error不是数组，只是字符串，则循环replace，依次替换%s。*/ + /* Just a string, cycle the $replaces. */ if(!is_array($error)) { foreach($replaces as $replace) { $pos = strpos($error, '%s'); if($pos === false) break; - $error = substr($error, 0, $pos) . $replace . substr($error, $pos +2); + $error = substr($error, 0, $pos) . $replace . substr($error, $pos + 2); } } - /* 如果error是一个数组，则从数组中挑选%s个数与replace元素个数相同的。*/ + /* If the error define is an array, select the one which %s counts match the $replaces. */ else { - /* 去掉replace中空白的元素。*/ + /* Remove the empty items. */ foreach($replaces as $key => $value) if(is_null($value)) unset($replaces[$key]); $replacesCount = count($replaces); foreach($error as $errorString) @@ -723,21 +912,36 @@ class dao dao::$errors[$fieldName][] = $error; } - /* 判断这次查询是否有错误。*/ + /** + * Judge any error or not. + * + * @access public + * @return bool + */ public function isError() { return !empty(dao::$errors); } - /* 返回error。*/ + /** + * Get the errors. + * + * @access public + * @return array + */ public function getError() { $errors = dao::$errors; - dao::$errors = array(); + dao::$errors = array(); // Must clear it. return $errors; } - /* 获得某一个表的字段类型。*/ + /** + * Get the defination of fields of the table. + * + * @access private + * @return array + */ private function getFieldsType() { try @@ -799,20 +1003,20 @@ class dao } /** - * SQL查询封装类。 + * The SQL class. * * @package ZenTaoPHP */ class sql { /** - * 所有方法的参数个数最大值。 + * The max count of params of all methods. * */ const MAX_ARGS = 3; /** - * SQL语句。 + * The sql string. * * @var string * @access private @@ -820,7 +1024,7 @@ class sql private $sql = ''; /** - * 全局的$dbh（数据库访问句柄）对象。 + * The global $dbh. * * @var object * @access protected @@ -828,7 +1032,7 @@ class sql protected $dbh; /** - * INSERT或者UPDATE时赋给的数据。 + * The data to update or insert. * * @var mix * @access protected @@ -836,7 +1040,7 @@ class sql public $data; /** - * 是否是首次调用set。 + * Is the first time to call set. * * @var bool * @access private; @@ -844,7 +1048,7 @@ class sql private $isFirstSet = true; /** - * 是否在条件判断中。 + * If in the logic of judge condition or not. * * @var bool * @access private; @@ -852,7 +1056,7 @@ class sql private $inCondition = false; /** - * 判断条件是否为ture。 + * The condition is true or not. * * @var bool * @access private; @@ -860,14 +1064,20 @@ class sql private $conditionIsTrue = false; /** - * 是否自动magic quote。 + * Magic quote or not. * * @var bool * @access public */ public $magicQuote; - /* 构造函数。*/ + /** + * The construct function. user factory() to instance it. + * + * @param string $table + * @access private + * @return void + */ private function __construct($table = '') { global $dbh; @@ -875,13 +1085,25 @@ class sql $this->magicQuote = get_magic_quotes_gpc(); } - /* 实例化方法，通过该方法实例对象。*/ + /** + * The factory method. + * + * @param string $table + * @access public + * @return object + */ public function factory($table = '') { return new sql($table); } - /* 查询语句开始。*/ + /** + * The sql is select. + * + * @param string $field + * @access public + * @return object + */ public function select($field = '*') { $sqlobj = self::factory(); @@ -889,7 +1111,13 @@ class sql return $sqlobj; } - /* 更新语句开始。*/ + /** + * The sql is update. + * + * @param string $table + * @access public + * @return object + */ public function update($table) { $sqlobj = self::factory(); @@ -897,7 +1125,13 @@ class sql return $sqlobj; } - /* 插入语句开始。*/ + /** + * The sql is insert. + * + * @param string $table + * @access public + * @return object + */ public function insert($table) { $sqlobj = self::factory(); @@ -905,7 +1139,13 @@ class sql return $sqlobj; } - /* 替换语句开始。*/ + /** + * The sql is replace. + * + * @param string $table + * @access public + * @return object + */ public function replace($table) { $sqlobj = self::factory(); @@ -913,7 +1153,12 @@ class sql return $sqlobj; } - /* 删除语句开始。*/ + /** + * The sql is delete. + * + * @access public + * @return object + */ public function delete() { $sqlobj = self::factory(); @@ -921,30 +1166,54 @@ class sql return $sqlobj; } - /* 给定一个key=>value结构的数组或者对象，拼装成key = value的形式。*/ + /** + * Join the data items by key = value. + * + * @param object $data + * @access public + * @return object + */ public function data($data) { $this->data = $data; foreach($data as $field => $value) $this->sql .= "`$field` = " . $this->quote($value) . ','; - $this->sql = rtrim($this->sql, ','); // 去掉最后面的逗号。 + $this->sql = rtrim($this->sql, ','); // Remove the last ','. return $this; } - /* 加左边的括弧。*/ + /** + * Aadd an '(' at left. + * + * @param int $count + * @access public + * @return ojbect + */ public function markLeft($count = 1) { $this->sql .= str_repeat('(', $count); return $this; } - /* 加右边的括弧。*/ + /** + * Add an ')' ad right. + * + * @param int $count + * @access public + * @return object + */ public function markRight($count = 1) { $this->sql .= str_repeat(')', $count); return $this; } - /* SET key=value。*/ + /** + * The set part. + * + * @param string $set + * @access public + * @return object + */ public function set($set) { if($this->isFirstSet) @@ -959,48 +1228,94 @@ class sql return $this; } - /* 设定要查询的表名。*/ + /** + * Create the from part. + * + * @param string $table + * @access public + * @return object + */ public function from($table) { $this->sql .= "FROM $table"; return $this; } - /* 设置别名。*/ + /** + * Create the Alias part. + * + * @param string $alias + * @access public + * @return object + */ public function alias($alias) { $this->sql .= " AS $alias "; + return $this; } - /* 设定LEFT JOIN语句。*/ + /** + * Create the left join part. + * + * @param string $table + * @access public + * @return object + */ public function leftJoin($table) { $this->sql .= " LEFT JOIN $table"; return $this; } - /* 设定ON条件。*/ + /** + * Create the on part. + * + * @param string $condition + * @access public + * @return object + */ public function on($condition) { $this->sql .= " ON $condition "; return $this; } - /* 条件判断开始。*/ + /** + * Begin condition judge. + * + * @param bool $condition + * @access public + * @return object + */ public function beginIF($condition) { $this->inCondition = true; $this->conditionIsTrue = $condition; + return $this; } - /* 条件判断结束。*/ + /** + * End the condition judge. + * + * @access public + * @return object + */ public function fi() { $this->inCondition = false; $this->conditionIsTrue = false; + return $this; } - /* WHERE语句部分开始。*/ + /** + * Create the where part. + * + * @param string $arg1 the field name + * @param string $arg2 the operator + * @param string $arg3 the value + * @access public + * @return object + */ public function where($arg1, $arg2 = null, $arg3 = null) { if($this->inCondition and !$this->conditionIsTrue) return $this; @@ -1018,7 +1333,13 @@ class sql return $this; } - /* 追加AND条件。*/ + /** + * Create the AND part. + * + * @param string $condition + * @access public + * @return object + */ public function andWhere($condition) { if($this->inCondition and !$this->conditionIsTrue) return $this; @@ -1026,7 +1347,13 @@ class sql return $this; } - /* 追加OR条件。*/ + /** + * Create the OR part. + * + * @param bool $condition + * @access public + * @return object + */ public function orWhere($condition) { if($this->inCondition and !$this->conditionIsTrue) return $this; @@ -1034,7 +1361,13 @@ class sql return $this; } - /* 等于。*/ + /** + * Create the '='. + * + * @param string $value + * @access public + * @return object + */ public function eq($value) { if($this->inCondition and !$this->conditionIsTrue) return $this; @@ -1042,7 +1375,13 @@ class sql return $this; } - /* 不等于。*/ + /** + * Create '!='. + * + * @param string $value + * @access public + * @return void + */ public function ne($value) { if($this->inCondition and !$this->conditionIsTrue) return $this; @@ -1050,7 +1389,13 @@ class sql return $this; } - /* 大于。*/ + /** + * Create '>'. + * + * @param string $value + * @access public + * @return object + */ public function gt($value) { if($this->inCondition and !$this->conditionIsTrue) return $this; @@ -1058,7 +1403,13 @@ class sql return $this; } - /* 小于。*/ + /** + * Create '<'. + * + * @param mixed $value + * @access public + * @return object + */ public function lt($value) { if($this->inCondition and !$this->conditionIsTrue) return $this; @@ -1066,7 +1417,14 @@ class sql return $this; } - /* 生成between语句。*/ + /** + * Create "between and" + * + * @param string $min + * @param string $max + * @access public + * @return object + */ public function between($min, $max) { if($this->inCondition and !$this->conditionIsTrue) return $this; @@ -1074,7 +1432,13 @@ class sql return $this; } - /* 生成 IN部分语句。*/ + /** + * Create in part. + * + * @param mixed $ids list string by ',' or an array + * @access public + * @return object + */ public function in($ids) { if($this->inCondition and !$this->conditionIsTrue) return $this; @@ -1082,7 +1446,13 @@ class sql return $this; } - /* 生成 NOTIN部分语句。*/ + /** + * Create not in part. + * + * @param mixed $ids list string by ',' or an array + * @access public + * @return object + */ public function notin($ids) { if($this->inCondition and !$this->conditionIsTrue) return $this; @@ -1090,7 +1460,13 @@ class sql return $this; } - /* 生成LIKE部分语句。*/ + /** + * Create the like by part. + * + * @param string $string + * @access public + * @return object + */ public function like($string) { if($this->inCondition and !$this->conditionIsTrue) return $this; @@ -1098,16 +1474,28 @@ class sql return $this; } - /* 设定ORDER BY。*/ + /** + * Create the order by part. + * + * @param string $order + * @access public + * @return object + */ public function orderBy($order) { $order = str_replace(array('|', '', '_'), ' ', $order); - $order = str_replace('left', '`left`', $order); // 处理left关键字。 + $order = str_replace('left', '`left`', $order); // process the left to `left`. $this->sql .= ' ' . DAO::ORDERBY . " $order"; return $this; } - /* 设定LIMIT。*/ + /** + * Create the limit part. + * + * @param string $limit + * @access public + * @return object + */ public function limit($limit) { if(empty($limit)) return $this; @@ -1115,27 +1503,50 @@ class sql return $this; } - /* 设定GROUP BY。*/ + /** + * Create the groupby part. + * + * @param string $groupBy + * @access public + * @return object + */ public function groupBy($groupBy) { $this->sql .= ' ' . DAO::GROUPBY . " $groupBy"; return $this; } - /* 设定having。*/ + /** + * Create the having part. + * + * @param string $having + * @access public + * @return object + */ public function having($having) { $this->sql .= ' ' . DAO::HAVING . " $having"; return $this; } - /* 返回拼装好的语句。*/ + /** + * Get the sql string. + * + * @access public + * @return string + */ public function get() { return $this->sql; } - /* 转义。*/ + /** + * Uuote a var. + * + * @param mixed $value + * @access public + * @return mixed + */ public function quote($value) { if($this->magicQuote) $value = stripslashes($value);