对于popularize.lib.php的进一步详细注释

core/popularize.lib.php

@@ -1,13 +1,5 @@
 <?php
 namespace LaneWeChat\Core;
-/**
- * 推广支持
- * User: lane
- * Date: 14-10-31
- * Time: 下午4:15
- * E-mail: lixuan868686@163.com
- * WebSite: http://www.lanecn.com
- */
 class Popularize{
     /**
      * 生成带参数的二维码 - 第一步 创建二维码ticket
@@ -18,61 +10,81 @@ class Popularize{
      * 前者有过期时间，最大为1800秒，但能够生成较多数量，后者无过期时间，数量较少（目前参数只支持1--100000）。
      * 两种二维码分别适用于帐号绑定、用户来源统计等场景。
      *
-     * @param $type Int 临时二维码类型为1，永久二维码类型为2
+     * @param int $type 二维码类型，临时二维码类型为1，永久二维码类型为2
-     * @param $expireSeconds Int 过期时间，只在类型为临时二维码时有效。最大为1800，单位秒
+     * @param int $expireSeconds 过期时间，只在类型为临时二维码时有效。最大为1800，单位秒
-     * @param $sceneId Int 场景值ID，临时二维码时为32位非0整型，永久二维码时最大值为100000（目前参数只支持1--100000）
+     * @param int $sceneId 场景值ID，临时二维码时为32位非0整型，永久二维码时最大值为100000（目前参数只支持1--100000）
-     * @return Array(
+     * @return array 返回创建二维码ticket的结果
      *      //获取的二维码ticket，凭借此ticket可以在有效时间内换取二维码。
      *      "ticket"=>"gQH47joAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL2taZ2Z3TVRtNzJXV1Brb3ZhYmJJAAIEZ23sUwMEmm3sUw==",
      *      //二维码的有效时间，以秒为单位。最大不超过1800。
      *      "expire_seconds"=>60,
      *      //二维码图片解析后的地址，开发者可根据该地址自行生成需要的二维码图片
      *      "url"=>"http://weixin.qq.com/q/kZgfwMTm72WWPkovabbI"
-     * )
      */
     public static function createTicket($type, $expireSeconds, $sceneId){
+        // 拼接请求URL，使用AccessToken::getAccessToken()获取access_token
         $queryUrl = 'https://api.weixin.qq.com/cgi-bin/qrcode/create?access_token='.AccessToken::getAccessToken();
+        // 请求方法为POST
         $queryAction = 'POST';
+        // 初始化模板数组
         $template = array();
+        // 根据二维码类型设置模板参数
         if($type == 1){
-            $template['expire_seconds'] = $expireSeconds;
+            $template['expire_seconds'] = $expireSeconds; // 设置临时二维码的有效时间
-            $template['action_name'] = 'QR_SCENE';
+            $template['action_name'] = 'QR_SCENE'; // 设置动作名称为QR_SCENE
         }else{
-            $template['action_name'] = 'QR_LIMIT_SCENE';
+            $template['action_name'] = 'QR_LIMIT_SCENE'; // 设置动作名称为QR_LIMIT_SCENE
         }
+        // 设置场景ID
         $template['action_info']['scene']['scene_id'] = $sceneId;
+        // 将模板数组转换为JSON格式
         $template = json_encode($template);
+        // 调用Curl::callWebServer()方法发送请求并返回结果
         return Curl::callWebServer($queryUrl, $template, $queryAction);
     }
 
     /**
      * 生成带参数的二维码 - 第二步 通过ticket换取二维码
-     * @param $ticket Popularize::createTicket()获得的
+     * @param string $ticket Popularize::createTicket()获得的ticket
-     * @param $filename String 文件路径，如果不为空，则会创建一个图片文件，二维码文件为jpg格式，保存到指定的路径
+     * @param string $filename 文件路径，如果不为空，则会创建一个图片文件，二维码文件为jpg格式，保存到指定的路径
-     * @return 直接echo本函数的返回值，并在调用页面添加header('Content-type: image/jpg');，将会展示出一个二维码的图片。
+     * @return string 直接echo本函数的返回值，并在调用页面添加header('Content-type: image/jpg');，将会展示出一个二维码的图片。
      */
     public static function getQrcode($ticket, $filename=''){
+        // 拼接请求URL，使用urlencode()对ticket进行URL编码
         $queryUrl = 'https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket='.urlencode($ticket);
+        // 请求方法为GET
         $queryAction = 'GET';
+        // 调用Curl::callWebServer()方法发送请求并获取结果
         $result = Curl::callWebServer($queryUrl, '', $queryAction, 0);
+        // 如果指定了保存文件名，则将结果保存到文件
         if(!empty($filename)){
             file_put_contents($filename, $result);
         }
+        // 返回二维码图片内容或保存结果
         return $result;
     }
 
     /**
      * 将一条长链接转成短链接。
-     * 主要使用场景：开发者用于生成二维码的原链接（商品、支付二维码等）太长导致扫码速度和成功率下降，将原长链接通过此接口转成短链接再生成二维码将大大提升扫码速度和成功率。
+     * 主要使用场景：开发者用于生成二维码的原链接（商品、支付二维码等）太长导致扫码速度和成功率下降，
-     * @param $longUrl String 需要转换的长链接，支持http://、https://、weixin://wxpay 格式的url
+     * 将原长链接通过此接口转成短链接再生成二维码将大大提升扫码速度和成功率。
-     * @return array('errcode'=>0, 'errmsg'=>'错误信息', 'short_url'=>'http://t.cn/asdasd')错误码为0表示正常
+     * @param string $longUrl 需要转换的长链接，支持http://、https://、weixin://wxpay 格式的url
+     * @return array 返回短链接结果
+     *      'errcode'=>0, 'errmsg'=>'错误信息', 'short_url'=>'http://t.cn/asdasd'
+     *      错误码为0表示正常
      */
     public static function long2short($longUrl){
+        // 拼接请求URL，使用AccessToken::getAccessToken()获取access_token
         $queryUrl = 'https://api.weixin.qq.com/cgi-bin/shorturl?access_token='.AccessToken::getAccessToken();
+        // 请求方法为POST
         $queryAction = 'POST';
+        // 初始化模板数组
         $template = array();
+        // 设置长链接
         $template['long_url'] = $longUrl;
+        // 设置动作名称为long2short
         $template['action'] = 'long2short';
+        // 调用Curl::callWebServer()方法发送请求并返回结果
         return Curl::callWebServer($queryUrl, '', $queryAction);
     }
 }