From: Michael Wallner Date: Wed, 25 May 2005 17:04:34 +0000 (+0000) Subject: - update docs X-Git-Tag: RELEASE_0_8_0~18 X-Git-Url: https://git.m6w6.name/?a=commitdiff_plain;h=7f914f24a4276b5c3489d410814f8d1125c8264f;p=m6w6%2Fext-http - update docs --- diff --git a/docs/functions.html b/docs/functions.html index 641db09..4c6ff04 100644 --- a/docs/functions.html +++ b/docs/functions.html @@ -6,13 +6,20 @@ font-size: 80%; font-family: sans-serif; } - h2 { + h2, h3 { color: #339; clear: both; font-size: 1.2em; background: #ffc; padding: .2em; } + h2.o { + color: #66b; + clear: both; + font-size: 1.3em; + background: #f0f0f0; + padding: .2em; + } p { margin-left: 1em; } @@ -64,9 +71,9 @@ The qualifier is recognized and languages without qualifier are rated highest. the supported languages as array values.

-Example:


-<?php
$langs
= array(
        
'en-US',// default
        
'fr',
        
'fr-FR',
        
'de',
        
'de-DE',
        
'de-AT',
        
'de-CH',
);
include
'./langs/'. http_negotiate_language($langs) .'.php';
?>
-

+Example:


+<?php
$langs
= array(
        
'en-US',// default
        
'fr',
        
'fr-FR',
        
'de',
        
'de-DE',
        
'de-AT',
        
'de-CH',
);
include
'./langs/'. http_negotiate_language($langs) .'.php';
?>
+



@@ -80,9 +87,9 @@ The qualifier is recognized and charset without qualifier are rated highest.
the supported charsets as array values.

-Example:


-<?php
$charsets
= array(
        
'iso-8859-1', // default
        
'iso-8859-2',
        
'iso-8859-15',
        
'utf-8'
);
$pref = http_negotiate_charset($charsets);
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');
}
?>
-

+Example:


+<?php
$charsets
= array(
        
'iso-8859-1', // default
        
'iso-8859-2',
        
'iso-8859-15',
        
'utf-8'
);
$pref = http_negotiate_charset($charsets);
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');
}
?>
+



@@ -105,7 +112,7 @@ be "saved" by the client/user (i.e. by browsers "Save as..." popup window).

This matches the given ETag against the clients
"If-Match" resp. "If-None-Match" HTTP headers.

bool http_cache_last_modified([int timestamp_or_expires]])

-

If timestamp_or_exires is greater than 0, it is handled as timestamp
+

If timestamp_or_expires is greater than 0, it is handled as timestamp
and will be sent as date of last modification. If it is 0 or omitted,
the current time will be sent as Last-Modified date. If it's negative,
it is handled as expiration time in seconds, which means that if the
@@ -119,10 +126,17 @@ checksum of the output (uses output buffering).
If clients "If-None-Match" header matches the supplied/calculated
ETag, the body is considered cached on the clients side and
a "304 Not Modified" status code is issued.

-

string ob_httpetaghandler(string data, int mode)

-

For use with ob_start().
-Note that this has to be started as first output buffer.
-WARNING: Don't use with http_send_*().

+

string ob_etaghandler(string data, int mode)

+

For use with ob_start().

+

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

+

Use with http_send() API.
+
+Example:


+<?php
// ~ 20 kbyte/s
# http_throttle(1, 20000);
# http_throttle(0.5, 10000);
# http_throttle(0.1, 2000);
http_send_file('document.pdf');
?>
+

+

+
+

void http_redirect([string url[, array params[, bool session,[ bool permanent]]]])

Redirect to a given url.
The supplied url will be expanded with http_absolute_uri(), the params array will
@@ -146,9 +160,9 @@ if the client doesn't redirect immediatly.

Returns false on failure.

array http_split_response(string http_response)

This function splits an HTTP response into an array with headers and the
-content body. The returned array may look simliar to the following example:


-<?php
array(
    
0 => array(
        
'Status' => '200 Ok',
        
'Content-Type' => 'text/plain',

        
'Content-Language' => 'en-US'
    
),
    
1 => "Hello World!"
);
?>
-

+content body. The returned array may look simliar to the following example:


+<?php
array(
    
0 => array(
        
'Response Status' => '200 Ok',
        
'Content-Type' => 'text/plain',
        
'Content-Language' => 'en-US'
    
),
    
1 => "Hello World!"
);
?>
+



@@ -186,10 +200,12 @@ array where the following keys will be recognized:

 - redirect:
                      has no effect, if the size of the requested entity is not known
- lastmodified: int, timestamp for If-(Un)Modified-Since header
- timeout: int, seconds the request may take
- - connecttimeout: int, seconds the connect may take

The optional third parameter will be filled with some additional information
-in form af an associative array, if supplied, like the following example:


-<?php
array (
    
'effective_url' => 'http://localhost',
    
'response_code' => 403,
    
'total_time' => 0.017,
    
'namelookup_time' => 0.013,
    
'connect_time' => 0.014,
    
'pretransfer_time' => 0.014,
    
'size_upload' => 0,
    
'size_download' => 202,
    
'speed_download' => 11882,
    
'speed_upload' => 0,
    
'header_size' => 145,
    
'request_size' => 62,
    
'ssl_verifyresult' => 0,
    
'filetime' => -1,
    
'content_length_download' => 202,
    
'content_length_upload' => 0,
    
'starttransfer_time' => 0.017,
    
'content_type' => 'text/html; charset=iso-8859-1',
    
'redirect_time' => 0,
    
'redirect_count' => 0,
    
'private' => '',
    
'http_connectcode' => 0,
    
'httpauth_avail' => 0,
    
'proxyauth_avail' => 0,
)
?>
-

+ - connecttimeout: int, seconds the connect may take
+ - onprogress: mixed, progress callback
+ - ondebug: mixed, debug callback

The optional third parameter will be filled with some additional information
+in form af an associative array, if supplied, like the following example:


+<?php
array (
    
'effective_url' => 'http://localhost',
    
'response_code' => 403,
    
'total_time' => 0.017,
    
'namelookup_time' => 0.013,
    
'connect_time' => 0.014,
    
'pretransfer_time' => 0.014,
    
'size_upload' => 0,
    
'size_download' => 202,
    
'speed_download' => 11882,
    
'speed_upload' => 0,
    
'header_size' => 145,
    
'request_size' => 62,
    
'ssl_verifyresult' => 0,
    
'filetime' => -1,
    
'content_length_download' => 202,
    
'content_length_upload' => 0,
    
'starttransfer_time' => 0.017,
    
'content_type' => 'text/html; charset=iso-8859-1',
    
'redirect_time' => 0,
    
'redirect_count' => 0,
    
'private' => '',
    
'http_connectcode' => 0,
    
'httpauth_avail' => 0,
    
'proxyauth_avail' => 0,
)
?>
+



@@ -201,21 +217,35 @@ See http_get() for a full list of available options.

Performs an HTTP POST request, posting data.
Returns the HTTP response as string.
See http_get() for a full list of available options.

-

string http_post_array(string url, array data[, array options[, array &info]])

+

string http_post_fields(string url, array data[, array files[, array options[, array &info]]])

Performs an HTTP POST request, posting www-form-urlencoded array data.
Returns the HTTP response as string.
See http_get() for a full list of available options.

+

string http_put_file(string url, string file[, array options[, array &info]])

+

+

string http_put_stream(string url, resource stream[, array options[, array &info]])

+

+

bool http_request()

