Provide HTTP transport with CURL. More...

Inheritance diagram for CURLTransport:

Public Member Functions
	__destruct ()
	doRequest ($uri, $method= 'GET', $headers=array(), $body=NULL)
	Perform a request.
	doRequestWithResource ($uri, $method, $headers, $resource)
	Perform a request, but use a resource to read the body.
	setHeaders ($curl, $headers)

Public Attributes
const	HTTP_USER_AGENT_SUFFIX = ' (c93c0a) CURL/1.0'
Public Attributes inherited from Transporter
const	HTTP_USER_AGENT = 'HPCloud-PHP/1.0'

Protected Member Functions
	handleDoRequest ($uri, $method, $headers, $in=NULL)
	Internal workhorse.
	execCurl ($handle)
	Poor man's connection pooling.
	fetchHeaders ($file)
	This function reads the header file into an array.
	determineMethod ($curl, $method)
	Set the appropriate constant on the CURL object.

Protected Attributes
	$curlInst = NULL
	$multi = NULL
	The curl_multi instance.

Detailed Description

Provide HTTP transport with CURL.

You should choose the Curl backend if...

You KNOW Curl support is compiled into your PHP version
You do not like the built-in PHP HTTP handler
Performance is a big deal to you
You will be sending large objects (>2M)
Or PHP stream wrappers for URLs are not supported on your system.

CURL is demonstrably faster than the built-in PHP HTTP handling, so ths library gives a performance boost. Error reporting is slightly better too.

But the real strong point to Curl is that it can take file objects and send them over HTTP without having to buffer them into strings first. This saves memory and processing.

The only downside to Curl is that it is not available on all hosts. Some installations of PHP do not compile support.

Definition at line 53 of file CURLTransport.php.

Constructor & Destructor Documentation

__destruct ( )

Definition at line 68 of file CURLTransport.php.

Member Function Documentation

determineMethod	(	$curl,
		$method
	)

protected

Set the appropriate constant on the CURL object.

Curl handles method name setting in a slightly counter-intuitive way, so we have a special function for setting the method correctly. Note that since we do not POST as www-form-*, we use a custom post.

Parameters

resource	$curl	A curl object.
string	$method	An HTTP method name.

Definition at line 374 of file CURLTransport.php.

Referenced by CURLTransport\handleDoRequest().

doRequest	(	$uri,
		$method = `'GET'`,
		$headers = `array()`,
		$body = `NULL`
	)

Perform a request.

Invoking this method causes a single request to be relayed over the transporter. The transporter MUST be capable of handling multiple invocations of a doRequest() call.

Parameters

string	$uri	The target URI.
string	$method	The method to be sent.
array	$headers	An array of name/value header pairs.
string	$body	The string containing the request body.

Implements Transporter.

Definition at line 85 of file CURLTransport.php.

References CURLTransport\handleDoRequest().

doRequestWithResource	(	$uri,
		$method,
		$headers,
		$resource
	)

Perform a request, but use a resource to read the body.

This is a special version of the doRequest() function. It handles a very spefic case where...

The HTTP verb requires a body (viz. PUT, POST)
The body is in a resource, not a string

Examples of appropriate cases for this variant:

Uploading large files.
Streaming data out of a stream and into an HTTP request.
Minimizing memory usage ($content strings are big).

Note that all parameters are required.

Parameters

string	$uri	The target URI.
string	$method	The method to be sent.
array	$headers	An array of name/value header pairs.
mixed	$resource	The string with a file path or a stream URL; or a file object resource. If it is a string, then it will be opened with the default context. So if you need a special context, you should open the file elsewhere and pass the resource in here.

Implements Transporter.

Definition at line 107 of file CURLTransport.php.

References CURLTransport\handleDoRequest().

execCurl ( $handle )

protected

Poor man's connection pooling.

Instead of using curl_exec(), we use curl_multi_* to handle the processing The CURL multi library tracks connections, and basically provides connection sharing across requests. So two requests made to the same server will use the same connection (even when they are executed separately) assuming that the remote server supports this.

We've noticed that this improves performance substantially, especially since SSL requests only require the SSL handshake once.

Parameters

resource $handle A CURL handle from curl_init().

Return values

boolean

Returns: boolean Returns a boolean value indicating whether or not CURL could process the request.

Definition at line 301 of file CURLTransport.php.

References CURLTransport\$multi.

Referenced by CURLTransport\handleDoRequest().

fetchHeaders ( $file )

protected

This function reads the header file into an array.

This format mataches the format returned by the stream handlers, so we can re-use the header parsing logic in Response.

Parameters

resource $file A file pointer to the file that has the headers.

Return values

array

Returns: array An array of headers, one header per line.

Definition at line 346 of file CURLTransport.php.

References $file.

Referenced by CURLTransport\handleDoRequest().

handleDoRequest	(	$uri,
		$method,
		$headers,
		$in = `NULL`
	)

protected

Internal workhorse.

Definition at line 128 of file CURLTransport.php.

References Bootstrap\config(), CURLTransport\determineMethod(), CURLTransport\execCurl(), CURLTransport\fetchHeaders(), Bootstrap\hasConfig(), and CURLTransport\setHeaders().

Referenced by CURLTransport\doRequest(), and CURLTransport\doRequestWithResource().

setHeaders	(	$curl,
		$headers
	)

Definition at line 402 of file CURLTransport.php.

References $name.

Referenced by CURLTransport\handleDoRequest().

Member Data Documentation

$curlInst = NULL

protected

Definition at line 58 of file CURLTransport.php.

$multi = NULL

protected

The curl_multi instance.

By using curl_multi to wrap CURL requests, we can re-use the same connection for multiple requests. This has tremendous value for cases where several transactions occur in short order.

Definition at line 66 of file CURLTransport.php.

Referenced by CURLTransport\execCurl().

const HTTP_USER_AGENT_SUFFIX = ' (c93c0a) CURL/1.0'

Definition at line 56 of file CURLTransport.php.

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

src/HPCloud/Transport/CURLTransport.php

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation