| commit | author | age | ||
| 2207d6 | 1 | # Aliyun OSS SDK for PHP |
| W | 2 | |
| 3 | [](https://packagist.org/packages/aliyuncs/oss-sdk-php) | |
| 4 | [](https://travis-ci.org/aliyun/aliyun-oss-php-sdk) | |
| 5 | [](https://coveralls.io/github/aliyun/aliyun-oss-php-sdk?branch=master) | |
| 6 | ||
| 7 | ## [README of English](https://github.com/aliyun/aliyun-oss-php-sdk/blob/master/README.md) | |
| 8 | ||
| 9 | ## 概述 | |
| 10 | ||
| 11 | 阿里云对象存储（Object Storage Service，简称OSS），是阿里云对外提供的海量、安全、低成本、高可靠的云存储服务。用户可以通过调用API，在任何应用、任何时间、任何地点上传和下载数据，也可以通过用户Web控制台对数据进行简单的管理。OSS适合存放任意文件类型，适合各种网站、开发企业及开发者使用。 | |
| 12 | ||
| 13 | ||
| 14 | ## 运行环境 | |
| 15 | - PHP 5.3+ | |
| 16 | - cURL extension | |
| 17 | ||
| 18 | 提示： | |
| 19 | ||
| 20 | - Ubuntu下可以使用apt-get包管理器安装php的cURL扩展 `sudo apt-get install php5-curl` | |
| 21 | ||
| 22 | ## 安装方法 | |
| 23 | ||
| 24 | 1. 如果您通过composer管理您的项目依赖，可以在你的项目根目录运行： | |
| 25 | ||
| 26 | $ composer require aliyuncs/oss-sdk-php | |
| 27 | ||
| 28 | 或者在你的`composer.json`中声明对Aliyun OSS SDK for PHP的依赖： | |
| 29 | ||
| 30 | "require": { | |
| 31 | "aliyuncs/oss-sdk-php": "~2.0" | |
| 32 | } | |
| 33 | ||
| 34 | 然后通过`composer install`安装依赖。composer安装完成后，在您的PHP代码中引入依赖即可： | |
| 35 | ||
| 36 | require_once __DIR__ . '/vendor/autoload.php'; | |
| 37 | ||
| 38 | 2. 您也可以直接下载已经打包好的[phar文件][releases-page]，然后在你 | |
| 39 | 的代码中引入这个文件即可： | |
| 40 | ||
| 41 | require_once '/path/to/oss-sdk-php.phar'; | |
| 42 | ||
| 43 | 3. 下载SDK源码，在您的代码中引入SDK目录下的`autoload.php`文件： | |
| 44 | ||
| 45 | require_once '/path/to/oss-sdk/autoload.php'; | |
| 46 | ||
| 47 | ## 快速使用 | |
| 48 | ||
| 49 | ### 常用类 | |
| 50 | ||
| 51 | | 类名 | 解释 | | |
| 52 | |:------------------|:------------------------------------| | |
| 53 | |OSS\OssClient | OSS客户端类，用户通过OssClient的实例调用接口 | | |
| 54 | |OSS\Core\OssException | OSS异常类，用户在使用的过程中，只需要注意这个异常| | |
| 55 | ||
| 56 | ### OssClient初始化 | |
| 57 | ||
| 58 | SDK的OSS操作通过OssClient类完成的，下面代码创建一个OssClient对象: | |
| 59 | ||
| 60 | ```php | |
| 61 | <?php | |
| 62 | $accessKeyId = "<您从OSS获得的AccessKeyId>"; ; | |
| 63 | $accessKeySecret = "<您从OSS获得的AccessKeySecret>"; | |
| 64 | $endpoint = "<您选定的OSS数据中心访问域名，例如oss-cn-hangzhou.aliyuncs.com>"; | |
| 65 | try { | |
| 66 | $ossClient = new OssClient($accessKeyId, $accessKeySecret, $endpoint); | |
| 67 | } catch (OssException $e) { | |
| 68 | print $e->getMessage(); | |
| 69 | } | |
| 70 | ``` | |
| 71 | ||
| 72 | ### 文件操作 | |
| 73 | ||
| 74 | 文件(又称对象,Object)是OSS中最基本的数据单元，您可以把它简单地理解为文件，用下面代码可以实现一个Object的上传： | |
| 75 | ||
| 76 | ```php | |
| 77 | <?php | |
| 78 | $bucket = "<您使用的Bucket名字，注意命名规范>"; | |
| 79 | $object = "<您使用的Object名字，注意命名规范>"; | |
| 80 | $content = "Hello, OSS!"; // 上传的文件内容 | |
| 81 | try { | |
| 82 | $ossClient->putObject($bucket, $object, $content); | |
| 83 | } catch (OssException $e) { | |
| 84 | print $e->getMessage(); | |
| 85 | } | |
| 86 | ``` | |
| 87 | ||
| 88 | ### 存储空间操作 | |
| 89 | ||
| 90 | 存储空间(又称Bucket)是一个用户用来管理所存储Object的存储空间,对于用户来说是一个管理Object的单元，所有的Object都必须隶属于某个Bucket。您可以按照下面的代码新建一个Bucket： | |
| 91 | ||
| 92 | ```php | |
| 93 | <?php | |
| 94 | $bucket = "<您使用的Bucket名字，注意命名规范>"; | |
| 95 | try { | |
| 96 | $ossClient->createBucket($bucket); | |
| 97 | } catch (OssException $e) { | |
| 98 | print $e->getMessage(); | |
| 99 | } | |
| 100 | ``` | |
| 101 | ||
| 102 | ### 返回结果处理 | |
| 103 | ||
| 104 | OssClient提供的接口返回返回数据分为两种： | |
| 105 | ||
| 106 | * Put，Delete类接口，接口返回null，如果没有OssException，即可认为操作成功 | |
| 107 | * Get，List类接口，接口返回对应的数据，如果没有OssException，即可认为操作成功，举个例子： | |
| 108 | ||
| 109 | ```php | |
| 110 | <?php | |
| 111 | $bucketListInfo = $ossClient->listBuckets(); | |
| 112 | $bucketList = $bucketListInfo->getBucketList(); | |
| 113 | foreach($bucketList as $bucket) { | |
| 114 | print($bucket->getLocation() . "\t" . $bucket->getName() . "\t" . $bucket->getCreatedate() . "\n"); | |
| 115 | } | |
| 116 | ``` | |
| 117 | 上面代码中的$bucketListInfo的数据类型是 `OSS\Model\BucketListInfo` | |
| 118 | ||
| 119 | ||
| 120 | ### 运行Sample程序 | |
| 121 | ||
| 122 | 1. 修改 `samples/Config.php`， 补充配置信息 | |
| 123 | 2. 执行 `cd samples/ && php RunAll.php` | |
| 124 | ||
| 125 | ### 运行单元测试 | |
| 126 | ||
| 127 | 1. 执行`composer install`下载依赖的库 | |
| 128 | 2. 设置环境变量 | |
| 129 | ||
| 130 | export OSS_ACCESS_KEY_ID=access-key-id | |
| 131 | export OSS_ACCESS_KEY_SECRET=access-key-secret | |
| 132 | export OSS_ENDPOINT=endpoint | |
| 133 | export OSS_BUCKET=bucket-name | |
| 134 | ||
| 135 | 3. 执行 `php vendor/bin/phpunit` | |
| 136 | ||
| 137 | ## License | |
| 138 | ||
| 139 | - MIT | |
| 140 | ||
| 141 | ## 联系我们 | |
| 142 | ||
| 143 | - [阿里云OSS官方网站](http://oss.aliyun.com) | |
| 144 | - [阿里云OSS官方论坛](http://bbs.aliyun.com) | |
| 145 | - [阿里云OSS官方文档中心](http://www.aliyun.com/product/oss#Docs) | |
| 146 | - 阿里云官方技术支持：[提交工单](https://workorder.console.aliyun.com/#/ticket/createIndex) | |
| 147 | ||
| 148 | [releases-page]: https://github.com/aliyun/aliyun-oss-php-sdk/releases | |
| 149 | [phar-composer]: https://github.com/clue/phar-composer | |
