fecshop service update: Helper ,Email , Image , Helper ,,etc

services/FecshopLang.php

@@ -12,6 +12,7 @@ namespace fecshop\services;
 use Yii;
 
 /**
+ * language services 语言部分
  * @author Terry Zhao <2358269014@qq.com>
  * @since 1.0
  */
@@ -37,26 +38,17 @@ class Fecshoplang extends Service
     {
         return $attrName.'_'.$langCode;
     }
-
+    /**
+     * @property $attrName | String 属性名称
+     * 得到默认语言的属性名称
+     */
     protected function actionGetDefaultLangAttrName($attrName)
     {
         return $attrName.'_'.$this->defaultLangCode;
     }
-
     /**
-     * 返回所有的，用于mongodb 生成fullSearch的语言名称。
+     * 得到所有的语言简码，譬如：en,es,fr,zh,de等
      */
-    /*
-    protected function actionGetAllmongoSearchLangName(){
-        $arr = [];
-        foreach($this->allLangCode as $codeInfo){
-            $mongoSearchLangName = $codeInfo['mongoSearchLangName'];
-            $arr[] = $mongoSearchLangName;
-        }
-        return $arr;
-    }
-    */
-
     protected function actionGetAllLangCode()
     {
         if (!$this->_allLangCode) {
@@ -82,6 +74,7 @@ class Fecshoplang extends Service
      * @property $attrName|String, attribute name ,like: title ,description.
      * get default language attr value.
      * example getDefaultLangAttrVal(['title_en'=>'xx','title_fr'=>'yy'],'title');
+     * 得到属性默认语言对应的值。上面是title属性默认语言的值。
      */
     protected function actionGetDefaultLangAttrVal($attrVal, $attrName)
     {

services/Image.php

@@ -43,7 +43,9 @@ class Image extends Service
     public $appbase;
 
     /**
-     *  1.1 app front image  Dir.
+     * @property $str | String 图片的相对路径
+     * @property $app | String @appimage下面的文件夹的名称。各个名称对应各个入口的名字，譬如common appfront appadmin等
+     * @return 返回图片的绝对路径。
      */
     protected function actionGetImgDir($str = '', $app = 'common')
     {
@@ -58,10 +60,10 @@ class Image extends Service
         }
     }
 
-    /**
-     *  1.2 app front image  Url*
-     *  example : <?= Yii::$service->image->getImgUrl('custom/logo.png','appfront'); ?>
-     *  it will find image in @appimage/$app.
+   /**
+     * @property $str | String 图片的相对路径
+     * @property $app | String @appimage下面的文件夹的名称。各个名称对应各个入口的名字，譬如common appfront appadmin等
+     * @return 返回图片的完整URL
      */
     protected function actionGetImgUrl($str, $app = 'common')
     {
@@ -78,7 +80,8 @@ class Image extends Service
     }
 
     /**
-     *  2.1 app front image base dir.
+     * @property $app | String @appimage下面的文件夹的名称。各个名称对应各个入口的名字，譬如common appfront appadmin等
+     * @return 返回图片存放目录的绝对路径。
      */
     protected function actionGetBaseImgDir($app = 'common')
     {
@@ -86,7 +89,8 @@ class Image extends Service
     }
 
     /**
-     *  2.2 app front image base Url.
+     * @property $app | String @appimage下面的文件夹的名称。各个名称对应各个入口的名字，譬如common appfront appadmin等
+     * @return 返回图片存放目录的URL
      */
     protected function actionGetBaseImgUrl($app = 'common')
     {
@@ -94,7 +98,8 @@ class Image extends Service
     }
 
     /**
-     * 设置上传图片的最大的size.
+     * @property $uploadSize | Int , 多少MB
+     * 设置上传图片的最大的size. 参数单位为MB
      */
     protected function actionSetMaxUploadSize($uploadSize)
     {
@@ -116,7 +121,7 @@ class Image extends Service
     }
 
     /**
-     * 得到保存图片所在相对根目录的url路径.
+     * 得到（上传）保存图片所在相对根目录的url路径.
      */
     protected function actionGetCurrentBaseImgUrl()
     {
@@ -124,7 +129,7 @@ class Image extends Service
     }
 
     /**
-     * 得到保存图片所在相对根目录的文件夹路径.
+     * 得到（上传）保存图片所在相对根目录的文件夹路径.
      */
     protected function actionGetCurrentBaseImgDir()
     {
@@ -132,6 +137,7 @@ class Image extends Service
     }
 
     /**
+     * @property $str | String , 图片的相对路径字符串
      * 通过图片的相对路径得到产品图片的url.
      */
     protected function actionGetUrlByRelativePath($str)
@@ -140,13 +146,19 @@ class Image extends Service
     }
 
     /**
+     * @property $str | String , 图片的相对路径字符串
      * 通过图片的相对路径得到产品图片的绝对路径.
      */
-    protected function actionGetDirByRelativePath()
+    protected function actionGetDirByRelativePath($str)
     {
         return $this->GetImgDir($this->imageFloder.$str, 'common');
     }
-    
+    /**
+     * @property $name | String , 图片的原始名字，也就是图片上传的时候的名字。
+     * @property $length | String ， 生成图片随机字符的长度。
+     * 随机生成图片的新名字，因为有的图片名字可能是中文或者其他语言，而fecshop在保存名字的时候会取名字的前2个字母生成2层文件夹
+     * 这样中文名字就会出现问题，因此需要使用随机生成的名字（生成2层文件夹，是为了让文件夹下面不至于太多的文件，linux文件夹下的文件超过几万个，查找文件就会有点慢，这样做是为了避免这个文件。）
+     */
     protected function generateImgName( $name,$length = 15 ) { 
         $arr = explode('.',$name);
         $fileType = '.'.$arr[count($arr)-1];
@@ -167,10 +179,9 @@ class Image extends Service
     
     /**
      * @property $param_img_file | Array .
-     * upload image from web page , you can get image from $_FILE['XXX'] ,
-     * $param_img_file is get from $_FILE['XXX'].
-     * return , if success ,return image saved relative file path , like '/b/i/big.jpg'
-     * if fail, reutrn false;
+     * 上传产品图片，
+     * 如果成功，保存产品相对路径，譬如： '/b/i/big.jpg'
+     * 如果失败，reutrn false;
      */
     protected function actionSaveUploadImg($FILE)
     {
@@ -236,6 +247,7 @@ class Image extends Service
      * @property $name|string , image file name ,not contain  image suffix.
      * @property $imageType|string , image file suffix. like '.gif','jpg'
      * return saved Image Name.
+     * 得到产品保存的唯一路径，因为可能存在名字重复的问题，因此使用该函数确保图片路径唯一。
      */
     protected function getUniqueImgNameInPath($imgSaveFloder, $name, $imageType, $randStr = '')
     {

services/helper/AR.php

@@ -13,7 +13,7 @@ use fecshop\services\Service;
 use Yii;
 
 /**
- * AR services.
+ * AR services.（Active Record）
  * @author Terry Zhao <2358269014@qq.com>
  * @since 1.0
  */
@@ -35,16 +35,16 @@ class AR extends Service
      * 		],
      * 	'asArray' => true,
      * ]
+     * 查询方面使用的函数，根据传递的参数，进行query
      */
     public function getCollByFilter($query, $filter)
     {
-        $select = isset($filter['select']) ? $filter['select'] : '';
-        $asArray = isset($filter['asArray']) ? $filter['asArray'] : true;
+        $select     = isset($filter['select']) ? $filter['select'] : '';
+        $asArray    = isset($filter['asArray']) ? $filter['asArray'] : true;
         $numPerPage = isset($filter['numPerPage']) ? $filter['numPerPage'] : $this->numPerPage;
-        $pageNum = isset($filter['pageNum']) ? $filter['pageNum'] : $this->pageNum;
-        $orderBy = isset($filter['orderBy']) ? $filter['orderBy'] : '';
-        $where = isset($filter['where']) ? $filter['where'] : '';
-
+        $pageNum    = isset($filter['pageNum']) ? $filter['pageNum'] : $this->pageNum;
+        $orderBy    = isset($filter['orderBy']) ? $filter['orderBy'] : '';
+        $where      = isset($filter['where']) ? $filter['where'] : '';
         if ($asArray) {
             $query->asArray();
         }
@@ -64,7 +64,6 @@ class AR extends Service
                 }
             }
         }
