README

这个库是用PHP编写的Sirv S3客户端。它是Sirv官方SDK的一个分支，经过一些修改，并重建为Composer包。

安装

安装客户端最简单的方法是使用 Composer

$ composer require benmajor/sirv-s3-client

由于没有外部依赖（除了PHP >= 5.4和安装了cURL模块），您也可以从src目录下载单个PHP类，并使用PHP的require语句将其包含在您的代码中

require '/path/to/SirvS3Client.php;

用法

此客户端提供了一些实用函数，以方便使用PHP处理Sirv S3存储桶并直接从您的项目中上传内容。用法和函数参考如下

1. 创建客户端

在使用任何函数之前，我们必须首先创建一个客户端。这可以通过使用您的Sirv S3存储桶、S3密钥和S3密钥（所有这些都可以在您的设置页面上找到）实例化类来完成，如下所示

# Include Composer autoloader:
require 'vendor/autoload.php';

use BenMajor\SirvPHP\SirvS3Client;

$client = new SirvS3Client(
  'SIRV_S3_BUCKET',
  'SIRV_S3_KEY',
  'SIRV_S3_SECRET'
);

客户端实例化后，您可以使用testConnection()方法检查连接是否有效且活跃

if( $client->testConnection() ) {
  # Connection is valid and ready.
} else {
  # Something went wrong with the connection.
}

2. 检查资源是否存在

要检查存储桶中是否存在文件夹，只需通过传递一个相对文件夹路径给方法checkIfObjectExists()即可。如果文件夹存在，则方法返回true，否则返回false

$client->checkIfObjectExists('/example/folder');

也可以通过将文件的basename（包括扩展名）作为第二个参数传递给checkIfObjectExists方法来检查文件夹中是否存在特定文件

$client->checkIfObjectExists('example/folder', 'image.jpg');

如果资源存在，则返回true，否则返回false。

3. 获取资源列表

要获取存在的资源列表（即文件夹和文件），请使用getBucketContents()方法

$client->getBucketContents('example/folder');

注意，我们已指定了一个文件夹路径，以检索仅存在于example/folder目录中的资源。该方法也可以不带参数调用，以检索存储桶根目录的内容。

此方法返回一个对象，如下所示

{
  "bucket": "BUCKET_NAME",
  "current_dir": "CURRENT_WORKING_DIRECTORY",
  "contents": [ ],
  "dirs": [ ]
}

4. 创建文件夹

要创建新文件夹，只需使用createFolder()方法，并将要创建的文件夹的相对路径作为第一个参数传递

$client->createFolder('example/new-folder');

如果文件夹成功创建，则返回true，否则返回false。

5. 上传文件

可以使用uploadFile()方法轻松上传文件。第一个参数是要上传到的目标文件夹和文件名。第二个参数必须包含一个指向服务器上已存在文件的相对路径（也可以是文件上传后创建的临时文件的引用）。

以下是两个示例；一个使用已存在的文件，另一个是从PHP的临时目录上传用户上传的文件。

上传服务器上已存在的文件

$client->uploadFile(
  'example/folder/my-picture.jpg',
  '/path/to/local/my-picture.jpg'
);

上传临时文件

$client->uploadFile(
  'example/folder/'.basename($_FILES['uploaded']['name']),
  $_FILES['uploaded']['TMP_NAME']
);

6. 下载文件

getFile() 方法可以用于从Bucket中检索文件的原始内容。然后可以使用这个字符串在本地文件系统中创建文件（使用 file_put_contents() 或类似方法）。如果文件在S3 Bucket中不存在，或者由于其他原因失败，该方法将返回一个空字符串，因此在使用之前建议检查返回值。

$file = $client->getFile('/path/to/file.jpg');

if( ! empty($file) ) {
  file_put_contents('file.jpg', $file);
}

7. 复制文件

有时，我们可能希望将文件从Bucket中的一个目录复制到另一个目录。为此，请使用 copyFile() 方法。第一个参数是源文件的路径，第二个参数是目标路径。

$client->copyFile(
  'path/to/image.jpg',
  'another/path/image.jpg'
);

文件也可以复制到同一目录，但必须重命名。

$client->copyFile(
	'path/to/image.jpg',
	'path/to/image-copy.jpg'
);

8. 重命名文件

有时需要在Bucket中重命名文件。可以使用 renameFile() 方法，并将相对路径作为第一个参数传递。

$client->renameFile(
  'example/folder/image.jpg',
  'example/folder/renamed.jpg'
);

9. 删除文件

可以使用 deleteFile() 方法从Bucket实例中删除文件。应将待删除资源的相对路径作为此方法的第一个参数传递。

$client->deleteFile('example/folder/image.jpg');

致谢

该包在很大程度上基于由 Sirv 发布的官方SDK，而Sirv SDK本身是 AWS PHP SDK 的简化版本。

许可协议

本Composer包按照以下方式在MIT许可协议下发布

版权所有 (c) 2020 Ben Major

特此授予任何获得此软件及其相关文档文件（“软件”）副本的人，免费使用该软件的权利，不受任何限制，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利，并允许软件提供方这样做，前提是遵守以下条件

上述版权声明和本许可声明应包含在软件的所有副本或主要部分中。

本软件按“原样”提供，不提供任何明示或暗示的保证，包括但不限于适销性、针对特定目的的适用性和非侵权性保证。在任何情况下，作者或版权所有者均不对任何索赔、损害或其他责任负责，无论该责任基于合同、侵权或其他法律依据，无论该责任源于、因之产生或与此软件或软件的使用或其他交易有关。

benmajor / sirv-s3-client

维护者

详细信息