全面更新与补全模型基础类的注释说明

common/base/classes/BaseClass.php

@@ -10,7 +10,9 @@ class BaseClass
     public static $baseFile; // 模型类名的路径字符串
 
     /**
-     * @return Base
+     * 获取模型对象
+     * @return Base|\yii\db\ActiveRecord
+     * @throws \yii\base\InvalidConfigException
      */
     protected static function getModel()
     {
@@ -29,15 +31,23 @@ class BaseClass
     }
 
     /**
-     * 获取模型对象
-     * @return yii\db\ActiveRecord;
+     * 获取模型对象 (ActiveRecord)
+     * @return \yii\db\ActiveRecord
      */
     public static function getActiveRecord()
     {
         return self::getModel();
     }
 
-    //查询全部 ssh 2019.11.27
+    /**
+     * 查询全部列表 (不分页)
+     * @param string|array $select 查询字段
+     * @param array $where 查询条件
+     * @param string|array $order 排序
+     * @param string|array $with 关联查询
+     * @return array
+     * @throws \Exception
+     */
     public static function getAllList($select, $where, $order = '', $with = '')
     {
         $model = self::getModel();
@@ -45,7 +55,15 @@ class BaseClass
         return $return;
     }
 
-    //分页查询 ssh 2019.9.21
+    /**
+     * 分页查询列表 (自动获取请求中的page和pageSize)
+     * @param string|array $select 查询字段
+     * @param array $where 查询条件
+     * @param string|array $order 排序
+     * @param string|array $with 关联查询
+     * @return array ['totalNum' => int, 'totalPage' => int, 'moreData' => int, 'list' => array]
+     * @throws \Exception
+     */
     public static function getList($select, $where, $order = '', $with = '')
     {
         $get = Yii::$app->request->get();
@@ -57,7 +75,16 @@ class BaseClass
         return $return;
     }
 
-    //查询指定条数 ssh 2019.11.30
+    /**
+     * 查询指定条数的列表
+     * @param string|array $select 查询字段
+     * @param array $where 查询条件
+     * @param int $limit 限制条数
+     * @param string|array $order 排序
+     * @param string|array $with 关联查询
+     * @return array
+     * @throws \Exception
+     */
     public static function getLimitList($select, $where, $limit = 10, $order = '', $with = '')
     {
         $model = self::getModel();
@@ -66,8 +93,9 @@ class BaseClass
     }
 
     /**
-     * @param $data
-     * @param bool $returnObject
+     * 添加数据
+     * @param array $data 数据数组
+     * @param bool $returnObject 是否返回对象
      * @return array|Base
      * @throws \Exception
      */
