X-Git-Url: https://git.m6w6.name/?a=blobdiff_plain;f=docs%2Ffunctions.html;h=fa3d1c5d301efc799c1db0f723f2d7195fc6d690;hb=419ba9235752d56f15b393fc7969316978c6c721;hp=8979c256b455fb05168ffdce2dbcf759e29e4a27;hpb=b63e146a77c6512cae1574c0bb520b3a7bbec1e7;p=m6w6%2Fext-http diff --git a/docs/functions.html b/docs/functions.html index 8979c25..fa3d1c5 100644 --- a/docs/functions.html +++ b/docs/functions.html @@ -43,9 +43,29 @@ p br, pre code br { display: block; } + .toc { + position: absolute; + top: 10px; + right: 10px; + width: 300px; + height: 95%; + overflow: scroll; + font-size: .9em; + } + body>div.toc { + position: fixed; + } + .toc ul { + padding-left: 15px; + margin-left: 0; + } + .toc li { + padding: 0; + margin: 0; + } -

http_functions.c

+

http_functions.c

string http_date([int timestamp])

Compose a valid HTTP date regarding RFC 822/1123
looking like: "Wed, 22 Dec 2004 11:34:47 GMT"

@@ -61,7 +81,7 @@ The host will be taken either from the Host HTTP header of the client
the SERVER_NAME or just localhost if prior are not available.
If a port is pecified in either the url or as sperate parameter,
it will be added if it differs from te default port for HTTP(S).

-

Returns the absolute URI as string.

+

Returns the absolute URI as string on success or false on failure.

Examples:



 <?php
$uri = http_build_uri("page.php", "https", NULL, 488);
?>

 

@@ -93,6 +113,19 @@ if none match.

 <?php
$charsets = array(
        'iso-8859-1', // default
        'iso-8859-2',
        'iso-8859-15',
        'utf-8'
);

$pref = http_negotiate_charset($charsets, $result);

if (strcmp($pref, 'iso-8859-1')) {
        iconv_set_encoding('internal_encoding', 'iso-8859-1');
        iconv_set_encoding('output_encoding', $pref);
        ob_start('ob_iconv_handler');
}

print_r($result);
?>

+

string http_negotiate_ctype(array supported[, array &result])

+

This function negotiates the clients preferred content type based on its
+Accept HTTP header. The qualifier is recognized and content types
+without qualifier are rated highest.

+

Expects an array as parameter cotaining the supported content types as values.
+If the optional second parameter is supplied, it will be filled with an
+array containing the negotiation results.

+

Returns the negotiated content type or the default content type
+(i.e. first array entry) if none match.

+

Example:



+<?php
$ctypes = array('application/xhtml+xml', 'text/html');
http_send_content_type(http_negotiate_content_type($ctypes));
?>

+

+

bool http_send_status(int status)

Send HTTP status code.

Expects an HTTP status code as parameter.

@@ -159,7 +192,7 @@ a "304 Not Modified" status code is issued.

string ob_etaghandler(string data, int mode)

For use with ob_start(). Output buffer handler generating an ETag with
the hash algorythm specified with the INI setting "http.etag_mode".

-

void http_throttle(double sec[, int bytes = 2097152])

+

void http_throttle(double sec[, int bytes = 40960])

Sets the throttle delay and send buffer size for use with http_send() API.
Provides a basic throttling mechanism, which will yield the current process
resp. thread until the entity has been completely sent, though.

@@ -250,7 +283,7 @@ array where the following keys will be recognized:

 - redirect:
  - compress:         bool, whether to allow gzip/deflate content encoding

                      (defaults to true)

  - port:             int, use another port as specified in the url

- - referer:          string, the referer to sends

+ - referer:          string, the referer to send

  - useragent:        string, the user agent to send

                      (defaults to PECL::HTTP/version (PHP/version)))

  - headers:          array, list of custom headers as associative array

@@ -307,7 +340,7 @@ See http_get() for a full list of available options.

 
Unregister a previously registered custom request method.

 
Expects either the request method name or ID.

 
Returns TRUE on success, or FALSE on failure.

-
long http_request_method_exists(mixed method)

+
int http_request_method_exists(mixed method)

 
Check if a request method is registered (or available by default).

 
Expects either the request method name or ID as parameter.

 
Returns TRUE if the request method is known, else FALSE.

@@ -317,8 +350,60 @@ See http_get() for a full list of available options.

 
Returns the request method name as string on success, or FALSE on failure.

 
string http_build_query(mixed formdata [, string prefix[, string arg_separator]])

 
Generates a form-encoded query string from an associative array or object.

+
string http_gzencode(string data[, int level = -1])

+
Compress data with the HTTP compatible GZIP encoding.

+
Expects the first parameter to be a string which contains the data that

+should be encoded.  Additionally accepts an optional in paramter specifying

+the compression level, where -1 is default, 0 is no compression and 9 is

+best compression ratio.

+
Returns the encoded string on success, or NULL on failure.

+
string http_gzdecode(string data)

+
Uncompress data compressed with the HTTP compatible GZIP encoding.

+
Expects a string as parameter containing the compressed data.

+
Returns the decoded string on success, or NULL on failure.

+
string http_deflate(string data[, int level = -1])

+
Compress data with the HTTP compatible DEFLATE encoding.

+
Expects the first parameter to be a string containing the data that should

+be encoded.  Additionally accepts an optional int parameter specifying the

+compression level, where -1 is default, 0 is no compression and 9 is best

+compression ratio.

+
Returns the encoded string on success, or NULL on failure.

+
string http_inflate(string data)

+
Uncompress data compressed with the HTTP compatible DEFLATE encoding.

+
Expects a string as parameter containing the compressed data.

+
Returns the decoded string on success, or NULL on failure.

+
string http_compress(string data[, int level = -1])

+
Compress data with the HTTP compatible COMPRESS encoding.

+
Expects the first parameter to be a string containing the data which should

+be encoded.  Additionally accepts an optional int parameter specifying the

+compression level, where -1 is default, 0 is no compression and 9 is best

+compression ratio.

+
Returns the encoded string on success, or NULL on failure.

+
string http_uncompress(string data)

+
Uncompress data compressed with the HTTP compatible COMPRESS encoding.

+
Expects a string as parameter containing the compressed data.

+
Returns the decoded string on success, or NULL on failure.

+
int http_support([int feature = 0])

+
Check for feature that require external libraries.

+
Accpepts an optional in parameter specifying which feature to probe for.

+If the parameter is 0 or omitted, the return value contains a bitmask of 

+all supported features that depend on external libraries.

+
Available features to probe for are:

+

+
Returns int, whether requested feature is supported, or a bitmask with

+all supported features.

 

-
http_message_object.c

+
http_message_object.c

 
HttpMessage

 
void HttpMessage::__construct([string message])

 
Instantiate a new HttpMessage object.

@@ -406,14 +491,24 @@ This provides limited functionality compared to HttpRequest and HttpResponse.
Accepts a bool parameter which specifies whether the returned string

 should also contain any parent messages.

 
Returns the full message as string.

+
int HttpMessage::count()

+
Implements Countable.

+
Returns the number of parent messages + 1.

+
string HttpMessage::serialize()

+
Implements Serializable.

+
Returns the serialized representation of the HttpMessage.

+
void HttpMessage::unserialize(string serialized)

+
Implements Serializable.

+
Re-constructs the HttpMessage based upon the serialized string.

 

-
http_request_object.c

+
http_request_object.c

 
HttpRequest

-
void HttpRequest::__construct([string url[, int request_method = HTTP_METH_GET]])

+
void HttpRequest::__construct([string url[, int request_method = HTTP_METH_GET[, array options]]])

 
Instantiate a new HttpRequest object.

 
Accepts a string as optional parameter containing the target request url.

 Additianally accepts an optional int parameter specifying the request method

-to use.

+to use and an associative array as optional third parameter which will be

+passed to HttpRequest::setOptions(). 

 
Throws HttpException.

 
void HttpRequest::__destruct()

 
Destroys the HttpRequest object.

