README

准备
安装
初始化
使用指南

开发准备

账号要求：已开通网宿云存储，并获取上传密钥，上传域名等
系统要求：PHP 5.4以上

安装说明

通过composer管理项目依赖

"require": {
    "wangsucs/wcs-sdk-php": "^2.0.0"
}

也可下载PHP SDK 后，手动导入

require_once __DIR__ . '/vendor/autoload.php';

PHP SDK加入了并发机制，网络情况不理想时可能出现并发原因导致的异常，可使用无并发机制的简化版

初始化配置说明

用户接入网宿云存储时，需要使用一对有效的AK和SK进行签名认证，并填写“上传域名”和“管理域名”等信息进行文件操作。配置信息只需要在整个应用程序中初始化一次即可，具体操作如下：

/*src/Wcs/Config.php*/
//相关url设置
$WCS_PUT_URL    = 'your uploadDomain';
$WCS_GET_URL    = 'your downloadDomain';
$WCS_MGR_URL	= 'your mgrDomain';

//access key 和 secret key 设置
$WCS_ACCESS_KEY	= 'your access key';
$WCS_SECRET_KEY	= 'your secrete key';

//token的deadline,默认是1小时,也就是3600s
const  WCS_TOKEN_DEADLINE = 3600;

//上传文件设置
const WCS_OVERWRITE = 0; //默认文件不覆盖

//超时时间
const WCS_TIMEOUT = 20;

//分片上传参数设置
const WCS_BLOCK_SIZE = 4 * 1024 * 1024; //默认块大小4M
const WCS_CHUNK_SIZE = 256 * 1024; //默认片大小256K
const WCS_RECORD_URL = './'; //默认当前文件目录
const WCS_COUNT_FOR_RETRY = 3;  //超时重试次数

功能说明

普通上传

普通上传采用表单上传的方式就文件直传到网宿云存储，建议文件小于20M时采用这种上传方式。普通上传支持客户自定义回调通知内容、网页跳转地址和预处理等操作

如果指定了callbackBody参数，云存储将向callbackUrl指定的业务服务器地址发起一个HTTP回调请求。业务服务器根据回调内容完成业务处理，在HTTP Response中自定义的响应内容，网宿云存储接收该响应后，将反馈的数据发送给客户端；如果不指定callbackBody参数，云存储将返回空串给客户端。
如果指定了returnBody和returnUrl，云存储将在上传成功后跳转到returnUrl指定的地址并携带returnBody指定的参数。如果希望上传成功后做预处理，可通过persistentOps参数指定，persistentNotifyUrl可指定处理成功后的通知地址。

范例：

//bucketName 空间名称
//fileKey   自定义文件名
//localFile 上传文件名
//returnBody    自定义返回内容  (可选）
//userParam 自定义变量名    <x:VariableName>    (可选）
//userVars  自定义变量值    <x:VariableValue>   (可选）
//mimeType  自定义上传类型  (可选）

require '../vendor/autoload.php';
use Wcs\Upload\Uploader;
use Wcs\Http\PutPolicy;

$pp = new PutPolicy();
if ($fileKey == null || $fileKey === '') {
    $pp->scope = $bucketName;
} else {
    $pp->scope = $bucketName . ':' . $fileKey;
}

// 通知上传
$pp->returnBody = '';
$pp->returnUrl = '';

// 回调上传
$pp->callbackBody = '';
$pp->callbackUrl = '';

// 预处理
$pp->persistentOps = '<cmd>';

// token有效期，可自定义token有效期截止时间，值为毫秒时间戳；不指定时会按照WCS_TOKEN_DEADLINE配置的有效期计算截止时间戳
$pp->deadline = '<timestamp>'; 
$token = $pp->get_token();

$client = new Uploader($token, $userParam, $userVars, $mimeType);
$resp = $client->upload_return($localFile);
print_r($resp);

命令行测试

$ php file_upload_return.php [-h | --help] -b <bucketName> -f <fileKey> -l <localFile> [-r <returnBody>] [-u <userParam>] [-v <userVars>] [-m <mimeType>]

$ php file_upload_callback.php [-h | --help] -b <bucketName> -f <fileKey> -l <localFile> -c <callbackUrl> [-r <returnBody>] [-u <userParam>] [-v <userVars>] [-m <mimeType>]

