refine readme #51
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,149 @@ | ||
| # Aliyun OSS SDK for PHP | ||
|
|
||
| [](https://packagist.org/packages/aliyuncs/oss-sdk-php) | ||
| [](https://travis-ci.org/aliyun/aliyun-oss-php-sdk) | ||
| [](https://coveralls.io/github/aliyun/aliyun-oss-php-sdk?branch=master) | ||
|
|
||
| ## [README of English](https://github.com/aliyun/aliyun-oss-php-sdk/blob/master/README.md) | ||
|
|
||
| ## 概述 | ||
|
|
||
| 阿里云对象存储（Object Storage Service，简称OSS），是阿里云对外提供的海量、安全、低成本、高可靠的云存储服务。用户可以通过调用API，在任何应用、任何时间、任何地点上传和下载数据，也可以通过用户Web控制台对数据进行简单的管理。OSS适合存放任意文件类型，适合各种网站、开发企业及开发者使用。 | ||
|
|
||
|
|
||
| ## 运行环境 | ||
| - PHP 5.3+ | ||
| - cURL extension | ||
|
|
||
| 提示： | ||
|
|
||
| - Ubuntu下可以使用apt-get包管理器安装php的cURL扩展 `sudo apt-get install php5-curl` | ||
|
|
||
| ## 安装方法 | ||
|
|
||
| 1. 如果您通过composer管理您的项目依赖，可以在你的项目根目录运行： | ||
|
|
||
| $ composer require aliyuncs/oss-sdk-php | ||
|
|
||
| 或者在你的`composer.json`中声明对Aliyun OSS SDK for PHP的依赖： | ||
|
|
||
| "require": { | ||
| "aliyuncs/oss-sdk-php": "~2.0" | ||
| } | ||
|
|
||
| 然后通过`composer install`安装依赖。composer安装完成后，在您的PHP代码中引入依赖即可： | ||
|
|
||
| require_once __DIR__ . '/vendor/autoload.php'; | ||
|
|
||
| 2. 您也可以直接下载已经打包好的[phar文件][releases-page]，然后在你 | ||
| 的代码中引入这个文件即可： | ||
|
|
||
| require_once '/path/to/oss-sdk-php.phar'; | ||
|
|
||
| 3. 下载SDK源码，在您的代码中引入SDK目录下的`autoload.php`文件： | ||
|
|
||
| require_once '/path/to/oss-sdk/autoload.php'; | ||
|
|
||
| ## 快速使用 | ||
|
|
||
| ### 常用类 | ||
|
|
||
| | 类名 | 解释 | | ||
| |:------------------|:------------------------------------| | ||
| |OSS\OssClient | OSS客户端类，用户通过OssClient的实例调用接口 | | ||
| |OSS\Core\OssException | OSS异常类，用户在使用的过程中，只需要注意这个异常| | ||
|
|
||
| ### OssClient初始化 | ||
|
|
||
| SDK的OSS操作通过OssClient类完成的，下面代码创建一个OssClient对象: | ||
|
|
||
| ```php | ||
| <?php | ||
| $accessKeyId = "<您从OSS获得的AccessKeyId>"; ; | ||
| $accessKeySecret = "<您从OSS获得的AccessKeySecret>"; | ||
| $endpoint = "<您选定的OSS数据中心访问域名，例如oss-cn-hangzhou.aliyuncs.com>"; | ||
| try { | ||
| $ossClient = new OssClient($accessKeyId, $accessKeySecret, $endpoint); | ||
| } catch (OssException $e) { | ||
| print $e->getMessage(); | ||
| } | ||
| ``` | ||
|
|
||
| ### 文件操作 | ||
|
|
||
| 文件(又称对象,Object)是OSS中最基本的数据单元，您可以把它简单地理解为文件，用下面代码可以实现一个Object的上传： | ||
|
|
||
| ```php | ||
| <?php | ||
| $bucket = "<您使用的Bucket名字，注意命名规范>"; | ||
| $object = "<您使用的Object名字，注意命名规范>"; | ||
| $content = "Hello, OSS!"; // 上传的文件内容 | ||
| try { | ||
| $ossClient->putObject($bucket, $object, $content); | ||
| } catch (OssException $e) { | ||
| print $e->getMessage(); | ||
| } | ||
| ``` | ||
|
|
||
| ### 存储空间操作 | ||
|
|
||
| 存储空间(又称Bucket)是一个用户用来管理所存储Object的存储空间,对于用户来说是一个管理Object的单元，所有的Object都必须隶属于某个Bucket。您可以按照下面的代码新建一个Bucket： | ||
|
|
||
| ```php | ||
| <?php | ||
| $bucket = "<您使用的Bucket名字，注意命名规范>"; | ||
| try { | ||
| $ossClient->createBucket($bucket); | ||
| } catch (OssException $e) { | ||
| print $e->getMessage(); | ||
| } | ||
| ``` | ||
|
|
||
| ### 返回结果处理 | ||
|
|
||
| OssClient提供的接口返回返回数据分为两种： | ||
|
|
||
| * Put，Delete类接口，接口返回null，如果没有OssException，即可认为操作成功 | ||
| * Get，List类接口，接口返回对应的数据，如果没有OssException，即可认为操作成功，举个例子： | ||
|
|
||
| ```php | ||
| <?php | ||
| $bucketListInfo = $ossClient->listBuckets(); | ||
| $bucketList = $bucketListInfo->getBucketList(); | ||
| foreach($bucketList as $bucket) { | ||
| print($bucket->getLocation() . "\t" . $bucket->getName() . "\t" . $bucket->getCreatedate() . "\n"); | ||
| } | ||
| ``` | ||
| 上面代码中的$bucketListInfo的数据类型是 `OSS\Model\BucketListInfo` | ||
|
|
||
|
|
||
| ### 运行Sample程序 | ||
|
|
||
| 1. 修改 `samples/Config.php`， 补充配置信息 | ||
| 2. 执行 `cd samples/ && php RunAll.php` | ||
|
|
||
| ### 运行单元测试 | ||
|
|
||
| 1. 执行`composer install`下载依赖的库 | ||
| 2. 设置环境变量 | ||
|
|
||
| export OSS_ACCESS_KEY_ID=access-key-id | ||
| export OSS_ACCESS_KEY_SECRET=access-key-secret | ||
| export OSS_ENDPOINT=endpoint | ||
| export OSS_BUCKET=bucket-name | ||
|
|
||
| 3. 执行 `php vendor/bin/phpunit` | ||
|
|
||
| ## License | ||
|
|
||
| - MIT | ||
|
|
||
| ## 联系我们 | ||
|
|
||
| - [阿里云OSS官方网站](http://oss.aliyun.com) | ||
| - [阿里云OSS官方论坛](http://bbs.aliyun.com) | ||
| - [阿里云OSS官方文档中心](http://www.aliyun.com/product/oss#Docs) | ||
| - 阿里云官方技术支持：[提交工单](https://workorder.console.aliyun.com/#/ticket/createIndex) | ||
|
|
||
| [releases-page]: https://github.com/aliyun/aliyun-oss-php-sdk/releases | ||
| [phar-composer]: https://github.com/clue/phar-composer |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,152 +1,150 @@ | ||
| # Alibaba Cloud OSS SDK for PHP | ||
|
|
||
| [](https://packagist.org/packages/aliyuncs/oss-sdk-php) | ||
| [](https://travis-ci.org/aliyun/aliyun-oss-php-sdk) | ||
| [](https://coveralls.io/github/aliyun/aliyun-oss-php-sdk?branch=master) | ||
|
|
||
| ## [README of Chinese](https://github.com/aliyun/aliyun-oss-php-sdk/blob/master/README-CN.md) | ||
|
|
||
| ## Overview | ||
|
|
||
| Alibaba Cloud Object Storage Service (OSS) is a cloud storage service provided by Alibaba Cloud, featuring a massive capacity, security, a low cost, and high reliability. You can upload and download data on any application anytime and anywhere by calling APIs, and perform simple management of data through the web console. The OSS can store any type of files and therefore applies to various websites, development enterprises and developers. | ||
|
|
||
|
|
||
| ## Run environment | ||
| - PHP 5.3+. | ||
| - cURL extension. | ||
|
|
||
| Tips: | ||
|
|
||
| - In Ubuntu, you can use the ***apt-get*** package manager to install the *PHP cURL extension*: `sudo apt-get install php5-curl`. | ||
|
|
||
| ## Install OSS PHP SDK | ||
|
|
||
| - If you use the ***composer*** to manage project dependencies, run the following command in your project's root directory: | ||
|
|
||
| composer require aliyuncs/oss-sdk-php | ||
|
|
||
| You can also declare the dependency on Alibaba Cloud OSS SDK for PHP in the `composer.json` file. | ||
|
|
||
| "require": { | ||
| "aliyuncs/oss-sdk-php": "~2.0" | ||
| } | ||
|
|
||
| Then run `composer install` to install the dependency. After the Composer Dependency Manager is installed, import the dependency in your PHP code: | ||
|
|
||
| require_once __DIR__ . '/vendor/autoload.php'; | ||
|
|
||
| - You can also directly download the packaged [PHAR File][releases-page], and | ||
| introduce the file to your code: | ||
|
|
||
| require_once '/path/to/oss-sdk-php.phar'; | ||
|
|
||
| - Download the SDK source code, and introduce the `autoload.php` file under the SDK directory to your code: | ||
|
|
||
| require_once '/path/to/oss-sdk/autoload.php'; | ||
|
|
||
| ## Quick use | ||
|
|
||
| ### Common classes | ||
|
|
||
| | Class | Explanation | | ||
| |:------------------|:------------------------------------| | ||
| |OSS\OSSClient | OSS client class. An OSSClient instance can be used to call the interface. | | ||
| |OSS\Core\OSSException |OSS Exception class . You only need to pay attention to this exception when you use the OSSClient. | | ||
|
|
||
| ### Initialize an OSSClient | ||
|
|
||
| The SDK's operations for the OSS are performed through the OSSClient class. The code below creates an OSSClient object: | ||
|
|
||
| ```php | ||
| <?php | ||
| $accessKeyId = "<AccessKeyID that you obtain from OSS>"; | ||
| $accessKeySecret = "<AccessKeySecret that you obtain from OSS>"; | ||
| $endpoint = "<Domain that you select to access an OSS data center, such as "oss-cn-hangzhou.aliyuncs.com>"; | ||
| try { | ||
| $ossClient = new OssClient($accessKeyId, $accessKeySecret, $endpoint); | ||
| } catch (OssException $e) { | ||
| print $e->getMessage(); | ||
| } | ||
| ``` | ||
|
|
||
| ### Operations on objects | ||
|
|
||
| Objects are the most basic data units on the OSS. You can simply consider objects as files. The following code uploads an object: | ||
|
Contributor
There was a problem hiding this comment. Objects are the most basic data units on the OSS |
||
|
|
||
| ```php | ||
| <?php | ||
| $bucket= "<Name of the bucket in use. Pay attention to naming conventions>"; | ||
| $object = "<Name of the object in use. Pay attention to naming conventions>"; | ||
| $content = "Hello, OSS!"; // Content of the uploaded file | ||
| try { | ||
| $ossClient->putObject($bucket, $object, $content); | ||
| } catch (OssException $e) { | ||
| print $e->getMessage(); | ||
| } | ||
| ``` | ||
|
|
||
| ### Operations on buckets | ||
|
|
||
| Buckets are the space that you use to manage the stored objects. It is an object management unit for users. Each object must belong to a bucket. You can create a bucket with the following code: | ||
|
|
||
| ```php | ||
| <?php | ||
| $bucket= "<Name of the bucket in use. Pay attention to naming conventions>"; | ||
| try { | ||
| $ossClient->createBucket($bucket); | ||
| } catch (OssException $e) { | ||
| print $e->getMessage(); | ||
| } | ||
| ``` | ||
|
|
||
| ### Handle returned results | ||
|
|
||
| The OSSClient provides the following two types of returned data from interfaces: | ||
|
|
||
| - Put and Delete interfaces: The *PUT* and *DELETE* operations are deemed successful if *null* is returned by the interfaces without *OSSException*. | ||
| - Get and List interfaces: The *GET* and *LIST* operations are deemed successful if the desired data is returned by the interfaces without *OSSException*. For example, | ||
|
|
||
| ```php | ||
| <?php | ||
| $bucketListInfo = $ossClient->listBuckets(); | ||
| $bucketList = $bucketListInfo->getBucketList(); | ||
| foreach($bucketList as $bucket) { | ||
| print($bucket->getLocation() . "\t" . $bucket->getName() . "\t" . $bucket->getCreatedate() . "\n"); | ||
| } | ||
| ``` | ||
| In the above code, $bucketListInfo falls into the 'OSS\Model\BucketListInfo' data type. | ||
|
|
||
|
|
||
| ### Run a sample project | ||
|
|
||
| - Modify `samples/Config.php` to complete the configuration information. | ||
| - Run `cd samples/ && php RunAll.php`. | ||
|
|
||
| ### Run a unit test | ||
|
|
||
| - Run `composer install` to download the dependent libraries. | ||
| - Set the environment variable. | ||
|
|
||
| export OSS_ACCESS_KEY_ID=access-key-id | ||
| export OSS_ACCESS_KEY_SECRET=access-key-secret | ||
| export OSS_ENDPOINT=endpoint | ||
| export OSS_BUCKET=bucket-name | ||
|
|
||
| - Run `php vendor/bin/phpunit` | ||
|
|
||
| ## License | ||
|
|
||
| - MIT | ||
|
|
||
| ## Contact us | ||
|
|
||
| - [Alibaba Cloud OSS official website](http://oss.aliyun.com). | ||
| - [Alibaba Cloud OSS official forum](http://bbs.aliyun.com). | ||
| - [Alibaba Cloud OSS official documentation center](http://www.aliyun.com/product/oss#Docs). | ||
| - Alibaba Cloud official technical support: [Submit a ticket](https://workorder.console.aliyun.com/#/ticket/createIndex). | ||
|
|
||
| [releases-page]: https://github.com/aliyun/aliyun-oss-php-sdk/releases | ||
| [phar-composer]: https://github.com/clue/phar-composer | ||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
After the Composer Dependency Manager is installed
->
After the Composer Dependency Manager installed