@@ -474,7 +569,7 @@ pairs to add.

 
bool HttpRequest::setMethod(int request_method)

 
Set the request method.

 
Expects an int as parameter specifying the request method to use.

-In PHP 5.1+ HttpRequest::METH, otherwise the HTTP_METH constants can be used.

+In PHP 5.1+ HttpRequest::METH_*, otherwise the HTTP_METH_* constants can be used.

 
Returns TRUE on success, or FALSE on failure.

 
int HttpRequest::getMethod()

 
Get the previously set request method.

@@ -622,6 +717,11 @@ cycle.

 references the last received response.  Use HttpMessage::getParentMessage()

 to access the data of previously sent requests whithin this request

 cycle.

+
Note that the internal request message is immutable, that means that the

+request message received through HttpRequest::getRequestMessage() will

+always look the same for the same request, regardless of any changes you

+may have made to the returned object.

+
Throws HttpMalformedHeadersException, HttpEncodingException.

 
HttpMessage HttpRequest::getHistory()

 
Get all sent requests and received responses as an HttpMessage object.

 
If you don't want to record history at all, set the instance variable

@@ -630,24 +730,30 @@ HttpRequest::$recoedHistory to FALSE. 

 history.

 
The object references the last received response, use HttpMessage::getParentMessage() 

 to access the data of previously sent requests and received responses.

-
Throws HttpMalformedHeaderException.

+
Note that the internal history is immutable, that means that any changes

+you make the the message list won't affect a history message list newly 

+created by another call to HttpRequest::getHistory().

+
Throws HttpMalformedHeaderException, HttpEncodingException.

 
void HttpRequest::clearHistory()

 
Clear the history.

 
HttpMessage HttpRequest::send()

 
Send the HTTP request.

 
Returns the received response as HttpMessage object.

+
NOTE: While an exception may be thrown, the transfer could have succeeded 

+at least partially, so you might want to check the return values of various

+HttpRequest::getResponse*() methods.

 
Throws HttpRuntimeException, HttpRequestException, 

 HttpMalformedHeaderException, HttpEncodingException.

 
GET example:


-<?php
$r = new HttpRequest('http://example.com/feed.rss', HTTP_GET);
$r->setOptions(array('lastmodified' => filemtime('local.rss')));
$r->addQueryData(array('category' => 3));
try {
    $r->send();
    if ($r->getResponseCode() == 200) {
        file_put_contents('local.rss', $r->getResponseBody());
   }
} catch (HttpException $ex) {
    echo $ex;
}
?>

+<?php
$r = new HttpRequest('http://example.com/feed.rss', HttpRequest::METH_GET);
$r->setOptions(array('lastmodified' => filemtime('local.rss')));
$r->addQueryData(array('category' => 3));
try {
    $r->send();
    if ($r->getResponseCode() == 200) {
        file_put_contents('local.rss', $r->getResponseBody());
   }
} catch (HttpException $ex) {
    echo $ex;
}
?>

 

 

 
POST example:


-<?php
$r = new HttpRequest('http://example.com/form.php', HTTP_POST);
$r->setOptions(array('cookies' => array('lang' => 'de')));
$r->addPostFields(array('user' => 'mike', 'pass' => 's3c|r3t'));
$r->addPostFile('image', 'profile.jpg', 'image/jpeg');
try {
    echo $r->send()->getBody();
} catch (HttpException $ex) {
    echo $ex;
}
?>

+<?php
$r = new HttpRequest('http://example.com/form.php', HttpRequest::METH_POST);
$r->setOptions(array('cookies' => array('lang' => 'de')));
$r->addPostFields(array('user' => 'mike', 'pass' => 's3c|r3t'));
$r->addPostFile('image', 'profile.jpg', 'image/jpeg');
try {
    echo $r->send()->getBody();
} catch (HttpException $ex) {
    echo $ex;
}
?>

 

 

 

-
http_requestpool_object.c