$ php file_upload_notify.php [-h | --help] -b <bucketName> -f <fileKey> -l <localFile> -n <notifyUrl> -c <cmd> [-u <userParam>] [-v <userVars>] [-m <mimeType>]

分片上传

分片上传，分片上传大致流程如下：

mkblk(每一块上传前必须先mkblk操作，服务器返回第一片ctx)
bput(mkblk之后进行bput操作，上传每一片附带上一片的ctx并返回当前的ctx)
mkfile(当文件上传完毕，进行mkfile操作，附带每一块的最有一片ctx信息)

注意：

分片上传默认在请求超时情况下会自动重传，其他情况下（状态码非28）报错退出，并将错误信息保存在当前目录的.文件名.log的隐藏文件下。
上传中断后，上传信息保存在隐藏文件.文件名.rcd下，每一条记录为片上传的信息，断点续传会从记录的最后一条信息分析当前上传的状态，并进行后续上传。上传成功后，会删除该记录文件。
断点续传，只需要重新执行一次分片上传操作。
分片上传只在块内作并发，而且是异步回调并发而非多线程并发，考虑到php对多线程操作的支持不是很好，因此采用异步回调的机制，用guzzlehttp实现。
默认块的大小是4M，片的大小256K,这样的目的是为了更稳定的上传，若客户觉得上传速度过慢，想要提高上传速度，只需调整块或片的大小，这样能提升上传的速度（相对来说，上传稳定性可能会降低）
由于有超时重传策略（默认重传3次）来保证传输的可靠性，因此客户如果希望提高上传速度，可将片的大小改为块的大小，保证最大并发数，提高上传速度。
分片上传进度信息在.文件名.rcd下面，以json的格式保存。每上传一片都会写入一条json记录，进度信息保存在$json['info']['progress']这个字段里,客户可根据需要处理该进度信息。
上传成功将删除 .文件名.rcd文件和.文件名.log文件.

变量说明:

//基本信息
private $blockSize;
private $chunkSize;
private $countForRetry;
private $timeoutForRetry;

//用户自定义信息
private $userParam;
private $encodedUserVars;
private $mimeType;

//uuid随机数用 php 的uniqid()
private $uuid;

//断点续传记录文件
private $recordFile;

//断点续传信息
private $localFile;
private $blockNumOfUploaded;    //已经上传的块数量
private $chunkNumOfUploaded;    //当前块已经上传的片数量
private $ctxListForMkfile;  //mkfile操作需要的每一块最后一片ctx
private $sizeOfFile;    //文件大小
private $sizeOfUploaded;    //已经上传的文件大小
private $latestChunkCtx;    //最新的ctx
private $time;  //token生成的时间，用来检验token是否失效

范例:

//bucketName 空间名称
//fileKey   自定义文件名
//localFile 上传文件名

require '../vendor/autoload.php';
use Wcs\Upload\ResumeUploader;
use Wcs\Http\PutPolicy;

$pp = new PutPolicy();
if ($fileKey == null || $fileKey === '') {
    $pp->scope = $bucketName;
} else {
    $pp->scope = $bucketName . ':' . $fileKey;
}

// token有效期，可自定义token有效期截止时间，值为毫秒时间戳；不指定时会按照WCS_TOKEN_DEADLINE配置的有效期计算截止时间戳
$pp->deadline = '<timestamp>'; 

$pp->persistentOps = $cmd;
$pp->persistentNotifyUrl = $notifyUrl;
$pp->returnBody = $returnBody;
$token = $pp->get_token();

$client = new ResumeUploader($token, $userParam, $encodeUserVars, $mimeType);
$client->upload($localFile);

资源管理

提供对文件的基本操作

删除文件

范例

require '../vendor/autoload.php';
use Wcs\SrcManage\FileManager;
use Wcs\MgrAuth;
use Wcs\Config;

$ak = Config::WCS_ACCESS_KEY
$sk = Config::WCS_SECRET_KEY;
$auth = new MgrAuth($ak, $sk);

$client = new FileManager($auth);
print_r($client->delete($bucketName, $fileKey));

命令行测试

$ php file_delete.php [-h | --help] -b <bucketName> -f <fileKey>

获取文件信息

范例

require '../vendor/autoload.php';
use Wcs\SrcManage\FileManager;
use Wcs\MgrAuth;
use Wcs\Config;

$ak = Config::WCS_ACCESS_KEY;
$sk = Config::WCS_SECRET_KEY;
$auth = new MgrAuth($ak, $sk);

$client = new FileManager($auth);
print_r($client->stat($bucketName, $fileKey));

命令行测试

$ php file_stat.php [-h | --help] -b <bucketName> -f <fileKey>

列举资源

范例

require '../vendor/autoload.php';
use Wcs\SrcManage\FileManager;
use Wcs\MgrAuth;
use Wcs\Config;

$ak = Config::WCS_ACCESS_KEY;
$sk = Config::WCS_SECRET_KEY;
$auth = new MgrAuth($ak, $sk);

$client = new FileManager($auth);
print_r($client->bucketList($bucketName, $limit, $prefix, $mode, $marker));

命令行测试

$ php file_download.php [-h | --help] -b <bucketName> [-l <limit>] [-p <prefix>] [-m <mode>] [--ma <marker>]

更新镜像资源

范例

require '../vendor/autoload.php';
use Wcs\SrcManage\FileManager;
use Wcs\MgrAuth;
use Wcs\Config;

$ak = Config::WCS_ACCESS_KEY;
$sk = Config::WCS_SECRET_KEY;
$auth = new MgrAuth($ak, $sk);

//fileKeys = "<fileKey1>|<fileKey2>|<fileKey3>";
$client = new FileManager($auth);
print_r($client->updateMirrorSrc($bucketName, $fileKeys));

命令行测试

   $ php file_stat.php [-h | --help] -b <bucket> -f [<fileKey1>|<fileKey2>|<fileKey3>...]

移动资源

范例

require '../vendor/autoload.php';
use Wcs\SrcManage\FileManager;
use Wcs\MgrAuth;
use Wcs\Config;

$ak = Config::WCS_ACCESS_KEY;
$sk = Config::WCS_SECRET_KEY;
$auth = new MgrAuth($ak, $sk);

$client = new FileManager($auth);
print_r($client->move($bucketSrc, $keySrc, $bucketDst, $keyDst));

命令行测试

$ php file_move.php [-h | --help] --bs <bucketSrc> --ks <keyStr> --bd <bucketDst> --kd <keyDst>

复制资源

范例

require '../vendor/autoload.php';
use Wcs\SrcManage\FileManager;
use Wcs\MgrAuth;
use Wcs\Config;

$ak = Config::WCS_ACCESS_KEY;
$sk = Config::WCS_SECRET_KEY;
$auth = new MgrAuth($ak, $sk);

$client = new FileManager($auth);
print_r($client->copy($bucketSrc, $keySrc, $bucketDst, $keyDst));

命令行测试

$ php file_copy.php [-h | --help] --bs <bucketSrc> --ks <keyStr> --bd <bucketDst> --kd <keyDst>

获取音视频元数据

范例

require '../vendor/autoload.php';
use Wcs\SrcManage\FileManager;
use Wcs\MgrAuth;
use Wcs\Config;

$ak = Config::WCS_ACCESS_KEY;
$sk = Config::WCS_SECRET_KEY;
$auth = new MgrAuth($ak, $sk);

$client = new FileManager($auth);
print_r($client->avInfo($key));

命令行测试

php avinfo.php [-h | --help] -k <key>

获取音视频简单元数据

范例

require '../vendor/autoload.php';
use Wcs\SrcManage\FileManager;
use Wcs\MgrAuth;
use Wcs\Config;

$ak = Config::WCS_ACCESS_KEY;
$sk = Config::WCS_SECRET_KEY;
$auth = new MgrAuth($ak, $sk);

$client = new FileManager($auth);
print_r($client->avInfo2($key));

命令行测试

$ php avinfo2.php [-h | --help] -k <key>

设置文件保存期限

范例：

require '../../vendor/autoload.php';
use Wcs\SrcManage\FileManager;
use Wcs\MgrAuth;
use Wcs\Config;

$ak = Config::WCS_ACCESS_KEY;
$sk = Config::WCS_SECRET_KEY;
$auth = new MgrAuth($ak, $sk);

$client = new FileManager($auth);
print_r($client->setDeadline($bucketName, $fileKey, $deadline));

命令行测试

$ php file_setDeadLine.php [-h | --help] -b <bucketName> -f <fileKey> -d <deadline>

音视频操作

fops操作

require '../../vendor/autoload.php';
use Wcs\PersistentFops\Fops;
use Wcs\Config;
use Wcs\MgrAuth;

//$fops的格式，不同的音视频操作对应不同的fops格式，详细见wcs api 文档

$bucket = '<input key>';
$key = '<input key>';

//参数设置
$notifyURL = '';
$force = 0;
$separate = 0;

//转码指令，如转封装为mp4
$fops = 'avthumb/mp4|saveas/YnVja2V0TmFtZTprZXlOYW1l';

$ak = Config::WCS_ACCESS_KEY;
$sk = Config::WCS_SECRET_KEY;
$auth = new MgrAuth($ak, $sk);

$client = new Fops($auth, $bucket);
print_r($client->exec($fops, $key, $notifyURL, $force, $separate));

fops查询

require '../../vendor/autoload.php';
use Wcs\PersistentFops\Fops;
print_r(Fops::status($persisetntId));

高级资源管理

支持对文件进行异步资源管理操作 1.抓取资源 2.复制资源 3.移动资源 4.删除资源 5.按前缀删除资源 6.fmgr任务查询

抓取资源

require '../../vendor/autoload.php';
use Wcs\Fmgr\Fmgr;
use Wcs\Config;
use Wcs\MgrAuth;
use Wcs\Utils;

//可选参数
$notifyURL = '';
$force = 0;
$separate  = 0;

//fops参数
$fetchURL = Utils::url_safe_base64_encode('https://www.baidu.com/img/bd_logo1.png');
$bucket = Utils::url_safe_base64_encode('<input key>');
$key = Utils::url_safe_base64_encode('<input key>');
$prefix = Utils::url_safe_base64_encode('<input key>');

$fops = 'fops=fetchURL/'.$fetchURL.'/bucket/'.$bucket.'/key/'.$key.'/prefix/'.$prefix.'&notifyURL='.Utils::url_safe_base64_encode($notifyURL).'&force='.$force.'&separate='.$separate;

$ak = Config::WCS_ACCESS_KEY;
$sk = Config::WCS_SECRET_KEY;
$auth = new MgrAuth($ak, $sk);

$client = new Fmgr($auth, $notifyURL, $force, $separate);
print_r($client->fetch($fops));

复制资源

// 请先填写相关字段,$fops字段格式详见wcs api 文档
require '../../vendor/autoload.php';
use Wcs\Fmgr\Fmgr;
use Wcs\Config;
use Wcs\MgrAuth;
use Wcs\Utils;

//可选参数
$notifyURL = '';
$force = 0;
$separate  = 0;

//fops参数
$resource = Utils::url_safe_base64_encode('<input key>');
$bucket = Utils::url_safe_base64_encode('<input key>');
$key = Utils::url_safe_base64_encode('<input key>');
$prefix = Utils::url_safe_base64_encode('<input key>');

$fops = 'fops=resource/'.$resource.'/bucket/'.$bucket.'/key/'.$key.'/prefix/'.$prefix.'&notifyURL='.Utils::url_safe_base64_encode($notifyURL).'&force='.$force.'&separate='.$separate;

$ak = Config::WCS_ACCESS_KEY;
$sk = Config::WCS_SECRET_KEY;
$auth = new MgrAuth($ak, $sk);

$client = new Fmgr($auth, $notifyURL, $force, $separate);
print_r($client->copy($fops));

移动资源

// 请先填写相关字段,$fops字段格式详见wcs api 文档
require '../../vendor/autoload.php';
use Wcs\Fmgr\Fmgr;
use Wcs\Config;
use Wcs\MgrAuth;
use Wcs\Utils;

//可选参数
$notifyURL = '';
$force = 0;
$separate  = 0;

//fops参数
$resource = Utils::url_safe_base64_encode('<input key>');
$bucket = Utils::url_safe_base64_encode('<input key>');
$key = Utils::url_safe_base64_encode('<input key>');
$prefix = Utils::url_safe_base64_encode('<input key>');

$fops = 'fops=resource/'.$resource.'/bucket/'.$bucket.'/key/'.$key.'/prefix/'.$prefix.'&notifyURL='.Utils::url_safe_base64_encode($notifyURL).'&force='.$force.'&separate='.$separate;

$ak = Config::WCS_ACCESS_KEY;
$sk = Config::WCS_SECRET_KEY;
$auth = new MgrAuth($ak, $sk);

$client = new Fmgr($auth, $notifyURL, $force, $separate);
print_r($client->move($fops));

删除资源

