## Changelog:
-Version | Change
---------|-------
-2.0.4 | Dropped the pecl/event conflict.
-2.4.0 | Dropped the ext/json dependency.
-2.4.2 | Added libidn2 and libicu as fallback for IDNA support.
+0. v2.0.4
+ * Dropped the pecl/event conflict.
+0. v2.4.0
+ * Dropped the ext/json dependency.
+0. v2.4.2
+ * Added libidn2 and libicu as fallback for IDNA support.
The HTTP client. See http\Client\Curl's [options](http/Client/Curl#Options:) which is the only driver currently supported.
-## Changelog:
-
-Version | Change
---------|-------
-2.3.0 | Deprecated methods:<br>http\Client::enablePipelining() and <br>http\Client::enableEvents().<br>Added Methods:<br>http\Client::configure(),<br>http\Client::getAvailableConfiguration() and<br>http\Client::getAvailableOptions().
-
-## Examples:
-
-### Sending a simple GET request:
-
- <?php
-
- $request = new http\Client\Request("GET",
- "http://localhost",
- ["User-Agent"=>"My Client/0.1"]
- );
- $request->setOptions(["timeout"=>1]);
-
- $client = new http\Client;
- $client->enqueue($request)->send();
-
- // pop the last retrieved response
- $response = $client->getResponse();
- printf("%s returned '%s' (%d)\n",
- $response->getTransferInfo("effective_url"),
- $response->getInfo(),
- $response->getResponseCode()
- );
- ?>
-
-#### Yields:
-
- http://localhost/ returned 'HTTP/1.1 200 OK' (200)
-
-
-### Submitting a standard form:
-
- <?php
-
- $request = new http\Client\Request("POST",
- "http://localhost/post.php",
- ["Content-Type" => "application/x-www-form-urlencoded"]
- );
- $request->getBody()->append(new http\QueryString([
- "user" => "mike",
- "name" => "Michael Wallner"
- ]));
-
- $client = new http\Client;
- $client->setOptions(["ssl" => [
- "version" => http\Client\Curl\SSL_VERSION_TLSv1
- ]]);
- $client->enqueue($request)->send();
-
- // ask for the response for this specific request
- $response = $client->getResponse($request);
- printf("-> %s\n", $response->getInfo());
-
- ?>
-
-#### Yields:
-
- -> HTTP/1.1 200 OK
-
-
-### Submitting a multipart form:
-
- <?php
-
- $request = new http\Client\Request("POST",
- "http://localhost/post.php"
- );
-
- // http\Message\Body::addForm() will automatically add
- // Content-Type: multipart/form-data to the request headers
- $request->getBody()->addForm([
- "user" => "mike",
- "name" => "Michael Wallner"
- ], [
- [
- "name" => "image",
- "type" => "image/jpeg",
- "file" => "image.jpg"
- ]
- ]);
-
- $client = new http\Client;
- $client->setOptions(["ssl" => [
- "version" => http\Client\Curl\SSL_VERSION_TLSv1
- ]]);
- $client->enqueue($request)->send();
-
- // ask for the response for this specific request
- $response = $client->getResponse($request);
- printf("-> %.2F kB\n @ %.2F Mbit",
- .001 * $response->getTransferInfo("size_upload"),
- .0000008 * $response->getTransferInfo("speed_upload")
- );
- ?>
-
-#### Yields:
-
- -> 15.98 kB @ 6.77 Mbit
-
+## Constants:
+
+* DEBUG_INFO
+ Debug callback's $data contains human readable text.
+* DEBUG_IN
+ Debug callback's $data contains data received.
+* DEBUG_OUT
+ Debug callback's $data contains data sent.
+* DEBUG_HEADER
+ Debug callback's $data contains headers.
+* DEBUG_BODY
+ Debug callback's $data contains a body part.
+* DEBUG_SSL
+ Debug callback's $data contains SSL data.
## Properties:
--- /dev/null
+# http\Client Changelog
+
+0. v2.3.0
+ * Deprecated methods:
+ * http\Client::enablePipelining()
+ * http\Client::enableEvents()
+ * Added methods:
+ * http\Client::configure()
+ * http\Client::getAvailableConfiguration()
+ * http\Client::getAvailableOptions()
+0. v2.6.0, v3.1.0
+ * Added methods:
+ * http\Client::setDebug()
+ * Added constants:
+ * http\Client::DEBUG_INFO
+ * http\Client::DEBUG_IN
+ * http\Client::DEBUG_OUT
+ * http\Client::DEBUG_HEADER
+ * http\Client::DEBUG_BODY
+ * http\Client::DEBUG_SSL
--- /dev/null
+# http\Client Examples
+
+## Sending a simple GET request:
+
+ <?php
+
+ $request = new http\Client\Request("GET",
+ "http://localhost",
+ ["User-Agent"=>"My Client/0.1"]
+ );
+ $request->setOptions(["timeout"=>1]);
+
+ $client = new http\Client;
+ $client->enqueue($request)->send();
+
+ // pop the last retrieved response
+ $response = $client->getResponse();
+ printf("%s returned '%s' (%d)\n",
+ $response->getTransferInfo("effective_url"),
+ $response->getInfo(),
+ $response->getResponseCode()
+ );
+ ?>
+
+### Yields:
+
+ http://localhost/ returned 'HTTP/1.1 200 OK' (200)
+
+
+## Submitting a standard form:
+
+ <?php
+
+ $request = new http\Client\Request("POST",
+ "http://localhost/post.php",
+ ["Content-Type" => "application/x-www-form-urlencoded"]
+ );
+ $request->getBody()->append(new http\QueryString([
+ "user" => "mike",
+ "name" => "Michael Wallner"
+ ]));
+
+ $client = new http\Client;
+ $client->setOptions(["ssl" => [
+ "version" => http\Client\Curl\SSL_VERSION_TLSv1
+ ]]);
+ $client->enqueue($request)->send();
+
+ // ask for the response for this specific request
+ $response = $client->getResponse($request);
+ printf("-> %s\n", $response->getInfo());
+
+ ?>
+
+### Yields:
+
+ -> HTTP/1.1 200 OK
+
+
+## Submitting a multipart form:
+
+ <?php
+
+ $request = new http\Client\Request("POST",
+ "http://localhost/post.php"
+ );
+
+ // http\Message\Body::addForm() will automatically add
+ // Content-Type: multipart/form-data to the request headers
+ $request->getBody()->addForm([
+ "user" => "mike",
+ "name" => "Michael Wallner"
+ ], [
+ [
+ "name" => "image",
+ "type" => "image/jpeg",
+ "file" => "image.jpg"
+ ]
+ ]);
+
+ $client = new http\Client;
+ $client->setOptions(["ssl" => [
+ "version" => http\Client\Curl\SSL_VERSION_TLSv1
+ ]]);
+ $client->enqueue($request)->send();
+
+ // ask for the response for this specific request
+ $response = $client->getResponse($request);
+ printf("-> %.2F kB\n @ %.2F Mbit",
+ .001 * $response->getTransferInfo("size_upload"),
+ .0000008 * $response->getTransferInfo("speed_upload")
+ );
+ ?>
+
+### Yields:
+
+ -> 15.98 kB @ 6.77 Mbit
The http\Client\Curl namespace holds option value constants specific to the curl driver of the http\Client.
-## Changelog
+## Constants:
-Version | Change
---------|-------
-2.1.0 | Added $dns_interface, $dns_local_ip4, $dns_local_ip6 and $expect_100_timeout options.
-2.1.2 | Added request option constants:<br> http\Client\Curl\POSTREDIR_303,<br> http\Client\Curl\AUTH_SPNEGO,<br> http\Client\Curl\SSL_VERSION_TLSv1_0,<br> http\Client\Curl\SSL_VERSION_TLSv1_1 and<br> http\Client\Curl\SSL_VERSION_TLSv1_2
-2.3.0 | Added $pinned_publickey, $ltsauth and $verifystatus $ssl options.<br>Added $proxyheader and $unix_socket_path options.<br>Added request option constants:<br>http\Client\Curl\HTTP_VERSION_2_0 and<br>http\Client\Curl\TLS_AUTH_SRP.
+### Features and Versions:
-## Constants:
+* FEATURES
+ Bitmask of available libcurl features.
+ See http\Client\Curl\Features namespace.
+* VERSIONS
+ List of library versions of or linked into libcurl,
+ e.g. "libcurl/7.50.0 OpenSSL/1.0.2h zlib/1.2.8 libidn/1.32 nghttp2/1.12.0".
+ See http\Client\Curl\Versions namespace.
### HTTP Protocol Version
Comma separated list of hosts where no proxy should be used. Available if libcurl is v7.19.4 or more recent.
* array $proxyheader
List of key/value pairs of headers which should only be sent to a proxy. Available if libcurl is v7.37.0 or more recent.
+* string $proxy_service_name
+ Proxy service name. The default service name is "HTTP" for HTTP based proxies and "rcmd" for SOCKS5. Available if libcurl is v7.43.0 or more recent and has built-in GSSAPI support.
### DNS
Disable [Nagle's algotrithm](http://tools.ietf.org/html/rfc896).
* string $unix_socket_path
Connect to the webserver listening at $unix_socket_path instead of opening a TCP connection to it. Available if libcurl is v7.40.0 or more recent.
+* bool $path_as_is
+ Do *not* squash sequences of "/../" or "/./" that may exist in the URL's path.
### Authentication
user:password
* int $httpauthtype
See http\Client\Curl\AUTH_* constants.
+* string $service_name
+ The name of the service for DIGEST-MD5, SPNEGO and KERBEROS5 authentication mechanisms. The default service name is "HTTP". Available if libcurl is v7.43.0 or more recent.
### Redirection
* string $lsauthpass
TLS-SRP password. Available if libcurl is v7.21.4 or more recent.
* bool $verifystatus
- Enable OCSP. Available if libcurl is v7.41.0 or more recent and was build with openssl, gnutls or nss support.
+ Enable OCSP. Available if libcurl is v7.41.0 or more recent and was built with OpenSSL, GnuTLS or NSS support.
+ * bool $falsestart
+ Whether false start should be used during the TLS handshake. Available if libcurl is v7.42.0 or more recent and was built with NSS or SecureTransport support.
## Configuration:
Simple list of server software names to blacklist for pipelining. Available if libcurl is v7.30.0 or more recent.
* array $pipelining_site_bl
Simple list of server host names to blacklist for pipelining. Available if libcurl is v7.30.0 or more recent.
-* bool $use_eventloop
- Whether to use an event loop. Available if pecl/http was built with libevent support.
+* mixed $use_eventloop
+ Whether to use an event loop. This option accepts either bool, whether to use
+ the internal event loop, or an instance of an http\Client\Curl\User implementation.
+ The internal event loop is only available if pecl/http was built with libevent support.
+* bool $share_cookies
+ Whether to let the client share cookies between requests.
+* bool $share_ssl
+ Whether to let the client share SSL/TLS sessions between requests. Available if libcurl is v7.23.0 or more recent.
--- /dev/null
+# http\Client\Curl Changelog
+
+0. v2.1.0
+ * Added request options:
+ * $dns_interface
+ * $dns_local_ip4
+ * $dns_local_ip6
+ * $expect_100_timeout
+0. v2.1.2
+ * Added request option constants:
+ * http\Client\Curl\POSTREDIR_303
+ * http\Client\Curl\AUTH_SPNEGO
+ * http\Client\Curl\SSL_VERSION_TLSv1_0
+ * http\Client\Curl\SSL_VERSION_TLSv1_1
+ * http\Client\Curl\SSL_VERSION_TLSv1_2
+0. v2.3.0
+ * Added request options:
+ * $proxyheader
+ * $unix_socket_path
+ * Added SSL request options:
+ * $pinned_publickey
+ * $tlsauth
+ * $verifystatus
+ * Added request option constants:
+ * http\Client\Curl\HTTP_VERSION_2_0
+ * http\Client\Curl\TLS_AUTH_SRP
+0. v2.5.1
+ * Added request options:
+ * $proxy_service_name
+ * $service_name
+ * Added SSL request options:
+ * $falsestart
+0. v2.5.6
+ * Added request option constants:
+ * http\Client\Curl\HTTP_VERSION_2TLS
+0. v2.6.0, v3.1.0
+ * Added methods:
+ * http\Client::setDebug()
+ * Added client configure options:
+ * $share_cookies
+ * $share_ssl
+ * Changed client configure options:
+ * bool $use_eventloop changed to mixed to accept an http\Client\Curl\User implementation
+ * Added constants:
+ * http\Client\Curl::FEATURES
+ * http\Client\Curl::VERSIONS
+ * Added namespaces:
+ * http\Client\Curl\Features
+ * http\Client\Curl\Versions
+ * Added interfaces:
+ * http\Client\Curl\User
--- /dev/null
+# namespace http\Client\Curl\Features
+
+CURL feature constants.
+
+> ***NOTE:***
+> These constants have been added in v2.6.0, resp. v3.1.0.
+
+## Constants:
+
+* ASYNCHDNS
+ Whether libcurl supports asynchronous domain name resolution.
+* GSSAPI
+ Whether libcurl supports the Generic Security Services Application Program Interface. Available if libcurl is v7.38.0 or more recent.
+* GSSNEGOTIATE
+ Whether libcurl supports HTTP Generic Security Services negotiation.
+* HTTP2
+ Whether libcurl supports the HTTP/2 protocol. Available if libcurl is v7.33.0 or more recent.
+* IDN
+ Whether libcurl supports international domain names.
+* IPV6
+ Whether libcurl supports IPv6.
+* KERBEROS4
+ Whether libcurl supports the old Kerberos protocol.
+* KERBEROS5
+ Whether libcurl supports the more recent Kerberos v5 protocol. Available if libcurl is v7.40.0 or more recent.
+* LARGEFILE
+ Whether libcurl supports large files.
+* LIBZ
+ Whether libcurl supports gzip/deflate compression.
+* NTLM
+ Whether libcurl supports the NT Lan Manager authentication.
+* NTLM_WB
+ Whether libcurl supports NTLM delegation to a winbind helper. Available if libcurl is v7.22.0 or more recent.
+* PSL
+ Whether libcurl supports the Public Suffix List for cookie host handling. Available if libcurl is v7.47.0 or more recent.
+* SPNEGO
+ Whether libcurl supports the Simple and Protected GSSAPI Negotiation Mechanism.
+* SSL
+ Whether libcurl supports SSL/TLS protocols.
+* SSPI
+ Whether libcurl supports the Security Support Provider Interface.
+* TLSAUTH_SRP
+ Whether libcurl supports TLS Secure Remote Password authentication. Available if libcurl is v7.21.4 or more recent.
+* UNIX_SOCKETS
+ Whether libcurl supports connections to unix sockets. Available if libcurl is v7.40.0 or more recent.
--- /dev/null
+# interface http\Client\Curl\User
+
+Interface to an user event loop implementation for http\Client::configure()'s $use_eventloop option.
+
+> ***NOTE:***
+> This interface was added in v2.6.0, resp. v3.1.0.
+
+## Constants:
+
+* POLL_NONE
+ No action.
+* POLL_IN
+ Poll for read readiness.
+* POLL_OUT
+ Poll for write readiness.
+* POLL_INOUT
+ Poll for read/write readiness.
+* POLL_REMOVE
+ Stop polling for activity on this descriptor.
--- /dev/null
+# http\Client\Curl\User Examples
+
+## Example using the [pecl/ev](http://pecl.php.net/ev) loop:
+
+ <?php
+
+ class UserHandler implements http\Client\Curl\User
+ {
+ private $client;
+ private $run;
+ private $ios = [];
+ private $timeout;
+
+
+ function __construct(http\Client $client) {
+ $this->client = $client;
+ }
+
+ function init(callable $run) {
+ $this->run = $run;
+ }
+
+ function timer(int $timeout_ms) {
+ echo "T";
+ if (isset($this->timeout)) {
+ $this->timeout->set($timeout_ms/1000, 0);
+ $this->timeout->start();
+ } else {
+ $this->timeout = new EvTimer($timeout_ms/1000, 0, function() {
+ if (!call_user_func($this->run, $this->client)) {
+ if ($this->timeout) {
+ $this->timeout->stop();
+ $this->timeout = null;
+ }
+ }
+ });
+ }
+ }
+
+ function socket($socket, int $action) {
+ echo "S";
+
+ switch ($action) {
+ case self::POLL_NONE:
+ break;
+ case self::POLL_REMOVE:
+ if (isset($this->ios[(int) $socket])) {
+ echo "U";
+ $this->ios[(int) $socket]->stop();
+ unset($this->ios[(int) $socket]);
+ }
+ break;
+
+ default:
+ $ev = 0;
+ if ($action & self::POLL_IN) {
+ $ev |= Ev::READ;
+ }
+ if ($action & self::POLL_OUT) {
+ $ev |= Ev::WRITE;
+ }
+ if (isset($this->ios[(int) $socket])) {
+ $this->ios[(int) $socket]->set($socket, $ev);
+ } else {
+ $this->ios[(int) $socket] = new EvIo($socket, $ev, function($watcher, $events) use($socket) {
+ $action = 0;
+ if ($events & Ev::READ) {
+ $action |= self::POLL_IN;
+ }
+ if ($events & Ev::WRITE) {
+ $action |= self::POLL_OUT;
+ }
+ if (!call_user_func($this->run, $this->client, $socket, $action)) {
+ if ($this->timeout) {
+ $this->timeout->stop();
+ $this->timeout = null;
+ }
+ }
+ });
+ }
+ break;
+ }
+ }
+
+ function once() {
+ throw new BadMethodCallException("this example uses Ev::run()");
+ }
+
+ function wait(int $timeout_ms = null) {
+ throw new BadMethodCallException("this example uses Ev::run()");
+ }
+
+ function send() {
+ throw new BadMethodCallException("this example uses Ev::run()");
+ }
+ }
+
+ $client = new http\Client;
+ $client->configure([
+ "use_eventloop" => new UserHandler($client)
+ ]);
+ $client->enqueue(new http\Client\Request("GET", "http://example.com/"), function($r) {
+ var_dump($r->getResponseCode());
+ });
+
+ Ev::run();
+
+ ?>
+
+### Yields:
+
+ TTTTTTTTSTSTSUint(200)
--- /dev/null
+# void http\Client\Curl\User::init(callable $run)
+
+Initialize the event loop.
+
+
+## Params:
+
+* callable $run as function(http\Client $c, resource $s = null, int $action = http\Client\Curl\User::POLL_NONE) : int
+ Internal callback returning the number of unfinished requests pending.
+
+
+> ***NOTE***:
+> The callback should be run when a timeout occurs or a watched socket needs action.
--- /dev/null
+# void http\Client\Curl\User::once()
+
+Run the loop as long as it does not block.
+
+> ***NOTE:***
+> This method is called by http\Client::once(), so it does not need to have an actual implementation if http\Client::once() is never called.
+
+
+## Params:
+
+None.
--- /dev/null
+# void http\Client\Curl\User::send()
+
+Run the loop.
+
+> ***NOTE:***
+> This method is called by http\Client::send(), so it does not need to have an actual implementation if http\Client::send() is never called.
+
+## Params:
+
+None.
--- /dev/null
+# void http\Client\Curl\User::socket(resource $socket, int $poll)
+
+Register (or deregister) a socket watcher.
+
+## Params:
+
+* resource $socket
+ The socket descriptor to watch.
+* int $poll
+ http\Client\Curl\User::POLL_* constant.
--- /dev/null
+# void http\Client\Curl\User::timer(int $timeout_ms)
+
+Register a timeout watcher.
+
+## Params:
+
+* int $timeout_ms
+ Desired maximum timeout in milliseconds.
--- /dev/null
+# void http\Client\Curl\User::wait([int $timeout_ms = null])
+
+Wait/poll/select (block the loop) until events fire.
+
+> ***NOTE:***
+> This method is called by http\Client::wait(), so it does not need to have an actual implementation if http\Client::wait() is never called.
+
+## Params:
+
+* Optional int $timeout_ms = null
+ Block for at most this milliseconds.
--- /dev/null
+# namespace http\Client\Curl\Versions
+
+CURL version constants.
+
+> ***NOTE:***
+> These constants have been added in v2.6.0, resp. v3.1.0.
+
+## Constants:
+
+* CURL
+ Version string of libcurl, e.g. "7.50.0".
+* SSL
+ Version string of the SSL/TLS library, e.g. "OpenSSL/1.0.2h".
+* LIBZ
+ Version string of the zlib compression library, e.g. "1.2.8".
+* ARES
+ Version string of the c-ares library, e.g. "1.11.0".
+* IDN
+ Version string of the IDN library, e.g. "1.32".
Configure the client's low level options.
+> ***NOTE:***
+> This method has been added in v2.3.0.
+
## Params:
* array $configuration
* http\Exception\InvalidArgumentException
* http\Exception\UnexpectedValueException
-
-## Changelog:
-
-Version | Change
---------|-------
-2.3.0 | This method has been deprecated.
* http\Exception\InvalidArgumentException
* http\Exception\UnexpectedValueException
-
-## Changelog:
-
-Version | Change
---------|-------
-2.3.0 | This method has been deprecated.
--- /dev/null
+# http\Client http\Client::setDebug(callable $callback)
+
+Set client debugging callback.
+
+> ***NOTE:***
+> This method has been added in v2.6.0, resp. v3.1.0.
+
+## Params:
+
+* callable $callback as function(http\Client $c, http\Client\Request $r, int $type, string $data)
+ The debug callback. For $type see http\Client::DEBUG_* constants.
+
+## Returns:
+
+* http\Client, self.
+
+## Throws:
+
+* http\Exception\InvalidArgumentException
+
+## Example:
+
+ <?php
+
+ (new http\Client)->setDebug(function($c, $r, $type, $data) {
+ if ($type === http\Client::DEBUG_INFO) {
+ printf("INFO: %s\n", $data);
+ } else {
+ repeat:
+ if ($type & http\Client::DEBUG_OUT) {
+ $sep = ">";
+ } elseif ($type & http\Client::DEBUG_IN) {
+ $sep = "<";
+ }
+ if ($type & http\Client::DEBUG_SSL) {
+ printf("%s <%d bytes of SSL data>\n", $sep, strlen($data));
+ } else {
+ printf("%s %s\n", $sep, str_replace("\n", "\n$sep ", rtrim($data, "\n")));
+ }
+ }
+ })->enqueue(new http\Client\Request("GET", "http://example.com"))->send();
+
+ ?>
+
+> ***NOTE:***
+> Except for http\Client::DEBUG_INFO, which always occurs separately, the debug
+> callback's $type argument contains a bitmask of (http\Client::DEBUG_IN or http\Client::DEBUG_OUT)
+> and (http\Client::DEBUG_HEADER or http\Client::DEBUG_BODY or http\Client::DEBUG_SSL).
+
+### Yields:
+
+ INFO: Trying 93.184.216.34...
+
+ INFO: Connected to example.com (93.184.216.34) port 80 (#0)
+
+ > GET / HTTP/1.1
+ > Host: example.com
+ > User-Agent: PECL_HTTP/2.6.0dev PHP/5.6.19RC1 libcurl/7.50.0-DEV
+ > Accept: */*
+ >
+ < HTTP/1.1 200 OK
+ < Cache-Control: max-age=604800
+ < Content-Type: text/html
+ < Date: Thu, 18 Aug 2016 17:55:10 GMT
+ < Etag: "359670651+gzip+ident"
+ < Expires: Thu, 25 Aug 2016 17:55:10 GMT
+ < Last-Modified: Fri, 09 Aug 2013 23:54:35 GMT
+ < Server: ECS (iad/182A)
+ < Vary: Accept-Encoding
+ < X-Cache: HIT
+ < x-ec-custom-error: 1
+ < Content-Length: 1270
+ <
+ < <!doctype html>
+ < <html>
+ < <head>
+ < <title>Example Domain</title>
+ <
+ < <meta charset="utf-8" />
+ < <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
+ < <meta name="viewport" content="width=device-width, initial-scale=1" />
+ < <style type="text/css">
+ < body {
+ < background-color: #f0f0f2;
+ < margin: 0;
+ < padding: 0;
+ < font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
+ <
+ < }
+ < div {
+ < width: 600px;
+ < margin: 5em auto;
+ < padding: 50px;
+ < background-color: #fff;
+ < border-radius: 1em;
+ < }
+ < a:link, a:visited {
+ < color: #38488f;
+ < text-decoration: none;
+ < }
+ < @media (max-width: 700px) {
+ < body {
+ < background-color: #fff;
+ < }
+ < div {
+ < width: auto;
+ < margin: 0 auto;
+ < border-radius: 0;
+ < padding: 1em;
+ < }
+ < }
+ < </style>
+ < </head>
+ <
+ < <body>
+ < <div>
+ < <h1>Example Domain</h1>
+ < <p>This domain is established to be used for illustrative examples in documents. You may use this
+ < domain in examples without prior coordination or asking for permission.</p>
+ < <p><a href="http://www.iana.org/domains/example">More information...</a></p>
+ < </div>
+ < </body>
+ < </html>
+ INFO: Connection #0 to host example.com left intact
# class http\Env
The http\Env class provides static methods to manipulate and inspect the server's current request's HTTP environment.
-
-## Changelog:
-
-| Version | Change
-|---------|--------
-| 2.4.0 | Split off pecl/[apfd](apfd) and pecl/[json_post](json_post)
-
-## Request startup
-
-In versions lower than 2.4.0, the http\Env module extends PHP's builtin POST data parser to be run also if the request method is not POST. Additionally it will handle application/json payloads if ext/json is available. Successfully parsed JSON will be put right into the $_POST array.
-
-This functionality has been separated into two distict extensions, pecl/[apfd](apfd) and pecl/[json_post](json_post).
-
--- /dev/null
+# http\Env Changelog
+
+0. v2.4.0
+ * Split off pecl/[apfd](apfd) and pecl/[json_post](json_post)
+
+## Backwards compatibility notes
+
+### Request startup prior v2.4.0
+
+In versions lower than 2.4.0, the http\Env module extends PHP's builtin POST data parser to be run also if the request method is not POST. Additionally it will handle application/json payloads if ext/json is available. Successfully parsed JSON will be put right into the $_POST array.
+
+This functionality has been separated into two distict extensions, pecl/[apfd](apfd) and pecl/[json_post](json_post).
See http\Message for inherited members.
-## Changelog:
-
-Version | Changes
---------|--------
-2.2.0 | Added http\Env\Request::getCookie() and http\Env\Request::$cookie.
-
## Constants:
None.
--- /dev/null
+# http\Env\Request Changelog
+
+0. v2.2.0
+ * Added methods:
+ * http\Env\Request::getCookie()
+ * Added properties:
+ * http\Env\Request::$cookie
See http\Message for inherited members.
-## Changelog:
-
-Version | Changes
---------|--------
-2.2.0 | Added http\Env\Response::setCookie() and http\Env\Response::$cookies.
-
## Constants:
* CONTENT_ENCODING_NONE
--- /dev/null
+# http\Env\Response Changelog
+
+0. v2.2.0
+ * Added methods:
+ * http\Env\Response::setCookie()
+ * Added properties:
+ * http\Env\Response::$cookies
--- /dev/null
+# class http\Env\Url extends http\Url
+
+URL class using the HTTP environment by default.
+
+> ***NOTE:***
+> This class has been added in v3.0.0.
+
+Always adds http\Url::FROM_ENV to the $flags constructor argument. See also http\Url.
The parser which is underlying http\Header and http\Message.
-## Changelog:
-
-| Version | Change
-|---------|--------
-| 2.3.0 | Added http\Header\Parser API
+> ***NOTE:***
+> This class has been added in v2.3.0.
## Constants:
# class http\Message implements Countable, Serializable, Iterator
The message class builds the foundation for any request and response message.
+
See http\Client\Request and http\Client\Response, as well as http\Env\Request and http\Env\Response.
## Constants:
The parser which is underlying http\Message.
-## Changelog:
-
-| Version | Change
-|---------|--------
-| 2.2.0 | Added http\Message\Parser API
+> ***NOTE:****
+> This class was added in v2.2.0.
## Constants:
}
array(1) {
["Cache-Control"]=>
- array(2) {
- [0]=>
- string(7) "private"
- [1]=>
- string(15) "must-revalidate"
- }
+ string(24) "private, must-revalidate"
}
Cache-Control: private, must-revalidate
Set a single header.
See http\Message::getHeader() and http\Message::addHeader().
+> **NOTE:**
+> Prior to v2.5.6/v3.1.0 headers with the same name were merged into a single
+> header with values concatenated by comma.
+
## Params:
* string $header
## Returns:
* http\Message, self.
+
+## Changelog:
+
+Version | Changes
+-------------|--------
+2.5.6, 3.1.0 | Multiple headers with the same name are kept separate instead of merged together.
Set the message headers.
See http\Message::getHeaders() and http\Message::addHeaders().
+> **NOTE:**
+> Prior to v2.5.6/v3.1.0 headers with the same name were merged into a single
+> header with values concatenated by comma.
+
## Params:
* array $headers = NULL
array(0) {
}
+## Changelog:
+
+Version | Changes
+-------------|--------
+2.5.6, 3.1.0 | Multiple headers with the same name are kept separate instead of merged together.
Parse, interpret and compose HTTP (header) parameters.
-## Changelog:
-
-Version | Change
---------|-------
-2.1.0 | Added [RFC5987](http://tools.ietf.org/html/rfc5987) support
-2.5.0 | Added [RFC5988](http://tools.ietf.org/html/rfc5987) support
-
-## Example:
-
- <?php
-
- $u = urlencode("ü");
- $s = urlencode("ß");
-
- $t = "p1*=utf-8'de's$u$s,p2*=utf-8''hei$s;a1*=utf-8''a$s;a2*=utf-8''e$s;a3=no,p3=not";
- $p = new http\Params($t);
-
- var_dump($p->params, $p->toString());
-
- ?>
-
-Yields:
-
- array(3) {
- ["p1"]=>
- array(2) {
- ["*rfc5987*"]=>
- array(1) {
- ["de"]=>
- string(5) "süß"
- }
- ["arguments"]=>
- array(0) {
- }
- }
- ["p2"]=>
- array(2) {
- ["*rfc5987*"]=>
- array(1) {
- [""]=>
- string(5) "heiß"
- }
- ["arguments"]=>
- array(2) {
- ["*rfc5987*"]=>
- array(2) {
- ["a1"]=>
- array(1) {
- [""]=>
- string(3) "aß"
- }
- ["a2"]=>
- array(1) {
- [""]=>
- string(3) "eß"
- }
- }
- ["a3"]=>
- string(2) "no"
- }
- }
- ["p3"]=>
- array(2) {
- ["value"]=>
- string(3) "not"
- ["arguments"]=>
- array(0) {
- }
- }
- }
- string(98) "p1*=utf-8'de's%C3%BC%C3%9F,p2*=utf-8''hei%C3%9F;a1*=utf-8''a%C3%9F;a2*=utf-8''e%C3%9F;a3=no,p3=not"
-
-## Web Linking Example:
-
- $link = <<<EOF
- Link: </TheBook/chapter2>;
- rel="previous"; title*=UTF-8'de'letztes%20Kapitel,
- </TheBook/chapter4>;
- rel="next"; title*=UTF-8'de'n%c3%a4chstes%20Kapitel
- EOF;
-
- $p = current(http\Header::parse($link, "http\\Header"))->getParams(
- http\Params::DEF_PARAM_SEP,
- http\Params::DEF_ARG_SEP,
- http\Params::DEF_VAL_SEP,
- http\Params::PARSE_RFC5988 | http\Params::PARSE_ESCAPED
- );
-
- var_dump($p->params);
- var_dump((string)$p);
-
-Yields:
-
- array(2) {
- ["/TheBook/chapter2"]=>
- array(2) {
- ["value"]=>
- bool(true)
- ["arguments"]=>
- array(2) {
- ["rel"]=>
- string(8) "previous"
- ["*rfc5987*"]=>
- array(1) {
- ["title"]=>
- array(1) {
- ["de"]=>
- string(15) "letztes Kapitel"
- }
- }
- }
- }
- ["/TheBook/chapter4"]=>
- array(2) {
- ["value"]=>
- bool(true)
- ["arguments"]=>
- array(2) {
- ["rel"]=>
- string(4) "next"
- ["*rfc5987*"]=>
- array(1) {
- ["title"]=>
- array(1) {
- ["de"]=>
- string(17) "nächstes Kapitel"
- }
- }
- }
- }
- }
- string(139) "</TheBook/chapter2>;rel="previous";title*=utf-8'de'letztes%20Kapitel,</TheBook/chapter4>;rel="next";title*=utf-8'de'n%C3%A4chstes%20Kapitel"
-
## Constants:
* DEF_PARAM_SEP
--- /dev/null
+# http\Params Changelog
+
+0. v2.1.0
+ * Added constants:
+ * http\Params::PARSE_RFC5987 ([RFC5987](http://tools.ietf.org/html/rfc5987) support)
+0. v2.5.0
+ * Added constants:
+ * http\Params::PARSE_RFC5988 ([RFC5988](http://tools.ietf.org/html/rfc5987) support)
--- /dev/null
+# http\Params Examples
+
+## RFC5987 example:
+
+ <?php
+
+ $u = urlencode("ü");
+ $s = urlencode("ß");
+
+ $t = "p1*=utf-8'de's$u$s,p2*=utf-8''hei$s;a1*=utf-8''a$s;a2*=utf-8''e$s;a3=no,p3=not";
+ $p = new http\Params($t);
+
+ var_dump($p->params, $p->toString());
+
+ ?>
+
+### Yields:
+
+ array(3) {
+ ["p1"]=>
+ array(2) {
+ ["*rfc5987*"]=>
+ array(1) {
+ ["de"]=>
+ string(5) "süß"
+ }
+ ["arguments"]=>
+ array(0) {
+ }
+ }
+ ["p2"]=>
+ array(2) {
+ ["*rfc5987*"]=>
+ array(1) {
+ [""]=>
+ string(5) "heiß"
+ }
+ ["arguments"]=>
+ array(2) {
+ ["*rfc5987*"]=>
+ array(2) {
+ ["a1"]=>
+ array(1) {
+ [""]=>
+ string(3) "aß"
+ }
+ ["a2"]=>
+ array(1) {
+ [""]=>
+ string(3) "eß"
+ }
+ }
+ ["a3"]=>
+ string(2) "no"
+ }
+ }
+ ["p3"]=>
+ array(2) {
+ ["value"]=>
+ string(3) "not"
+ ["arguments"]=>
+ array(0) {
+ }
+ }
+ }
+ string(98) "p1*=utf-8'de's%C3%BC%C3%9F,p2*=utf-8''hei%C3%9F;a1*=utf-8''a%C3%9F;a2*=utf-8''e%C3%9F;a3=no,p3=not"
+
+## Web Linking Example:
+
+ $link = <<<EOF
+ Link: </TheBook/chapter2>;
+ rel="previous"; title*=UTF-8'de'letztes%20Kapitel,
+ </TheBook/chapter4>;
+ rel="next"; title*=UTF-8'de'n%c3%a4chstes%20Kapitel
+ EOF;
+
+ $p = current(http\Header::parse($link, "http\\Header"))->getParams(
+ http\Params::DEF_PARAM_SEP,
+ http\Params::DEF_ARG_SEP,
+ http\Params::DEF_VAL_SEP,
+ http\Params::PARSE_RFC5988 | http\Params::PARSE_ESCAPED
+ );
+
+ var_dump($p->params);
+ var_dump((string)$p);
+
+### Yields:
+
+ array(2) {
+ ["/TheBook/chapter2"]=>
+ array(2) {
+ ["value"]=>
+ bool(true)
+ ["arguments"]=>
+ array(2) {
+ ["rel"]=>
+ string(8) "previous"
+ ["*rfc5987*"]=>
+ array(1) {
+ ["title"]=>
+ array(1) {
+ ["de"]=>
+ string(15) "letztes Kapitel"
+ }
+ }
+ }
+ }
+ ["/TheBook/chapter4"]=>
+ array(2) {
+ ["value"]=>
+ bool(true)
+ ["arguments"]=>
+ array(2) {
+ ["rel"]=>
+ string(4) "next"
+ ["*rfc5987*"]=>
+ array(1) {
+ ["title"]=>
+ array(1) {
+ ["de"]=>
+ string(17) "nächstes Kapitel"
+ }
+ }
+ }
+ }
+ }
+ string(139) "</TheBook/chapter2>;rel="previous";title*=utf-8'de'letztes%20Kapitel,</TheBook/chapter4>;rel="next";title*=utf-8'de'n%C3%A4chstes%20Kapitel"
The http\Url class provides versatile means to parse, construct and manipulate URLs.
-## Changelog:
-
-Version | Changes
---------|--------
-2.2.0 | Added parser constants:<br> http\Url::PARSE_MBUTF8,<br> http\Url::PARSE_MBLOC (on systems with wide character support),<br>http\Url::PARSE_TOPCT,<br>http\Url::PARSE_TOIDN (with libidn support).
-
-## Backwards compatibility
-
-### New parser in v2.2.0
-
-PHP's [parse_url()](http://php.net/parse_url) is avoided since v2.2.0.
-
-Creating an empty url by `new http\Url(NULL, NULL, 0)` will not result in `http://localhost/` anymore but in an empty URL instead.
-
## Constants:
* REPLACE
--- /dev/null
+# http\Url Changelog
+
+0. v2.2.0
+ * Added parser constants:
+ * http\Url::PARSE_MBUTF8
+ * http\Url::PARSE_MBLOC (on systems with wide character support)
+ * http\Url::PARSE_TOIDN (with libidn support)
+ * http\Url::PARSE_TOPCT
+
+## Backwards compatibility notes
+
+### New parser in v2.2.0
+
+PHP's [parse_url()](http://php.net/parse_url) is avoided since v2.2.0.
+
+Creating an empty url by `new http\Url(NULL, NULL, 0)` will not result in `http://localhost/` anymore but in an empty URL instead.
+
+### No more default parts from the environment in v3.0.0
+
+The default value of the $flags parameter of http\Url::__construct() was changed from http\Url::FROM_ENV to 0 and http\Env\Url was introduced instead.
-# void http\Url::__construct([mixed $old_url = NULL[, mixed $new_url = NULL[, int $flags = http\Url::FROM_ENV]]])
+# void http\Url::__construct([mixed $old_url = NULL[, mixed $new_url = NULL[, int $flags = 0]]])
Create an instance of an http\Url.
+> ***NOTE:***
+> Prior to v3.0.0, the default for the $flags parameter was http\Url::FROM_ENV.
+
+See also http\Env\Url.
+
## Params:
* Optional mixed $old_url = NULL
Initial URL parts. Either an array, object, http\Url instance or string to parse.
* Optional mixed $new_url = NULL
Overriding URL parts. Either an array, object, http\Url instance or string to parse.
-* Optional int $flags = http\Url::FROM_ENV
+* Optional int $flags = 0
The modus operandi of constructing the url. See http\Url constants.
## Throws:
* http\Exception\InvalidArgumentException
* http\Exception\BadUrlException
+## Changelog:
+
+0. v3.0.0
+ * Changed the default of the $flags parameter from http\Url::FROM_ENV to 0.
Clone this URL and apply $parts to the cloned URL.
-> **Note:** This method returns a clone (copy) of this instance.
+> ***NOTE:***
+> This method returns a clone (copy) of this instance.
## Params:
## Changelog:
-Version | Changes
---------|--------
-2.5.0 | Added http\Url::SANITIZE_PATH to default flags.
+0. v2.5.0
+ * Added http\Url::SANITIZE_PATH to default flags.
projects / mdref / mdref-http / commitdiff
