README

Unofficial PHP SDK for Selectel Cloud Storage API.

需求

此包需要 PHP 5.6 或更高版本。

安装

您可以通过 composer 安装此包

$ composer require argentcrusade/selectel-cloud-storage

使用方法

初始化存储

use ArgentCrusade\Selectel\CloudStorage\Api\ApiClient;
use ArgentCrusade\Selectel\CloudStorage\CloudStorage;

$apiClient = new ApiClient('username', 'password');
$storage = new CloudStorage($apiClient);

CloudStorage

ArgentCrusade\Selectel\CloudStorage\CloudStorage 类允许您访问和创建容器。

// Retrieve single container.
$container = $storage->getContainer('my-container');

// Create new container.
$type = 'public'; // Can be 'public', 'private' or 'gallery'.
$newContainer = $storage->createContainer('new-container-name', $type);

// Retrieve containers list.
$containers = $storage->containers();

容器集合

CloudStorage::containers 方法返回包含检索到的容器对象的 ArgentCrusade\Selectel\CloudStorage\Collections\Collection 类的实例。此集合对象实现了 ArrayAccess、Countable、Iterator 和 JsonSerializable 接口，这使得您可以执行以下操作

$containers = $storage->containers();

// Check if container exists.
if ($containers->has('my-container')) {
	// Container exists.
}

// Get containers count.
$containersCount = count($containers); // Or $containers->count();

// Access specific container.
$container = $containers['my-container']; // Or $containers->get('my-container');

// Iterate through containers.
foreach ($containers as $container) {
	echo 'Container "'.$container->name().'" has size of '.$container->size().' bytes';
}

// Send JSON representation of collection.
header('Content-Type: application/json;charset=utf-8');
echo json_encode($containers);

容器实例

您从容器集合中检索到的容器是 ArgentCrusade\Selectel\CloudStorage\Container 实例对象，该对象实现了 Countable 和 JsonSerializable 接口。

$container = $containers->get('my-container');

// Get container attributes.
$name = $container->name(); // 'container-name'.
$type = $container->type(); // 'private', 'public' or 'gallery'.
$filesCount = $container->filesCount(); // or count($container); // or $container->count();
$sizeInBytes = $container->size();
$uploadedBytes = $container->uploadedBytes(); // Total number of bytes uploaded to container (rx_bytes).
$downloadedBytes = $container->downloadedBytes(); // Total number of bytes downloaded from container (tx_bytes).
$json = json_encode($container); // JSON representation of container.

// Change container type.
$container->setType('private'); // Set container visiblity to 'public', 'private' or 'gallery'.

// Check if file exists in container.
$fileExists = $container->files()->exists('/path/to/file.txt'); // true or false.

// Get single file instance.
$file = $container->files()->find('/path/to/file.txt');

// Delete container.
// Note: container must be empty!
$container->delete();

流畅文件加载器

您可以使用 ArgentCrusade\Selectel\CloudStorage\FluentFilesLoader 类的实例从容器中检索文件。流畅加载器返回文件数组或 File 对象的 Collection。

此实例可通过 $container->files() 方法访问，并允许您执行以下操作

// All files (first 10000 by default).
$files = $container->files()->get(); // or $container->files()->all();

// Files from specific directory.
$filesFromDirectory = $container->files()->fromDirectory('/directory')->get();

// Files that satisfies given prefix.
// Useful for retrieving files with same name pattern:
// image-001.jpg, image-002.jpg, image-003.jpg, etc.
$filesWithPrefix = $container->files()->withPrefix('image-')->get();

// You can also combine fromDirectory() and withPrefix() methods to load prefixed files
// from a specific directory:
$filesFromDirectoryWithPrefix = $container->files()->fromDirectory('/directory')->withPrefix('image-')->get();

// You can apply limit/marker values to any results set (before calling get() method).
// Marker file is a filename of last file from previous request (pagination).
// If you have 100 files with names like 'image-001.jpg', 'image-002.jpg', ... , 'image-100.jpg'
// and you need to load 50 files from 'image-051.jpg', you can do this:
$files = $container->files()
    ->fromDirectory('photos')
    ->withPrefix('image-')
    ->limit(50, 'image-050.jpg')
    ->get();

// Note: if you're working inside a directory (fromDirectory('photos')), then you can omit
// its path when using withPrefix() or marker file. If you're not in a directory, then
// full path to prefixed files and/or marker file is required.
$container->files()->fromDirectory('photos')->withPrefix('image-')->get(); // Full path is not required in withPrefix() method
$container->files()->withPrefix('photos/image-')->get(); // Full path is required.

// Use asFileObjects() method in chain to return Collection of File objects:
$files = $container->files()->fromDirectory('photos')->asFileObjects()->get();
$files[0]->name(); // First file's name.

// Warning: converting a lot of files to `File` instances may result in performance loss.

如果您需要创建不带 Container 实例的 FluentFilesLoader 实例，请使用以下代码

