# PHP SDK

# 源码

https://github.com/SinaCloudStorage/SinaCloudStorage-SDK-PHP (opens new window)

# 下载地址

请从GitHub下载，地址https://github.com/SinaCloudStorage/SinaCloudStorage-SDK-PHP/archive/master.zip (opens new window)。

# 环境要求

PHP版本 >= 5.2.0
需要安装curl扩展

# 调用方式

您可以使用如下两种方式调用SDK：

使用类的方式，$scs = new SCS($scsAccessKey, $scsSecretKey);$scs->getObject(...);
使用静态调用方式，SCS::setAuth($scsAccessKey, $scsSecretKey);SCS::getObject(...);

# 错误信息模式

您可以设置是否开启操作中遇到到的错误返回的格式，是返回异常还是返回Boolean类型，

// $scsAccessKey 和 $scsSecretKey 请从管理面板获取。
SCS::setAuth($scsAccessKey, $scsSecretKey);
SCS::setExceptions(true);

try
{
    $response = SCS::getObjectInfo($bucket, $uri);
    print_r($response);
}
catch(SCSException $e)
{
    echo $e->getMessage();
}

# 获取AccessKey和SecretKey

以下操作都需要使用用到AccessKey和SecretKey，从在线管理平台可以获取（https://scs.sinacloud.com (opens new window)），如下图所示：

提示

请将以下所有例子中的AccessKey和SecretKey替换为您自己的AccessKey和SecretKey。

# 关于引用文件SCS.php

提示

所有的例子中都引用了云存储的类SCS.php文件，请从 https://github.com/SinaCloudStorage/SinaCloudStorage-SDK-PHP/blob/master/class/SCS.php (opens new window) 获取，下文不再单独说明。

# bucket操作示例

# 获取bucket列表（不含详细信息）

# 示例代码

<?php
require ('./SCS.php');
// 换成你的AccessKey
$accessKey = 'AccessKey';
// 换成你的SecretKey
$secretKey = 'SecretKey';
$scs_instance = new SCS($accessKey, $secretKey);
$bucket_list = $scs_instance->listBuckets();
var_dump($bucket_list);

# 返回结果样例

array(9) {
  [0]=>
  string(13) "sinaappengine"
  [1]=>
  string(10) "opensource"
  [2]=>
  string(25) "opensource.changes.com.cn"
  [3]=>
  string(19) "test.changes.com.cn"
  [4]=>
  string(18) "cdn.changes.com.cn"
  [5]=>
  string(19) "imgx.changes.com.cn"
  [6]=>
  string(21) "cccccc.changes.com.cn"
  [7]=>
  string(19) "show.changes.com.cn"
  [8]=>
  string(9) "lazytools"
}

# 代码下载

点击下载

# 获取bucket列表（含详细信息）

# 示例代码

<?php
require ('./SCS.php');
// 换成你的AccessKey
$accessKey = 'AccessKey';
// 换成你的SecretKey
$secretKey = 'SecretKey';
$scs_instance = new SCS($accessKey, $secretKey);
$bucket_list = $scs_instance->listBuckets(true);
var_dump($bucket_list);

# 返回结果样例

array(2) {
  ["owner"]=>
  array(2) {
    ["id"]=>
    string(20) "SINA0000000000K7Y55F"
    ["name"]=>
    string(0) ""
  }
  ["buckets"]=>
  array(9) {
    [0]=>
    array(3) {
      ["name"]=>
      string(13) "sinaappengine"
      ["time"]=>
      int(1406535268)
      ["consumed_bytes"]=>
      string(10) "1678676465"
    }
    [1]=>
    array(3) {
      ["name"]=>
      string(10) "opensource"
      ["time"]=>
      int(1421376381)
      ["consumed_bytes"]=>
      string(10) "2620494842"
    }
    [2]=>
    array(3) {
      ["name"]=>
      string(25) "opensource.changes.com.cn"
      ["time"]=>
      int(1421817544)
      ["consumed_bytes"]=>
      string(1) "0"
    }
    [3]=>
    array(3) {
      ["name"]=>
      string(19) "test.changes.com.cn"
      ["time"]=>
      int(1465986857)
      ["consumed_bytes"]=>
      string(1) "0"
    }
    [4]=>
    array(3) {
      ["name"]=>
      string(18) "cdn.changes.com.cn"
      ["time"]=>
      int(1484656236)
      ["consumed_bytes"]=>
      string(1) "0"
    }
    [5]=>
    array(3) {
      ["name"]=>
      string(19) "imgx.changes.com.cn"
      ["time"]=>
      int(1490666704)
      ["consumed_bytes"]=>
      string(1) "0"
    }
    [6]=>
    array(3) {
      ["name"]=>
      string(21) "cccccc.changes.com.cn"
      ["time"]=>
      int(1492159233)
      ["consumed_bytes"]=>
      string(1) "0"
    }
    [7]=>
    array(3) {
      ["name"]=>
      string(19) "show.changes.com.cn"
      ["time"]=>
      int(1492690801)
      ["consumed_bytes"]=>
      string(1) "0"
    }
    [8]=>
    array(3) {
      ["name"]=>
      string(9) "lazytools"
      ["time"]=>
      int(1513513181)
      ["consumed_bytes"]=>
      string(10) "8105267027"
    }
  }
}

# 代码下载

点击下载

# 创建bucket

# 示例代码

<?php 
require ('./SCS.php');
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
$scs_instance = new SCS($accessKey, $secretKey);
// 这里的bucket名称请换成你需要的bucket 名称
$bucket_name = substr(md5($accessKey),0, 10);
$create_ret = $scs_instance->putBucket($bucket_name, SCS::ACL_PUBLIC_READ);
var_dump($create_ret);

# 返回值

bool(true)

# 代码下载

点击下载

# 删除bucket

# 示例代码

<?php
require ('./SCS.php');
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
$scs_instance = new SCS($accessKey, $secretKey);
// 这里换为需要删除的bucket名称
$bucket_name = substr(md5($accessKey),0, 10);
$create_ret = $scs_instance->deleteBucket($bucket_name);
var_dump($create_ret);

# 返回值

bool(true)

# 代码下载

点击下载

说明

如果bucket中还有文件，则bucket不允许删除，需要先遍历删除所有的bucket下的文件，才可以删除bucket。

# object文件操作

# 从文件上传

# 说明

这个例子演示了如何将一个本地的文件上传到云存储的bucket的某个制定的路径。

说明

如果服务端是从表单的提交值中获取文件，直接将下面的文件路径改为$_FILES['file']['tmp_name']即可，其中file是表单中文件选择的name。

# 示例代码

<?php
require('./SCS.php');
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
$scs_instance = new SCS($accessKey, $secretKey);

/*这里换成你自己的bucket名称*/
$bucket = 'sinaappengine';
/*本地的文件*/
$file_local = 'bird.txt';
/*如果是从表单获取的文件可以按下面的方式写文件路径*/
//$file_local = $_FILES['file']['tmp_name'];
/*写到bucket中的路径，故意加了一个example_folder的前缀*/
$file_remote = sprintf('example_folder/%s', $file_local);
// SCS::ACL_PUBLIC_READ 表示文件可以匿名访问
// SCS::ACL_PRIVATE权限则为私有，需要加签名才能访问
$ret = $scs_instance->putObject($scs_instance->inputFile($file_local, false), $bucket, $file_remote, SCS::ACL_PUBLIC_READ);

var_dump($ret);

# 返回值

bool(true)

# 代码下载

点击下载

# 从字符串上传

# 说明

这个例子演示了如何将一个字符串内容写入到云存储的bucket的某个制定的路径。

说明

云存储的文件不支持追加写，如果需要追加写文件需要先读出原有的文件内容，从程序中拼接再重新写入。

# 示例代码

<?php
require ('./SCS.php');
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
$scs_instance = new SCS($accessKey, $secretKey);

/*这里换成你自己的bucket名称*/
$bucket = 'sinaappengine';

$content = 'something to write';
/*写到bucket中的路径，故意加了一个example_folder的前缀*/
$file_remote = sprintf('example_folder/%s', 'file_from_string.txt');
// SCS::ACL_PUBLIC_READ 表示文件可以匿名访问
// SCS::ACL_PRIVATE权限则为私有，需要加签名才能访问
$ret = $scs_instance->putObject($content, $bucket, $file_remote, SCS::ACL_PUBLIC_READ, array(), array('Content-Type' => 'text/plain'));

var_dump($ret);

# 返回值

bool(true)

# 说明

从字符串上传时需要手工制定content-type，否则将被设置为 application/octet-stream，这样浏览器再直接打开时会启动下载，而不是直接渲染
写入的字符串可以是任意的内容，可以为二进制内容

# 代码下载

点击下载

# 创建一个文件夹

注意

云存储的文件夹是一个特殊名称的文件，例如example_folder文件夹下的222文件夹实际对应的是example_folder/222/，这个文件的大小为0，文件类型为application/octet-stream。因此创建文件的时候只需要创建这个特殊的文件即可。

# 示例代码

<?php
require ('./SCS.php');
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
$scs_instance = new SCS($accessKey, $secretKey);

/*这里换成你自己的bucket名称*/
$bucket = 'sinaappengine';

$content = '';
$file_remote = 'example_folder/333/';
// SCS::ACL_PUBLIC_READ 表示文件可以匿名访问
// SCS::ACL_PRIVATE权限则为私有，需要加签名才能访问
$ret = $scs_instance->putObject($content, $bucket, $file_remote, SCS::ACL_PUBLIC_READ, array(), array('Content-Type' => 'application/octet-stream'));

var_dump($ret);

以上代码将创建将在example_folder下创建一个名字叫333的文件夹。

# 执行结果

bool(true)

# 代码下载

点击下载

# 获取object列表（不含分隔符，不返回CommonPrefixes）

# 描述

获取某个路径下的文件列表，不使用分隔符，不返回CommonPrefixes，返回值将所有的前缀（文件夹）和文件都对待为文件，文件路径如下图所示：

# 示例代码

<?php
require ('./SCS.php');
// 这里替换为你的AccessKey和SecretKey
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
// 这里替换为你的bucket名称
$bucket = 'sinaappengine';
$scs_instance = new SCS($accessKey, $secretKey);

$object_list = $scs_instance->getBucket($bucket, 'example_folder/', null, 10, '', false, $nextMarker, $isTruncated);
var_dump($object_list, $nextMarker, $isTruncated);

# 返回信息

array(4) {
  ["example_folder/222/"]=>
  array(7) {
    ["name"]=>
    string(19) "example_folder/222/"
    ["time"]=>
    int(1536226301)
    ["type"]=>
    string(24) "application/octet-stream"
    ["owner"]=>
    string(20) "SINA0000000000K7Y55F"
    ["size"]=>
    int(0)
    ["md5"]=>
    string(32) "d41d8cd98f00b204e9800998ecf8427e"
    ["sha1"]=>
    string(40) "da39a3ee5e6b4b0d3255bfef95601890afd80709"
  }
  ["example_folder/333/"]=>
  array(7) {
    ["name"]=>
    string(19) "example_folder/333/"
    ["time"]=>
    int(1536230337)
    ["type"]=>
    string(24) "application/octet-stream"
    ["owner"]=>
    string(20) "SINA0000000000K7Y55F"
    ["size"]=>
    int(0)
    ["md5"]=>
    string(32) "d41d8cd98f00b204e9800998ecf8427e"
    ["sha1"]=>
    string(40) "da39a3ee5e6b4b0d3255bfef95601890afd80709"
  }
  ["example_folder/bird.txt"]=>
  array(7) {
    ["name"]=>
    string(23) "example_folder/bird.txt"
    ["time"]=>
    int(1536223092)
    ["type"]=>
    string(10) "text/plain"
    ["owner"]=>
    string(20) "SINA0000000000K7Y55F"
    ["size"]=>
    int(31)
    ["md5"]=>
    string(32) "4a352a50064f0e93d3e1fd3eefd011b5"
    ["sha1"]=>
    string(40) "a1a3733242c95a736e017d2fd36cf53f63d12970"
  }
  ["example_folder/file_from_string.txt"]=>
  array(7) {
    ["name"]=>
    string(35) "example_folder/file_from_string.txt"
    ["time"]=>
    int(1536225607)
    ["type"]=>
    string(10) "text/plain"
    ["owner"]=>
    string(20) "SINA0000000000K7Y55F"
    ["size"]=>
    int(18)
    ["md5"]=>
    string(32) "e3aec7e6407da835ef01a2027e9f7960"
    ["sha1"]=>
    string(40) "d4efba551f4f012ee51d09ba7680e39cf251302e"
  }
}
string(35) "example_folder/file_from_string.txt"
bool(false)

返回值说明

$nextMarker的返回值为example_folder/file_from_string.txt，表示下次请求查询剩余的文件时应该传递的marker参数值
$isTruncated的值为false，为false表示之后没有其他的文件，为true表示后面还有其他的文件
文件列表是一个数组，其中包含了文件的详细信息

# 代码下载

点击下载

# 获取object列表（分隔符为/，返回CommonPrefixes）

# 描述

获取某个路径下的文件列表，使用分隔符 /，返回CommonPrefixes，文件路径如下图所示：

# 示例代码

<?php
require ('./SCS.php');
// 这里替换为你的AccessKey和SecretKey
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
// 这里替换为你的bucket名称
$bucket = 'sinaappengine';
$scs_instance = new SCS($accessKey, $secretKey);

$object_list = $scs_instance->getBucket($bucket, 'example_folder/', null, 10, '/', true, $nextMarker, $isTruncated);
var_dump($object_list, $nextMarker, $isTruncated);

# 返回值

