From: Michael Wallner Date: Mon, 5 Oct 2015 07:51:47 +0000 (+0200) Subject: Merge pull request #4 from trs998/patch-1 X-Git-Url: https://git.m6w6.name/?a=commitdiff_plain;h=6798bca9841b2dda9d77beaeab68305cd0528825;hp=74f83aeeda34f2b58d9408928798760f427928c0;p=mdref%2Fmdref-http Merge pull request #4 from trs998/patch-1 Update getResponseCode.md --- diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..9b444ae --- /dev/null +++ b/.editorconfig @@ -0,0 +1,23 @@ +; see http://editorconfig.org +root = true + +[*] +end_of_line = lf +insert_final_newline = true +indent_style = tab +charset = utf-8 +trim_trailing_whitespace = true + +[*.md] +trim_trailing_whitespace = false + +[*.json] +indent_style = space +indent_size = 4 + +[package.xml] +indent_style = space +indent_size = 1 + +[config.w32] +end_of_line = crlf diff --git a/AUTHORS b/AUTHORS new file mode 100644 index 0000000..67bbd91 --- /dev/null +++ b/AUTHORS @@ -0,0 +1 @@ +Michael Wallner diff --git a/BUGS b/BUGS new file mode 100644 index 0000000..ebbf227 --- /dev/null +++ b/BUGS @@ -0,0 +1 @@ +Yay, no known and unresolved issues yet! diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..968bd44 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,39 @@ +# Contributor Code of Conduct + +As contributors and maintainers of this project, and in the interest of +fostering an open and welcoming community, we pledge to respect all people who +contribute through reporting issues, posting feature requests, updating +documentation, submitting pull requests or patches, and other activities. + +We are committed to making participation in this project a harassment-free +experience for everyone, regardless of level of experience, gender, gender +identity and expression, sexual orientation, disability, personal appearance, +body size, race, ethnicity, age, religion, or nationality. + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery +* Personal attacks +* Trolling or insulting/derogatory comments +* Public or private harassment +* Publishing other's private information, such as physical or electronic + addresses, without explicit permission +* Other unethical or unprofessional conduct. + +Project maintainers have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct. By adopting this Code of Conduct, project +maintainers commit themselves to fairly and consistently applying these +principles to every aspect of managing this project. Project maintainers who do +not follow or enforce the Code of Conduct may be permanently removed from the +project team. + +This code of conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by opening an issue or contacting one or more of the project maintainers. + +This Code of Conduct is adapted from the +[Contributor Covenant](http://contributor-covenant.org), version 1.2.0, +available at http://contributor-covenant.org/version/1/2/0/. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..ba06d60 --- /dev/null +++ b/LICENSE @@ -0,0 +1,18 @@ +Permission is hereby granted by the holder(s) of copyright or other legal +privileges, author(s) or assembler(s), and contributor(s) of this work, to any +person who obtains a copy of this work in any form, to reproduce, modify, +distribute, publish, sell, sublicense, use, and/or otherwise deal in the +licensed material without restriction, provided the following conditions are +met: + +Redistributions, modified or unmodified, in whole or in part, must retain +applicable copyright and other legal privilege notices, the above license +notice, these conditions, and the following disclaimer. + +NO WARRANTY OF ANY KIND IS IMPLIED BY, OR SHOULD BE INFERRED FROM, THIS LICENSE +OR THE ACT OF DISTRIBUTION UNDER THE TERMS OF THIS LICENSE, INCLUDING BUT NOT +LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, +AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS, ASSEMBLERS, OR HOLDERS OF +COPYRIGHT OR OTHER LEGAL PRIVILEGE BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER +LIABILITY, WHETHER IN ACTION OF CONTRACT, TORT, OR OTHERWISE ARISING FROM, OUT +OF, OR IN CONNECTION WITH THE WORK OR THE USE OF OR OTHER DEALINGS IN THE WORK. diff --git a/README.md b/README.md new file mode 100644 index 0000000..f976ddf --- /dev/null +++ b/README.md @@ -0,0 +1,16 @@ +# mdref-http + +Sources for https://mdref.m6w6.name/http + + +## License + +mdref-http is licensed under the Open Works license, which can be found in +the accompanying [LICENSE](./LICENSE) file. + +## Contributing + +All forms of contribution are welcome! Please see the bundled +[CONTRIBUTING](./CONTRIBUTING.md) note for the general principles followed. + +The list of past and current contributors is maintained in [THANKS](./THANKS). diff --git a/THANKS b/THANKS new file mode 100644 index 0000000..d0eae43 --- /dev/null +++ b/THANKS @@ -0,0 +1 @@ +Thanks go to the following people, who have contributed to this project: diff --git a/TODO b/TODO new file mode 100644 index 0000000..e69de29 diff --git a/http.md b/http.md index 0f39541..d5924f1 100644 --- a/http.md +++ b/http.md @@ -17,6 +17,50 @@ This extension is hosted at [PECL](http://pecl.php.net) and can be installed wit ## Dependencies: +pecl/http depends on a number of system libraries and PHP extensions for special features. + +#### Required system libraries: + +The following system libraries are required to build this extension: + +=zlib= + Provides gzip/zlib/deflate encoding. + Minimum version: 1.2.0.4 + Install on Debian: `apt-get install zlib1g-dev` + + +#### Optional system libraries: + +The following system libraries are optional and provide additional features: + +=libidn= + Provides IDNA support in URLs. + Minimum version: none + Install on Debian: `apt-get install libidn11-dev` + +=libidn2= + Provides IDNA support in URLs (fallback if libidn is not available). + Minimum version: none + Install on Debian: `apt-get install libidn2-0-dev` + +=libicu= + Provides IDNA support in URLs (fallback if libidn is not available). + Minimum version: none + Install on Debian: `apt-get install libicu-dev` + +=libcurl= + Provides HTTP request functionality. + Minimum version: 7.18.2 + Install on Debian: `apt-get install libcurl4-openssl-dev` + Note: There are usually different styles of SSL support for libcurl available, so you can replace 'openssl' in the above command f.e. with 'nss' or 'gnutls'. + +=libevent= + Eventloop support for the HTTP client. + Minimum version: none + Install on Debian: `apt-get install libevent-dev` + +### PHP extensions: + This extension unconditionally depends on the pre-loaded presence of the following PHP extensions: * raphf @@ -28,7 +72,21 @@ If configured ```--with-http-shared-deps``` (default) it depends on the pre-load * hash * iconv -* json +* json (only until < 2.4.0) + +Please ensure that all extension on which pecl/http depends, are loaded before it, e.g in your `php.ini`: + + ; obligatory deps + extension = raphf.so + extension = propro.so + + ; if shared deps were enabled + extension = hash.so + extension = iconv.so + extension = json.so + + ; finally load pecl/http + extension = http.so ## Conflicts: @@ -60,3 +118,5 @@ The http extension registers the ```http.*``` namespace for its stream filters. 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. diff --git a/http/Client.md b/http/Client.md index d86ad75..14626a7 100644 --- a/http/Client.md +++ b/http/Client.md @@ -2,6 +2,12 @@ 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:
http\Client::enablePipelining() and
http\Client::enableEvents().
Added Methods:
http\Client::configure(),
http\Client::getAvailableConfiguration() and
http\Client::getAvailableOptions(). + ## Examples: ### Sending a simple GET request: diff --git a/http/Client/Curl.md b/http/Client/Curl.md index 82b86ab..efd8d96 100644 --- a/http/Client/Curl.md +++ b/http/Client/Curl.md @@ -6,8 +6,9 @@ The http\Client\Curl namespace holds option value constants specific to the curl Version | Change --------|------- -2.1.0 | Added $dns_interface, $dns_local_ip4, $dns_local_ip6 options, $expect_100_timeout. -2.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 and
http\Client\Curl::SSL_VERSION_TLSv1_2 +2.1.0 | Added $dns_interface, $dns_local_ip4, $dns_local_ip6 and $expect_100_timeout options. +2.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 and
http\Client\Curl\SSL_VERSION_TLSv1_2 +2.3.0 | Added $pinned_publickey, $ltsauth and $verifystatus $ssl options.
Added $proxyheader and $unix_socket_path options.
Added request option constants:
http\Client\Curl\HTTP_VERSION_2_0 and
http\Client\Curl\TLS_AUTH_SRP. ## Constants: @@ -17,6 +18,8 @@ Version | Change Use HTTP/1.0 protocol version. * HTTP_VERSION_1_1 Use HTTP/1.1 protocol version. +* HTTP_VERSION_2_0 + Use HTTP/2 protocol version. Available if libcurl is v7.33.0 or more recent and was built with nghttp2 support. * HTTP_VERSION_ANY Use any HTTP protocol version. @@ -37,6 +40,11 @@ Version | Change * SSL_VERSION_ANY Use any encryption. +### TLS Auth Types + +* TLS_AUTH_SRP + Use TLS SRP authentication. Available if libcurl is v7.21.4 or more recent and was built with gnutls or openssl with TLS-SRP support. + ### DNS IP Version * IPRESOLVE_V4 @@ -96,31 +104,33 @@ The option names used here are more or less derived from the corresponding CURLO ### HTTP * int $protocol - The HTTP protocol version. See http\Client\Curl::HTTP_VERSION_* constants. + The HTTP protocol version. See http\Client\Curl\HTTP_VERSION_* constants. ### Proxies * string $proxyhost The hostname of the proxy. * int $proxytype - See http\Client\Curl::PROXY_* constants. + See http\Client\Curl\PROXY_* constants. * int $proxyport The port number of the proxy. * string $proxyauth user:password * int $proxyauthtype - See http\Client\Curl::AUTH_* constants. + See http\Client\Curl\AUTH_* constants. * bool $proxytunnel Tunnel all operations through the proxy. * string $noproxy 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. ### DNS * int $dns_cache_timeout Resolved hosts will be kept fot this number of seconds. * int $ipresolve - See http\Client\Curl::IPRESOLVE_* constants. + See http\Client\Curl\IPRESOLVE_* constants. * array $resolve A list of HOST:PORT:ADDRESS mappings which pre-populate the DNS cache. Available if libcurl is v7.21.3 or more recent. * string $dns_servers @@ -166,13 +176,15 @@ The option names used here are more or less derived from the corresponding CURLO Interval in seconds to wait between sending keepalive probes. Available if libcurl is v7.25.0 or more recent. * bool $tcp_nodelay 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. + ### Authentication * string $httpauth user:password * int $httpauthtype - See http\Client\Curl::AUTH_* constants. + See http\Client\Curl\AUTH_* constants. ### Redirection @@ -181,7 +193,7 @@ The option names used here are more or less derived from the corresponding CURLO * bool $unrestricted_auth Whether to keep sending authentication credentials on redirects to different hosts. * int $postredir - See http\Client\Curl::POSTREDIR_* constants. Available if libcurl is v7.19.1 or more recent. + See http\Client\Curl\POSTREDIR_* constants. Available if libcurl is v7.19.1 or more recent. ### Retries @@ -249,7 +261,7 @@ The option names used here are more or less derived from the corresponding CURLO * string $engine Crypto engine to use for the private key. * int $version - See http\Client\Curl::SSL_VERSION_* constants. + See http\Client\Curl\SSL_VERSION_* constants. * bool $verifypeer Whether to apply peer verification. * bool $verifyhost @@ -270,3 +282,36 @@ The option names used here are more or less derived from the corresponding CURLO File with the concatenation of CRL in PEM format. Available if libcurl was built with OpenSSL support. * bool $certinfo Enable gathering of SSL certificate chain information. Available if libcurl is v7.19.1 or more recent. + * string $pinned_publickey + File with a public key to pin. Available if libcurl is v7.39.0 or more recent. + * int $tlsauthtype + TLS_AUTH_* constant. Available if libcurl is v7.21.4 or more recent. + * string $tlsauthuser + TLS-SRP username. Available if libcurl is v7.21.4 or more recent. + * 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. + +## Configuration: + +* int $maxconnects + Size of the connection cache. +* int $max_host_connections + Maximum number of connections to a single host. Available if libcurl is v7.30.0 or more recent. +* int $max_pipeline_length + Maximum number of requests in a pipeline. Available if libcurl is v7.30.0 or more recent. +* int $max_total_connections + Maximum number of simultaneous open connections of this client. Available if libcurl is v7.30.0 or more recent. +* bool $pipelining + Whether to enable HTTP/1.1 pipelining. +* int $chunk_length_penalty_size + Chunk length threshold for pipelining; no more requests on this pipeline if exceeded. Available if libcurl is v7.30.0 or more recent. +* int $content_length_penalty_size + Size threshold for pipelining; no more requests on this pipeline if exceeded. Available if libcurl is v7.30.0 or more recent. +* array $pipelining_server_bl + 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. diff --git a/http/Client/Request/addSslOptions.md b/http/Client/Request/addSslOptions.md index f11e35c..bb2eb6e 100644 --- a/http/Client/Request/addSslOptions.md +++ b/http/Client/Request/addSslOptions.md @@ -1,7 +1,7 @@ # http\Client\Request http\Client\Request::addSslOptions([array $ssl_options = NULL]) Add specific SSL options. -See http\Client\Request::setSslOptions(), http\Client\Request::setOptions() and http\Client\Curl::$ssl options. +See http\Client\Request::setSslOptions(), http\Client\Request::setOptions() and http\Client\Curl\$ssl options. ## Params: diff --git a/http/Client/Request/setSslOptions.md b/http/Client/Request/setSslOptions.md index 36bdcbc..c2d67e2 100644 --- a/http/Client/Request/setSslOptions.md +++ b/http/Client/Request/setSslOptions.md @@ -1,7 +1,7 @@ # http\Client\Request http\Client\Request::setSslOptions([array $ssl_options = NULL]) Specifically set SSL options. -See http\Client\Request::setOptions() and http\Client\Curl::$ssl options. +See http\Client\Request::setOptions() and http\Client\Curl\$ssl options. ## Params: diff --git a/http/Client/addSslOptions.md b/http/Client/addSslOptions.md index 639ae65..af3851c 100644 --- a/http/Client/addSslOptions.md +++ b/http/Client/addSslOptions.md @@ -1,7 +1,7 @@ # http\Client http\Client::addSslOptions([array $ssl_options = NULL]) Add specific SSL options. -See http\Client::setSslOptions(), http\Client::setOptions() and http\Client\Curl::$ssl options. +See http\Client::setSslOptions(), http\Client::setOptions() and http\Client\Curl\$ssl options. ## Params: diff --git a/http/Client/configure.md b/http/Client/configure.md new file mode 100644 index 0000000..21cca06 --- /dev/null +++ b/http/Client/configure.md @@ -0,0 +1,30 @@ +# http\Client http\Client::configure(array $configuration) + +Configure the client's low level options. + +## Params: + + * array $configuration + Key/value pairs of low level options. + See f.e. the [configuration options for the Curl driver](http/Client/Curl#Configuration:). + +## Returns: + +* http\Client, self. + +## Throws: + +* http\Exception\InvalidArgumentException +* http\Exception\UnexpectedValueException + +## Example: + + configure([ + "max_host_connections" => 8, + "pipelining" => true, + ]); + + ?> diff --git a/http/Client/enableEvents.md b/http/Client/enableEvents.md index 96bfd77..4411289 100644 --- a/http/Client/enableEvents.md +++ b/http/Client/enableEvents.md @@ -2,6 +2,9 @@ Enable usage of an event library like libevent, which might improve performance with big socket sets. +> ***NOTE:*** +> This method has been deprecated in 2.3.0, please use http\Client::configure() instead. + ## Params: * Optional bool $enable = true @@ -15,3 +18,9 @@ Enable usage of an event library like libevent, which might improve performance * http\Exception\InvalidArgumentException * http\Exception\UnexpectedValueException + +## Changelog: + +Version | Change +--------|------- +2.3.0 | This method has been deprecated. diff --git a/http/Client/enablePipelining.md b/http/Client/enablePipelining.md index 1f4c225..af8d82c 100644 --- a/http/Client/enablePipelining.md +++ b/http/Client/enablePipelining.md @@ -2,6 +2,9 @@ Enable sending pipelined requests to the same host if the driver supports it. +> ***NOTE:*** +> This method has been deprecated in 2.3.0, please use http\Client::configure() instead. + ## Params: * Optional bool $enable = true @@ -15,3 +18,9 @@ Enable sending pipelined requests to the same host if the driver supports it. * http\Exception\InvalidArgumentException * http\Exception\UnexpectedValueException + +## Changelog: + +Version | Change +--------|------- +2.3.0 | This method has been deprecated. diff --git a/http/Client/getAvailableConfiguration.md b/http/Client/getAvailableConfiguration.md new file mode 100644 index 0000000..d9d7c76 --- /dev/null +++ b/http/Client/getAvailableConfiguration.md @@ -0,0 +1,52 @@ +# array http\Client::getAvailableConfiguration() + +Get a list of available configuration options and their default values. + +See f.e. the [configuration options for the Curl driver](http/Client/Curl#Configuration:). + +## Params: + +None. + +## Returns: + +* array, list of key/value pairs of available configuarion options and their default values. + +## Throws: + +* http\Exception\InvalidArgumentException + +## Example: + + getAvailableConfiguration()); + + ?> + +Yields: + + array(10) { + ["maxconnects"]=> + int(-1) + ["max_host_connections"]=> + int(0) + ["max_pipeline_length"]=> + int(5) + ["max_total_connections"]=> + int(0) + ["pipelining"]=> + bool(false) + ["chunk_length_penalty_size"]=> + int(0) + ["content_length_penalty_size"]=> + int(0) + ["pipelining_server_bl"]=> + NULL + ["pipelining_site_bl"]=> + NULL + ["use_eventloop"]=> + bool(false) + } + diff --git a/http/Client/getAvailableOptions.md b/http/Client/getAvailableOptions.md new file mode 100644 index 0000000..fbb6c83 --- /dev/null +++ b/http/Client/getAvailableOptions.md @@ -0,0 +1,179 @@ +# array http\Client::getAvailableOptions() + +Retrieve a list of available request options and their default values. + +See f.e. the [request options for the Curl driver](http/Client/Curl#Options:). + +## Params: + +None. + +## Returns: + +* array, list of key/value pairs of available request options and their default values. + +## Throws: + +* http\Exception\InvalidArgumentException + +## Example: + + getAvailableOptions()); + + ?> + +Yields: + + array(49) { + ["proxyhost"]=> + NULL + ["proxytype"]=> + int(0) + ["proxyport"]=> + int(0) + ["proxyauth"]=> + NULL + ["proxyauthtype"]=> + int(-18) + ["proxytunnel"]=> + bool(false) + ["noproxy"]=> + NULL + ["proxyheader"]=> + NULL + ["unix_socket_path"]=> + NULL + ["dns_cache_timeout"]=> + int(60) + ["ipresolve"]=> + int(0) + ["resolve"]=> + NULL + ["low_speed_limit"]=> + int(0) + ["low_speed_time"]=> + int(0) + ["fresh_connect"]=> + bool(false) + ["forbid_reuse"]=> + bool(false) + ["interface"]=> + NULL + ["portrange"]=> + NULL + ["port"]=> + int(0) + ["address_scope"]=> + int(0) + ["httpauth"]=> + NULL + ["httpauthtype"]=> + int(-18) + ["redirect"]=> + int(0) + ["unrestricted_auth"]=> + bool(false) + ["postredir"]=> + int(0) + ["retrycount"]=> + int(0) + ["retrydelay"]=> + float(0) + ["referer"]=> + NULL + ["autoreferer"]=> + bool(true) + ["useragent"]=> + string(51) "PECL_HTTP/2.3.0dev PHP/5.6.6-dev libcurl/7.41.0-DEV" + ["resume"]=> + int(0) + ["range"]=> + NULL + ["etag"]=> + NULL + ["compress"]=> + bool(false) + ["lastmodified"]=> + int(0) + ["encodecookies"]=> + bool(true) + ["cookies"]=> + NULL + ["cookiesession"]=> + bool(false) + ["cookiestore"]=> + NULL + ["maxfilesize"]=> + int(0) + ["protocol"]=> + int(0) + ["timeout"]=> + float(0) + ["connecttimeout"]=> + float(3) + ["expect_100_timeout"]=> + float(1) + ["tcp_nodelay"]=> + bool(false) + ["tcp_keepalive"]=> + bool(false) + ["tcp_keepidle"]=> + int(60) + ["tcp_keepintvl"]=> + int(60) + ["ssl"]=> + array(24) { + ["cert"]=> + NULL + ["certtype"]=> + string(3) "PEM" + ["key"]=> + NULL + ["keytype"]=> + string(3) "PEM" + ["keypasswd"]=> + NULL + ["engine"]=> + NULL + ["version"]=> + int(0) + ["verifypeer"]=> + bool(true) + ["verifyhost"]=> + bool(true) + ["verifystatus"]=> + bool(false) + ["cipher_list"]=> + NULL + ["cainfo"]=> + string(34) "/etc/ssl/certs/ca-certificates.crt" + ["capath"]=> + NULL + ["random_file"]=> + NULL + ["egdsocket"]=> + NULL + ["issuercert"]=> + NULL + ["crlfile"]=> + NULL + ["certinfo"]=> + bool(false) + ["enable_npn"]=> + bool(true) + ["enable_alpn"]=> + bool(true) + ["pinned_publickey"]=> + NULL + ["tlsauthtype"]=> + int(0) + ["tlsauthuser"]=> + NULL + ["tlsauthpass"]=> + NULL + } + } + diff --git a/http/Client/getTransferInfo.md b/http/Client/getTransferInfo.md index a644ea7..d8ad5d5 100644 --- a/http/Client/getTransferInfo.md +++ b/http/Client/getTransferInfo.md @@ -80,9 +80,6 @@ The transfer info might look as follows: [2]=> string(7) "dynamic" } - ["cookies"]=> - array(0) { - } ["redirect_url"]=> string(15) "http://php.net/" ["primary_ip"]=> diff --git a/http/Client/setSslOptions.md b/http/Client/setSslOptions.md index 9304c37..df216e3 100644 --- a/http/Client/setSslOptions.md +++ b/http/Client/setSslOptions.md @@ -1,7 +1,7 @@ # http\Client http\Client::setSslOptions([array $ssl_options = NULL]) Specifically set SSL options. -See http\Client::setOptions() and http\Client\Curl::$ssl options. +See http\Client::setOptions() and http\Client\Curl\$ssl options. ## Params: diff --git a/http/Env.md b/http/Env.md index 5571b9d..255c81a 100644 --- a/http/Env.md +++ b/http/Env.md @@ -2,10 +2,15 @@ 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 -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. +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). diff --git a/http/Header/Parser.md b/http/Header/Parser.md new file mode 100644 index 0000000..76f4eaf --- /dev/null +++ b/http/Header/Parser.md @@ -0,0 +1,36 @@ +# class http\Header\Parser + +The parser which is underlying http\Header and http\Message. + +## Changelog: + +| Version | Change +|---------|-------- +| 2.3.0 | Added http\Header\Parser API + +## Constants: + +### Parser flags: + +* CLEANUP + Finish up parser at end of (incomplete) input. + +### Parser states: + +* STATE_FAILURE + Parse failure. +* STATE_START + Expecting HTTP info (request/response line) or headers. +* STATE_KEY + Expecting a key or already parsing a key. +* STATE_VALUE + Expecting a value or already parsing the value. +* STATE_VALUE_EX + At EOL of an header, checking whether a folded header line follows. +* STATE_HEADER_DONE + A header was completed. +* STATE_DONE + Finished parsing the headers. + +> ***NOTE:*** +> Most of this states won't be returned to the user, because the parser immediately jumps to the next expected state. diff --git a/http/Header/Parser/getState.md b/http/Header/Parser/getState.md new file mode 100644 index 0000000..14a29bd --- /dev/null +++ b/http/Header/Parser/getState.md @@ -0,0 +1,16 @@ +# int http\Header\Parser::getState() + +Retrieve the current state of the parser. +See http\Header\Parser::STATE_* constants. + +## Params: + +None. + +## Returns: + +* int, http\Header\Parser::STATE_* constant. + +## Throws: + +* http\Exception\InvalidArgumentException diff --git a/http/Header/Parser/parse.md b/http/Header/Parser/parse.md new file mode 100644 index 0000000..444a1b3 --- /dev/null +++ b/http/Header/Parser/parse.md @@ -0,0 +1,76 @@ +# int http\Header\Parser::parse(string $data, int $flags, array &$message = NULL) + +Parse a string. + +## Params: + +* string $data + The (part of the) header to parse. +* int $flags + Any combination of [parser flags](http/Header/Parser#Parser.flags:). +* array &$header = NULL + Successfully parsed headers. + +## Returns: + +* int, http\Header\Parser::STATE_* constant. + +## Throws: + +* http\Exception\InvalidArgumentException + +## Example: + + "FAILURE",0=>"START","KEY","VALUE","VALUE_EX","HEADER_DONE","DONE"]; + $parser = new http\Header\Parser; + do { + $state = $parser->parse($part = array_shift($headers), + $headers ? 0 : http\Header\Parser::CLEANUP, + $result); + printf("%2\$-32s | %1\$s\n", $states[$state], addcslashes($part, "\r\n\t\0")); + } while ($headers && $state !== http\Header\Parser::STATE_FAILURE); + + var_dump($result); + + ?> + +Yields: + + Test + One: | VALUE + header\n | VALUE_EX + Two: header\n\tlines\n | VALUE_EX + Three | KEY + : header\n lines\n here\n | VALUE_EX + More: than one header\n | VALUE_EX + More: | VALUE + than: | VALUE + you: | VALUE + expect\n | VALUE_EX + \n | DONE + array(4) { + ["One"]=> + string(6) "header" + ["Two"]=> + string(12) "header lines" + ["Three"]=> + string(17) "header lines here" + ["More"]=> + array(2) { + [0]=> + string(15) "than one header" + [1]=> + string(17) "than: you: expect" + } + } diff --git a/http/Header/Parser/stream.md b/http/Header/Parser/stream.md new file mode 100644 index 0000000..a9dc71f --- /dev/null +++ b/http/Header/Parser/stream.md @@ -0,0 +1,21 @@ +# int http\Header\Parser::stream(resource $stream, int $flags, array &$headers) + +Parse a stream. + +## Params: + +* stream $resource + The header stream to parse from. +* int $flags + Any combination of [parser flags](http/Header/Parser#Parser.flags:). +* array &$headers + The headers parsed. + +## Returns: + +* int, http\Header\Parser::STATE_* constant. + +## Throws: + +* http\Exception\InvalidArgumentException +* http\Exception\UnexpectedValueException diff --git a/http/Header/parse.md b/http/Header/parse.md index 84c7d82..fcfb029 100644 --- a/http/Header/parse.md +++ b/http/Header/parse.md @@ -1,6 +1,7 @@ # static array http\Header::parse(string $header[, string $header_class = NULL]) Parse HTTP headers. +See also http\Header\Parser. ## Params: diff --git a/http/Message/Parser.md b/http/Message/Parser.md index 78398fd..bd70220 100644 --- a/http/Message/Parser.md +++ b/http/Message/Parser.md @@ -43,3 +43,6 @@ The parser which is underlying http\Message. Finished parsing the body. * STATE_DONE Finished parsing the message. + +> ***NOTE:*** +> Most of this states won't be returned to the user, because the parser immediately jumps to the next expected state. diff --git a/http/Params.md b/http/Params.md index 44d90d3..7943b97 100644 --- a/http/Params.md +++ b/http/Params.md @@ -6,7 +6,8 @@ Parse, interpret and compose HTTP (header) parameters. Version | Change --------|------- -2.0.1 | Added [RFC5987](http://tools.ietf.org/html/rfc5987) support +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: @@ -47,16 +48,16 @@ Yields: array(2) { ["*rfc5987*"]=> array(2) { - ["a1"]=> - array(1) { - [""]=> - string(3) "aß" - } - ["a2"]=> - array(1) { - [""]=> - string(3) "eß" - } + ["a1"]=> + array(1) { + [""]=> + string(3) "aß" + } + ["a2"]=> + array(1) { + [""]=> + string(3) "eß" + } } ["a3"]=> string(2) "no" @@ -73,6 +74,66 @@ Yields: } 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 = <<; + rel="previous"; title*=UTF-8'de'letztes%20Kapitel, + ; + 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) ";rel="previous";title*=utf-8'de'letztes%20Kapitel,;rel="next";title*=utf-8'de'n%C3%A4chstes%20Kapitel" ## Constants: @@ -96,6 +157,8 @@ Yields: Parse URL querystring (same as http\Params::PARSE_URLENCODED|http\Params::PARSE_DIMENSION). * PARSE_RFC5987 Parse [RFC5987](http://tools.ietf.org/html/rfc5987) style encoded character set and language information embedded in HTTP header params. +* PARSE_RFC5988 + Parse [RFC5988](http://tools.ietf.org/html/rfc5988) (Web Linking) tags of Link headers. ## Properties: diff --git a/http/QueryString/unserialize.md b/http/QueryString/unserialize.md index ba14d0a..d7e4642 100644 --- a/http/QueryString/unserialize.md +++ b/http/QueryString/unserialize.md @@ -1,4 +1,4 @@ -# void http\QueryString::unseralize(string $serialized) +# void http\QueryString::unserialize(string $serialized) Implements Serializable. diff --git a/http/Url.md b/http/Url.md index 61ab10d..71d41e1 100644 --- a/http/Url.md +++ b/http/Url.md @@ -2,7 +2,7 @@ The http\Url class provides versatile means to parse, construct and manipulate URLs. -## Changelog +## Changelog: Version | Changes --------|-------- diff --git a/http/Url/mod.md b/http/Url/mod.md index 9fab9a8..ac474ec 100644 --- a/http/Url/mod.md +++ b/http/Url/mod.md @@ -1,4 +1,4 @@ -# http\Url http\Url::mod(mixed $parts[, int $flags = http\Url::JOIN_PATH|http\Url::JOIN_QUERY) +# http\Url http\Url::mod(mixed $parts[, int $flags = http\Url::JOIN_PATH|http\Url::JOIN_QUERY|http\Url::SANITIZE_PATH) Clone this URL and apply $parts to the cloned URL. @@ -8,7 +8,7 @@ Clone this URL and apply $parts to the cloned URL. * mixed $parts New URL parts. -* Optional int $flags = http\Url::JOIN_PATH|http\Url::JOIN_QUERY +* Optional int $flags = http\Url::JOIN_PATH|http\Url::JOIN_QUERY|http\Url::SANITIZE_PATH Modus operandi of URL construction. See http\Url constants. ## Returns: @@ -17,6 +17,11 @@ Clone this URL and apply $parts to the cloned URL. ## Throws: - * http\Exception\InvalidArgumentException * http\Exception\BadUrlException + +## Changelog: + +Version | Changes +--------|-------- +2.5.0 | Added http\Url::SANITIZE_PATH to default flags.