Objects

Show details for an object

Show auth code
<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);
/** @var \OpenStack\ObjectStore\v1\Models\StorageObject $object */
$object = $openstack->objectStoreV1()
                    ->getContainer('{containerName}')
                    ->getObject('{objectName}');

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

At this point, the object returned is empty because we did not execute a HTTP request to receive the state of the container from the API. This is in accordance with one of the SDK’s general policies of not assuming too much at the expense of performance.

To synchronize the local object’s state with the remote API, you can run:

$object->retrieve();

printf("%s/%s is %d bytes long and was last modified on %s",
    $object->containerName, $object->name, $object->contentLength, $object->lastModified);

and all of the local properties will match those of the remote resource. The retrieve call, although fetching all of the object’s metadata, will not download the object’s content. To do this, see the next section.

Download an object

Show auth code
<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);
/** @var \GuzzleHttp\Stream\Stream $stream */
$stream = $openstack->objectStoreV1()
                    ->getContainer('{containerName}')
                    ->getObject('{objectName}')
                    ->download();

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

As you will notice, a Stream object is returned by this call. For more information about dealing with streams, please consult Guzzle’s docs.

List objects

Show auth code
<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);
$container = $openstack->objectStoreV1()
                       ->getContainer('{containerName}');

foreach ($container->listObjects() as $object) {
    /** @var \OpenStack\ObjectStore\v1\Models\StorageObject $object */
}

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

When listing objects, you must be aware that not all information about a container is returned in a collection. Very often only the MD5 hash, last modified date, bytes used, content type and object name will be returned. If you would like to access all of the remote state of a collection item, you can call retrieve like so:

foreach ($objects as $object) {
    // To retrieve metadata
    $object->retrieve();
}

If you have a large collection of $object, this will slow things down because you’re issuing a HEAD request per object.

By default, PHP generators are used to represent collections of resources in the SDK. The benefit of using generators is that it generally improves performance, since objects are not saved in memory as the iteration cycle goes on; instead, each resource is directly output to the user-defined foreach loop. For all intents and purposes, you interact with generators like any other Traversable object, but to retain collections in memory, you will need to implement your own logic.

Create an object

When creating an object, you can upload its content according to a string representation:

Show auth code
<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);
$options = [
    'name'    => '{objectName}',
    'content' => '{objectContent}',
];

/** @var \OpenStack\ObjectStore\v1\Models\StorageObject $object */
$object = $openstack->objectStoreV1()
                    ->getContainer('{containerName}')
                    ->createObject($options);

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

If that is not optimal or convenient, you can use a stream instead. Any instance of \Psr\Http\Message\StreamInterface is acceptable. For example, to use a normal Guzzle stream:

Show auth code
<?php

require 'vendor/autoload.php';

use GuzzleHttp\Psr7\Stream;

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);
// You can use any instance of \Psr\Http\Message\StreamInterface
$stream = new Stream(fopen('/path/to/object.txt', 'r'));

$options = [
    'name'   => '{objectName}',
    'stream' => $stream,
];

/** @var \OpenStack\ObjectStore\v1\Models\StorageObject $object */
$object = $openstack->objectStoreV1()
    ->getContainer('{containerName}')
    ->createObject($options);

Create a large object (over 5GB)

For large objects (those over 5GB), you will need to use a concept in Swift called Dynamic Large Objects (DLO). When uploading, this is what happens under the hood:

  1. The large file is separated into smaller segments
  2. Each segment is uploaded
  3. A manifest file is created which, when requested by clients, will concatenate all the segments as a single file

To upload a DLO, you need to call:

Show auth code
<?php

require 'vendor/autoload.php';

use Guzzle\Stream\Stream;

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);
$options = [
    'name'   => 'object_name.txt',
    'stream' => new Stream(fopen('/path/to/large_object.mov', 'r')),
];

// optional: specify the size of each segment in bytes
$options['segmentSize'] = 1073741824;

// optional: specify the container where the segments live. This does not necessarily have to be the
// same as the container which holds the manifest file
$options['segmentContainer'] = 'test_segments';


/** @var \OpenStack\ObjectStore\v1\Models\StorageObject $object */
$object = $openstack->objectStoreV1()
                    ->getContainer('test')
                    ->createLargeObject($options);

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Copy object

Show auth code
<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);
$openstack->objectStoreV1()
          ->getContainer('{containerName}')
          ->getObject('{objectName}')
          ->copy([
              'destination' => '{newContainerName}/{newObjectName}'
          ]);

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Delete object

Show auth code
<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);
$openstack->objectStoreV1()
          ->getContainer('{containerName}')
          ->getObject('{objectName}')
          ->delete();

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

Get metadata

Show auth code
<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);
/** @var array $metadata */
$metadata = $openstack->objectStoreV1()
                      ->getContainer('{containerName}')
                      ->getObject('{objectName}')
                      ->getMetadata();

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

The returned value will be a standard associative array, or hash, containing arbitrary key/value pairs. These will correspond to the values set either when the object was created, or when a previous mergeMetadata or resetMetadata operation was called.

Replace all metadata with new values

Show auth code
<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);
$openstack->objectStoreV1()
          ->getContainer('{containerName}')
          ->getObject('{objectName}')
          ->resetMetadata([
              '{key_1}' => '{val_1}',
              '{key_2}' => '{val_2}',
          ]);

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

In order to replace all existing metadata with a set of new values, you can use this operation. Any existing metadata items which not specified in the new set will be removed. For example, say an account has the following metadata already set:

Foo: value1
Bar: value2

and you reset the metadata with these values:

Foo: value4
Baz: value3

the metadata of the account will now be:

Foo: value4
Baz: value3

Merge new metadata values with existing

Show auth code
<?php

require 'vendor/autoload.php';

$openstack = new OpenStack\OpenStack([
    'authUrl' => '{authUrl}',
    'region'  => '{region}',
    'user'    => [
        'id'       => '{userId}',
        'password' => '{password}'
    ],
    'scope'   => ['project' => ['id' => '{projectId}']]
]);
$openstack->objectStoreV1()
          ->getContainer('{containerName}')
          ->getObject('{objectName}')
          ->mergeMetadata([
              '{key_1}' => '{val_1}',
              '{key_2}' => '{val_2}',
          ]);

To see all the required and optional parameters for this operation, along with their types and descriptions, view the reference documentation.

In order to merge a set of new metadata values with the existing metadata set, you can use this operation. Any existing metadata items which are not specified in the new set will be preserved. For example, say an account has the following metadata already set:

Foo: value1
Bar: value2

and you merge them with these values:

Foo: value4
Baz: value3

the metadata of the account will now be:

Foo: value4
Bar: value2
Baz: value3