feat: 完善文档注释

Author: sabakugaara

composer.json

@@ -12,7 +12,8 @@
         "guzzlehttp/guzzle": "~6.0"
     },
     "require-dev": {
-        "phpunit/phpunit": "~4.0"
+        "phpunit/phpunit": "~4.0",
+        "phpdocumentor/phpdocumentor": "^2.9"
     },
     "autoload": {
         "psr-4": { "Upyun\\": "src/Upyun/" }

src/Upyun/Api/Form.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Upyun\Api;
+
+use Upyun\Signature;
+use GuzzleHttp\Client;
+
+class Form extends Rest{
+
+    public function upload($path, $stream, $params) {
+        $params['save-key'] = $path;
+        $params['bucket'] = $this->config->bucketName;
+        if (!isset($params['expiration'])) {
+            $params['expiration'] = time() + 30 * 60 * 60; // 30 分钟
+        }
+
+        $result = Signature::getFormSignature($this->config, $params);
+        $policy = $result['policy'];
+        $signature = $result['signature'];
+        $client = new Client([
+            'timeout' => $this->config->timeout,
+        ]);
+
+        $url = ($this->config->useSsl ? 'https://' : 'http://') . $this->endpoint;
+
+        $response = $client->request('POST', $url, array(
+            'multipart' => array(
+                array(
+                    'name' => 'policy',
+                    'contents' => $policy,
+                ),
+                array(
+                    'name' => 'signature',
+                    'contents' => $signature,
+                ),
+                array(
+                    'name' => 'file',
+                    'contents' => $stream,
+                )
+            )
+        ));
+        return $response->getStatusCode() === 200;
+    }
+}

src/Upyun/Api/Multi.php

@@ -22,9 +22,10 @@ public function __construct(Config $config) {
     }
 
     /**
-     * @param $path upyun storage path
-     * @param Psr7\stream $resource content that will be stored in upyun
-     * @param array $params
+     * @param string $path 文件存储路径
+     * @param Psr7\stream $stream 通过 `Psr7\stream_for` 方法格式化的流资源
+     * @param string $fileHash 文件 md5 值
+     * @param array $params 其他自定义参数
      *
      * @return Psr7\Response
      * @throws \Exception

src/Upyun/Api/Pretreat.php

@@ -25,7 +25,7 @@ public function process($source, $tasks) {
 
         $params = array(
             'bucket_name' => $this->config->bucketName,
-            'notify_url' => $this->config->videoNotifyUrl,
+            'notify_url' => $this->config->processNotifyUrl,
             'source' => $source,
             'tasks' => $encodedTasks,
             'accept' => 'json'

src/Upyun/Config.php

@@ -8,85 +8,89 @@
  */
 class Config {
     /**
-     * @var string
+     * @var string 服务名称
      */
     public $bucketName;
     /**
-     * @var string
+     * @var string 操作员名
      */
     public $operatorName;
     /**
-     * @var string
+     * @var string 操作员密码 md5 hash 值
      */
     public $operatorPassword;
 
     /**
-     * @var bool: if true, use ssl
+     * @var bool 是否使用 https
      */
     public $useSsl;
 
     /**
-     * @var string: REST, use rest api upload file; BLOCK use multipart api upload file; AUTO, decide by file size
+     * @var string 上传使用的接口类型，可以设置为 `REST`：使用 rest api 上传，`AUTO` 根据文件大小自动判断，`BLOCK` 使用断点续传
+     * 当上传小文件时，不推荐使用断点续传；上传时如果设置了异步预处理`withAsyncProcess=true`，将会使用表单 api 上传
      */
     public $uploadType = 'AUTO';
 
     /**
-     * @var int: if upload type is AUTO, when file size big than 10M will choose block upload, else use rest api upload
+     * @var int 上传的接口类型设置为 `AUTO` 时，文件大小的边界值：小于该值时，使用 rest api，否则使用断点续传。 默认 30M
      */
-    public $sizeBoundary = 10485760;
+    public $sizeBoundary = 31457280;
     /**
-     * @var int: max block size 5M
+     * @var int 分块上传`Multi`接口的最大分块值
      */
     public $maxBlockSize = 5242880;
 
+    /**
+     * @var int 分块时，每个块的过期时间
+     */
     public $blockExpiration = 60;
 
     /**
-     * @var int: request timeout seconds
+     * @var int request timeout seconds
      */
     public $timeout = 60;
-    
-    
-    public $videoNotifyUrl;
-    
-    public $formReturnUrl;
-    public $formNotifyUrl;
-    
+
+
+    /**
+     * @var string 异步云处理的回调通知地址
+     */
+    public $processNotifyUrl;
+
     private $version = '3.0.0';
 
 
 
     /**
-     * @var string
+     * @var string 表单 api 的秘钥
      */
     private $formApiKey;
 
     /**
-     * @var string
+     * @var string rest api 和 form api 的接口地址
      */
     static $restApiEndPoint;
 
 
     /**
-     * different route type, detail see http://docs.upyun.com/api/
+     * rest api 和 form api 接口请求地址，详见：http://docs.upyun.com/api/rest_api/
      */
     const ED_AUTO            = 'v0.api.upyun.com';
     const ED_TELECOM         = 'v1.api.upyun.com';
     const ED_CNC             = 'v2.api.upyun.com';
     const ED_CTT             = 'v3.api.upyun.com';
 
     /**
-     * multipart api endpoint
+     * 分块上传接口请求地址
      */
     const ED_FORM            = 'm0.api.upyun.com';
 
     /**
-     * media api endpoint
+     * 异步云处理接口地址
      */
     const ED_VIDEO           = 'p0.api.upyun.com';
 
     /**
-     * purge api endpoint
+     * 刷新接口地址
      */
     const ED_PURGE           = 'http://purge.upyun.com/purge/';
 
@@ -113,8 +117,8 @@ public function getFormApiKey() {
     public function setFormApiKey($key) {
         $this->formApiKey = $key;
     }
-    
+
     public function getVersion() {
-        return $this->version; 
+        return $this->version;
     }
 }

src/Upyun/Uploader.php

@@ -2,7 +2,7 @@
 namespace Upyun;
 
 use Upyun\Api\Rest;
-use Upyun\Api\Multi;
+use Upyun\Api\Form;
 use GuzzleHttp\Psr7;
 
 class Uploader {
@@ -18,11 +18,16 @@ public function __construct(Config $config) {
         $this->config = $config;
     }
 
-    public function upload($path, $file, $params) {
+    public function upload($path, $file, $params, $withAsyncProcess) {
         $stream = Psr7\stream_for($file);
         $size = $stream->getSize();
         $useBlock = $this->needUseBlock($size);
 
+        if ($withAsyncProcess) {
+            $req = new Form($this->config);
+            return $req->upload($path, $stream, $params);
+        }
+
         if(! $useBlock) {
             $req = new Rest($this->config);
             return $req->request('PUT', $path)
@@ -31,11 +36,6 @@ public function upload($path, $file, $params) {
                        ->send();
         } else {
             return $this->pointUpload($path, $stream, $params);
-            /**
-             * 也可以使用分块上传替代, 不推荐使用
-             */
-            //$req = new Multi($this->config);
-            //return $req->upload($path, $stream, Util::md5Hash($file), $params);
         }
     }