From 3355715608bf96dcaa4255582798a8c997759562 Mon Sep 17 00:00:00 2001 From: jrfnl Date: Sun, 21 Mar 2021 06:05:29 +0100 Subject: [PATCH] Docs: update content and various tweaks to the markdown The "Documentation" section of the https://requests.ryanmccue.info/ website is automatically generated from the files in the `docs` folder. The last time the site was generated was in 2016. Since then a lot has changed in GH Pages and a lot of the [dependencies](https://pages.github.com/versions/) used to generate a site have been updated to newer releases. This commit makes various tweaks to the markdown for improved rendering on the current GH Pages setup. While going through the pages, I've also done a cursory review of the content and fixed up information which was extremely outdated or plain incorrect by now. Includes: * Use spaces not tabs for indentation in markdown files. * Fixing up various URLs/links. * Removal of various uses of ableist language. * Punctuation fixes. --- README.md | 2 +- docs/authentication-custom.md | 38 +++++++++--------- docs/authentication.md | 8 ++-- docs/goals.md | 8 ++-- docs/hooks.md | 48 ++++++++++++----------- docs/proxy.md | 8 ++-- docs/usage-advanced.md | 13 +++---- docs/usage.md | 66 ++++++++++++++++--------------- docs/why-requests.md | 73 +++++++++++++---------------------- 9 files changed, 124 insertions(+), 140 deletions(-) diff --git a/README.md b/README.md index 018a9a20b..601fbbc13 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ var_dump($request->body); Requests allows you to send **HEAD**, **GET**, **POST**, **PUT**, **DELETE**, and **PATCH** HTTP requests. You can add headers, form data, multipart files, -and parameters with simple arrays, and access the response data in the same way. +and parameters with basic arrays, and access the response data in the same way. Requests uses cURL and fsockopen, depending on what your system has available, but abstracts all the nasty stuff out of your way, providing a consistent API. diff --git a/docs/authentication-custom.md b/docs/authentication-custom.md index a6ea0db1b..8a524588c 100644 --- a/docs/authentication-custom.md +++ b/docs/authentication-custom.md @@ -1,44 +1,44 @@ Custom Authentication ===================== -Custom authentication handlers are designed to be extremely simple to write. +Custom authentication handlers are designed to be straight-forward to write. In order to write a handler, you'll need to implement the `Requests_Auth` interface. -An instance of this handler is then passed in by the user via the `auth` +An instance of this handler can then be passed to Requests via the `auth` option, just like for normal authentication. Let's say we have a HTTP endpoint that checks for the `Hotdog` header and -authenticates you if said header is set to `Yummy`. (I don't know of any +authenticates the call if said header is set to `Yummy`. (I don't know of any services that do this; perhaps this is a market waiting to be tapped?) ```php class MySoftware_Auth_Hotdog implements Requests_Auth { - protected $password; + protected $password; - public function __construct($password) { - $this->password = $password; - } + public function __construct($password) { + $this->password = $password; + } - public function register(Requests_Hooks &$hooks) { - $hooks->register('requests.before_request', array($this, 'before_request')); - } + public function register(Requests_Hooks &$hooks) { + $hooks->register('requests.before_request', array($this, 'before_request')); + } - public function before_request(&$url, &$headers, &$data, &$type, &$options) { - $headers['Hotdog'] = $this->password; - } + public function before_request(&$url, &$headers, &$data, &$type, &$options) { + $headers['Hotdog'] = $this->password; + } } ``` -We then use this in our request calls: +We then use this in our request calls like this: -``` +```php $options = array( - 'auth' => new MySoftware_Auth_Hotdog('yummy') + 'auth' => new MySoftware_Auth_Hotdog('yummy') ); $response = Requests::get('http://hotdogbin.org/admin', array(), $options); ``` -(For more information on how to register and use hooks, see the [hooking -system documentation][hooks]) +For more information on how to register and use hooks, see the [hooking +system documentation][hooks]. -[hooks]: hooks.md \ No newline at end of file +[hooks]: hooks.md diff --git a/docs/authentication.md b/docs/authentication.md index 574a49cc0..face442e3 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -4,11 +4,11 @@ Many requests that you make will require authentication of some type. Requests includes support out of the box for HTTP Basic authentication, with more built-ins coming soon. -Making a Basic authenticated call is ridiculously easy: +A Basic authenticated call can be made like this: ```php $options = array( - 'auth' => new Requests_Auth_Basic(array('user', 'password')) + 'auth' => new Requests_Auth_Basic(array('user', 'password')) ); Requests::get('http://httpbin.org/basic-auth/user/password', array(), $options); ``` @@ -18,12 +18,12 @@ and password, you can also just pass in an array as a shorthand: ```php $options = array( - 'auth' => array('user', 'password') + 'auth' => array('user', 'password') ); Requests::get('http://httpbin.org/basic-auth/user/password', array(), $options); ``` -Note that POST/PUT can also take a data parameter, so you also need that +Note that `POST`/`PUT` requests take a `$data` parameter, so you need to pass that before `$options`: ```php diff --git a/docs/goals.md b/docs/goals.md index 3275a3f09..c71274207 100644 --- a/docs/goals.md +++ b/docs/goals.md @@ -1,9 +1,9 @@ Goals ===== -1. **Simple interface** +1. **Straight-forward interface** - Requests is designed to provide a simple, unified interface to making + Requests is designed to provide a straight forward, unified interface to making requests, regardless of what is available on the system. This means not worrying. 2. **Fully tested code** @@ -11,8 +11,8 @@ Goals Requests strives to have 90%+ code coverage from the unit tests, aiming for the ideal 100%. Introducing new features always means introducing new tests - (Note: some parts of the code are not covered by design. These sections are - marked with `@codeCoverageIgnore` tags) + Note: some parts of the code are not covered by design. These sections are + marked with `@codeCoverageIgnore` tags. 3. **Maximum compatibility** diff --git a/docs/hooks.md b/docs/hooks.md index 17d3b0f90..b307f4e3d 100644 --- a/docs/hooks.md +++ b/docs/hooks.md @@ -6,72 +6,74 @@ process along with internal transport hooks. Check out the [API documentation for `Requests_Hooks`][requests_hooks] for more information on how to use the hook system. +[requests_hooks]: {{ '/api/class-Requests_Hooks.html' | prepend: site.baseurl }} + Available Hooks --------------- -* `requests.before_request` +* **`requests.before_request`** - Alter the request before it's sent to the transport. + Alter the request before it is sent to the transport. Parameters: `string &$url`, `array &$headers`, `array|string &$data`, `string &$type`, `array &$options` -* `requests.before_parse` +* **`requests.before_parse`** - Alter the raw HTTP response before parsing + Alter the raw HTTP response before parsing. Parameters: `string &$response` -* `requests.after_request` +* **`requests.after_request`** - Alter the response object before it's returned to the user + Alter the response object before it is returned to the user. Parameters: `Requests_Response &$return` -* `curl.before_request` +* **`curl.before_request`** Set cURL options before the transport sets any (note that Requests may - override these) + override these). Parameters: `cURL resource &$fp` -* `curl.before_send` +* **`curl.before_send`** - Set cURL options just before the request is actually sent via `curl_exec` + Set cURL options just before the request is actually sent via `curl_exec()`. Parameters: `cURL resource &$fp` -* `curl.after_request` +* **`curl.after_request`** - Alter the raw HTTP response before returning for parsing + Alter the raw HTTP response before returning for parsing. Parameters: `string &$response, array &$info` `$info` contains the associated array as defined in [curl-getinfo-returnvalues](http://php.net/manual/en/function.curl-getinfo.php#refsect1-function.curl-getinfo-returnvalues) -* `fsockopen.before_request` +* **`fsockopen.before_request`** - Run events before the transport does anything + Run events before the transport does anything. -* `fsockopen.after_headers` +* **`fsockopen.after_headers`** - Add extra headers before the body begins (i.e. before `\r\n\r\n`) + Add extra headers before the body begins (i.e. before `\r\n\r\n`). Parameters: `string &$out` -* `fsockopen.before_send` +* **`fsockopen.before_send`** - Add body data before sending the request + Add body data before sending the request. Parameters: `string &$out` -* `fsockopen.after_send` +* **`fsockopen.after_send`** - Run events after writing the data to the socket + Run events after writing the data to the socket. -* `fsockopen.after_request` +* **`fsockopen.after_request`** - Alter the raw HTTP response before returning for parsing + Alter the raw HTTP response before returning for parsing. Parameters: `string &$response, array &$info` @@ -86,7 +88,7 @@ Authentication guide][authentication-custom] instead. [authentication-custom]: authentication-custom.md In order to register your own hooks, you need to instantiate `Requests_hooks` -and pass this in via the 'hooks' option. +and pass the object in via the 'hooks' option. ```php $hooks = new Requests_Hooks(); diff --git a/docs/proxy.md b/docs/proxy.md index cb2675de2..7ab3bec56 100644 --- a/docs/proxy.md +++ b/docs/proxy.md @@ -1,23 +1,23 @@ Proxy Support ============= -You can easily make requests through HTTP proxies. +Making requests through HTTP proxies is fully supported. To make requests through an open proxy, specify the following options: ```php $options = array( - 'proxy' => '127.0.0.1:3128' + 'proxy' => '127.0.0.1:3128' ); Requests::get('http://httpbin.org/ip', array(), $options); ``` If your proxy needs you to authenticate, the option will become an array like -the following: +in the following example: ```php $options = array( - 'proxy' => array( '127.0.0.1:3128', 'my_username', 'my_password' ) + 'proxy' => array( '127.0.0.1:3128', 'my_username', 'my_password' ) ); Requests::get('http://httpbin.org/ip', array(), $options); ``` diff --git a/docs/usage-advanced.md b/docs/usage-advanced.md index b3f288085..739273d92 100644 --- a/docs/usage-advanced.md +++ b/docs/usage-advanced.md @@ -47,7 +47,7 @@ accepted by cURL and OpenSSL): ```php $options = array( - 'verify' => '/path/to/cacert.pem' + 'verify' => '/path/to/cacert.pem' ); $response = Requests::get('https://httpbin.org/', array(), $options); ``` @@ -60,14 +60,11 @@ avoided. Requests supports SSL across both cURL and fsockopen in a transparent manner. Unlike other PHP HTTP libraries, support for verifying the certificate name is built-in; that is, a request for `https://github.com/` will actually verify the -certificate's name even with the fsockopen transport. This makes Requests the -first and currently only PHP HTTP library that supports full SSL verification. +certificate's name even with the fsockopen transport. Requests was the +first PHP HTTP library to fully support SSL verification. -(Note that WordPress now also supports this verification, thanks to efforts by -the Requests development team.) - -(See also the [related PHP][php-bug-47030] and [OpenSSL-related][php-bug-55820] -bugs in PHP for more information on Subject Alternate Name field.) +See also the [related PHP][php-bug-47030] and [OpenSSL-related][php-bug-55820] +bugs in PHP for more information on Subject Alternate Name field. [Mozilla certificate authority list]: http://www.mozilla.org/projects/security/certs/ [php-bug-47030]: https://bugs.php.net/bug.php?id=47030 diff --git a/docs/usage.md b/docs/usage.md index 53ca4956c..90db5c181 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,14 +1,16 @@ Usage ===== -Ready to go? Make sure you have Requests installed before attempting any of the +Ready to go? Make sure you have Requests [installed][download] before attempting any of the steps in this guide. +[download]: {{ '/download/' | prepend: site.baseurl }} + Loading Requests ---------------- Before we can load Requests up, we'll need to make sure it's loaded. This is a -simple two-step: +straight-forward two-step: ```php // First, include Requests @@ -26,10 +28,10 @@ Make a GET Request ------------------ One of the most basic things you can do with HTTP is make a GET request. -Let's grab GitHub's public timeline: +Let's grab GitHub's public events: ```php -$response = Requests::get('https://github.com/timeline.json'); +$response = Requests::get('https://api.github.com/events'); ``` `$response` is now a **Requests_Response** object. Response objects are what @@ -42,7 +44,7 @@ Now that we have the response from GitHub, let's get the body of the response. ```php var_dump($response->body); -// string(42865) "[{"repository":{"url":"... +// string(42865) "[{"id":"15624773365","type":"PushEvent","actor":{... ``` @@ -52,7 +54,7 @@ If you want to add custom headers to the request, simply pass them in as an associative array as the second parameter: ```php -$response = Requests::get('https://github.com/timeline.json', array('X-Requests' => 'Is Awesome!')); +$response = Requests::get('https://api.github.com/events', array('X-Requests' => 'Is Awesome!')); ``` @@ -78,26 +80,26 @@ var_dump($response->body); This gives the output: - string(503) "{ - "origin": "124.191.162.147", - "files": {}, - "form": { - "key2": "value2", - "key1": "value1" - }, - "headers": { - "Content-Length": "23", - "Accept-Encoding": "deflate;q=1.0, compress;q=0.5, gzip;q=0.5", - "X-Forwarded-Port": "80", - "Connection": "keep-alive", - "User-Agent": "php-requests/1.6-dev", - "Host": "httpbin.org", - "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8" - }, - "url": "http://httpbin.org/post", - "args": {}, - "data": "" - }" + string(503) "{ + "origin": "124.191.162.147", + "files": {}, + "form": { + "key2": "value2", + "key1": "value1" + }, + "headers": { + "Content-Length": "23", + "Accept-Encoding": "deflate;q=1.0, compress;q=0.5, gzip;q=0.5", + "X-Forwarded-Port": "80", + "Connection": "keep-alive", + "User-Agent": "php-requests/1.6-dev", + "Host": "httpbin.org", + "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8" + }, + "url": "http://httpbin.org/post", + "args": {}, + "data": "" + }" To send raw data, simply pass in a string instead. You'll probably also want to set the Content-Type header to ensure the remote server knows what you're @@ -140,15 +142,17 @@ We can also grab headers pretty easily: ```php var_dump($response->headers['Date']); -// string(29) "Thu, 09 Feb 2012 15:22:06 GMT" +// string(29) "Thu, 09 Feb 2021 15:22:06 GMT" ``` Note that this is case-insensitive, so the following are all equivalent: -* `$response->headers['Date']` -* `$response->headers['date']` -* `$response->headers['DATE']` -* `$response->headers['dAtE']` +```php +$response->headers['Date'] +$response->headers['date'] +$response->headers['DATE'] +$response->headers['dAtE'] +``` If a header isn't set, this will give `null`. You can also check with `isset($response->headers['date'])` diff --git a/docs/why-requests.md b/docs/why-requests.md index c1a7c69b4..4c02acdee 100644 --- a/docs/why-requests.md +++ b/docs/why-requests.md @@ -12,22 +12,18 @@ Why should I use Requests? 1. **Designed for maximum compatibility** The realities of working with widely deployable software mean that awesome - PHP features aren't always available. PHP 5.3, cURL, OpenSSL and more are not + PHP features aren't always available. PHP 8.0, cURL, OpenSSL and more are not necessarily going to be available on every system. While you're welcome to - require PHP 5.3, 5.4 or even 5.5, it's not our job to force you to use those. - - (The WordPress project estimates [about 1.5%][wpstats] of hosts are running - PHP 5.2, so this may be an issue for developers working on large - deployable projects.) + require PHP 5.6, 7.2 or even 8.0, it's not our job to force you to use those. Don't worry though, Requests will automatically use better features where possible, giving you an extra speed boost with cURL. -2. **Simple API** +2. **Straight-forward API** Requests' API is designed to be able to be learnt in 10 minutes. Everything from basic requests all the way up to advanced usage involving custom SSL - certificates and stored cookies is handled by a simple API. + certificates and stored cookies is handled by a straight-forward API. Other HTTP libraries optimize for the library developer's time; **Requests optimizes for your time**. @@ -35,7 +31,7 @@ Why should I use Requests? 3. **Thoroughly tested** Requests is [continuously integrated with Travis][travis] and test coverage - is [constantly monitored with Coveralls][coveralls] to give you confidence in + is [constantly monitored with CodeCov][codecov] to give you confidence in the library. We aim for test coverage **over 90%** at all times, and new features require new tests to go along with them. This ensures that you can be confident in the quality of the code, as well as being able to update to @@ -43,26 +39,26 @@ Why should I use Requests? 4. **Secure by default** - Unlike other HTTP libraries, Requests is secure by default. Requests is the - **first and currently only** standalone HTTP library to + Unlike other HTTP libraries, Requests is secure by default. Requests was the + **first** standalone HTTP library to **[fully verify][requests_ssl] all HTTPS requests** even without cURL. We also bundle the latest root certificate authorities to ensure that your secure requests are actually secure. - (Of note is that WordPress as of version 3.7 also supports full checking of + _Of note is that WordPress as of version 3.7 also supports full checking of the certificates, thanks to [evangelism efforts on our behalf][wpssl]. Together, we are the only HTTP libraries in PHP to fully verify certificates - to the same level as browsers.) + to the same level as browsers._ 5. **Extensible from the core** - If you need low-level access to Requests' internals, simply plug your + If you need low-level access to Requests' internals, plug your callbacks in via the built-in [hooking system][] and mess around as much as - you want. Requests' simple hooking system is so powerful that both + you want. Requests' hooking system is so powerful that both authentication handlers and cookie support is actually handled internally with hooks. -[coveralls]: https://coveralls.io/r/rmccue/Requests +[codecov]: https://app.codecov.io/gh/WordPress/Requests/branch/master [hooking system]: hooks.md [requests_ssl]: https://github.com/WordPress/Requests/blob/master/library/Requests/SSL.php [travis]: https://travis-ci.org/WordPress/Requests @@ -99,37 +95,34 @@ instead of something else, in our opinion. ### Guzzle -1. **Requires cURL and PHP 5.3+** +1. **Requires cURL and PHP 7.2+** Guzzle is designed to be a client to fit a large number of installations, but as a result of optimizing for Guzzle developer time, it uses cURL as an - underlying transport. As noted above, this is a majority of systems, but - far from all. + underlying transport. As noted above, this is fine for a majority of systems, + but far from all. - The same is true for PHP 5.3+. While we'd all love to rely on PHP's newer + The same is true for PHP 7.2+. While we'd all love to rely on PHP's newer features, the fact is that a huge percentage of hosts are still running on - PHP 5.2. (The WordPress project estimates [about 60%][wpstats] of hosts are - running PHP 5.2.) + older versions of PHP. 2. **Not just a HTTP client** Guzzle is not intended to just be a HTTP client, but rather to be a - full-featured REST client. Requests is just a HTTP client, intentionally. Our - development strategy is to act as a low-level library that REST clients can + full-featured REST client. Requests is just and only a HTTP client, intentionally. + Our development strategy is to act as a low-level library that REST clients can easily be built on, not to provide the whole kitchen sink for you. If you want to rapidly develop a web service client using a framework, Guzzle will suit you perfectly. On the other hand, if you want a HTTP client without all the rest, Requests is the way to go. -[wpstats]: http://wordpress.org/about/stats/ - ### Buzz -1. **Requires PHP 5.3+** +1. **Requires PHP 7.1+** - As with Guzzle, while PHP 5.3+ is awesome, you can't always rely on it being + As with Guzzle, while PHP 7.1+ is awesome, you can't always rely on it being on a host. With widely distributable software, this is a huge problem. 2. **Not transport-transparent** @@ -158,30 +151,18 @@ instead of something else, in our opinion. PEAR is (in theory) a great distribution system (with a less than wonderful implementation), however it is not ubiquitous, as many hosts disable it to save on space that most people aren't going to use anyway. - - PEAR is also a pain for users. Users want to be able to download a zip of - your project without needing to install anything else from PEAR. - - (If you really want though, Requests is available via PEAR. Check the README - to see how to grab it.) + + PEAR has also largely been superseded by Composer, making installation via + PEAR a pain for users. Users want to be able to install via Composer or to + download a zip of a project without needing to install anything else from PEAR. 2. **Depends on other PEAR utilities** - HTTP\_Request2 requires Net_URL2 in order to function, locking you in to + HTTP\_Request2 requires Net\_URL2 in order to function, locking you in to using PEAR for your project. Requests is entirely self-contained, and includes all the libraries it needs - (for example, Requests\_IRI is based on ComplexPie\_IRI by Geoffrey Sneddon). - - -### PECL HttpRequest - -1. **Requires a PECL extension** - - Similar to PEAR, users aren't big fans of installing extra libraries. Unlike - PEAR though, PECL extensions require compiling, which end users will be - unfamiliar with. In addition, on systems where users do not have full - control over PHP, they will be unable to install custom extensions. + (for example, `Requests_IRI` is based on `ComplexPie_IRI` by Geoffrey Sneddon). ### Zend Framework's Zend\_Http\_Client