+
http_requestpool_object.c

 
HttpRequestPool

 
void HttpRequestPool::__construct([HttpRequest request[, ...]])

 
Instantiate a new HttpRequestPool object.  An HttpRequestPool is

@@ -656,7 +762,7 @@ able to send several HttpRequests in parallel.

 object while you're using the implemented Interator interface. 

 
Accepts virtual infinite optional parameters each referencing an

 HttpRequest object.

-
Throws HttpRequestException, HttpRequestPoolException, HttpInvalidParamException.

+
Throws HttpRequestPoolException (HttpRequestException, HttpInvalidParamException).

 
Example:


 <?php
try {
    $pool = new HttpRequestPool(
        new HttpRequest('http://www.google.com/', HttpRequest::METH_HEAD),
        new HttpRequest('http://www.php.net/', HttpRequest::METH_HEAD)
    );
    $pool->send();
    foreach($pool as $request) {
        printf("%s is %s (%d)\n",
            $request->getUrl(),
            $request->getResponseCode() ? 'alive' : 'not alive',
            $request->getResponseCode()
        );
    }
} catch (HttpException $e) {
    echo $e;
}
?>

 

@@ -682,12 +788,11 @@ HttpRequestPool object.

 
bool HttpRequestPool::send()

 
Send all attached HttpRequest objects in parallel.

 
Returns TRUE on success, or FALSE on failure.

-
Throws HttpSocketException, HttpRequestException, 

-HttpRequestPoolException, HttpMalformedHeaderException.

+
Throws HttpRequestPoolException (HttpSocketException, HttpRequestException, HttpMalformedHeaderException).

 
protected bool HttpRequestPool::socketPerform()

 
Returns TRUE until each request has finished its transaction.

 
Usage:


-<?php
    while ($pool->socketPerform()) {
        do_something_else();
        if (!$pool->socketSelect()) {
            die('Socket error');
        }
    }
?>

+<?php
class MyPool extends HttpRequestPool
{
    public function send()
    {
        while ($this->socketPerform()) {
            if (!$this->socketSelect()) {
                throw new HttpSocketExcpetion;
            }
        }
    }
    
    protected final function socketPerform()
    {
        $result = parent::socketPerform();
        foreach ($this->getFinishedRequests() as $r) {
            $this->detach($r);
            // handle response of finished request
        }
        return $result;
    }
} 
?>

 

 

 
protected bool HttpRequestPool::socketSelect()

@@ -703,8 +808,18 @@ HttpRequestPoolException, HttpMalformedHeaderException.

 
Implements Iterator::next().

 
void HttpRequestPool::rewind()

 
Implements Iterator::rewind().

+
int HttpRequestPool::count()

+
Implements Countable.

+
Returns the number of attached HttpRequest objects.

+
array HttpRequestPool::getAttachedRequests()

+
Get attached HttpRequest objects.

+
Returns an array containing all currently attached HttpRequest objects.

+
array HttpRequestPool::getFinishedRequests()

+
Get attached HttpRequest objects that already have finished their work.

+
Returns an array containing all attached HttpRequest objects that

+already have finished their work.

 

-
http_response_object.c

+
http_response_object.c

 
static bool HttpResponse::setHeader(string name, mixed value[, bool replace = true])

 
Send an HTTP header.

 
Expects a string parameter containing the name of the header and a mixed

@@ -760,7 +875,7 @@ contain a primary and secondary content type part.

 
static string HttpResponse::getContentType()

 
Get current Content-Type header setting.

 
Returns the currently set content type as string.

-
static string HttpResponse::guessContentType(string magic_file[, long magic_mode = MAGIC_MIME])

+
static string HttpResponse::guessContentType(string magic_file[, int magic_mode = MAGIC_MIME])

 
Attempts to guess the content type of supplied payload through libmagic.

 If the attempt is successful, the guessed content type will automatically

 be set as response content type.  

@@ -859,7 +974,233 @@ http.cache_log is set.

 

 

 

-    
Generated at: Wed, 05 Oct 2005 14:35:52 +0000

+
Table of Contents
+
+

+    
Generated at: Fri, 09 Dec 2005 13:56:42 +0100