array(4) {
  ["example_folder/222/"]=>
  array(1) {
    ["prefix"]=>
    string(19) "example_folder/222/"
  }
  ["example_folder/333/"]=>
  array(1) {
    ["prefix"]=>
    string(19) "example_folder/333/"
  }
  ["example_folder/bird.txt"]=>
  array(7) {
    ["name"]=>
    string(23) "example_folder/bird.txt"
    ["time"]=>
    int(1536223092)
    ["type"]=>
    string(10) "text/plain"
    ["owner"]=>
    string(20) "SINA0000000000K7Y55F"
    ["size"]=>
    int(31)
    ["md5"]=>
    string(32) "4a352a50064f0e93d3e1fd3eefd011b5"
    ["sha1"]=>
    string(40) "a1a3733242c95a736e017d2fd36cf53f63d12970"
  }
  ["example_folder/file_from_string.txt"]=>
  array(7) {
    ["name"]=>
    string(35) "example_folder/file_from_string.txt"
    ["time"]=>
    int(1536225607)
    ["type"]=>
    string(10) "text/plain"
    ["owner"]=>
    string(20) "SINA0000000000K7Y55F"
    ["size"]=>
    int(18)
    ["md5"]=>
    string(32) "e3aec7e6407da835ef01a2027e9f7960"
    ["sha1"]=>
    string(40) "d4efba551f4f012ee51d09ba7680e39cf251302e"
  }
}
string(35) "example_folder/file_from_string.txt"
bool(false)

说明

如果文件的详细信息的数组中包含 prefix，则说明当前文件时一个前缀（文件夹）

# 代码下载

点击下载

# 获取object文件内容

# 描述

本示例通过SDK获取某个object的文件内容。

# 示例代码

<?php
require ('./SCS.php');
// 这里替换为你的AccessKey和SecretKey
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
// 这里替换为你的bucket名称
$bucket = 'sinaappengine';
$scs_instance = new SCS($accessKey, $secretKey);
$file_remote = 'example_folder/file_from_string.txt';
$ret = $scs_instance->getObject($bucket, $file_remote);

var_dump($ret);

# 返回值

object(stdClass)#4 (4) {
  ["error"]=>
  bool(false)
  ["body"]=>
  string(18) "something to write"
  ["headers"]=>
  array(6) {
    ["date"]=>
    int(1536232386)
    ["type"]=>
    string(10) "text/plain"
    ["size"]=>
    int(18)
    ["time"]=>
    int(1536225607)
    ["hash"]=>
    string(32) "e3aec7e6407da835ef01a2027e9f7960"
    ["x-amz-meta-crc32"]=>
    string(8) "F881BE78"
  }
  ["code"]=>
  int(200)
}

返回值说明

返回值是一个对象
body为文件的内容
header为返回的HTTP header的部分
code是本次请求的HTTP code

# 将文件下载到本地

# 描述

通过SDK将云存储中的某个object下载到本地文件系统。

# 代码示例

<?php
require ('./SCS.php');
// 这里替换为你的AccessKey和SecretKey
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
/*这里换成你自己的bucket名称*/
$bucket = 'sinaappengine';

$scs_instance = new SCS($accessKey, $secretKey);
$file_remote = 'example_folder/file_from_string.txt';
$temp_file = tempnam(sys_get_temp_dir(), 'Tux');
$ret = $scs_instance->getObject($bucket, $file_remote, $temp_file);

var_dump($ret, file_get_contents($temp_file));

# 返回值


object(stdClass)#4 (4) {
  ["error"]=>
  bool(false)
  ["body"]=>
  NULL
  ["headers"]=>
  array(6) {
    ["date"]=>
    int(1536234930)
    ["type"]=>
    string(10) "text/plain"
    ["size"]=>
    int(18)
    ["time"]=>
    int(1536225607)
    ["hash"]=>
    string(32) "e3aec7e6407da835ef01a2027e9f7960"
    ["x-amz-meta-crc32"]=>
    string(8) "F881BE78"
  }
  ["code"]=>
  int(200)
}
string(18) "something to write"

注意

返回值的的body为空，但是可以获取header中关于文件信息的描述。

# 代码下载

点击下载

# 获取object的meta信息

# 描述

通过SDK获取文件的元信息，返回创建时间、文件content-type、MD5值等。

# 示例代码

<?php
require ('./SCS.php');
// 这里替换为你的AccessKey和SecretKey
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
// 这里替换为你的bucket名称
$bucket = 'sinaappengine';
$scs_instance = new SCS($accessKey, $secretKey);
$file_remote = 'example_folder/file_from_string.txt';
$ret = $scs_instance->getObjectInfo($bucket, $file_remote, true);
var_dump($ret);

# 返回值

array(5) {
  ["date"]=>
  int(1536233410)
  ["type"]=>
  string(16) "application/json"
  ["time"]=>
  int(1536225607)
  ["hash"]=>
  string(32) "e3aec7e6407da835ef01a2027e9f7960"
  ["x-amz-meta-crc32"]=>
  string(8) "F881BE78"
}

# 代码下载

点击下载

# 云端拷贝文件

# 描述

将bucket的object A拷贝为object B，A和B的文件内容一致，不需要将文件下载到本地再上传。

拷贝前的文件路径：

# 示例代码

<?php 
require ('./SCS.php');
// 这里替换为你的AccessKey和SecretKey
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
// 这里替换为你的bucket名称
$bucket = 'sinaappengine';
$scs_instance = new SCS($accessKey, $secretKey);