+

}}} */
+
+/* {{{ proto long http_request_method_register(string method)

+

bool http_request_method_unregister(mixed method)

+

+

long http_request_method_exists(mixed method)

+

+

string http_request_method_name(long method)

+

bool http_auth_basic(string user, string pass[, string realm = "Restricted"])

-

Example:


-<?php
if (!http_auth_basic('mike', 's3c|r3t')) {
    die(
'<h1>Authorization failed!</h1>');
}
?>
-

+

Example:


+<?php
if (!http_auth_basic('mike', 's3c|r3t')) {
    die(
'<h1>Authorization failed!</h1>');
}
?>
+



bool http_auth_basic_cb(mixed callback[, string realm = "Restricted"])

-

Example:


-<?php
function auth_cb($user, $pass)
{
    global
$db;
    
$query = 'SELECT pass FROM users WHERE user='. $db->quoteSmart($user);
    if (
strlen($realpass = $db->getOne($query)) {
        return
$pass === $realpass;
    }
    return
false;
}
if (!
http_auth_basic_cb('auth_cb')) {
    die(
'<h1>Authorization failed</h1>');
}
?>
-

+

Example:


+<?php
function auth_cb($user, $pass)
{
    global
$db;
    
$query = 'SELECT pass FROM users WHERE user='. $db->quoteSmart($user);
    if (
strlen($realpass = $db->getOne($query)) {
        return
$pass === $realpass;
    }
    return
false;
}
if (!
http_auth_basic_cb('auth_cb')) {
    die(
'<h1>Authorization failed</h1>');
}
?>
+



@@ -223,13 +253,14 @@ See http_get() for a full list of available options.

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


http_methods.c

-

void HttpResponse::__construct(bool cache, bool gzip)

+

HttpResponse

+

void HttpResponse::__construct(bool cache, bool gzip)

Instantiates a new HttpResponse object, which can be used to send
any data/resource/file to an HTTP client with caching and multiple
ranges/resuming support.

NOTE: GZIPping is not implemented yet.

-

bool HttpResponse::setCache(bool cache)

+

bool HttpResponse::setCache(bool cache)

Whether it sould be attempted to cache the entitity.
This will result in necessary caching headers and checks of clients
"If-Modified-Since" and "If-None-Match" headers. If one of those headers
@@ -237,159 +268,216 @@ matches a "304 Not Modified" status code will be issued.

NOTE: If you're using sessions, be shure that you set session.cache_limiter
to something more appropriate than "no-cache"!

-

bool HttpResponse::getCache()

+

bool HttpResponse::getCache()

Get current caching setting.

-

bool HttpResponse::setGzip(bool gzip)

+

bool HttpResponse::setGzip(bool gzip)

Enable on-thy-fly gzipping of the sent entity. NOT IMPLEMENTED YET.

-

bool HttpResponse::getGzip()

+

bool HttpResponse::getGzip()

Get current gzipping setting.

-

bool HttpResponse::setCacheControl(string control[, bool raw = false])

+

bool HttpResponse::setCacheControl(string control[, bool raw = false])

Set a custom cache-control header, usually being "private" or "public"; if
$raw is set to true the header will be sent as-is.

-

string HttpResponse::getCacheControl()

+

string HttpResponse::getCacheControl()

Get current Cache-Control header setting.

-

bool HttpResponse::setContentType(string content_type)

+

bool HttpResponse::setContentType(string content_type)

Set the content-type of the sent entity.

-

string HttpResponse::getContentType()

+

string HttpResponse::getContentType()

Get current Content-Type header setting.

-

bool HttpResponse::setContentDisposition(string filename[, bool inline = false])

+

bool HttpResponse::setContentDisposition(string filename[, bool inline = false])

Set the Content-Disposition of the sent entity. This setting aims to suggest
the receiveing user agent how to handle the sent entity; usually the client
will show the user a "Save As..." popup.

-

array HttpResponse::getContentDisposition()

+

array HttpResponse::getContentDisposition()

Get current Content-Disposition setting.
Will return an associative array like:

array(
'filename' => 'foo.bar',
'inline' => false
)

-

bool HttpResponse::setETag(string etag)

+

bool HttpResponse::setETag(string etag)

Set a custom ETag. Use this only if you know what you're doing.

-

string HttpResponse::getETag()

+

string HttpResponse::getETag()

Get the previously set custom ETag.

-

bool HttpResponse::setData(string data)

+

void HttpResponse::setThrottleDelay(double seconds)

+

+

double HttpResponse::getThrottleDelay()

+

+

void HttpResponse::setSendBuffersize(long bytes)

+

+

long HttpResponse::getSendBuffersize()

+

+

bool HttpResponse::setData(string data)

Set the data to be sent.

-

string HttpResponse::getData()

+

string HttpResponse::getData()

Get the previously set data to be sent.

-

bool HttpResponse::setStream(resource stream)

+

bool HttpResponse::setStream(resource stream)

Set the resource to be sent.

-

resource HttpResponse::getStream()

+

resource HttpResponse::getStream()

Get the previously set resource to be sent.

-

bool HttpResponse::setFile(string file)

+

bool HttpResponse::setFile(string file)

Set the file to be sent.

-

string HttpResponse::getFile()

+

string HttpResponse::getFile()

Get the previously set file to be sent.

-

bool HttpResponse::send()

+

bool HttpResponse::send()

Finally send the entity.

-Example:


-<?php
$r
= new HttpResponse(true);
$r->setFile('../hidden/contract.pdf');
$r->setContentType('application/pdf');
$r->send();
?>
-

+Example:


+<?php
$r
= new HttpResponse(true);
$r->setFile('../hidden/contract.pdf');
$r->setContentType('application/pdf');
$r->send();
?>
+



-

void HttpRequest::__construct([string url[, long request_method = HTTP_GET]])

+

static HttpMessage HttpMessage::fromString(string raw_message)

+

Create an HttpMessage object from a string.

+

HttpMessage

+

void HttpMessage::__construct([string message])

+

Instantiate a new HttpMessage object.

+

string HttpMessage::getBody()

+

Get the body of the parsed Message.

+

array HttpMessage::getHeaders()

+

Get Message Headers.

+

void HttpMessage::setHeaders(array headers)

+

Sets new headers.

+

void HttpMessage::addHeaders(array headers[, bool append = false])

+

Add headers. If append is true, headers with the same name will be separated, else overwritten.

+

long HttpMessage::getType()

+

Get Message Type. (HTTP_MSG_NONE|HTTP_MSG_REQUEST|HTTP_MSG_RESPONSE)

+

void HttpMessage::setType(long type)

+

Set Message Type. (HTTP_MSG_NONE|HTTP_MSG_REQUEST|HTTP_MSG_RESPONSE)

+

long HttpMessage::getResponseCode()

+

Get the Response Code of the Message.

+

bool HttpMessage::setResponseCode(long code)

+

Set the response code of an HTTP Response Message.
+Returns false if the Message is not of type HTTP_MSG_RESPONSE,
+or if the response code is out of range (100-510).

+

string HttpMessage::getRequestMethod()

+

Get the Request Method of the Message.
+Returns false if the Message is not of type HTTP_MSG_REQUEST.

+

bool HttpMessage::setRequestMethod(string method)

+

Set the Request Method of the HTTP Message.
+Returns false if the Message is not of type HTTP_MSG_REQUEST.

+

string HttpMessage::getRequestUri()

+

Get the Request URI of the Message.

+

bool HttpMessage::setRequestUri(string URI)

+

Set the Request URI of the HTTP Message.
+Returns false if the Message is not of type HTTP_MSG_REQUEST,
+or if paramtere URI was empty.

+

string HttpMessage::getHttpVersion()

+

Get the HTTP Protocol Version of the Message.

+

bool HttpMessage::setHttpVersion(string version)

+

Set the HTTP Protocol version of the Message.
+Returns false if version is invalid (1.0 and 1.1).

+

HttpMessage HttpMessage::getParentMessage()

+

Get parent Message.

+

bool HttpMessage::send()

+

Send the Message according to its type as Response or Request.

+

string HttpMessage::toString([bool include_parent = true])

+

Get the string representation of the Message.

+

HttpRequest

+

void HttpRequest::__construct([string url[, long request_method = HTTP_GET]])

Instantiate a new HttpRequest object which can be used to issue HEAD, GET
and POST (including posting files) HTTP requests.

-

void HttpRequest::__destruct()

+

void HttpRequest::__destruct()

Destroys the HttpRequest object.

-

bool HttpRequest::setOptions(array options)

+

bool HttpRequest::setOptions(array options)

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

-

array HttpRequest::getOptions()

+

array HttpRequest::getOptions()

Get current set options.

-

void HttpRequest::unsetOptions()

+

void HttpRequest::unsetOptions()

Unset all options/headers/cookies.

-

bool HttpRequest::setSslOptions(array options)

+

bool HttpRequest::setSslOptions(array options)

Set additional SSL options.

-

array HttpRequest::getSslOtpions()

+

array HttpRequest::getSslOtpions()

Get previously set SSL options.

-

void HttpRequest::unsetSslOptions()

+

void HttpRequest::unsetSslOptions()

Unset previously set SSL options.

-

bool HttpRequest::addHeaders(array headers)

+

bool HttpRequest::addHeaders(array headers)

Add request header name/value pairs.

-

array HttpRequest::getHeaders()

+

array HttpRequest::getHeaders()

Get previously set request headers.

-

void HttpRequest::unsetHeaders()

+

void HttpRequest::unsetHeaders()

Unset previously set request headers.

-

bool HttpRequest::addCookies(array cookies)

+

bool HttpRequest::addCookies(array cookies)

Add cookies.

-

array HttpRequest::getCookies()

+

array HttpRequest::getCookies()

Get previously set cookies.

-

void HttpRequest::unsetCookies()

+

void HttpRequest::unsetCookies()

-

bool HttpRequest::setURL(string url)

+

bool HttpRequest::setURL(string url)

Set the request URL.

-

string HttpRequest::getUrl()

+

string HttpRequest::getUrl()

Get the previously set request URL.

-

bool HttpRequest::setMethod(long request_method)

+

bool HttpRequest::setMethod(long request_method)

Set the request methods; one of the HTTP_HEAD, HTTP_GET or
HTTP_POST constants.

-

long HttpRequest::getMethod()

+

long HttpRequest::getMethod()

Get the previously set request method.

-

bool HttpRequest::setContentType(string content_type)

+

bool HttpRequest::setContentType(string content_type)

Set the content type the post request should have.
Use this only if you know what you're doing.

-

string HttpRequest::getContentType()

+

string HttpRequest::getContentType()

Get the previously content type.

-

bool HttpRequest::setQueryData(mixed query_data)

+

bool HttpRequest::setQueryData(mixed query_data)

Set the URL query parameters to use.
Overwrites previously set query parameters.
Affects any request types.

-

string HttpRequest::getQueryData()

+

string HttpRequest::getQueryData()

Get the current query data in form of an urlencoded query string.

-

bool HttpRequest::addQueryData(array query_params)

+

bool HttpRequest::addQueryData(array query_params)

Add parameters to the query parameter list.
Affects any request type.

-

void HttpRequest::unsetQueryData()

+

void HttpRequest::unsetQueryData()

Clean the query parameters.
Affects any request type.

-

bool HttpRequest::addPostData(array post_data)

+

bool HttpRequest::addPostFields(array post_data)

Adds POST data entries.
Affects only POST requests.

-

bool HttpRequest::setPostData(array post_data)

+

bool HttpRequest::setPostFields(array post_data)

Set the POST data entries.
Overwrites previously set POST data.
Affects only POST requests.

-

array HttpRequest::getPostData()

+

array HttpRequest::getPostFields()

Get previously set POST data.

-

void HttpRequest::unsetPostData()

+

void HttpRequest::unsetPostFields()

Clean POST data entires.
Affects only POST requests.

-

bool HttpRequest::addPostFile(string name, string file[, string content_type = "application/x-octetstream"])

+

bool HttpRequest::addPostFile(string name, string file[, string content_type = "application/x-octetstream"])

Add a file to the POST request.
Affects only POST requests.

-

array HttpRequest::getPostFiles()

+

array HttpRequest::getPostFiles()

Get all previously added POST files.

-

void HttpRequest::unsetPostFiles()

+

void HttpRequest::unsetPostFiles()

Unset the POST files list.
Affects only POST requests.

-

array HttpRequest::getResponseData()

+

array HttpRequest::getResponseData()

Get all response data after the request has been sent.

-

mixed HttpRequest::getResponseHeader([string name])

+

mixed HttpRequest::getResponseHeader([string name])

Get response header(s) after the request has been sent.

-

array HttpRequest::getResponseCookie([string name])

+

array HttpRequest::getResponseCookie([string name])

Get response cookie(s) after the request has been sent.

-

string HttpRequest::getResponseBody()

+

string HttpRequest::getResponseBody()

Get the response body after the request has been sent.

-

int HttpRequest::getResponseCode()

+

int HttpRequest::getResponseCode()

Get the response code after the request has been sent.

-

array HttpRequest::getResponseInfo([string name])

+

array HttpRequest::getResponseInfo([string name])

Get response info after the request has been sent.
See http_get() for a full list of returned info.

-

bool HttpRequest::send()

+

HttpMessage HttpRequest::getResponseMessage()

+

Get the full response as HttpMessage object.

+

bool HttpRequest::send()

Send the HTTP request.

-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));
if (
$r->send() && $r->getResponseCode() == 200) {
    
file_put_contents('local.rss', $r->getResponseBody());
}
?>
-

-

POST example:


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

+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;
}
?>
+

+

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');
if (
$r->send()) {
    echo
$r->getResponseBody();
}
?>
+




-

Generated at: Thu, 24 Mar 2005 18:02:15 +0100

+

Generated at: Wed, 25 May 2005 19:01:02 +0200

diff --git a/funcsummary.php b/funcsummary.php index b819827..dad2f5b 100644 --- a/funcsummary.php +++ b/funcsummary.php @@ -29,13 +29,20 @@ $preface = <<<_PREFACE font-size: 80%%; font-family: sans-serif; } - h2 { + h2, h3 { color: #339; clear: both; font-size: 1.2em; background: #ffc; padding: .2em; } + h2.o { + color: #66b; + clear: both; + font-size: 1.3em; + background: #f0f0f0; + padding: .2em; + } p { margin-left: 1em; } @@ -81,8 +88,13 @@ foreach (array_slice($_SERVER['argv'], 1) as $f) { if (mf($f, $m)) { printf("

%s

\n", basename($f)); foreach ($m[1] as $i => $p) { - printf("

%s

\n%s\n", - str_replace(', ', '_', $m[4][$i]), $p, ff($m[3][$i])); + if ($o = preg_match('/^(.*), (.*)$/', $m[4][$i], $n)) { + if ($n[2] == '__construct') { + printf("

%s

\n", $n[1], $n[1]); + } + } + printf("%s\n%s\n", + $o?3:2, $o?$n[1].'_'.$n[2]:$m[4][$i], $p, $o?3:2, ff($m[3][$i])); } print "
\n"; } diff --git a/http_functions.c b/http_functions.c index ba2bd56..94088c2 100644 --- a/http_functions.c +++ b/http_functions.c @@ -416,7 +416,7 @@ PHP_FUNCTION(ob_etaghandler) * Use with http_send() API. * * Example: - * + *
  * 
- * 
+ * 
*/ PHP_FUNCTION(http_throttle) {