X-Git-Url: https://git.m6w6.name/?a=blobdiff_plain;f=docs%2Ffunctions.html;h=64d9c930cdb7b119e8a54a66231d4236340f8473;hb=5aa958980652d72433ba8e9e500b8dfd123d56a1;hp=f785fd092f8916f6c99c7a4757743875670650a3;hpb=a0098fdbfef71be0fab417b5bc624dc884bd4549;p=m6w6%2Fext-http diff --git a/docs/functions.html b/docs/functions.html index f785fd0..64d9c93 100644 --- a/docs/functions.html +++ b/docs/functions.html @@ -72,20 +72,8 @@ looking like: "Wed, 22 Dec 2004 11:34:47 GMT"

Takes an optional unix timestamp as parameter.

Returns the HTTP date as string.

-

string http_build_uri(string url[, string proto[, string host[, int port]]])

-

Build a complete URI according to the supplied parameters.

-

If the url is already abolute but a different proto was supplied,
-only the proto part of the URI will be updated. If url has no
-path specified, the path of the current REQUEST_URI will be taken.
-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.

-

Examples:


-<?php
$uri 
http_build_uri("page.php""https"NULL488);
?>
-

-

+

string http_build_url(mixed url[, mixed parts[, array &new_url]])

+

Returns the new URL as string on success or FALSE on failure.

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

This function negotiates the clients preferred language based on its
Accept-Language HTTP header. The qualifier is recognized and languages
@@ -113,6 +101,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.

@@ -179,11 +180,10 @@ 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.

-

Note: This doesn't really work with the FastCGI SAPI.

Expects a double parameter specifying the seconds too sleep() after
each chunk sent. Additionally accepts an optional int parameter
representing the chunk size in bytes.

@@ -194,7 +194,7 @@ representing the chunk size in bytes.

void http_redirect([string url[, array params[, bool session = false[, int status = 302]]]])

Redirect to the given url.

-The supplied url will be expanded with http_build_uri(), the params array will
+The supplied url will be expanded with http_build_url(), the params array will
be treated with http_build_query() and the session identification will be appended
if session is true.

The HTTP response code will be set according to status.
@@ -205,7 +205,7 @@ You can use one of the following constants for convenience:
- HTTP_REDIRECT_TEMP 307 Temporary Redirect

Please see http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3
for which redirect response code to use in which situation.

-

To be RFC compliant, "Redirecting to URI." will be displayed,
+

To be RFC compliant, "Redirecting to URL." will be displayed,
if the client doesn't redirect immediatly, and the request method was
another one than HEAD.

Returns FALSE on failure, or *exits* on success.

@@ -240,7 +240,15 @@ several consecutive HTTP messages.

Expects a string parameter containing HTTP headers.

Returns an array on success, or FALSE on failure.

Example:


-<?php
$headers 
"content-type: text/html; charset=UTF-8\r\n".
           
"Server: Funky/1.0\r\n".
           
"Set-Cookie: foo=bar\r\n".
           
"Set-Cookie: baz=quux\r\n".
           
"Folded: works\r\n\ttoo\r\n";
print_r(http_parse_headers($headers));

