Inheritance diagram for Object:

Public Member Functions
	__construct ($name, $content=NULL, $type=NULL)
	Construct a new object for storage.
	setMetadata (array $array)
	Set the metadata.
	metadata ()
	Get any associated metadata.
	setName ($name)
	Override (change) the name of an object.
	name ()
	Get the name.
	setContentType ($type)
	Set the content type (MIME type) for the object.
	contentType ()
	Get the content type.
	setContent ($content, $type=NULL)
	Set the content for this object.
	content ()
	Retrieve the content.
	contentLength ()
	Calculate the content length.
	eTag ()
	Generate an ETag for the ObjectStorage server.
	setEncoding ($encoding)
	Set the encoding for a file.
	encoding ()
	Get the encoding (if any) for this object.
	setDisposition ($disposition)
	Set the content disposition.
	disposition ()
	Get the current disposition string, if any.
	setAdditionalHeaders ($headers)
	Set additional headers for storage.
	additionalHeaders ()
	Return additional headers.
	removeHeaders ($keys)
	Remove headers.
	isChunked ()
	This object should be transmitted in chunks.

Public Attributes
const	DEFAULT_CONTENT_TYPE = 'application/octet-stream'

Protected Attributes
	$name
	The name of the object.
	$content
	The content.
	$contentType = self::DEFAULT_CONTENT_TYPE
	The content type.
	$metadata = array()
	Associative array of stored metadata.
	$contentEncoding
	$contentDisposition
	$additionalHeaders = array()
	Extension mechanism for new headers.

Detailed Description

An object for ObjectStorage.

The HPCloud ObjectStorage system provides a method for storing complete chunks of data (objects) in the cloud. This class describes such a chunk of data.

An object has the following basic components:

Name: A filename (which may be pathlike, subject to OpenStack's pathing rules).
Content: The content of the object.
Content type: The MIME type of the object. Examples:
- text/plain; charset=UTF-8
- image/png
- application/x-my-custom-mime
Metadata: File attributes that are stored along with the file on object store.

Objects are stored and retrieved by name. So it is assumed that, per container, no more than one file with a given name exists.

You may create Object instance and then store them in Containers. Likewise, a Container instance can retrieve Object instances from the remote object store.

Definition at line 55 of file Object.php.

Constructor & Destructor Documentation

__construct	(	$name,
		$content = `NULL`,
		$type = `NULL`
	)

Construct a new object for storage.

Parameters

string	$name	A name (may be pathlike) for the object.
string	$content	Optional content to store in this object. This is the same as calling setContent().
string	$type	Optional content type for this content. This is the same as calling setContentType().

Definition at line 107 of file Object.php.

References $content, $name, Object\content(), Object\contentType(), and Object\name().

Member Function Documentation

additionalHeaders ( )

Return additional headers.

Headers here have likely not been stored remotely until Container::save() is called on the object.

Definition at line 492 of file Object.php.

Referenced by Object\removeHeaders(), Container\save(), and Object\setAdditionalHeaders().

content ( )

Retrieve the content.

Retrieve the ENTIRE content of an object.

Note that this may be binary data (depending on what the original content is). PHP strings are generally binary safe, but use this with caution if you do not know what kind of data is stored in an object.

OpenStack does not do anything to validate that the content type is accurate. While contentType() is intended to provide useful information, poorly managed data can be written with the wrong content type.

When extending this class, you should make sure that this function returns the entire contents of an object.

Return values

string

Returns: string The content of the file.

Reimplemented in RemoteObject.

Definition at line 315 of file Object.php.

References $content.

Referenced by Object\__construct(), Object\contentLength(), Object\eTag(), Container\save(), Object\setContent(), and Container\updateMetadata().

contentLength ( )

Calculate the content length.

This returns the number of bytes in a piece of content (not the number of characters). Among other things, it is used to let the remote object store know how big of an object to expect when transmitting data.

When extending this class, you should make sure to calculate the content length appropriately.

Return values

int

Returns: int The length of the content, in bytes.

Reimplemented in RemoteObject.

Definition at line 334 of file Object.php.

References Object\content().

Referenced by Container\save().

contentType ( )

Get the content type.

This returns the currently set content type.

Return values

string

Returns: string The content type, including any additional options.

Definition at line 256 of file Object.php.

Referenced by Object\__construct(), Container\save(), Object\setContent(), Object\setContentType(), and Container\updateMetadata().

disposition ( )

Get the current disposition string, if any.

See setDisposition() for discussion.

Return values

string

Returns: string The disposition string, or NULL if none is set.

Definition at line 439 of file Object.php.

Referenced by Container\save().

encoding ( )

Get the encoding (if any) for this object.

Encoding is used to indicate how a file was encoded or compressed. See setEncoding() for more information.

Return values

string

Returns: string The encoding type.

Definition at line 395 of file Object.php.

Referenced by Container\save().

eTag ( )

Generate an ETag for the ObjectStorage server.

OpenStack uses ETag to pass validation data. This generates an ETag using an MD5 hash of the content.

When extending this class, generate an ETag by creating an MD5 of the entire object's content (but not the metadata or name).

Return values

string

Returns: string An MD5 value as a string of 32 hex digits (0-9a-f).

Reimplemented in RemoteObject.

Definition at line 352 of file Object.php.

References Object\content().

Referenced by Container\save().

isChunked ( )

This object should be transmitted in chunks.

Indicates whether or not this object should be transmitted as chunked data (in HTTP).

This should be used when (a) the file size is large, or (b) the exact size of the file is unknown.

If this returns TRUE, it does not guarantee that the data will be transmitted in chunks. But it recommends that the underlying transport layer use chunked encoding.

The contentLength() method is not called for chunked transfers. So if this returns TRUE, contentLength() is ignored.

Return values

boolean

Returns: boolean TRUE to recommend chunked transfer, FALSE otherwise.

Definition at line 544 of file Object.php.

Referenced by Container\save().

metadata ( )

Get any associated metadata.

This returns an associative array of all metadata for this object.

Return values

array

Returns: array An associative array of metadata. This may be empty.

Reimplemented in RemoteObject.

Definition at line 170 of file Object.php.

Referenced by Container\save(), Object\setMetadata(), and Container\updateMetadata().

name ( )

Get the name.

Returns the name of an object. If the name has been overwritten using setName(), this will return the latest (overwritten) name.

Return values

string

Returns: string The name of the object.

Definition at line 207 of file Object.php.

References $name.

Referenced by Object\__construct(), Container\copy(), Container\save(), Object\setName(), and Container\updateMetadata().

removeHeaders ( $keys )

Remove headers.

This takes an array of header names, and removes any matching headers. Typically, only headers set by setAdditionalHeaders() are removed from an Object. (RemoteObject works differently).

Attention: Many headers are generated automatically, such as Content-Type and Content-Length. Removing these will simply result in their being regenerated.

Parameters

array $keys The header names to be removed.

Return values

HPCloud::Storage::ObjectStorage::Object

Returns: $this for the current object so it can be used in chaining methods.

Reimplemented in RemoteObject.

Definition at line 516 of file Object.php.

References Object\additionalHeaders().

setAdditionalHeaders ( $headers )

Set additional headers for storage.

Attention: EXPERT: You will need to understand OpenStack internals to use this effectively.

Headers set here will be added to the HTTP request during save operations. They are not merged into existing headers until save-time.

This provides a mechanism for adding extension headers. CORS headers and possibly others are stored by Swift, but have no semantic value to Swift or to popular user agents.

There are a few things to note about this mechanism:

Existing headers cannot be overwritten. Only new headers can be added.
Headers are not merged. They are simply sent to the remote server. A new object must be retrieved from the server before these headers will be accessible.
Swift only stores certain headers. If you supply an unrecognized header to Swift, it may simply ignore it.
The RemoteObject::headers() method provides access to all of the headers returned from Swift.
Headers are merged in as they are, with no cleaning, encoding, or checking. You must ensure that the headers are in the proper format.

Parameters

array $headers An associative array where each name is an HTTP header name, and each value is the HTTP header value. No encoding or escaping is done.

Return values

HPCloud::Storage::ObjectStorage::Object

Returns: $this so the method can be used in chaining.

Definition at line 481 of file Object.php.

References Object\additionalHeaders().

setContent	(	$content,
		$type = `NULL`
	)

Set the content for this object.

Place the content into the object. Typically, this is string content that will be stored remotely.

PHP's string is backed by a robust system that can accomodate moderately sized files. However, it is best to keep strings short (<2MB, for example – test for your own system's sweet spot). Larger data may be better handled with file system entries or database storage.

Note that the OpenStack will not allow files larger than 5G, and PHP will likely croak well before that marker. So use discretion.

Parameters

string	$content	The content of the object.
string	$type	The content type (MIME type). This can be set here for convenience, or you can call setContentType() directly.

Return values

HPCloud::Storage::ObjectStorage::Object

Returns: $this so the method can be used in chaining.

Definition at line 285 of file Object.php.

References $content, Object\content(), and Object\contentType().

Referenced by RemoteObject\content(), and RemoteObject\refresh().

setContentType ( $type )

Set the content type (MIME type) for the object.

Object storage is, to a certain degree, content-type aware. For that reason, a content type is mandatory.

The default MIME type used is application/octet-stream, which is the generic content type for a byte stream. Where possible, you should set a more accurate content type.

All HTTP type options are allowed. So, for example, you can add a charset to a text type:

<?php
$o = new Object('my.html');
$o->setContentType('text/html; charset=iso-8859-13');
?>

Content type is not parsed or verified locally (though it is remotely). It can be dangerous, too, to allow users to specify a content type.

Parameters

string $type A valid content type.

Return values

HPCloud::Storage::ObjectStorage::Object

Returns: $this so the method can be used in chaining.

Definition at line 242 of file Object.php.

References Object\contentType().

Referenced by RemoteObject\extractFromHeaders().

setDisposition ( $disposition )

Set the content disposition.

This makes it possible to have the file act like a download (in a browser or similar agent), even if the MIME type normally triggers a display.

The typical value for this is:

<?php
$object->setDisposition('attachment; filename=foo.png');
?>

A disposition string should not include any newline characters or binary data.

Parameters

string $disposition A valid disposition declaration. These are defined in various HTTP specifications.

Return values

HPCloud::Storage::ObjectStorage::Object

Returns: $this so the method can be used in chaining.

Definition at line 424 of file Object.php.

Referenced by RemoteObject\extractFromHeaders().

setEncoding ( $encoding )

Set the encoding for a file.

You can use content encoding on compressed content to indicate to the receiving agent that a file is encoded using a specific compression type.

Typical compression types are 'gzip', 'zip', and 'compress', though many others exist.

This allows you, for example, to save a zipped file, yet preserve its underlying content type. For example, for a gzipped text/plain file, you can set the content type to "text/plain" and the encoding to "gzip". This allows many user agents to receive the compressed data and automatically decompress them and display them correctly.

Parameters

string $encoding A valid encoding type.

Return values

HPCloud::Storage::ObjectStorage::Object

Returns: $this so the method can be used in chaining.

Definition at line 379 of file Object.php.

Referenced by RemoteObject\extractFromHeaders().

setMetadata ( array $array )

Set the metadata.

OpenStack allows you to specify metadata for a file. Metadata items must follow these conventions:

names must contain only letters, numbers, and short dashes. Since OpenStack normalizes the name to begin with uppercase, it is suggested that you follow this convetion: Foo, not foo. Or you can do your own normalizing (such as converting all to lowercase. OpenStack limits the name length to 126 unicode chars.
values must be encoded if they contain newlines or binary data. While the exact encoding is up to you, Base-64 encoding is probably your best bet. OpenStack limits the value to 256 unicode chars.

(The docs are ambiguous – they say chars, but they may mean bytes.)

This library does only minimal processing of metadata, and does no error checking, escaping, etc. This is up to the implementor. The OpenStack Swift implementation does not dictate what encoding is used, though it suggests url encoding of both name and values.

Currently, no length checking is performed in the library, nor is any encoding of the data performed.

IMPORTANT: Current versions of OpenStack Swift normalize metadata names so that the name is always given an initial capital leter. That is, foo becomes Foo.

Parameters

array $array An associative array of metadata names to values.

Return values

HPCloud::Storage::ObjectStorage::Object

Returns: $this so the method can be used in chaining.

Definition at line 155 of file Object.php.

References Object\metadata().

Referenced by RemoteObject\extractFromHeaders().

setName ( $name )

Override (change) the name of an object.

Note that this changes only the local copy of an object. It does not rename the remote copy. In fact, changing the local name and then saving it will result in a new object being created in the object store.

To copy an object, see HPCloud::Storage::ObjectStorage::Container::copyObject().

Parameters

string $name A file or object name.

Return values

HPCloud::Storage::ObjectStorage::Object

Returns: $this so the method can be used in chaining.

Definition at line 192 of file Object.php.

References $name, and Object\name().

Member Data Documentation

$additionalHeaders = array()

protected

Extension mechanism for new headers.

Definition at line 92 of file Object.php.

Referenced by RemoteObject\additionalHeaders().

$content

protected

The content.

Subclasses needn't use this to store an object's content, as they may prefer filesystem backing.

Definition at line 73 of file Object.php.

$contentDisposition

protected

Definition at line 87 of file Object.php.

$contentEncoding

protected

Definition at line 86 of file Object.php.

$contentType = self::DEFAULT_CONTENT_TYPE

protected

The content type.

The default type is 'application/octet-stream', which marks this as a generic byte stream.

Definition at line 80 of file Object.php.

$metadata = array()

protected

Associative array of stored metadata.

Definition at line 84 of file Object.php.

$name

protected

The name of the object.

This can be path-like, subject to OpenStack's definition of "path-like".

Definition at line 65 of file Object.php.

const DEFAULT_CONTENT_TYPE = 'application/octet-stream'

Definition at line 57 of file Object.php.

The documentation for this class was generated from the following file:

src/HPCloud/Storage/ObjectStorage/Object.php

Public Member Functions

Public Attributes

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation