Unofficial PHP SDK for Selectel Cloud Storage API.
This package requires PHP 5.6 or higher.
You can install the package via 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);
ArgentCrusade\Selectel\CloudStorage\CloudStorage
class allows you to access and create containers.
// 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
method returns instance of ArgentCrusade\Selectel\CloudStorage\Collections\Collection
class with retrieved containers objects. This collection object implements ArrayAccess
, Countable
, Iterator
and JsonSerializable
interfaces, what makes you able to do these things:
$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);
Container that you've retrieved from Containers Collection is an ArgentCrusade\Selectel\CloudStorage\Container
instance object which implements Countable
and JsonSerializable
interfaces.
$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();
You can use instance of ArgentCrusade\Selectel\CloudStorage\FluentFilesLoader
class to retrieve files from container.
Fluent loader returns Collection
of file arrays or Collection
of File
objects.
This instance is accesible from $container->files()
method and allows you to do following things:
// 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.
If you need to create FluentFilesLoader
instance without Container
instance, use following code:
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
class provides uploadFromString
method to upload file contents and uploadFromStream
method to upload file from stream.
// 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);
Both methods accepts array $params
as third optional argument.
$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.
];
Also, uploadFromString
method accepts 4th argument bool $verifyChecksum
. If true, Selectel will perform MD5 checksum comparison and if something went wrong during upload process, it won't accept file and exception will be thrown. This option is enabled by default for uploadFromString
method.
When you retrieve collection of files via Contrainer::files
method you get Collection
of file arrays:
$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'
]
*/
But when you're using Container::files()->find
method, you receive instance of ArgentCrusade\Selectel\CloudStorage\File
class that implements JsonSerializable
interface. With this object you can perform operations such as renaming, copying and deleting 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();
If you need to transform file from array to File
instance you can use Container::getFileFromArray
method:
$files = $container->files()->get();
$file = $container->getFileFromArray($files[0]);
Also, you can use Container::getFilesCollectionFromArrays
method to convert files Collection
or array of file arrays to Collection
of File
instances:
$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.
Fluent loader (FluentFilesLoader
) can also return Collection
of file objects by calling asFileObjects
method before get
method (see Fluent Files Loader section).
Warning: converting a lot of files to File
instances may result in performance loss.
Please see CHANGELOG for more information on what has changed recently.
$ vendor/bin/phpunit
Please see CONTRIBUTING for details.
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
The MIT License (MIT). Please see License File for more information.