$file_remote = 'example_folder/file_from_string.txt';
$file_remote_copy = 'example_folder/file_from_string_copy.txt';
$ret = $scs_instance->copyObject($bucket, $file_remote, $bucket, $file_remote_copy);

var_dump($ret);

# 返回值

bool(true)

# 拷贝后的文件路径

# 删除一个object

# 描述

删除一个指定路径的文件。

# 示例代码

<?php
require ('./SCS.php');
/*这里换成你的AccessKey和SecretKey*/
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
/*这里换成你自己的bucket名称*/
$bucket = 'sinaappengine';
$scs_instance = new SCS($accessKey, $secretKey);
$file_remote_delete = 'example_folder/file_from_string_copy.txt';
$ret = $scs_instance->deleteObject($bucket, $file_remote_delete);

var_dump($ret);

# 返回值

bool(true)

# 代码下载

点击下载

# 文件访问权限设置

# 描述

获取文件的访问权限，设置文件的新访问权限。

# 示例代码

<?php
require('./SCS.php');
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
/*这里换成你自己的bucket名称*/
$bucket = 'sinaappengine';

$scs_instance = new SCS($accessKey, $secretKey);
$file_remote = 'example_folder/file_from_string.txt';
$ret = $scs_instance->getAccessControlPolicy($bucket, $file_remote);
var_dump($ret);
if ($ret) {
    /*重新设置ACL*/
    $acp = array(
        'GRPS000000ANONYMOUSE' => array('read', 'write'),
        'GRPS0000000CANONICAL' => array('read', 'write'),
        $ret['owner'] => array('read', 'write', 'read_acp', 'write_acp')
    );
    $set_ret = $scs_instance->setAccessControlPolicy($bucket, $file_remote, $acp);
    var_dump($set_ret);
    if ($set_ret) {
        /*重新获取权限*/
        $new_rights = $scs_instance->getAccessControlPolicy($bucket, $file_remote);
        var_dump($new_rights);
    }
}

# 返回值

array(2) {
  ["owner"]=>
  string(20) "SINA0000000000K7Y55F"
  ["acl"]=>
  array(2) {
    ["GRPS000000ANONYMOUSE"]=>
    array(2) {
      [0]=>
      string(4) "read"
      [1]=>
      string(5) "write"
    }
    ["SINA0000000000K7Y55F"]=>
    array(4) {
      [0]=>
      string(4) "read"
      [1]=>
      string(5) "write"
      [2]=>
      string(8) "read_acp"
      [3]=>
      string(9) "write_acp"
    }
  }
}
bool(true)
array(2) {
  ["owner"]=>
  string(20) "SINA0000000000K7Y55F"
  ["acl"]=>
  array(3) {
    ["GRPS000000ANONYMOUSE"]=>
    array(2) {
      [0]=>
      string(4) "read"
      [1]=>
      string(5) "write"
    }
    ["GRPS0000000CANONICAL"]=>
    array(2) {
      [0]=>
      string(4) "read"
      [1]=>
      string(5) "write"
    }
    ["SINA0000000000K7Y55F"]=>
    array(4) {
      [0]=>
      string(4) "read"
      [1]=>
      string(5) "write"
      [2]=>
      string(8) "read_acp"
      [3]=>
      string(9) "write_acp"
    }
  }
}

# 代码下载

点击下载

# 分片上传

# 描述

本示例演示了如何通过分片上传问题，分片上传适合大文件上传场景，先使用Linux dd命令生成一个2MB的文件：

dd if=/dev/zero of=2M.file bs=1M count=2

# 示例代码

使用PHP SDK分片上传这个2MB的文件：

<?php
require('./SCS.php');
/*这里换成你的AccessKey和SecretKey*/
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
/*这里换成你自己的bucket名称*/
$bucket = 'sinaappengine';
$scs_instance = new SCS($accessKey, $secretKey);
$scs_instance->setExceptions(true);
/*本地的文件*/
$file = '2M.file';
/*写到云存储中的路径*/
$object = 'example_folder/'.$file;
try {
    //初始化上传
    $info = $scs_instance->initiateMultipartUpload($bucket, $object, SCS::ACL_PUBLIC_READ);
    $uploadId = $info['upload_id'];
    $fp = fopen($file, 'rb');
    $i = 1;
    $part_info = array();

    while (!feof($fp)) {
        /*上传分片，一个分片512KB*/
        $res = $scs_instance->putObject($scs_instance->inputResourceMultipart($fp, 1024 * 512, $uploadId, $i), $bucket, $object);
        if (isset($res['hash'])) {
            echo 'Part: ' . $i . " OK! \n";
            $part_info[] = array(
                'PartNumber' => $i,
                'ETag' => $res['hash'],
            );
        }
        $i++;
    }

    //列分片
    $parts = $scs_instance->listParts($bucket, $object, $uploadId);

    if (count($parts) > 0 && count($parts) == count($part_info)) {
        foreach ($parts as $part_number => $part) {
            if ($part['etag'] != $part_info[$part_number - 1]['ETag']) {
                exit('part not match');
                break;
            }
        }
        //合并分片
        echo "start complete action\n";
        $scs_instance->completeMultipartUpload($bucket, $object, $uploadId, $part_info);
        echo "upload success\n";
        fclose($fp);
    }
} catch (SCSException $e) {
    echo $e->getMessage();
}

# 返回值

Part: 1 OK! Part: 2 OK! Part: 3 OK! Part: 4 OK! Part: 5 OK! start complete action upload success

上传后的文件路径：

# 代码下载

点击下载

# 批量上传

# 描述

本示例演示了如何将本地的一个文件夹批量上传到云存储中。

说明

云存储没有批量上传的接口，因此需要遍历本地的文件循环上传。

# 示例代码

示例代码运行环境需要注意

以下代码需要在Linux和MAC环境下使用，如果用在Windows环境下，需要修改文件分隔符等。

示例代码将本地的bbb目录下的所有文件上传到云存储中的aaa目录下，并保留bbb下的目录结构：

<?php 
require ('./SCS.php');
// 这里替换为你的AccessKey和SecretKey
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
// 这里替换为你的bucket名称
$bucket = 'sinaappengine';
$scs_instance = new SCS($accessKey, $secretKey);

/*上传到的根目录，可以留空，留空表示上传到bucket的根目录下*/
$upload_folder = 'aaa';
/*本地的目录，可以写绝对路径*/
$local_folder = './bbb';

function get_files($dir)
{
    $files = array();
    for (; $dir->valid(); $dir->next()) {
        if ($dir->isDir() && !$dir->isDot()) {
            if ($dir->haschildren()) {
                $files = array_merge($files, get_files($dir->getChildren()));
            };
        } else if ($dir->isFile()) {
            $files[] = $dir->getPathName();
        }
    }
    return $files;
}
$dir = new RecursiveDirectoryIterator($local_folder);
$all_files = get_files($dir);
if (!$all_files) {
    echo(sprintf("Nothing to sync\n"));
    exit(0);
}
// 上传文件的前缀
if ($upload_folder) {
    $upload_folder = trim($upload_folder, '/');
}
$tmp_folder_length = strlen($local_folder);
foreach ($all_files as $f) {
    if (is_link($f)) {
        // 忽略链接文件
        continue;
    }
    $file_path_local = substr($f, $tmp_folder_length);
    $file_path_remote = $upload_folder.$file_path_local;
    $file_path_remote = ltrim($file_path_remote, '/');
    $input['file'] = $f;
    $ret = $scs_instance->putObject($input, $bucket, $file_path_remote, SCS::ACL_PUBLIC_READ);
    if (!$ret) {
        echo(sprintf("Upload file: %s to SCS failed.\n", $f));
        continue;
    }
}
echo("Upload all file success\n");

# 返回值

Upload all file success

# 上传后的文件路径

从云存储管理面板（https://scs.sinacloud.com (opens new window)）可以看到上传后的文件结构。

# 代码下载

点击下载

# 批量删除

# 描述

本示例演示如何批量删除bucket中的文件。

说明

云存储没有批量删除的接口，需要遍历文件调用单个文件删除接口删除，如果文件较多删除的时间会比较长，建议使用PHP CLI环境从命令行执行。

# 示例程序

<?php
require('./SCS.php');
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
/*这里换成你自己的bucket名称*/
$bucket = 'sinaappengine';

$scs_instance = new SCS($accessKey, $secretKey);

/*这里替换为空则删除所有的文件*/
$delete_file_path = 'aaa';

$marker = null;
try {
    while ($ret = $scs_instance->getBucket($bucket, $delete_file_path, $marker, 1000, null, false, $nextMarker, $isTruncated)) {
        foreach ($ret as $s) {
            $uri = $s['name'];
            echo(sprintf("start delete file: %s\n", $uri));
            $ret = $scs_instance->deleteObject($bucket, $uri);
        }
        if (!$isTruncated) {
            /*没有更多的文件了。*/
            break;
        } else {
            $marker = $nextMarker;
        }
    }
} catch (Exception $e) {
    /*程序出现异常*/
    var_dump($e->getMessage());
}

# 返回值

start delete file: aaa/1.txt
start delete file: aaa/2.txt

# 批量下载

# 描述

本示例演示将云存储bucket中某个目录下的所有文件下载到本地。

说明

云存储没有批量下载的接口，需要遍历所有的文件，然后调用下载接口，将文件保存到本地。

# 示例代码

<?php
require('./SCS.php');
// 这里替换为你的AccessKey和SecretKey
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
// 这里替换为你的bucket名称
$bucket = 'sinaappengine';

$scs_instance = new SCS($accessKey, $secretKey);

/*这里替换为空则下载所有的文件*/
$download_file_path = 'aaa';
$local_folder_path = '/tmp/';

$marker = null;
try {
    while ($ret = $scs_instance->getBucket($bucket, $download_file_path, $marker, 1000, null, false, $nextMarker, $isTruncated)) {
        foreach ($ret as $s) {
            $uri = $s['name'];
            echo(sprintf("start download file: %s\n", $uri));
            $local_path = sprintf('%s%s', $local_folder_path, $uri);
            $local_path_parse = pathinfo($local_path);
            if (!file_exists($local_path_parse['dirname'])) {
                mkdir($local_path_parse['dirname'], 0777, true);
            }
            $scs_instance->getObject($bucket, $uri, $local_path);
        }
        if (!$isTruncated) {
            /*没有更多的文件了。*/
            break;
        } else {
            $marker = $nextMarker;
        }
    }
} catch (Exception $e) {
    /*程序出现异常*/
    var_dump($e->getMessage());
}

# 程序输出

[root@yq230/tmp/lazy2/git]#php batch_download.php 
start download file: aaa/1.txt
start download file: aaa/2.txt

# 查看下载到本地的文件结构

# 大文件上传

服务端：大文件上传请使用 分片上传 接口；
浏览器：大文件上传请使用 表单上传 接口，表单上传请见下面的说明文档。

# 表单上传

# 描述

表单API是云存储POST上传文件的实际应用，方便您可以直接让终端用户直接从浏览器上传文件到云存储，而不需要先让文件上传到您的程序，然后从您的程序写入到云存储中，实现的流程为：

# 示例代码

<?php
require ('./SCS.php');
// 这里替换为你的AccessKey和SecretKey
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
// 这里替换为你的bucket名称
$bucket = 'sinaappengine';
$scs_instance = new SCS($accessKey, $secretKey);
/*可以为空，表示上传到根目录下*/
$path = 'myfiles/';
/*上传参数的有效时间，超出这个时间上传的参数就会失效*/
$lifetime = 3600;
/*用户最大上传尺寸的控制，如果你的用户选择的文件大于这个设置，上传将会失败，当前设置是50MB*/
$maxFileSize = (1024 * 1024 * 50);
/*写入文件的meta信息，例如设置是哪个用户写入的*/
$metaHeaders = array('uid' => 123);
/*设定写入文件的content-type，此处设置application/octet-stream写入后所有的文件都会是下载的格式*/
$requestHeaders = array(
    'Content-Type' => 'application/octet-stream',
    'Content-Disposition' => 'attachment; filename=${filename}'
);
$params = $scs_instance->getHttpUploadPostParams(
    $bucket,
    $path,
    SCS::ACL_PUBLIC_READ,
    $lifetime,
    $maxFileSize,
    201, // Or a URL to redirect to on success
    $metaHeaders,
    $requestHeaders,
    false // False since we're not using flash
);
$uploadURL = 'http://' . $bucket . '.sinacloud.net/';
?><!DOCTYPE html>
<html lang="zh-cn">
<head>
    <meta charset="utf-8">
    <title>SCS Form Upload</title>
</head>
<body>
<form method="post" action="<?php echo $uploadURL; ?>" enctype="multipart/form-data">
    <?php
    foreach ($params as $p => $v)
        echo "<input type=\"hidden\" name=\"{$p}\" value=\"{$v}\" />\n";
    ?>
    <input type="file" name="file" />&#160;<input type="submit" value="Upload" />
</form>
</body>
</html>

# 选择需要的文件上传

从表单选择需要上传的文件：

# 上传后

上传完成后可以看到上传的文件：

# 获取文件访问链接

关于签名

匿名用户没有读权限的文件必须带签名才能访问，否则访问会报403错误；
文件的URL中签名都含有过期时间属性，超出过期时间的链接将无法访问。

# AccessDenied错误

如果私有的文件匿名访问会提示 AccessDenied，如下图所示：

# ExpiredToken错误

如果链接超出了有效的时间，访问的时候会提示ExpiredToken，如下图所示：

# SignatureDoesNotMatch错误

如果签名错误，会提示 SignatureDoesNotMatch错误，如图所示：

# 使用云存储二级域名

# 描述

生成的链接域名将使用云存储的域名。

# 演示代码

<?php
require('./SCS.php');
/*这里替换为你的AccessKey和SecretKey*/
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
/*这里换成你自己的bucket名称*/
$bucket = 'sinaappengine';
$scs_instance = new SCS($accessKey, $secretKey);
$file_path = 'example_folder/file_from_string.txt';
$url1 = $scs_instance->getAuthenticatedURL($bucket, $file_path, 3600);
var_dump($url1);

# 返回值

string(135) "http://sinacloud.net/sinaappengine/example_folder/file_from_string.txt?KID=sina,k7y55fCeaP7RnnSWNer6&Expires=1536309551&ssig=GdMxxA8kEe"

说明

?KID=sina,k7y55fCeaP7RnnSWNer6&Expires=1536309551&ssig=GdMxxA8kEe 即为签名的部分；
Expires是链接过期的unix时间戳；

# 使用CDN域名

# 描述

使用CDN的域名。

# 示例代码

<?php
require('./SCS.php');
/*这里替换为你的AccessKey和SecretKey*/
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
/*这里换成你自己的bucket名称*/
$bucket = 'sinaappengine';
$scs_instance = new SCS($accessKey, $secretKey);
$scs_instance->setEndpoint('cdn.sinacloud.net');
$file_path = 'example_folder/file_from_string.txt';
$url1 = $scs_instance->getAuthenticatedURL($bucket, $file_path, 3600);
var_dump($url1);

# 返回值

http://cdn.sinacloud.net/sinaappengine/example_folder/file_from_string.txt?KID=sina,k7y55fCeaP7RnnSWNer6&Expires=1536320335&ssig=ItjJa4Chbc

# 使用独立域名

# 描述

使用绑定的独立域名生成访问链接。

# 代码示例

<?php
require('./SCS.php');
/*这里替换为你的AccessKey和SecretKey*/
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
/*这里换成你自己的bucket名称，注意这里必须写名称为独立域名的bucket*/
$bucket = 'cccccc.changes.com.cn';
$scs_instance = new SCS($accessKey, $secretKey);
$file_path = 'example_folder/file_from_string.txt';
/*这里的第四个参数$hostBucket需要设置为true*/
$url1 = $scs_instance->getAuthenticatedURL($bucket, $file_path, 3600, true);
var_dump($url1);

# 返回值

http://cccccc.changes.com.cn/example_folder/file_from_string.txt?KID=sina,k7y55fCeaP7RnnSWNer6&Expires=1536321268&ssig=Qwim%2Bynygs"

# 使用https域名

# 描述

生成https的访问域名。

# 示例代码

<?php
require('./SCS.php');
/*这里替换为你的AccessKey和SecretKey*/
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
/*这里换成你自己的bucket名称*/
$bucket = 'sinaappengine';
$scs_instance = new SCS($accessKey, $secretKey);
$file_path = 'example_folder/file_from_string.txt';
/*这里的第五个参数$https需要设置为true*/
$url1 = $scs_instance->getAuthenticatedURL($bucket, $file_path, 3600, false, true);
var_dump($url1);

# 返回值

https://sinacloud.net/sinaappengine/example_folder/file_from_string.txt?KID=sina,k7y55fCeaP7RnnSWNer6&Expires=1536321404&ssig=%2F6zzVzlUiO

# 增加IP验证

# 描述

生成链接的时候指定可以访问的IP或者IP段。

提示

如果授权的是IP段，需要按如下的写法实现，例如授权的IP段为123.1.1.0/24，则生成URL时传入的IP地址为123.1.1.，最后有一个点。

# 演示代码

<?php
require('./SCS.php');
/*这里替换为你的AccessKey和SecretKey*/
$accessKey = 'AccessKey';
$secretKey = 'SecretKey';
/*这里换成你自己的bucket名称*/
$bucket = 'sinaappengine';
$scs_instance = new SCS($accessKey, $secretKey);
//$scs_instance->setEndpoint('sinastorage.cn');
$file_path = 'example_folder/file_from_string.txt';
$ip = '61.135.152.';
$url1 = $scs_instance->getAuthenticatedURL($bucket, $file_path, 3600, false, false, $ip);
var_dump($url1);

说明

以上示例代码授权的是61.135.152.0/24 IP段。

# 返回信息

http://sinacloud.net/sinaappengine/example_folder/file_from_string.txt?ip=61.135.152.&KID=sina,k7y55fCeaP7RnnSWNer6&Expires=1536326895&ssig=9Rxf5qQnTf

# 自行拼接无签名URL

如果object的ACL属性包含匿名用户可读，则可以生成一个不含签名部分的访问链接，当前SDK中没有生成没有签名部分的链接，需要自行实现一个版本。

提示

在确认使用不含签名的资源链接前，请务必确认文件包含匿名用户可读的ACL设置。

# 通过在线管理平台设置文件的ACL

如何设置文件的匿名用户读权限，请参考下图步骤操作：

设置完成后，就可以通过不加签名访问文件资源。

# 示例代码

<?php
// 这里需要换成你自己的bucket
$bucket = 'sinaappengine';
$file_path = 'example_folder/file_from_string.txt';
$file_path = str_replace(array('%2F'), array('/'), rawurlencode($file_path));
$url = sprintf('http://%s.%s/%s', $bucket, 'sinacloud.net', $file_path);
var_dump($url);

# 返回值

http://sinaappengine.sinacloud.net/example_folder/file_from_string.txt

提示

如果您的文件都是用于公开访问，建议在上传时先制定所有文件的ACL为SCS::ACL_PUBLIC_READ。

← API文档 Python SDK →