A Transport response. More...

Public Member Functions
	__construct ($handle, $metadata, $headers=NULL)
	Construct a new Response.
	__destruct ()
	Destroy the object.
	file ()
	Get the file handle.
	content ()
	Get the contents of this response as a string.
	metadata ()
	Get metadata.
	header ($name, $default=NULL)
	Convenience function to retrieve a single header.
	headers ()
	Get the HTTP headers.
	status ()
	Get the HTTP status code.
	statusMessage ()
	The server-returned status message.
	protocol ()
	The protocol and version used for this transaction.
	__toString ()

Static Public Member Functions
static	failure ($code, $err= 'Unknown', $uri= '', $method= '', $extra= '')
	Handle error response.

Protected Member Functions
	parseHeaders ($headerArray)
	Parse the HTTP headers.

Protected Attributes
	$handle
	$metadata
	$headers

Detailed Description

A Transport response.

When one of the transporters makes a request, it will return one of these as a response. The response is simplified to the needs of the HP Cloud services and isn't a general purpose HTTP response object.

The transport wraps three pieces of information:

The response body.
The HTTP headers.
Other metadata about the request.

There are two different "modes" for working with a response object. Either you can work with the raw file data directly or you can work with the string content of the file.

You should work with the raw file directly (using file()) if you are working with large objects, such as those returned from Object Storage.

You may prefer to work with string data when you are working with the JSON data returned by the vast majority of requests.

Definition at line 53 of file Response.php.

Constructor & Destructor Documentation

__construct	(	$handle,
		$metadata,
		$headers = `NULL`
	)

Construct a new Response.

The Transporter implementations use this to construct a response.

Definition at line 114 of file Response.php.

References Response\$handle, Response\$headers, Response\$metadata, Response\headers(), Response\metadata(), and Response\parseHeaders().

__destruct ( )

Destroy the object.

Definition at line 128 of file Response.php.

Member Function Documentation

__toString ( )

Definition at line 308 of file Response.php.

References Response\content().

content ( )

Get the contents of this response as a string.

This returns the body of the response (no HTTP headers) as a single string.

Attention: IMPORTANT: This can only be called once. HTTP streams handled by PHP's stream wrapper cannot be rewound, and to keep memory usage low, we don't want to store the entire content in a string.

Return values

string

Returns: string The contents of the response body.

Definition at line 169 of file Response.php.

References Response\header(), and Response\metadata().

Referenced by Response\__toString().

static failure	(	$code,
		$err = `'Unknown'`,
		$uri = `''`,
		$method = `''`,
		$extra = `''`
	)

static

Handle error response.

When a response is a failure, it should pass through this function, which generates the appropriate exception and then throws it.

Parameters

int	$code	The HTTP status code, e.g. 404, 500.
string	$err	The error string, as bubbled up.
string	$uri	The URI.
string	$method	The HTTP method, e.g. 'HEAD', 'GET', 'DELETE'.
string	$extra	An extra string of debugging information. (NOT USED)

Exceptions

HPCloud::Exception A wide variety of HPCloud::Transport exceptions.

Definition at line 78 of file Response.php.

file ( )

Get the file handle.

This provides raw access to the IO stream. Users are responsible for all IO management.

Note that if the handle is closed through this object, the handle returned by file() will also be closed (they are one and the same).

Return values

resource

Returns: resource A file handle.

Definition at line 149 of file Response.php.

header	(	$name,
		$default = `NULL`
	)

Convenience function to retrieve a single header.

Parameters

string	$name	The name of the header.
mixed	$default	An optional default value.

Return values

mixed

Returns: mixed The value, if found, or the default, is specified, or NULL.

Definition at line 228 of file Response.php.

References $name, and Response\headers().

Referenced by Response\content().

headers ( )

Get the HTTP headers.

This returns an associative array of all of the headers returned by the remote server.

These are available even if the stream has been closed.

Return values

array

Returns: array The array of headers.

Definition at line 248 of file Response.php.

Referenced by Response\__construct(), and Response\header().

metadata ( )

Get metadata.

This returns any available metadata on the file. Not all Transporters will have any associated metadata. Some return extra information on the processing of the data.

Return values

array

Returns: array An associative array of metadata about the transaction resulting in this response.

Definition at line 212 of file Response.php.

Referenced by Response\__construct(), and Response\content().

parseHeaders ( $headerArray )

protected

Parse the HTTP headers.

Parameters

array $headerArray An indexed array of headers, as returned by the PHP stream library.

Return values

array

Returns: array An associative array of header name/value pairs.

Definition at line 322 of file Response.php.

References $name, Response\parseHeaders(), and Response\protocol().

Referenced by Response\__construct(), and Response\parseHeaders().

protocol ( )

The protocol and version used for this transaction.

Example: HTTP/1.1

Return values

string

Returns: string The protocol name and version.

Definition at line 304 of file Response.php.

Referenced by Response\parseHeaders().

status ( )

Get the HTTP status code.

This will give the HTTP status codes on successful transactions.

A successful transaction is one that does not generate an HTTP error. This does not necessarily mean that the REST-level request was fulfilled in the desired way.

Example: Attempting to create a container in object storage when such a container already exists results in a 202 response code, which is an HTTP success code, but indicates failure to fulfill the requested action.

Unsuccessful transactions throw exceptions and do not return Response objects. Example codes of this sort: 403, 404, 500.

Redirects are typically followed, and thus rarely (if ever) appear in a Response object.

Return values

int

Returns: int The HTTP code, e.g. 200 or 202.

Definition at line 277 of file Response.php.

statusMessage ( )

The server-returned status message.

Typically these follow the HTTP protocol specification's recommendations. e.g. 200 returns 'OK'.

Return values

string

Returns: string A server-generated status message.

Definition at line 291 of file Response.php.

Member Data Documentation

$handle

protected

Definition at line 55 of file Response.php.

Referenced by Response\__construct().

$headers

protected

Definition at line 57 of file Response.php.

Referenced by Response\__construct().

$metadata

protected

Definition at line 56 of file Response.php.

Referenced by Response\__construct().

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

src/HPCloud/Transport/Response.php

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation