Documentation

Container extends AbstractContainer
in package

Application

A container is a storage compartment for your data and provides a way for you to organize your data. You can think of a container as a folder in Windows or a directory in Unix. The primary difference between a container and these other file system concepts is that containers cannot be nested.

A container can also be CDN-enabled (for public access), in which case you will need to interact with a CDNContainer object instead of this one.

GLOBAL_METADATA_PREFIX = 'X'
METADATA_LABEL = 'Container'
PATCH_CONTENT_TYPE = OpenCloudCommonConstantsMime::JSON_PATCH
$name : string: The name of the container.
$aliases : array<string|int, mixed>: The aliases configure for the properties of the instance.
$metadata : Metadata
$metadataClass : string
$service : ServiceInterface
$cdn : CDNContainer|null: This is the object that holds all the CDN functionality. This Container therefore acts as a simple wrapper and is interested in storage concerns only.
$logger : LoggerInterface: The logger instance
$properties : array<string|int, mixed>: Holds all the properties added by overloading.
__call() : mixed: Intercept non-existent method calls for dynamic getter/setter functionality.
__construct() : mixed
appendToMetadata() : array<string|int, mixed>: Append a particular array of values to the existing metadata. Analogous to a merge. You must call to actually persist the metadata using the ObjectStore service.
checkJsonError() : mixed: Checks the most recent JSON operation for errors.
dataObject() : DataObject: Get either a fresh data object (no $info), or get an existing one by passing in data for population.
delete() : mixed
deleteAllObjects() : mixed: Deletes all objects that this container currently contains. Useful when doing operations (like a delete) that require an empty container first.
deleteObject() : mixed: Delete an object from the API.
deleteWithObjects() : mixed
disableCdn() : Response: Disables the containers CDN function. Note that the container will still be available on the CDN until its TTL expires.
disableLogging() : Response: Disable access logs.
enableCdn() : mixed: Enable this container for public CDN access.
enableLogging() : Response: Turn on access logs, which track all the web traffic that your data objects accrue.
fromResponse() : static: Factory method that instantiates an object from a Response object.
generateUuid() : mixed
getBytesQuota() : null|string|int
getBytesUsed() : null|string|int
getCdn() : null|CDNContainer: Get the CDN object.
getCdnService() : Service: For internal use only.
getClient() : Client: For internal use only.
getCountQuota() : null|string|int
getInstance() : static
getLogger() : LoggerInterface: Returns the Logger object.
getMetadata() : Metadata: Returns metadata for this object.
getObject() : DataObject: Retrieve an object from the API. Apart from using the name as an identifier, you can also specify additional headers that will be used fpr a conditional GET request. These are
getObjectCount() : null|string|int: It would be awesome to put these convenience methods (which are identical to the ones in the Account object) in a trait, but we have to wait for v5.3 EOL first.
getPartialObject() : $this: Essentially the same as {@see getObject()}, except only the metadata is fetched from the API.
getService() : Service: For internal use only.
getTransId() : string: Return the transaction ID for an HTTP API operation. Useful for debugging.
getUrl() : Url: For internal use only
hasLogger() : bool
hasLogRetention() : bool: Returns whether this container has log retention enabled or not.
isCdnEnabled() : bool: Returns whether this container is CDN-enabled or not.
makeResourceIteratorOptions() : mixed
objectExists() : bool: Check if an object exists inside a container. Uses {@see getPartialObject()} to save on bandwidth and time.
objectList() : Collection: Creates a Collection of objects in the container
populate() : mixed: Populates the current object based on an unknown data type.
primaryKeyField() : string: For internal use only
refresh() : mixed
retrieveMetadata() : Metadata: Retrieve metadata from the API. This method will then set and return this value.
saveMetadata() : Response: Push local metadata to the API, thereby executing a permanent save.
setBytesQuota() : mixed
setCountQuota() : mixed
setLogger() : $this: Sets the logger.
setMetadata() : AbstractResource: Set the metadata (local-only) for this object. You must call saveMetadata to actually persist the metadata using the ObjectStore service.
setStaticErrorPage() : Response: Set the default error page for your static site.
setStaticIndexPage() : Response: This method will enable your CDN-enabled container to serve out HTML content like a website.
setupObjectTransfer() : mixed: When uploading large files (+5GB), you need to upload the file as chunks using multibyte transfer. This method sets up the transfer, and in order to execute the transfer, you need to call upload() on the returned object.
stockHeaders() : array<string|int, mixed>: Prepend/stock the header names with a resource-specific prefix.
stripNamespace() : mixed
toCamel() : mixed: Convert a string to camelCase format.
toUnderscores() : mixed: Convert string to underscore format.
trimHeaders() : array<string|int, mixed>: Trim headers of their resource-specific prefixes.
unsetMetadataItem() : Response: To delete or unset a particular metadata item.
uploadDirectory() : mixed: Upload the contents of a local directory to a remote container, effectively syncing them.
uploadObject() : DataObject: Upload a single file to the API.
uploadObjects() : array<string|int, Response>: Upload an array of objects for upload. This method optimizes the upload procedure by batching requests for faster execution. This is a very useful procedure when you just have a bunch of unremarkable files to be uploaded quickly. Each file must be under 5GB.
url() : mixed
createRefreshRequest() : mixed
getJsonHeader() : mixed
getPatchHeaders() : mixed
getProperty() : mixed: Grab value out of the data array.
headerIsValidMetadata() : mixed
propertyExists() : bool: Basic check to see whether property exists.
refreshCdnObject() : mixed
setProperty() : mixed: We can set a property under three conditions:
stripPrefix() : mixed: Strip an individual header name of its resource-specific prefix.
checkAttributePrefix() : bool: Checks the attribute $property and only permits it if the prefix is in the specified $prefixes array
isAccessible() : bool: Does the property exist in the object variable list (i.e. does it have public or protected visibility?)

GLOBAL_METADATA_PREFIX


    public
    mixed
    GLOBAL_METADATA_PREFIX
    = 'X'

METADATA_LABEL


    public
    mixed
    METADATA_LABEL
    = 'Container'

PATCH_CONTENT_TYPE


    public
    mixed
    PATCH_CONTENT_TYPE
    = OpenCloudCommonConstantsMime::JSON_PATCH

$name

The name of the container.


    public
        string
    $name

The only restrictions on container names is that they cannot contain a forward slash (/) and must be less than 256 bytes in length. Please note that the length restriction applies to the name after it has been URL encoded. For example, a container named Course Docs would be URL encoded as Course%20Docs - which is 13 bytes in length rather than the expected 11.

$aliases

The aliases configure for the properties of the instance.


    protected
        array<string|int, mixed>
    $aliases
     = array()

$metadata


    protected
        Metadata
    $metadata

$metadataClass


    protected
        string
    $metadataClass
     = 'OpenCloud\Common\Metadata'

The FQCN of the metadata object used for the container.

$service


    protected
        ServiceInterface
    $service

The service object.

$cdn

This is the object that holds all the CDN functionality. This Container therefore acts as a simple wrapper and is interested in storage concerns only.


    private
        CDNContainer|null
    $cdn

$logger

The logger instance


    private
        LoggerInterface
    $logger

$properties

Holds all the properties added by overloading.


    private
        array<string|int, mixed>
    $properties
     = array()

__call()

Intercept non-existent method calls for dynamic getter/setter functionality.


    public
                __call( $method,  $args) : mixed

Parameters

$method :
$args :

Return values

mixed —

__construct()


    public
                __construct(ServiceInterface $service[, mixed $data = null ]) : mixed

Parameters

$service : ServiceInterface
$data : mixed = null

Return values

mixed —

appendToMetadata()

Append a particular array of values to the existing metadata. Analogous to a merge. You must call to actually persist the metadata using the ObjectStore service.


    public
                appendToMetadata(array<string|int, mixed> $values) : array<string|int, mixed>

Parameters

$values : array<string|int, mixed>: The array of values you want to append to metadata.

Return values

array<string|int, mixed> —

Metadata, after $values are appended.

checkJsonError()

Checks the most recent JSON operation for errors.


    public
            static    checkJsonError() : mixed

Return values

mixed —

dataObject()

Get either a fresh data object (no $info), or get an existing one by passing in data for population.


    public
                dataObject([mixed $info = null ]) : DataObject

Parameters

$info : mixed = null

Return values

DataObject —

delete()


    public
                delete([mixed $deleteObjects = false ]) : mixed

Parameters

$deleteObjects : mixed = false

Return values

mixed —

deleteAllObjects()

Deletes all objects that this container currently contains. Useful when doing operations (like a delete) that require an empty container first.


    public
                deleteAllObjects() : mixed

Return values

mixed —

deleteObject()

Delete an object from the API.


    public
                deleteObject(string $name) : mixed

Parameters

$name : string: The name of object you want to delete

Return values

mixed —

deleteWithObjects()


    public
                deleteWithObjects([mixed $secondsToWait = null ]) : mixed

Parameters

$secondsToWait : mixed = null

Return values

mixed —

disableCdn()

Disables the containers CDN function. Note that the container will still be available on the CDN until its TTL expires.


    public
                disableCdn() : Response

Return values

Response —

disableLogging()

Disable access logs.


    public
                disableLogging() : Response

Return values

Response —

enableCdn()

Enable this container for public CDN access.


    public
                enableCdn([null $ttl = null ]) : mixed

Parameters

$ttl : null = null

Return values

mixed —

enableLogging()

Turn on access logs, which track all the web traffic that your data objects accrue.


    public
                enableLogging() : Response

Return values

Response —

fromResponse()

Factory method that instantiates an object from a Response object.


    public
            static    fromResponse(Response $response, ServiceInterface $service) : static

Parameters

$response : Response
$service : ServiceInterface

Return values

static —

generateUuid()


    public
            static    generateUuid() : mixed

Return values

mixed —

getBytesQuota()


    public
                getBytesQuota() : null|string|int

Return values

null|string|int —

getBytesUsed()


    public
                getBytesUsed() : null|string|int

Return values

null|string|int —

getCdn()

Get the CDN object.


    public
                getCdn() : null|CDNContainer

Return values

null|CDNContainer —

getCdnService()

For internal use only.


    public
                getCdnService() : Service

Return values

Service —

The CDN version of the ObjectStore service associated with this ObjectStore resource.

getClient()

For internal use only.


    public
                getClient() : Client

Return values

Client —

The HTTP client associated with the associated ObjectStore service.

getCountQuota()


    public
                getCountQuota() : null|string|int

Return values

null|string|int —

getInstance()


    public
            static    getInstance() : static

Return values

static —

getLogger()

Returns the Logger object.


    public
                getLogger() : LoggerInterface

Return values

LoggerInterface —

getMetadata()

Returns metadata for this object.


    public
                getMetadata() : Metadata

Return values

Metadata —

Metadata set on this object.

getObject()

Retrieve an object from the API. Apart from using the name as an identifier, you can also specify additional headers that will be used fpr a conditional GET request. These are


    public
                getObject(string $name[, array<string|int, mixed> $headers = array() ]) : DataObject