// 请先填写相关字段,$fops字段格式详见wcs api 文档
require '../../vendor/autoload.php';
use Wcs\Fmgr\Fmgr;
use Wcs\Config;
use Wcs\MgrAuth;
use Wcs\Utils;

//可选参数
$notifyURL = '';
$force = 0;
$separate  = 0;

//fops参数
$bucket = Utils::url_safe_base64_encode('<input key>');
$key = Utils::url_safe_base64_encode('<input key>');

$fops = 'fops=bucket/'.$bucket.'/key/'.$key.'&notifyURL='.Utils::url_safe_base64_encode($notifyURL).'&force='.$force.'&separate='.$separate;

$ak = Config::WCS_ACCESS_KEY;
$sk = Config::WCS_SECRET_KEY;
$auth = new MgrAuth($ak, $sk);

$client = new Fmgr($auth, $notifyURL, $force, $separate);
print_r($client->delete($fops));

按前缀删除资源

// 请先填写相关字段,$fops字段格式详见wcs api 文档
require '../../vendor/autoload.php';
use Wcs\Fmgr\Fmgr;
use Wcs\Config;
use Wcs\MgrAuth;
use Wcs\Utils;

//可选参数
$notifyURL = '';
$force = 0;
$separate  = 0;

//fops参数
$bucket = Utils::url_safe_base64_encode('<input key>');
$prefix = Utils::url_safe_base64_encode('<input key>');
$output = Utils::url_safe_base64_encode('<input key>');

$fops = 'fops=bucket/'.$bucket.'/prefix/'.$prefix.'&notifyURL='.Utils::url_safe_base64_encode($notifyURL).'&force='.$force.'&separate='.$separate;

$ak = Config::WCS_ACCESS_KEY;
$sk = Config::WCS_SECRET_KEY;
$auth = new MgrAuth($ak, $sk);

$client = new Fmgr($auth, $notifyURL, $force, $separate);
print_r($client->deletePrefix($fops));

多文件压缩

require '../../vendor/autoload.php';
use Wcs\Fmgr\Fmgr;
use Wcs\Config;
use Wcs\MgrAuth;
use Wcs\Utils;


//可选参数
$notifyURL = '';
$force = 0;
$separate  = 0;

//fops参数
$bucket = Utils::url_safe_base64_encode('<input key>');
$keys = Utils::url_safe_base64_encode('<input key1>').'|'.Utils::url_safe_base64_encode('<input key2>');
$keyList = Utils::url_safe_base64_encode('<input keylist>');
$targetSource = Utils::url_safe_base64_encode('<bucket:key>');


// $keys同$keyList同时存在时，$keyList无效
if ($keys) {
    $fops = 'fops=bucket/'.$bucket.'/keys/'.$keys.'/keylist/'.$keyList.'/saveas/'.$targetSource;
}

$ak = Config::WCS_ACCESS_KEY;
$sk = Config::WCS_SECRET_KEY;

$auth = new MgrAuth($ak, $sk);

$client = new Fmgr($auth, $notifyURL, $force, $separate);
$res = $client->compress($fops);
print_r($res->code." ".$res->respBody);
print_r("\n");

fmgr任务查询

// 请先填写相关字段,$fops字段格式详见wcs api 文档
require '../../vendor/autoload.php';
use Wcs\Fmgr\Fmgr;
use Wcs\Config;
use Wcs\MgrAuth;

//可选参数
$notifyURL = '';
$force = 0;
$separate  = 0;

$ak = Config::WCS_ACCESS_KEY;
$sk = Config::WCS_SECRET_KEY;
$auth = new MgrAuth($ak, $sk);

$client = new Fmgr($auth, $notifyURL, $force, $separate);
print_r($client->status("<input persistentId>"));

etag计算

通过SDK提供的方法计算本地文件的etag，可以和上传成功时服务端响应的etag对比来校验已上传成功文件的完整性

wcs_etag.GetEtag($localFile)

wangsucs / wcs-sdk-php

Maintainers

Details

README

开发准备

安装说明

初始化配置说明

功能说明

普通上传

分片上传

资源管理

删除文件

获取文件信息

列举资源

更新镜像资源

移动资源

复制资源

获取音视频元数据

获取音视频简单元数据

设置文件保存期限

音视频操作

fops操作

fops查询

高级资源管理

抓取资源

复制资源

移动资源

删除资源

按前缀删除资源

多文件压缩

fmgr任务查询

etag计算