@@ -79,6 +107,9 @@ class BaseClass
 
     /**
      * 批量添加
+     * @param array $data 二维数组
+     * @return void
+     * @throws \Exception
      */
     public static function batchAdd($data)
     {
@@ -88,8 +119,8 @@ class BaseClass
 
     /**
      * 根据主键ID删除一条记录
-     * @param $id
-     * @return false|int the number of rows deleted, or `false` if the deletion is unsuccessful for some reason.
+     * @param int|string $id 主键ID
+     * @return int|false 删除的行数，失败返回false
      * @throws \Throwable
      * @throws \yii\db\StaleObjectException
      */
@@ -101,8 +132,9 @@ class BaseClass
 
     /**
      * 根据条件删除一条或多条记录
-     * @param $condition
-     * @return int
+     * @param array $condition 查询条件
+     * @return int 删除的行数
+     * @throws \Exception
      */
     public static function deleteByCondition($condition)
     {
@@ -111,7 +143,12 @@ class BaseClass
         return $count;
     }
 
-    //根据id批量删 ssh 2019.12.7
+    /**
+     * 根据多个主键ID批量删除
+     * @param array $ids 主键ID数组
+     * @return int 删除的行数
+     * @throws \Exception
+     */
     public static function deleteByIds($ids)
     {
         $model = self::getModel();
@@ -120,6 +157,9 @@ class BaseClass
 
     /**
      * 根据主键ID更新一条记录
+     * @param int|string $id 主键ID
+     * @param array $data 更新的数据
+     * @return array ['status' => bool, 'data' => array]
      */
     public static function updateById($id, $data)
     {
@@ -127,7 +167,12 @@ class BaseClass
         return $model->updateById($id, $data);
     }
 
-    //根据多个主键id更新 ssh 2019.9.3
+    /**
+     * 根据多个主键ID批量更新
+     * @param array $ids 主键ID数组
+     * @param array $data 更新的数据
+     * @return int 更新的行数
+     */
     public static function updateByIds($ids, $data)
     {
         $model = self::getModel();
@@ -136,6 +181,9 @@ class BaseClass
 
     /**
      * 根据条件更新一条或多条记录
+     * @param array $condition 查询条件
+     * @param array $data 更新的数据
+     * @return int 更新的行数
      */
     public static function updateByCondition($condition, $data)
     {
@@ -146,9 +194,9 @@ class BaseClass
 
     /**
      * 根据主键ID查出一条记录
-     * @param $id
-     * @param bool $returnObject
-     * @param string $field
+     * @param int|string $id 主键ID
+     * @param bool $returnObject 是否返回对象
+     * @param string|array $field 查询字段
      * @return array|\yii\db\ActiveRecord|null
      */
     public static function getById($id, $returnObject = false, $field = '*')
@@ -157,7 +205,13 @@ class BaseClass
         return $model->getById($id, $returnObject, $field);
     }
 
-    //随机取一个 ssh 2020.2.10
+    /**
+     * 获取第一条记录
+     * @param bool $returnObject 是否返回对象
+     * @param string|array|bool $order 排序
+     * @param string|array $field 查询字段
+     * @return array|\yii\db\ActiveRecord|null
+     */
     public static function getOne($returnObject = false, $order = false, $field = '*')
     {
         $model = self::getModel();
@@ -166,10 +220,10 @@ class BaseClass
 
     /**
      * 根据条件查出一条记录
-     * @param $condition
-     * @param bool $returnObject
-     * @param bool $order
-     * @param string $field
+     * @param array $condition 查询条件
+     * @param bool $returnObject 是否返回对象
+     * @param string|array|bool $order 排序
+     * @param string|array $field 查询字段
      * @return array|\yii\db\ActiveRecord|null
      */
     public static function getByCondition($condition, $returnObject = false, $order = false, $field = '*')
@@ -179,8 +233,8 @@ class BaseClass
     }
 
     /**
-     * 是否存在
-     * @param $condition
+     * 判断数据是否存在
+     * @param array $condition 查询条件
      * @return bool
      * @throws \yii\base\InvalidConfigException
      */
@@ -192,11 +246,11 @@ class BaseClass
 
     /**
      * 根据条件查出多条记录
-     * @param array $condition
-     * @param null $order
-     * @param string $field
-     * @param null $indexBy
-     * @param bool $returnObject
+     * @param array $condition 查询条件
+     * @param string|array|null $order 排序
+     * @param string|array $field 查询字段
+     * @param string|callable|null $indexBy 索引字段
+     * @param bool $returnObject 是否返回对象
      * @return array|\yii\db\ActiveRecord[]
      */
     public static function getAllByCondition($condition, $order = null, $field = '*', $indexBy = null, $returnObject = false)
@@ -207,6 +261,11 @@ class BaseClass
 
     /**
      * 根据多个主键ID查询多条记录
+     * @param array $ids 主键ID数组
+     * @param string|array|null $order 排序
+     * @param string|callable|null $indexBy 索引字段
+     * @param string|array $field 查询字段
+     * @return array
      */
     public static function getByIds($ids, $order = null, $indexBy = null, $field = '*')
     {
@@ -215,7 +274,9 @@ class BaseClass
     }
 
     /**
-     *根据条件查出数量
+     * 根据条件获取记录数量
+     * @param array $condition 查询条件
+     * @return int|string
      */
     public static function getCount($condition)
     {
@@ -223,21 +284,37 @@ class BaseClass
         return $model->getCount($condition);
     }
 
-    //计数器+1-1 shizq 2019-12-05
+    /**
+     * 更新计数器 (原子操作)
+     * @param array $counters 更新的计数器数组
+     * @param array $condition 更新条件
+     * @param array $params 绑定参数
+     * @return int 更新行数
+     */
     public static function counters($counters, $condition, $params = [])
     {
         $model = self::getModel();
         return $model->counters($counters, $condition, $params);
     }
 
-    //根据主键获取被销的信息 ssh 2021.5.18
+    /**
+     * 根据主键获取记录并锁定 (SELECT FOR UPDATE)
+     * @param int|string $id 主键ID
+     * @param string|array $field 查询字段
+     * @return array|\yii\db\ActiveRecord|null
+     */
     public static function getLockById($id, $field = '*')
     {
         $model = self::getModel();
         return $model->getLockById($id, $field);
     }
 
-    //求和
+    /**
+     * 求和
+     * @param array $condition 查询条件
+     * @param string $field 求和字段
+     * @return mixed
+     */
     public static function sum($condition, $field)
     {
         $model = self::getModel();

common/base/models/Base.php

@@ -9,6 +9,7 @@ class Base extends ActiveRecord
 {
 
     /**
+     * 获取当前模型实例
      * @return static
      */
     public function getModel()
@@ -18,9 +19,9 @@ class Base extends ActiveRecord
     }
 
     /**
-     * 添加
-     * @param $data
-     * @param bool $returnObject
+     * 添加数据
+     * @param array $data 数据数组
+     * @param bool $returnObject 是否返回对象，true返回模型对象，false返回数组
      * @return $this|array
      * @throws \Exception
      */
@@ -60,6 +61,8 @@ class Base extends ActiveRecord
 
     /**
      * 批量添加
+     * @param array $data 二维数组 [['name'=>'a'], ['name'=>'b']]
+     * @return void
      */
     public function batchAdd($data)
     {
@@ -73,7 +76,8 @@ class Base extends ActiveRecord
     }
 
     /**
-     * 取表的字段
+     * 获取表的所有字段名
+     * @return array
      */
     public function getFields()
     {
@@ -84,8 +88,8 @@ class Base extends ActiveRecord
 
     /**
      * 根据主键ID删除一条记录
-     * @param $id
-     * @return int|false the number of rows deleted, or `false` if the deletion is unsuccessful for some reason.
+     * @param int|string $id 主键ID
+     * @return int|false 删除的行数，失败返回false
      * @throws \Throwable
      * @throws \yii\db\StaleObjectException
      */
@@ -96,9 +100,9 @@ class Base extends ActiveRecord
     }
 
     /**
-     * 根据id批量删 ssh 2019.12.7
-     * @param $ids
-     * @return int the number of rows deleted
+     * 根据多个主键ID批量删除
+     * @param array $ids 主键ID数组
+     * @return int 删除的行数
      */
     public function deleteByIds($ids)
     {
@@ -108,8 +112,8 @@ class Base extends ActiveRecord
 
     /**
      * 根据条件删除一条或多条记录
-     * @param $condition
-     * @return int
+     * @param array $condition 查询条件
+     * @return int 删除的行数
      */
     public function deleteByCondition($condition)
     {
@@ -130,6 +134,9 @@ class Base extends ActiveRecord
 
     /**
      * 根据主键ID更新一条记录
+     * @param int|string $id 主键ID
+     * @param array $data 更新的数据
+     * @return array ['status' => bool, 'data' => array] status=true更新成功，false更新失败
      */
     public function updateById($id, $data)
     {
@@ -149,7 +156,12 @@ class Base extends ActiveRecord
         return ['status' => false, 'data' => $data];
     }
 
-    //多个主键更新 ssh 2019.9.3
+    /**
+     * 根据多个主键ID批量更新
+     * @param array $ids 主键ID数组
+     * @param array $data 更新的数据
+     * @return int 更新的行数
+     */
     public function updateByIds($ids, $data)
     {
         return self::updateAll($data, ['id' => $ids]);
@@ -157,6 +169,9 @@ class Base extends ActiveRecord
 
     /**
      * 根据条件更新一条或多条记录
+     * @param array $condition 查询条件
+     * @param array $data 更新的数据
+     * @return int 更新的行数
      */
     public function updateByCondition($condition, $data)
     {
@@ -173,9 +188,9 @@ class Base extends ActiveRecord
 
     /**
      * 根据主键ID查出一条记录
-     * @param $id
-     * @param bool $returnObject
-     * @param string $field
+     * @param int|string $id 主键ID
+     * @param bool $returnObject 是否返回对象
+     * @param string|array $field 查询字段
      * @return array|ActiveRecord|null
      */
     public function getById($id, $returnObject = false, $field = '*')
@@ -190,10 +205,10 @@ class Base extends ActiveRecord
 
     /**
      * 根据条件查出一条记录
-     * @param $condition
-     * @param bool $returnObject
-     * @param bool $order
-     * @param string $field
+     * @param array $condition 查询条件
+     * @param bool $returnObject 是否返回对象
+     * @param string|array|bool $order 排序
+     * @param string|array $field 查询字段
      * @return array|ActiveRecord|null
      */
     public function getByCondition($condition, $returnObject = false, $order = false, $field = '*')
@@ -205,7 +220,13 @@ class Base extends ActiveRecord
         return $returnObject == true ? $query->one() : $query->asArray()->one();
     }
 
-    //随机取一个 ssh 2020.2.10
+    /**
+     * 获取第一条记录 (通常用于获取任意一条或结合排序获取特定一条)
+     * @param bool $returnObject 是否返回对象
+     * @param string|array|bool $order 排序
+     * @param string|array $field 查询字段
+     * @return array|ActiveRecord|null
+     */
     public function getOne($returnObject = false, $order = false, $field = '*')
     {
         $query = $this->conditionQuery([])->select($field);
@@ -216,16 +237,20 @@ class Base extends ActiveRecord
     }
 
     /**
-     * 支持查询条件包括
-        $condition = [
-            'name' => 'john',               // 等于
-            'id>' => 3,                     // 大于
-            'id<' => 10,                    // 小于
-            'id!=' => -1,                   // 不等于
-            'id' => ['in', [10,11,12]],     // IN
-            'age' => ['between', [20,30]],  // BETWEEN
-            'name' => ['like', 'Jack']      // LIKE
-        ];
+     * 构建查询条件对象
+     * 支持查询条件包括:
+     * $condition = [
+     *     'name' => 'john',               // 等于
+     *     'id>' => 3,                     // 大于
+     *     'id<' => 10,                    // 小于
+     *     'id!=' => -1,                   // 不等于
+     *     'id' => ['in', [10,11,12]],     // IN
+     *     'id' => ['not in', [10,11,12]], // NOT IN
+     *     'age' => ['between', [20,30]],  // BETWEEN
+     *     'name' => ['like', 'Jack']      // LIKE
+     * ];
+     * @param array $condition 查询条件数组
+     * @return \yii\db\ActiveQuery
      */
     public function conditionQuery($condition = [])
     {
@@ -279,8 +304,8 @@ class Base extends ActiveRecord
     }
 
     /**
-     * 是否存在数据
-     * @param $condition
+     * 判断数据是否存在
+     * @param array $condition 查询条件
      * @return bool
      */
     public function exists($condition)
@@ -289,7 +314,13 @@ class Base extends ActiveRecord
     }
 
     /**
-     *根据条件查出多条记录
+     * 根据条件查出多条记录
+     * @param array $condition 查询条件
+     * @param string|array|null $order 排序
+     * @param string|array $field 查询字段
+     * @param string|callable|null $indexBy 索引字段
+     * @param bool $returnObject 是否返回对象
+     * @return array|ActiveRecord[]
      */
     public function getAllByCondition($condition, $order = null, $field, $indexBy = null, $returnObject = false)
     {
@@ -310,6 +341,11 @@ class Base extends ActiveRecord
 
     /**
      * 根据多个主键ID查询多条记录
+     * @param array $ids 主键ID数组
+     * @param string|array|null $order 排序
+     * @param string|callable|null $indexBy 索引字段
+     * @param string|array $field 查询字段
+     * @return array
      */
     public function getByIds($ids, $order = null, $indexBy = null, $field = '*')
     {
@@ -329,14 +365,25 @@ class Base extends ActiveRecord
     }
 
     /**
-     *根据条件查出数量
+     * 根据条件获取记录数量
+     * @param array $condition 查询条件
+     * @return int|string
      */
     public function getCount($condition)
     {
         return $this->conditionQuery($condition)->count();
     }
 
-    //分页查询 ssh 2019.9.21
+    /**
+     * 分页查询列表
+     * @param string|array $field 查询字段
+     * @param array $where 查询条件
+     * @param int $page 当前页码
+     * @param int $pageSize 每页数量
+     * @param string|array $order 排序
+     * @param string|array $with 关联查询
+     * @return array ['totalNum' => int, 'totalPage' => int, 'moreData' => int, 'list' => array]
+     */
     public function getList($field, $where, $page, $pageSize, $order = '', $with = '')
     {
         $offset = ($page - 1) * $pageSize;
@@ -360,7 +407,14 @@ class Base extends ActiveRecord
         return $data;
     }
 
-    //查询全部 ssh 2019.11.27
+    /**
+     * 查询全部列表 (不分页)
+     * @param string|array $field 查询字段
+     * @param array $where 查询条件
+     * @param string|array $order 排序
+     * @param string|array $with 关联查询
+     * @return array
+     */
     public function getAllList($field, $where, $order = '', $with = '')
     {
         $query = $this->conditionQuery($where)->select($field);
@@ -374,7 +428,15 @@ class Base extends ActiveRecord
         return $list;
     }
 
-    //查询指定条数 ssh 2019.11.30
+    /**
+     * 查询指定条数的列表
+     * @param string|array $field 查询字段
+     * @param array $where 查询条件
+     * @param int $limit 限制条数
+     * @param string|array $order 排序
+     * @param string|array $with 关联查询
+     * @return array
+     */
     public function getLimitList($field, $where, $limit, $order = '', $with = '')
     {
         $offset = 0;
@@ -390,29 +452,45 @@ class Base extends ActiveRecord
     }
 
     /**
-     * 计数器+1-1
-     * $counters = ['num' => 1] 1数量+1 -1数量-1
-     * $condition = ['id' => $id]
+     * 更新计数器 (原子操作)
+     * @param array $counters 更新的计数器数组，例如 ['view_count' => 1] 表示加1，['view_count' => -1] 表示减1
+     * @param array $condition 更新条件
+     * @param array $params 绑定参数
+     * @return int 更新行数
      */
     public function counters($counters, $condition, $params = [])
     {
         return self::updateAllCounters($counters, $condition, $params);
     }
 
-    // 获取图书的作者
+    /**
+     * 获取图书的作者
+     * @return \yii\db\ActiveQuery
+     * @note 此方法疑似为示例代码，建议检查
+     */
     public function getAuthor()
     {
         //同样第一个参数指定关联的子表模型类名
         return $this->hasOne(Author::className(), ['id' => 'author_id']);
     }
 
-    //根据主键获取被销的信息 ssh 2021.5.18
+    /**
+     * 根据主键获取记录并锁定 (SELECT FOR UPDATE)
+     * @param int|string $id 主键ID
+     * @param string|array $field 查询字段
+     * @return array|ActiveRecord|null
+     */
     public function getLockById($id, $field = '*')
     {
         return self::findBySql('select ' . $field . ' from ' . static::tableName() . ' where id = :id for update', ['id' => $id])->one();
     }
 
-    //求和
+    /**
+     * 求和
+     * @param array $condition 查询条件
+     * @param string $field 求和字段
+     * @return mixed
+     */
     public function sum($condition, $field)
     {
         return $this->conditionQuery($condition)->sum($field);