Array
(
    [
Content-Type] => text/htmlchatset=UTF-8
    
[Server] => Funky/1.0
    
[Set-Cookie] => Array
        (
            [
0] => foo=bar
            
[1] => baz=quux
        
)
    [
Folded] => works
        too 
?>

+<?php
$headers 
"content-type: text/html; charset=UTF-8\r\n".
           
"Server: Funky/1.0\r\n".
           
"Set-Cookie: foo=bar\r\n".
           
"Set-Cookie: baz=quux\r\n".
           
"Folded: works\r\n\ttoo\r\n";
print_r(http_parse_headers($headers));

Array
(
    [
Content-Type] => text/htmlchatset=UTF-8
    
[Server] => Funky/1.0
    
[Set-Cookie] => Array
        (
            [
0] => foo=bar
            
[1] => baz=quux
        
)
    [
Folded] => works
        too 

?>
+

+

+ +

Parses HTTP cookies like sent in a response into a struct.

+

Expects a string as parameter containing the value of a Set-Cookie response header.

+

Returns an stdClass object with the cookie params as properties on success or FALSE on failure.

+

Example:


+<?php
print_r
(http_parse_cookie("foo=bar; path=/"));

stdClass Object
(
    [
name] => foo
    
[value] => bar
    
[path] => /
)
?>

array http_get_request_headers(void)

@@ -270,7 +278,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
@@ -337,44 +345,28 @@ 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.

+

string http_deflate(string data[, int flags = 0])

+

Compress data with gzip, zlib AKA deflate or raw 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.

+be encoded.

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.

+

Uncompress data compressed with either gzip, deflate AKA zlib or raw
+deflate encoding.

Expects a string as parameter containing the compressed data.

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

+

string ob_deflatehandler(string data, int mode)

+

For use with ob_start(). The deflate output buffer handler can only be used once.
+It conflicts with ob_gzhanlder and zlib.output_compression as well and should
+not be used after ext/mbstrings mb_output_handler and ext/sessions URL-Rewriter (AKA
+session.use_trans_sid).

+

string ob_inflatehandler(string data, int mode)

+

For use with ob_start(). Same restrictions as with ob_deflatehandler apply.

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 featuers that depend on external libraries.

+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_deflatestream_object.c

+

HttpDeflateStream

+

void HttpDeflateStream::__construct([int flags = 0])

+

Creates a new HttpDeflateStream object instance.

+

Accepts an optional int parameter specifying how to initialize the deflate stream.

+

string HttpDeflateStream::update(string data)

+

Passes more data through the deflate stream.

+

Expects a string parameter containing (a part of) the data to deflate.

+

Returns deflated data on success or FALSE on failure.

+

string HttpDeflateStream::flush([string data])

+

Flushes the deflate stream.

+

Returns some deflated data as string on success or FALSE on failure.

+

string HttpDeflateStream::finish([string data])

+

Finalizes the deflate stream. The deflate stream can be reused after finalizing.

+

Returns the final part of deflated data.

+
+

http_inflatestream_object.c

+

string HttpInflateStream::update(string data)

+

Passes more data through the inflate stream.

+

Expects a string parameter containing (a part of) the data to inflate.

+

Returns inflated data on success or FALSE on failure.

+

string HttpInflateStream::flush([string data])

+

Flush the inflate stream.

+

Returns some inflated data as string on success or FALSE on failure.

+

string HttpInflateStream::finish([string data])

+

Finalizes the inflate stream. The inflate stream can be reused after finalizing.

+

Returns the final part of inflated data.

+

http_message_object.c

HttpMessage

void HttpMessage::__construct([string message])

@@ -452,15 +470,15 @@ not of type HttpMessage::TYPE_REQUEST.

Expects a string parameter containing the request method name.

Returns TRUE on success, or FALSE if the message is not of type
HttpMessage::TYPE_REQUEST or an invalid request method was supplied.

-

string HttpMessage::getRequestUri()

-

Get the Request URI of the Message.

-

Returns the request uri as string on success, or FALSE if the message
+

string HttpMessage::getRequestUrl()

+

Get the Request URL of the Message.

+

Returns the request url as string on success, or FALSE if the message
is not of type HttpMessage::TYPE_REQUEST.

-

bool HttpMessage::setRequestUri(string URI)

-

Set the Request URI of the HTTP Message.

-

Expects a string parameters containing the request uri.

+

bool HttpMessage::setRequestUrl(string url)

+

Set the Request URL of the HTTP Message.

+

Expects a string parameters containing the request url.

Returns TRUE on success, or FALSE if the message is not of type
-HttpMessage::TYPE_REQUEST or supplied URI was empty.

+HttpMessage::TYPE_REQUEST or supplied URL was empty.

string HttpMessage::getHttpVersion()

Get the HTTP Protocol Version of the Message.

Returns the HTTP protocol version as string.

@@ -480,6 +498,15 @@ 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

HttpRequest

@@ -490,8 +517,6 @@ Additianally accepts an optional int parameter specifying the request method
passed to HttpRequest::setOptions().

Throws HttpException.

-

void HttpRequest::__destruct()

-

Destroys the HttpRequest object.

bool HttpRequest::setOptions([array options])

Set the request options to use. See http_get() for a full list of available options.

Accepts an array as optional parameters, wich values will overwrite the
@@ -549,7 +574,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.

@@ -697,6 +722,17 @@ 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.

+

string HttpRequest::getRawRequestMessage()

+

Get sent HTTP message.

+

Returns an HttpMessage in a form of a string

+

string HttpRequest::getRawResponseMessage()

+

Get the entire HTTP response.

+

Returns the complete web server response, including the headers in a form of a string.

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
@@ -705,20 +741,26 @@ 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;
}
?>


@@ -728,10 +770,10 @@ HttpMalformedHeaderException, HttpEncodingException.

Instantiate a new HttpRequestPool object. An HttpRequestPool is
able to send several HttpRequests in parallel.

WARNING: Don't attach/detach HttpRequest objects to the HttpRequestPool
-object while you're using the implemented Interator interface.

+object while you're using the implemented Iterator 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;
}
?>

@@ -757,12 +799,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()

@@ -778,6 +819,16 @@ 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

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

@@ -940,12 +991,14 @@ http.cache_log is set.

+
  • http_deflatestream_object.c + +
  • +
  • http_inflatestream_object.c + +
  • http_message_object.c
  • http_request_object.c
  • @@ -1152,7 +1227,7 @@ http.cache_log is set.

    -

    Generated at: Tue, 11 Oct 2005 11:33:16 +0000

    +

    Generated at: Tue, 03 Jan 2006 20:04:51 +0100