`If-Match'
`If-None-Match'
`If-Modified-Since'
`If-Unmodified-Since'
`Range' For example: bytes=-5 would mean the last 5 bytes of the object bytes=10-15 would mean 5 bytes after a 10 byte offset bytes=32- would mean all dat after first 32 bytes

These are also documented in RFC 2616.

Parameters

$name : string
$headers : array<string|int, mixed> = array()

Return values

DataObject —

getObjectCount()

It would be awesome to put these convenience methods (which are identical to the ones in the Account object) in a trait, but we have to wait for v5.3 EOL first.


    public
                getObjectCount() : null|string|int

Return values

null|string|int —

getPartialObject()

Essentially the same as {@see getObject()}, except only the metadata is fetched from the API.


    public
                getPartialObject( $name[, array<string|int, mixed> $headers = array() ]) : $this

This is useful for cases when the user does not want to fetch the full entity body of the object, only its metadata.

Parameters

$name :
$headers : array<string|int, mixed> = array()

Return values

$this —

getService()

For internal use only.


    public
                getService() : Service

Return values

Service —

The ObjectStore service associated with this ObjectStore resource.

getTransId()

Return the transaction ID for an HTTP API operation. Useful for debugging.


    public
                getTransId() : string

Return values

string —

Transaction ID

getUrl()

For internal use only


    public
                getUrl([string $path = null ][, array<string|int, mixed> $params = array() ]) : Url

Parameters

$path : string = null: Path to add to URL. Optional.
$params : array<string|int, mixed> = array(): Query parameters to add to URL. Optional.

Return values

Url —

URL of this container + path + query parameters.

hasLogger()


    public
                hasLogger() : bool

Return values

bool —

hasLogRetention()

Returns whether this container has log retention enabled or not.


    public
                hasLogRetention() : bool

Return values

bool —

true if this container has log retention enabled; false, otherwise.

isCdnEnabled()

Returns whether this container is CDN-enabled or not.


    public
                isCdnEnabled() : bool

Return values

bool —

true if this container is CDN-enabled; false, otherwise.

makeResourceIteratorOptions()


    public
                makeResourceIteratorOptions(mixed $resource) : mixed

Parameters

$resource : mixed

Return values

mixed —

objectExists()

Check if an object exists inside a container. Uses {@see getPartialObject()} to save on bandwidth and time.


    public
                objectExists( $name) : bool

Parameters

$name :: Object name

Return values

bool —

True, if object exists in this container; false otherwise.

objectList()

Creates a Collection of objects in the container


    public
                objectList([array<string|int, mixed> $params = array() ]) : Collection

Parameters

$params : array<string|int, mixed> = array()

associative array of parameter values.

account/tenant - The unique identifier of the account/tenant.
container- The unique identifier of the container.
limit (Optional) - The number limit of results.
marker (Optional) - Value of the marker, that the object names greater in value than are returned.
end_marker (Optional) - Value of the marker, that the object names less in value than are returned.
prefix (Optional) - Value of the prefix, which the returned object names begin with.
format (Optional) - Value of the serialized response format, either json or xml.
delimiter (Optional) - Value of the delimiter, that all the object names nested in the container are returned.

Return values

Collection —

populate()

Populates the current object based on an unknown data type.


    public
                populate(mixed $info[, mixed $setObjects = true ]) : mixed

Parameters

$info : mixed
$setObjects : mixed = true

Return values

mixed —

primaryKeyField()

For internal use only


    public
                primaryKeyField() : string

Return values

string —

Name of the primary key field for this resource

refresh()


    public
                refresh([mixed $id = null ][, mixed $url = null ]) : mixed

Parameters

$id : mixed = null
$url : mixed = null

Return values

mixed —

retrieveMetadata()

Retrieve metadata from the API. This method will then set and return this value.


    public
                retrieveMetadata() : Metadata

Return values

Metadata —

Metadata returned from the ObjectStore service for this object/container.

saveMetadata()

Push local metadata to the API, thereby executing a permanent save.


    public
                saveMetadata(array<string|int, mixed> $metadata[, bool $stockPrefix = true ]) : Response

Parameters

$metadata : array<string|int, mixed>: The array of values you want to set as metadata
$stockPrefix : bool = true: Whether to prepend each array key with the metadata-specific prefix. For objects, this would be X-Object-Meta-Foo => Bar

Return values

Response —

HTTP response from API operation.

setBytesQuota()


    public
                setBytesQuota( $value) : mixed

Parameters

$value :

Return values

mixed —

setCountQuota()


    public
                setCountQuota( $value) : mixed

Parameters

$value :

Return values

mixed —

setLogger()

Sets the logger.


    public
                setLogger([LoggerInterface $logger = null ]) : $this

Parameters

$logger : LoggerInterface = null

Return values

$this —

setMetadata()

Set the metadata (local-only) for this object. You must call saveMetadata to actually persist the metadata using the ObjectStore service.


    public
                setMetadata(array<string|int, mixed> $data[, bool $constructFromResponse = false ]) : AbstractResource

Parameters

$data : array<string|int, mixed>: Object/container metadata key/value pair array.
$constructFromResponse : bool = false: Whether the metadata key/value pairs were obtiained from an HTTP response of an ObjectStore API operation.

Return values

AbstractResource —

This object, with metadata set.

setStaticErrorPage()

Set the default error page for your static site.


    public
                setStaticErrorPage(mixed $page) : Response

Parameters

$page : mixed

Return values

Response —

The HTTP response for this operation.

setStaticIndexPage()

This method will enable your CDN-enabled container to serve out HTML content like a website.


    public
                setStaticIndexPage(mixed $page) : Response

Parameters

$page : mixed

Return values

Response —

The HTTP response for this API operation.

setupObjectTransfer()

When uploading large files (+5GB), you need to upload the file as chunks using multibyte transfer. This method sets up the transfer, and in order to execute the transfer, you need to call upload() on the returned object.


    public
                setupObjectTransfer([array<string|int, mixed> $options = array() ]) : mixed

Parameters

$options : array<string|int, mixed> = array()

Return values

mixed —

stockHeaders()

Prepend/stock the header names with a resource-specific prefix.


    public
            static    stockHeaders(array<string|int, mixed> $headers) : array<string|int, mixed>

Parameters

$headers : array<string|int, mixed>: Headers to use on ObjectStore resource.

Return values

array<string|int, mixed> —

Headers returned with appropriate prefix as expected by ObjectStore service.

stripNamespace()


    public
                stripNamespace(mixed $namespace) : mixed

Parameters

$namespace : mixed

Return values

mixed —

toCamel()

Convert a string to camelCase format.


    public
                toCamel( $string[, bool $capitalise = true ]) : mixed

Parameters

$string :
$capitalise : bool = true: Optional flag which allows for word capitalization.

Return values

mixed —

toUnderscores()

Convert string to underscore format.


    public
                toUnderscores( $string) : mixed

Parameters

$string :

Return values

mixed —

trimHeaders()

Trim headers of their resource-specific prefixes.


    public
            static    trimHeaders(array<string|int, mixed> $headers) : array<string|int, mixed>

For internal use only.

Parameters

$headers : array<string|int, mixed>: Headers as returned from an HTTP response

Return values

array<string|int, mixed> —

Trimmed headers

unsetMetadataItem()

To delete or unset a particular metadata item.


    public
                unsetMetadataItem( $key) : Response

Parameters

$key :: Metadata key to unset

Return values

Response —

HTTP response returned from API operation to unset metadata item.

uploadDirectory()

Upload the contents of a local directory to a remote container, effectively syncing them.


    public
                uploadDirectory(string $path[, string $targetDir = null ]) : mixed

Parameters

$path : string: The local path to the directory.
$targetDir : string = null: The path (or pseudo-directory) that all files will be nested in.

Return values

mixed —

uploadObject()

Upload a single file to the API.


    public
                uploadObject( $name,  $data[, array<string|int, mixed> $headers = array() ]) : DataObject

Parameters

$name :: Name that the file will be saved as in your container.
$data :: Either a string or stream representation of the file contents to be uploaded.
$headers : array<string|int, mixed> = array(): Optional headers that will be sent with the request (useful for object metadata).

Return values

DataObject —

uploadObjects()

Upload an array of objects for upload. This method optimizes the upload procedure by batching requests for faster execution. This is a very useful procedure when you just have a bunch of unremarkable files to be uploaded quickly. Each file must be under 5GB.


    public
                uploadObjects(array<string|int, mixed> $files[, array<string|int, mixed> $commonHeaders = array() ][, string $returnType = ReturnType::RESPONSE_ARRAY ]) : array<string|int, Response>

Parameters

$files : array<string|int, mixed>: With the following array structure: name' Name that the file will be saved as in your container. Required. path' Path to an existing file, OR `body' Either a string or stream representation of the file contents to be uploaded.
$commonHeaders : array<string|int, mixed> = array()
$returnType : string = ReturnType::RESPONSE_ARRAY: One of OpenCloud\ObjectStore\Enum\ReturnType::RESPONSE_ARRAY (to return an array of Guzzle\Http\Message\Response objects) or OpenCloud\ObjectStore\Enum\ReturnType::DATA_OBJECT_ARRAY (to return an array of OpenCloud\ObjectStore\Resource\DataObject objects).