-
         $offset = ($pageNum - 1) * $numPerPage;
         $query->limit($numPerPage)->offset($offset);
         if ($orderBy) {
@@ -73,7 +72,11 @@ class AR extends Service
 
         return $query;
     }
-
+    /**
+     * @property $model | Object , 数据库model
+     * @property $one | Array ， 数据数组，对model进行赋值
+     * 通过循环的方式，对$model对象的属性进行赋值。
+     */
     public function save($model, $one, $serialize = false)
     {
         if (!$model) {

services/helper/Captcha.php

@@ -12,17 +12,17 @@ namespace fecshop\services\helper;
 use fecshop\services\Service;
 
 /**
- * Helper Captcha services.
+ * Helper Captcha services. 验证码部分
  * @author Terry Zhao <2358269014@qq.com>
  * @since 1.0
  */
 class Captcha extends Service
 {
     public $charset = 'abcdefghkmnprstuvwxyzABCDEFGHKMNPRSTUVWXYZ0123456789'; //随机因子
-    public $codelen = 4; //验证码长度
-    public $width = 130; //宽度
-    public $height = 50; //高度
-    public $fontsize = 20; //指定字体大小
+    public $codelen = 4;    //验证码长度
+    public $width   = 130;  //宽度
+    public $height  = 50;   //高度
+    public $fontsize= 20;  //指定字体大小
     public $case_sensitive = false;
     private $fontcolor; //指定字体颜色
     private $code; //验证码
@@ -37,7 +37,6 @@ class Captcha extends Service
     public function __construct()
     {
         $this->font = dirname(__FILE__).'/captcha/Elephant.ttf'; //注意字体路径要写对，否则显示不了图片
-        //echo $this->font;exit;
     }
 
     //生成随机码
@@ -52,8 +51,8 @@ class Captcha extends Service
     //生成背景
     private function createBg()
     {
-        $this->img = imagecreatetruecolor($this->width, $this->height);
-        $color = imagecolorallocate($this->img, mt_rand(157, 255), mt_rand(157, 255), mt_rand(157, 255));
+        $this->img  = imagecreatetruecolor($this->width, $this->height);
+        $color      = imagecolorallocate($this->img, mt_rand(157, 255), mt_rand(157, 255), mt_rand(157, 255));
         imagefilledrectangle($this->img, 0, $this->height, $this->width, 0, $color);
     }
 

services/helper/Country.php

@@ -19,7 +19,9 @@ use fecshop\services\Service;
 class Country extends Service
 {
     public $default_country;
-
+    /**
+     * 得到默认的国家
+     */
     public function getDefaultCountry()
     {
         if (!$this->default_country) {
@@ -28,7 +30,9 @@ class Country extends Service
 
         return $this->default_country;
     }
-
+    /**
+     * 通过国家，得到省的option html的字符串
+     */
     public function getStateOptionsByContryCode($CountryCode, $selected = '')
     {
         if (!$CountryCode) {
@@ -54,8 +58,9 @@ class Country extends Service
 
         return $str;
     }
-
-    //得到所有国家的option
+    /**
+     * 得到所有国家的option
+     */
     public function getAllCountryOptions($name = 'country', $class = 'country', $current = '', $nullShow = '')
     {
         $all_country_array = $this->getAllCountryArray();
@@ -80,14 +85,18 @@ class Country extends Service
 
         return $str;
     }
-
+    /**
+     * 通过国家简码得到国家的全称名字
+     */
     public function getCountryNameByKey($key)
     {
         $all_country = $this->getAllCountryArray();
 
         return isset($all_country[$key]) ? $all_country[$key] : $key;
     }
-
+    /**
+     * 国家option html
+     */
     public static function getCountryOptionsHtml($selectd = '')
     {
         if (!$selectd) {

services/helper/Errors.php

@@ -34,7 +34,11 @@ class Errors extends Service
             $this->_errors[] = $errros;
         }
     }
-
+    /**
+     * @property $model_errors | Array
+     * Yii2的model在使用rules验证数据格式的时候，报错保存在errors中
+     * 本函数将errors的内容添加到errors services中。
+     */
     public function addByModelErrors($model_errors)
     {
         $error_arr = [];
@@ -60,17 +64,18 @@ class Errors extends Service
      */
     public function get($separator = false)
     {
-        if ($this->_errors) {
-            $errors = $this->_errors;
+        if ($errors = $this->_errors;) {
             $this->_errors = false;
-            if (!$separator) {
-                if ($separator === true) {
-                    $separator = '|';
-                }
+            if(is_array($errors) && !empty($errors)){
+                if ($separator) {
+                    if ($separator === true) {
+                        $separator = '|';
+                    }
 
-                return implode($separator, $errors);
-            } else {
-                return $errors;
+                    return implode($separator, $errors);
+                } else {
+                    return $errors;
+                }
             }
         }
 

services/helper/Format.php

@@ -12,7 +12,7 @@ namespace fecshop\services\helper;
 use fecshop\services\Service;
 
 /**
- * AR services.
+ * Format services.
  * @author Terry Zhao <2358269014@qq.com>
  * @since 1.0
  */
@@ -23,7 +23,7 @@ class Format extends Service
      * @property $number | Float
      * @property $bits | Int
      * @return $number | Float
-     *                 返回格式化形式的
+     * 返回格式化形式的float小数，譬如2 会变成2.00
      */
     public function number_format($number, $bits = 2)
     {

services/helper/MobileDetect.php

@@ -31,7 +31,7 @@ class MobileDetect
 {
     /**
      * Mobile detection type.
-     *
+     * 这是第三方的文件，用来检测设备。是pc mobile等
      * @deprecated since version 2.6.9
      */
     const DETECTION_TYPE_MOBILE = 'mobile';