use ArgentCrusade\Selectel\CloudStorage\Api\ApiClient;
use ArgentCrusade\Selectel\CloudStorage\FluentFilesLoader;

$api = new ApiClient('username', 'password');
$filesLoader = new FluentFilesLoader($api, 'container-name', '/container-name');
$files = $filesLoader->fromDirectory('photos')->limit(10)->asFileObjects()->get();

文件上传

Container 类提供了 uploadFromString 方法用于上传文件内容，以及 uploadFromStream 方法用于从流上传文件。

// Upload file from string contents.
$contents = file_get_contents('test.txt');
$etag = $container->uploadFromString('/path/to/file.txt', $contents);

// Upload file from stream.
$stream = fopen('test.txt', 'r');
$etag = $container->uploadFromStream('/path/to/file.txt', $stream);

这两种方法都接受第三个可选的 array $params 参数。

$params = [
	'contentType' => 'application/json',
    'contentDisposition' => 'attachment; filename="filename.json"',
    'deleteAfter' => $seconds, // File will be deleted in X seconds after upload.
    'deleteAt' => strtotime('next monday'), // File will be deleted at given UNIX timestamp.
];

此外，uploadFromString 方法还接受第四个参数 bool $verifyChecksum。如果为真，Selectel 将执行 MD5 校验和比较，如果在上传过程中出现错误，它将不接受文件，并抛出异常。此选项默认启用。

文件实例

当您通过 Contrainer::files 方法检索文件集合时，您得到文件数组 Collection。

$files = $container->files()->get();
$firstFile = $files->get(0);
/*
$firstFile will be something like this:

[
	'bytes' => 31,
    'content_type' => 'text/html',
    'hash' => 'b302ffc3b75770453e96c1348e30eb93',
    'last_modified': "2013-05-27T14:42:04.669760",
    'name': 'path/to/my_index.html',
    'filename': 'my_index.html'
]
*/

但是，当您使用 Container::files()->find 方法时，您会收到实现了 JsonSerializable 接口的 ArgentCrusade\Selectel\CloudStorage\File 类的实例。使用此对象，您可以执行诸如重命名、复制和删除文件等操作。

$file = $container->files()->find('/path/to/file.txt');

// Get file attributes.
$containerName = $file->container(); // 'my-container'
$path = $file->path(); // Full path to file (from container root): '/path/to/file.txt'
$directory = $file->directory(); // Full path to directory (from container root) without filename: '/path/to'
$name = $file->name(); // Filename 'file.txt'
$sizeInBytes = $file->size(); // File size in bytes.
$contentType = $file->contentType(); // 'text/plain'
$lastModifiedAt = $file->lastModifiedAt(); // '2013-05-27T14:42:04.669760'
$etag = $file->etag(); // md5 hash of file contents.
$isDeleted = $file->isDeleted(); // Becomes true only after deletion operation.
$json = json_encode($file); // JSON representation of file.

// Read file.
$contents = $file->read(); // Read file and return string.
$resource = $file->readStream(); // Read file and return stream resource.

// If you need PSR-7's StreamInterface instead of resource, provide $psr7Stream = true argument to File::readStream method:
$psr7Stream = $file->readStream(true); // Instance of \Psr\Http\Message\StreamInterface

// Rename file.
$file->rename('new-name.txt'); // File will be placed in the same directory.

// Copy file.
$file->copy('/path/to/new/file.txt'); // Provide full path to destination file (from container root).

// Copy file to another container.
$file->copy('/path/to/file.txt', 'my-second-container');

// Delete file.
// Note: after file deletion you won't be able to perform
// any of operations listed above (except $file->isDeleted() one).
$file->delete();

如果您需要将文件从数组转换为 File 实例，可以使用 Container::getFileFromArray 方法。

$files = $container->files()->get();
$file = $container->getFileFromArray($files[0]);

此外，您还可以使用 Container::getFilesCollectionFromArrays 方法将文件 Collection 或文件数组转换为 File 实例的 Collection。

$files = $container->files()->get();

$filesCollection = $container->getFilesCollectionFromArrays($files);
$filesCollection[0]->name(); // Returns first file's name.
// Same as:
$filesCollection = $container->getFilesCollectionFromArrays([
	$files[0], $files[1],
]);
$filesCollection[0]->name(); // Returns first file's name.

流畅加载器 (FluentFilesLoader) 还可以通过在 get 方法之前调用 asFileObjects 方法来返回文件对象的 Collection（请参阅流畅文件加载器部分）。

警告：将大量文件转换为 File 实例可能会导致性能下降。

变更日志

请参阅 CHANGELOG 了解最近更改的详细信息。

测试

$ vendor/bin/phpunit

贡献

请参阅 CONTRIBUTING 了解详细信息。

安全性

如果您发现任何与安全相关的问题，请通过电子邮件发送至 zurbaev@gmail.com，而不是使用问题跟踪器。

许可协议

MIT 许可协议（MIT）。请参阅 许可文件 获取更多信息。