Return values

array<string|int, Response> —

or OpenCloud\ObjectStore\Resource\DataObject[] depending on $returnType

url()


    public
                url([mixed $path = null ][, array<string|int, mixed> $query = array() ]) : mixed

Parameters

$path : mixed = null
$query : array<string|int, mixed> = array()

Return values

mixed —

createRefreshRequest()


    protected
                createRefreshRequest() : mixed

Return values

mixed —

getJsonHeader()


    protected
            static    getJsonHeader() : mixed

Return values

mixed —

getPatchHeaders()


    protected
            static    getPatchHeaders() : mixed

Return values

mixed —

getProperty()

Grab value out of the data array.


    protected
                getProperty(string $property) : mixed

Parameters

$property : string

Return values

mixed —

headerIsValidMetadata()


    protected
            static    headerIsValidMetadata(mixed $header) : mixed

Parameters

$header : mixed

Return values

mixed —

propertyExists()

Basic check to see whether property exists.


    protected
                propertyExists(string $property[, bool $allowRetry = true ]) : bool

Parameters

$property : string: The property name being investigated.
$allowRetry : bool = true: If set to TRUE, the check will try to format the name in underscores because there are sometimes discrepancies between camelCaseNames and underscore_names.

Return values

bool —

refreshCdnObject()


    protected
                refreshCdnObject() : mixed

Return values

mixed —

setProperty()

We can set a property under three conditions:


    protected
                setProperty(mixed $property, mixed $value) : mixed

If it has a concrete setter: setProperty()
If the property exists
If the property name's prefix is in an approved list

Parameters

$property : mixed
$value : mixed

Return values

mixed —

stripPrefix()

Strip an individual header name of its resource-specific prefix.


    protected
            static    stripPrefix( $header) : mixed

Parameters

$header :

Return values

mixed —

checkAttributePrefix()

Checks the attribute $property and only permits it if the prefix is in the specified $prefixes array


    private
                checkAttributePrefix(string $property) : bool

This is to support extension namespaces in some services.

Parameters

$property : string: the name of the attribute

Return values

bool —

isAccessible()

Does the property exist in the object variable list (i.e. does it have public or protected visibility?)


    private
                isAccessible( $property) : bool

Parameters

$property :

Return values

bool —