X-Git-Url: https://git.m6w6.name/?a=blobdiff_plain;ds=inline;f=docs%2Ffunctions.html;h=b815071d31a3cf5b33523658f2e578956c086127;hb=0acbfc76b5a3e4122a6d06d64bd834a810806656;hp=41cf9063697a5510be706e250699b6e2e707a12f;hpb=336ab37eb6fa1e0e91857d65fae0e747b4ad481c;p=m6w6%2Fext-http diff --git a/docs/functions.html b/docs/functions.html index 41cf906..b815071 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; } @@ -30,133 +37,240 @@ width: auto; float: left; } + p, pre { + clear: both; + } 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; + } -
This function returns a valid HTTP date regarding RFC 822/1123
+
Compose a valid HTTP date regarding RFC 822/1123
looking like: "Wed, 22 Dec 2004 11:34:47 GMT"
This function returns an absolute URI constructed from url.
-If the url is already abolute but a different proto was supplied,
+
Takes an optional unix timestamp as parameter.
+
+Returns the HTTP date as string.
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.
-
-Some examples:
url = "page.php" => http://www.example.com/current/path/page.php-
- url = "/page.php" => http://www.example.com/page.php
- url = "/page.php", proto = "https" => https://www.example.com/page.php
-
Returns the absolute URI as string.
+Examples:
++
+<?php
$uri = http_build_uri("page.php", "https", NULL, 488);
?>
+
This function negotiates the clients preferred language based on its
-Accept-Language HTTP header. It returns the negotiated language or
-the default language if none match.
-
-The qualifier is recognized and languages without qualifier are rated highest.
-
-The supported parameter is expected to be an array having
-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';
?>
-
-
-
-
Expects an array as parameter cotaining the supported languages as values.
+If the optional second parameter is supplied, it will be filled with an
+array containing the negotiation results.
Returns the negotiated language or the default language (i.e. first array entry)
+if none match.
Example:
++
+<?php
$langs = array(
'en-US',// default
'fr',
'fr-FR',
'de',
'de-DE',
'de-AT',
'de-CH',
);
include './langs/'. http_negotiate_language($langs, $result) .'.php';
print_r($result);
?>
+
This function negotiates the clients preferred charset based on its
-Accept-Charset HTTP header. It returns the negotiated charset or
-the default charset if none match.
-
-The qualifier is recognized and charset without qualifier are rated highest.
-
-The supported parameter is expected to be an array having
-the supported charsets as array values.
-
-Example:
+Accept-Charset HTTP header. The qualifier is recognized and charsets
-<?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');
}
?>
-
-
-
-
Expects an array as parameter cotaining the supported charsets as values.
+If the optional second parameter is supplied, it will be filled with an
+array containing the negotiation results.
Returns the negotiated charset or the default charset (i.e. first array entry)
+if none match.
Example:
++
+<?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);
?>
+
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));
?>
+
Send HTTP status code.
+Expects an HTTP status code as parameter.
+Returns TRUE on success or FALSE on failure.
This converts the given timestamp to a valid HTTP date and
+
Send a "Last-Modified" header with a valid HTTP date.
+Accepts a unix timestamp, converts it to a valid HTTP date and
sends it as "Last-Modified" HTTP header. If timestamp is
-omitted, current time is sent.
Returns TRUE on success or FALSE on failure.
Sets the content type.
+Send the Content-Type of the sent entity. This is particularly important
+if you use the http_send() API.
Accepts an optional string parameter containing the desired content type
+(primary/secondary).
Returns TRUE on success or FALSE on failure.
Set the Content Disposition. The Content-Disposition header is very useful
+
Send the Content-Disposition. The Content-Disposition header is very useful
if the data actually sent came from a file or something similar, that should
be "saved" by the client/user (i.e. by browsers "Save as..." popup window).
Matches the given timestamp against the clients "If-Modified-Since" resp.
-"If-Unmodified-Since" HTTP headers.
This matches the given ETag against the clients
-"If-Match" resp. "If-None-Match" HTTP headers.
Expects a string parameter specifying the file name the "Save as..." dialogue
+should display. Optionally accepts a bool parameter, which, if set to true
+and the user agent knows how to handle the content type, will probably not
+cause the popup window to be shown.
Returns TRUE on success or FALSE on failure.
+Matches the given unix timestamp against the clients "If-Modified-Since"
+resp. "If-Unmodified-Since" HTTP headers.
Accepts a unix timestamp which should be matched. Optionally accepts an
+additional bool parameter, which if set to true will check the header
+usually used to validate HTTP ranges. If timestamp is omitted, the
+current time will be used.
Returns TRUE if timestamp represents an earlier date than the header,
+else FALSE.
Matches the given ETag against the clients "If-Match" resp.
+"If-None-Match" HTTP headers.
Expects a string parameter containing the ETag to compare. Optionally
+accepts a bool parameter, which, if set to true, will check the header
+usually used to validate HTTP ranges.
Retuns TRUE if ETag matches or the header contained the asterisk ("*"),
+else FALSE.
If timestamp_or_exires is greater than 0, it is handled as timestamp
+
Attempts to cache the sent entity by its last modification date.
+Accepts a unix timestamp as parameter which is handled as follows:
+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
requested last modification date is not between the calculated timespan,
the Last-Modified header is updated and the actual body will be sent.
Returns FALSE on failure, or *exits* with "304 Not Modified" if the entity is cached.
+A log entry will be written to the cache log if the INI entry
+http.cache_log is set and the cache attempt was successful.
This function attempts to cache the HTTP body based on an ETag,
-either supplied or generated through calculation of the MD5
-checksum of the output (uses output buffering).
-
-If clients "If-None-Match" header matches the supplied/calculated
+
Attempts to cache the sent entity by its ETag, either supplied or generated
+by the hash algorythm specified by the INI setting "http.etag_mode".
If the 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.
For use with ob_start().
-Note that this has to be started as first output buffer.
-WARNING: Don't use with http_send_*().
Redirect to a given url.
-The supplied url will be expanded with http_absolute_uri(), the params array will
+
Returns FALSE on failure, or *exits* with "304 Not Modified" if the entity is cached.
+A log entry is written to the cache log if the INI entry
+"http.cache_log" is set and the cache attempt was successful.
For use with ob_start(). Output buffer handler generating an ETag with
+the hash algorythm specified with the INI setting "http.etag_mode".
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.
Example:
++
+<?php
// ~ 20 kbyte/s
# http_throttle(1, 20000);
# http_throttle(0.5, 10000);
# http_throttle(0.1, 2000);
http_send_file('document.pdf');
?>
+
Redirect to the given url.
+
+The supplied url will be expanded with http_build_uri(), the params array will
be treated with http_build_query() and the session identification will be appended
-if session is true.
-
-Depending on permanent the redirection will be issued with a permanent
-("301 Moved Permanently") or a temporary ("302 Found") redirection
-status code.
-
-To be RFC compliant, "Redirecting to URI." will be displayed,
-if the client doesn't redirect immediatly.
The HTTP response code will be set according to status.
+You can use one of the following constants for convenience:
+ - HTTP_REDIRECT 302 Found
+ - HTTP_REDIRECT_PERM 301 Moved Permanently
+ - HTTP_REDIRECT_POST 303 See Other
+ - 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,
+if the client doesn't redirect immediatly, and the request method was
+another one than HEAD.
Returns FALSE on failure, or *exits* on success.
+A log entry will be written to the redirect log, if the INI entry
+"http.redirect_log" is set and the redirect attempt was successful.
Sends raw data with support for (multiple) range requests.
+Retursn TRUE on success, or FALSE on failure.
Sends a file with support for (multiple) range requests.
+Expects a string parameter referencing the file to send.
+Returns TRUE on success, or FALSE on failure.
Sends an already opened stream with support for (multiple) range requests.
+Expects a resource parameter referncing the stream to read from.
+Returns TRUE on success, or FALSE on failure.
This function decodes a string that was HTTP-chunked encoded.
-Returns false on failure.
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!"
);
?>
-
-
-
-
Decodes a string that was HTTP-chunked encoded.
+Expects a chunked encoded string as parameter.
+Returns the decoded string on success or FALSE on failure.
+Parses (a) http_message(s) into a simple recursive object structure.
+Expects a string parameter containing a single HTTP message or
+several consecutive HTTP messages.
Returns an hierachical object structure of the parsed messages.
+Example:
+
+<?php
print_r(http_parse_message(http_get(URL, array('redirect' => 3)));
stdClass object
(
[type] => 2
[httpVersion] => 1.1
[responseCode] => 200
[headers] => Array
(
[Content-Length] => 3
[Server] => Apache
)
[body] => Hi!
[parentMessage] => stdClass object
(
[type] => 2
[httpVersion] => 1.1
[responseCode] => 302
[headers] => Array
(
[Content-Length] => 0
[Location] => ...
)
[body] =>
[parentMessage] => ...
)
)
?>
+
Parses HTTP headers into an associative array.
+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/html; chatset=UTF-8
[Server] => Funky/1.0
[Set-Cookie] => Array
(
[0] => foo=bar
[1] => baz=quux
)
[Folded] => works
too
?>
+
Get a list of incoming HTTP headers.
+Returns an associative array of incoming request headers.
+Get the raw request body (e.g. POST or PUT data).
+Returns NULL when using the CLI SAPI.
+Match an incoming HTTP header.
+Expects two string parameters representing the header name (case-insensitive)
+and the header value that should be compared. The case sensitivity of the
+header value depends on the additional optional bool parameter accepted.
Returns TRUE if header value matches, else FALSE.
Performs an HTTP GET request on the supplied url.
-
-The second parameter is expected to be an associative
+
Performs an HTTP GET request on the supplied url.
+The second parameter, if set, is expected to be an associative
array where the following keys will be recognized:
- redirect: int, whether and how many redirects to follow
- unrestrictedauth: bool, whether to continue sending credentials on
redirects to a different host
@@ -169,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
@@ -183,134 +297,911 @@ 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 takeThe 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
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,
'http_connectcode' => 0,
'httpauth_avail' => 0,
'proxyauth_avail' => 0,
)
?>
+Returns the HTTP response(s) as string on success, or FALSE on failure.
string http_head(string url[, array options[, array &info]])
-Performs an HTTP HEAD request on the suppied url.
-
-Returns the HTTP response as string.
-See http_get() for a full list of available options.string http_post_data(string url, string data[, array options[, &info]])
-Performs an HTTP POST request, posting data.
-Returns the HTTP response as string.
+Performs an HTTP HEAD request on the supplied url.
+See http_get() for a full list of available parameters and options.
+Returns the HTTP response as string on success, or FALSE on failure.
+string http_post_data(string url, string data[, array options[, array &info]])
+Performs an HTTP POST requeston the supplied url.
+Expects a string as second parameter containing the pre-encoded post data.
+
+See http_get() for a full list of available parameters and options.
+
+Returns the HTTP response(s) as string on success, or FALSE on failure.string http_post_fields(string url, array data[, array files[, array options[, array &info]]])
+Performs an HTTP POST request on the supplied url.
+Expecrs an associative array as second parameter, which will be
+
+www-form-urlencoded. See http_get() for a full list of available options.Returns the HTTP response(s) as string on success, or FALSE on failure.
+string http_put_file(string url, string file[, array options[, array &info]])
+Performs an HTTP PUT request on the supplied url.
+Expects the second parameter to be a string referncing the file to upload.
-
See http_get() for a full list of available options.string http_post_array(string url, array data[, array options[, array &info]])
-Performs an HTTP POST request, posting www-form-urlencoded array data.
-Returns the HTTP response as string.
+Returns the HTTP response(s) as string on success, or FALSE on failure.
+string http_put_stream(string url, resource stream[, array options[, array &info]])
+Performs an HTTP PUT request on the supplied url.
+Expects the second parameter to be a resource referencing an already
-
+opened stream, from which the data to upload should be read.
See http_get() for a full list of available options.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>');
}
?>
-
-
-
-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>');
}
?>
-
-
-
-string http_build_query(mixed formdata [, string prefix])
+Returns the HTTP response(s) as string on success. or FALSE on failure.
+int http_request_method_register(string method)
+Register a custom request method.
+Expects a string parameter containing the request method name to register.
+Returns the ID of the request method on success, or FALSE on failure.
+bool http_request_method_unregister(mixed method)
+Unregister a previously registered custom request method.
+Expects either the request method name or ID.
+Returns TRUE on success, or FALSE on failure.
+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.
+string http_request_method_name(int method)
+Get the literal string representation of a standard or registered request method.
+Expects the request method ID as parameter.
+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.
Instantiate a new HttpMessage object.
+Accepts an optional string parameter containing a single or several
+consecutive HTTP messages. The constructed object will actually
+represent the *last* message of the passed string. If there were
+prior messages, those can be accessed by HttpMessage::getParentMessage().
Throws HttpMalformedHeaderException.
+Create an HttpMessage object from a string. Kind of a static constructor.
+Expects a string parameter containing a sinlge or several consecutive
+HTTP messages.
Returns an HttpMessage object on success or NULL on failure.
+Throws HttpMalformedHeadersException.
+Get the body of the parsed HttpMessage.
+Returns the message body as string.
+Set the body of the HttpMessage.
+NOTE: Don't forget to update any headers accordingly.
Expects a string parameter containing the new body of the message.
+Get Message Headers.
+Returns an associative array containing the messages HTTP headers.
+Sets new headers.
+Expects an associative array as parameter containing the new HTTP headers,
+which will replace *all* previous HTTP headers of the message.
Add headers. If append is true, headers with the same name will be separated, else overwritten.
+Expects an associative array as parameter containing the additional HTTP headers
+to add to the messages existing headers. If the optional bool parameter is true,
+and a header with the same name of one to add exists already, this respective
+header will be converted to an array containing both header values, otherwise
+it will be overwritten with the new header value.
Get Message Type. (HTTP_MSG_NONE|HTTP_MSG_REQUEST|HTTP_MSG_RESPONSE)
+Returns the HttpMessage::TYPE.
+Set Message Type. (HTTP_MSG_NONE|HTTP_MSG_REQUEST|HTTP_MSG_RESPONSE)
+Exptects an int parameter, the HttpMessage::TYPE.
+Get the Response Code of the Message.
+Returns the HTTP response code if the message is of type
+HttpMessage::TYPE_RESPONSE, else FALSE.
Set the response code of an HTTP Response Message.
+Expects an int parameter with the HTTP response code.
+Returns TRUE on success, or FALSE if the message is not of type
+HttpMessage::TYPE_RESPONSE or the response code is out of range (100-510).
Get the Request Method of the Message.
+Returns the request method name on success, or FALSE if the message is
+not of type HttpMessage::TYPE_REQUEST.
Set the Request Method of the HTTP Message.
+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.
Get the Request URI of the Message.
+Returns the request uri as string on success, or FALSE if the message
+is not of type HttpMessage::TYPE_REQUEST.
Set the Request URI of the HTTP Message.
+Expects a string parameters containing the request uri.
+Returns TRUE on success, or FALSE if the message is not of type
+HttpMessage::TYPE_REQUEST or supplied URI was empty.
Get the HTTP Protocol Version of the Message.
+Returns the HTTP protocol version as string.
+Set the HTTP Protocol version of the Message.
+Expects a string parameter containing the HTTP protocol version.
+Returns TRUE on success, or FALSE if supplied version is out of range (1.0/1.1).
+Get parent Message.
+Returns the parent HttpMessage on success, or NULL if there's none.
+Send the Message according to its type as Response or Request.
+This provides limited functionality compared to HttpRequest and HttpResponse.
Returns TRUE on success, or FALSE on failure.
+Get the string representation of the Message.
+Accepts a bool parameter which specifies whether the returned string
+should also contain any parent messages.
Returns the full message as string.
+Implements Countable.
+Returns the number of parent messages + 1.
+Implements Serializable.
+Returns the serialized representation of the HttpMessage.
+Implements Serializable.
+Re-constructs the HttpMessage based upon the serialized string.
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 and an associative array as optional third parameter which will be
+passed to HttpRequest::setOptions().
Throws HttpException.
+Destroys the HttpRequest object.
+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
+currently set request options. If the parameter is empty or mitted,
+the optoions of the HttpRequest object will be reset.
Returns TRUE on success, or FALSE on failure.
+Get currently set options.
+Returns an associative array containing currently set options.
+Set SSL options.
+Accepts an associative array as parameter containing any SSL specific options.
+If the parameter is empty or omitted, the SSL options will be reset.
Returns TRUE on success, or FALSE on failure.
+Set additional SSL options.
+Expects an associative array as parameter containing additional SSL specific options.
+Returns TRUE on success, or FALSE on failure.
+Get previously set SSL options.
+Returns an associative array containing any previously set SSL options.
+Add request header name/value pairs.
+Expects an ssociative array as parameter containing additional header
+name/value pairs.
Returns TRUE on success, or FALSE on failure.
+Set request header name/value pairs.
+Accepts an associative array as parameter containing header name/value pairs.
+If the parameter is empty or omitted, all previously set headers will be unset.
Returns TRUE on success, or FALSE on failure.
+Get previously set request headers.
+Returns an associative array containing all currently set headers.
+Set cookies.
+Accepts an associative array as parameter containing cookie name/value pairs.
+If the parameter is empty or omitted, all previously set cookies will be unset.
Returns TRUE on success, or FALSE on failure.
+Add cookies.
+Expects an associative array as parameter containing any cookie name/value
+pairs to add.
Returns TRUE on success, or FALSE on failure.
+Get previously set cookies.
+Returns an associative array containing any previously set cookies.
+Set the request URL.
+Expects a string as parameter specifying the request url.
+Returns TRUE on success, or FALSE on failure.
+Get the previously set request URL.
+Returns the currently set request url as string.
+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.
Returns TRUE on success, or FALSE on failure.
+Get the previously set request method.
+Returns the currently set request method.
+Set the content type the post request should have.
+Expects a string as parameters containing the content type of the request
+(primary/secondary).
Returns TRUE on success, or FALSE if the content type does not seem to
+contain a primary and a secondary part.
Get the previously content type.
+Returns the previously set content type as string.
+Set the URL query parameters to use, overwriting previously set query parameters.
+Affects any request types.
Accepts a string or associative array parameter containing the pre-encoded
+query string or to be encoded query fields. If the parameter is empty or
+omitted, the query data will be unset.
Returns TRUE on success, or FALSE on failure.
+Get the current query data in form of an urlencoded query string.
+Returns a string containing the urlencoded query.
+Add parameters to the query parameter list, leaving previously set unchanged.
+Affects any request type.
Expects an associative array as parameter containing the query fields to add.
+Returns TRUE on success, or FALSE on failure.
+Adds POST data entries, leaving previously set unchanged, unless a
+post entry with the same name already exists.
+Affects only POST and custom requests.
Expects an associative array as parameter containing the post fields.
+Returns TRUE on success, or FALSE on failure.
+Set the POST data entries, overwriting previously set POST data.
+Affects only POST and custom requests.
Accepts an associative array as parameter containing the post fields.
+If the parameter is empty or omitted, the post data will be unset.
Returns TRUE on success, or FALSE on failure.
+Get previously set POST data.
+Returns the currently set post fields as associative array.
+Set raw post data to send, overwriting previously set raw post data. Don't
+forget to specify a content type. Affects only POST and custom requests.
+Only either post fields or raw post data can be used for each request.
+Raw post data has higher precedence and will be used even if post fields
+are set.
Accepts a string as parameter containing the *raw* post data.
+Returns TRUE on success, or FALSE on failure.
+Add raw post data, leaving previously set raw post data unchanged.
+Affects only POST and custom requests.
Expects a string as parameter containing the raw post data to concatenate.
+Returns TRUE on success, or FALSE on failure.
+Get previously set raw post data.
+Returns a string containing the currently set raw post data.
+Add a file to the POST request, leaving prefiously set files unchanged.
+Affects only POST and custom requests. Cannot be used with raw post data.
Expects a string parameter containing the form element name, and a string
+paremeter containing the path to the file which should be uploaded.
+Additionally accepts an optional string parameter which chould contain
+the content type of the file.
Returns TRUE on success, or FALSE if the content type seems not to contain a
+primary and a secondary content type part.
Set files to post, overwriting previously set post files.
+Affects only POST and requests. Cannot be used with raw post data.
Accepts an array containing the files to post. Each entry should be an
+associative array with "name", "file" and "type" keys. If the parameter
+is empty or omitted the post files will be unset.
Returns TRUE on success, or FALSE on failure.
+Get all previously added POST files.
+Returns an array containing currently set post files.
+Set file to put. Affects only PUT requests.
+Accepts a string as parameter referencing the path to file.
+If the parameter is empty or omitted the put file will be unset.
Returns TRUE on success, or FALSE on failure.
+Get previously set put file.
+Returns a string containing the path to the currently set put file.
+Get all response data after the request has been sent.
+Returns an associative array with the key "headers" containing an associative
+array holding all response headers, as well as the ley "body" containing a
+string with the response body.
If redirects were allowed and several responses were received, the data
+references the last received response.
Get response header(s) after the request has been sent.
+Accepts an string as optional parameter specifying a certain header to read.
+If the parameter is empty or omitted all response headers will be returned.
Returns either a string with the value of the header matching name if requested,
+FALSE on failure, or an associative array containing all reponse headers.
If redirects were allowed and several responses were received, the data
+references the last received response.
Get response cookie(s) after the request has been sent.
+Accepts a string as optional parameter specifying the name of the cookie to read.
+If the parameter is empty or omitted, an associative array with all received
+cookies will be returned.
Returns either an associative array with the cookie's name, value and any
+additional params of the cookie matching name if requested, FALSE on failure,
+or an array containing all received cookies as arrays.
If redirects were allowed and several responses were received, the data
+references the last received response.
Get the response body after the request has been sent.
+Returns a string containing the response body.
+If redirects were allowed and several responses were received, the data
+references the last received response.
Get the response code after the request has been sent.
+Returns an int representing the response code.
+If redirects were allowed and several responses were received, the data
+references the last received response.
Get response info after the request has been sent.
+See http_get() for a full list of returned info.
Accepts a string as optional parameter specifying the info to read.
+If the parameter is empty or omitted, an associative array containing
+all available info will be returned.
Returns either a scalar containing the value of the info matching name if
+requested, FALSE on failure, or an associative array containing all
+available info.
If redirects were allowed and several responses were received, the data
+references the last received response.
Get the full response as HttpMessage object after the request has been sent.
+Returns an HttpMessage object of the response.
+If redirects were allowed and several responses were received, the data
+references the last received response. Use HttpMessage::getParentMessage()
+to access the data of previously received responses whithin this request
+cycle.
Throws HttpException.
+Get sent HTTP message.
+Returns an HttpMessage object representing the sent request.
+If redirects were allowed and several responses were received, the data
+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.
+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
+HttpRequest::$recoedHistory to FALSE.
Returns an HttpMessage object representing the complete request/response
+history.
The object references the last received response, use HttpMessage::getParentMessage()
+to access the data of previously sent requests and received responses.
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.
+Clear the history.
+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;
}
?>
+
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;
}
?>
+
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.
Accepts virtual infinite optional parameters each referencing an
+HttpRequest object.
Throws HttpRequestException, HttpRequestPoolException, 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;
}
?>
+
Clean up HttpRequestPool object.
+Detach all attached HttpRequest objects.
+Attach an HttpRequest object to this HttpRequestPool.
+WARNING: set all options prior attaching!
Expects the parameter to be an HttpRequest object not alread attached to
+antother HttpRequestPool object.
Returns TRUE on success, or FALSE on failure.
+Throws HttpInvalidParamException, HttpRequestException,
+HttpRequestPoolException, HttpEncodingException.
Detach an HttpRequest object from this HttpRequestPool.
+Expects the parameter to be an HttpRequest object attached to this
+HttpRequestPool object.
Returns TRUE on success, or FALSE on failure.
+Throws HttpInvalidParamException, HttpRequestPoolException.
+Send all attached HttpRequest objects in parallel.
+Returns TRUE on success, or FALSE on failure.
+Throws HttpSocketException, HttpRequestException,
+HttpRequestPoolException, HttpMalformedHeaderException.
Returns TRUE until each request has finished its transaction.
+Usage:
++
+<?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;
}
}
?>
+
See HttpRequestPool::socketPerform().
+Returns TRUE on success, or FALSE on failure.
+Implements Iterator::valid().
+Implements Iterator::current().
+Implements Iterator::key().
+Implements Iterator::next().
+Implements Iterator::rewind().
+Implements Countable.
+Returns the number of attached HttpRequest objects.
+Get attached HttpRequest objects.
+Returns an array containing all currently attached HttpRequest objects.
+Get attached HttpRequest objects that already have finished their work.
+Returns an array containing all attached HttpRequest objects that
+already have finished their work.
Send an HTTP header.
+Expects a string parameter containing the name of the header and a mixed
+parameter containing the value of the header, which will be converted to
+a string. Additionally accepts an optional boolean parameter, which
+specifies whether an existing header should be replaced. If the second
+parameter is unset no header with this name will be sent.
Returns TRUE on success, or FALSE on failure.
+Throws HttpHeaderException if http.only_exceptions is TRUE.
+Get header(s) about to be sent.
+Accepts a string as optional parameter which specifies the name of the
+header to read. If the parameter is empty or omitted, an associative array
+with all headers will be returned.
Returns either a string containing the value of the header matching name,
+FALSE on failure, or an associative array with all headers.
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
+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"!
Expects a boolean as parameter specifying whether caching should be attempted.
+Returns TRUE ons success, or FALSE on failure.
+Get current caching setting.
+Returns TRUE if caching should be attempted, else FALSE.
+Enable on-thy-fly gzipping of the sent entity.
+Expects a boolean as parameter indicating if GZip compression should be enabled.
+Returns TRUE on success, or FALSE on failure.
+Get current gzipping setting.
+Returns TRUE if GZip compression is enabled, else FALSE.
+Set a custom cache-control header, usually being "private" or "public";
+The max_age parameter controls how long the cache entry is valid on the client side.
Expects a string parameter containing the primary cache control setting.
+Addtitionally accepts an int parameter specifying the max-age setting.
Returns TRUE on success, or FALSE if control does not match one of
+"public" , "private" or "no-cache".
Throws HttpInvalidParamException if http.only_exceptions is TRUE.
+Get current Cache-Control header setting.
+Returns the current cache control setting as a string like sent in a header.
+Set the content-type of the sent entity.
+Expects a string as parameter specifying the content type of the sent entity.
+Returns TRUE on success, or FALSE if the content type does not seem to
+contain a primary and secondary content type part.
Throws HttpInvalidParamException if http.only_exceptions is TRUE.
+Get current Content-Type header setting.
+Returns the currently set content type as string.
+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.
Expects a string parameter specifying the magic.mime database to use.
+Additionally accepts an optional int parameter, being flags for libmagic.
Returns the guessed content type on success, or FALSE on failure.
+Throws HttpRuntimeException, HttpInvalidParamException
+if http.only_exceptions is TRUE.
Set the Content-Disposition. The Content-Disposition header is very useful
+if the data actually sent came from a file or something similar, that should
+be "saved" by the client/user (i.e. by browsers "Save as..." popup window).
Expects a string parameter specifying the file name the "Save as..." dialogue
+should display. Optionally accepts a bool parameter, which, if set to true
+and the user agent knows how to handle the content type, will probably not
+cause the popup window to be shown.
Returns TRUE on success or FALSE on failure.
+Get current Content-Disposition setting.
+Returns the current content disposition as string like sent in a header.
+Set a custom ETag. Use this only if you know what you're doing.
+Expects an unquoted string as parameter containing the ETag.
+Returns TRUE on success, or FALSE on failure.
+Get calculated or previously set custom ETag.
+Returns the calculated or previously set ETag as unquoted string.
+Set a custom Last-Modified date.
+Expects an unix timestamp as parameter representing the last modification
+time of the sent entity.
Returns TRUE on success, or FALSE on failure.
+Get calculated or previously set custom Last-Modified date.
+Returns the calculated or previously set unix timestamp.
+Sets the throttle delay for use with HttpResponse::setBufferSize().
+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.
Returns TRUE on success, or FALSE on failure.
+Get the current throttle delay.
+Returns a double representing the throttle delay in seconds.
+Sets the send buffer size for use with HttpResponse::setThrottleDelay().
+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 an int parameter representing the chunk size in bytes.
+Returns TRUE on success, or FALSE on failure.
+Get current buffer size.
+Returns an int representing the current buffer size in bytes.
+Set the data to be sent.
+Expects one parameter, which will be converted to a string and contains
+the data to send.
Returns TRUE on success, or FALSE on failure.
+Get the previously set data to be sent.
+Returns a string containing the previously set data to send.
+Set the resource to be sent.
+Expects a resource parameter referencing an already opened stream from
+which the data to send will be read.
Returns TRUE on success, or FALSE on failure.
+Get the previously set resource to be sent.
+Returns the previously set resource.
+Set the file to be sent.
+Expects a string as parameter, specifying the path to the file to send.
+Returns TRUE on success, or FALSE on failure.
+Get the previously set file to be sent.
+Returns the previously set path to the file to send as string.
+Finally send the entity.
+Accepts an optional boolean parameter, specifying wheter the ouput
+buffers should be discarded prior sending. A successful caching attempt
+will cause a script termination, and write a log entry if the INI setting
+http.cache_log is set.
Returns TRUE on success, or FALSE on failure.
+Throws HttpHeaderException, HttpResponseException if http.onyl_excpetions is TRUE.
+Example:
++
+<?php
HttpResponse::setCache(true);
HttpResponse::setContentType('application/pdf');
HttpResponse::setContentDisposition("$user.pdf", false);
HttpResponse::setFile('sheet.pdf');
HttpResponse::send();
?>
+
Capture script output.
+Example:
+
+<?php
HttpResponse::setCache(true);
HttpResponse::capture();
// script follows
?>
+
Generated at: Fri, 4 Mar 2005 14:10:16 +0100
+Generated at: Mon, 21 Nov 2005 16:56:18 +0100
- \ No newline at end of file +