Objects¶

Upload a single file (under 5GB)¶

The simplest way to upload a local object, without additional metadata, is by its path:

$container->uploadObject('example.txt', fopen('/path/to/file.txt', 'r+'));

The resource handle will be automatically closed by Guzzle in its destructor, so there is no need to execute fclose.

Get the executable PHP script for this example

Upload a single file (under 5GB) with metadata¶

Although the previous section handles most use cases, there are times when you want greater control over what is being uploaded. For example, you might want to control the object’s metadata, or supply additional HTTP headers to coerce browsers to handle the download a certain way. To add metadata to a new object:

use OpenCloud\ObjectStore\Resource\DataObject;

// specify optional metadata
$metadata = array(
    'Author' => 'Camera Obscura',
    'Origin' => 'Glasgow',
);

// specify optional HTTP headers
$httpHeaders = array(
    'Content-Type' => 'application/json',
);

// merge the two
$allHeaders = array_merge(DataObject::stockHeaders($metadata), $httpHeaders);

// upload as usual
$container->uploadObject('example.txt', fopen('/path/to/file.txt', 'r+'), $allHeaders);

As you will notice, the first argument to uploadObject is the remote object name, i.e. the name it will be uploaded as. The second argument is either a file handle resource, or a string representation of object content (a temporary resource will be created in memory), and the third is an array of additional headers.

Get the executable PHP script for this example

Batch upload multiple files (each under 5GB)¶

$files = array(
    array(
        'name' => 'apache.log',
        'path' => '/etc/httpd/logs/error_log'
    ),
    array(
        'name' => 'mysql.log',
        'body' => fopen('/tmp/mysql.log', 'r+')
    ),
    array(
        'name' => 'to_do_list.txt',
        'body' => 'PHONE HOME'
    )
);

$container->uploadObjects($files);

As you can see, the name key is required for every file. You must also specify either a path key (to an existing file), or a body. The body can either be a PHP resource or a string representation of the content you want to upload.

Get the executable PHP script for this example

Upload large files (over 5GB)¶

For files over 5GB, you will need to use the OpenCloud\ObjectStore\Upload\TransferBuilder factory to build and execute your transfer. For your convenience, the Container resource object contains a simple method to do this heavy lifting for you:

$transfer = $container->setupObjectTransfer(array(
    'name'        => 'video.mov',
    'path'        => '/home/user/video.mov',
    'metadata'    => array('Author' => 'Jamie'),
    'concurrency' => 4,
    'partSize'    => 1.5 * Size::GB
));

$transfer->upload();

You can specify how many concurrent cURL connections are used to upload parts of your file. The file is fragmented into chunks, each of which is uploaded individually as a separate file (the filename of each part will indicate that it’s a segment rather than the full file). After all parts are uploaded, a manifestfile is uploaded. When the end-user accesses the 5GB by its true filename, it actually references the manifest file which concatenates each segment into a streaming download.

In Swift terminology, the name for this process is Dynamic Large Object (DLO). To find out more details, please consult the official documentation.

Get the executable PHP script for this example

Get object’s parent container¶

/** @param $container OpenCloud\ObjectStore\Resource\Container */
$container = $object->getContainer();

Get file name¶

/** @param $name string */
$name = $object->getName();

Get file size¶

/** @param $size int */
$size = $object->getContentLength();

Get content of file¶

/** @param $content Guzzle\Http\EntityBody */
$content = $object->getContainer();

Get type of file¶

/** @param $type string */
$type = $object->getContentType();

Get file checksum¶

/** @param $etag string */
$etag = $object->getEtag();

Get last modified date of file¶

/** @param $lastModified string */
$lastModified = $object->getLastModified();

Conditional requests¶

You can also perform conditional requests according to RFC 2616 specification (§§ 14.24-26). Supported headers are If-Match, If-None-Match, If-Modified-Since and If-Unmodified-Since.

So, to retrieve a file’s contents only if it’s been recently changed

$file = $container->getObject('error_log.txt', array(
    'If-Modified-Since' => 'Tue, 15 Nov 1994 08:12:31 GMT'
));

if ($file->getContentLength()) {
    echo 'Has been changed since the above date';
} else {
    echo 'Has not been changed';
}

Retrieve a file only if it has NOT been modified (and expect a 412 on failure):

use Guzzle\Http\Exception\ClientErrorResponseException;

try {
    $oldImmutableFile = $container->getObject('payroll_2001.xlsx', array(
        'If-Unmodified-Since' => 'Mon, 31 Dec 2001 23:00:00 GMT'
    ));
} catch (ClientErrorResponseException $e) {
    echo 'This file has been modified...';
}

Finally, you can specify a range - which will return a subset of bytes from the file specified. To return the last 20B of a file:

$snippet = $container->getObject('output.log', array('range' => 'bytes=-20'));