getType( )
Like Exception::getCode(), but a string code.
Like getCode(), but a string code.
Like Exception::getCode(), but a string code.
Like getCode(), but a string code.
diff --git a/docs/authentication-custom.md b/docs/authentication-custom.md index 08aad2661..9775bfe3f 100755 --- a/docs/authentication-custom.md +++ b/docs/authentication-custom.md @@ -2,53 +2,54 @@ layout: documentation title: Custom Authentication --- -Custom Authentication -===================== -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 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 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; - - public function __construct($password) { - $this->password = $password; - } - - 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; - } -} -``` - -We then use this in our request calls like this: - -```php -$options = array( - '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]. - -[hooks]: hooks.html - -*** - -Previous: [Authenticating your request](authentication.html) - -Next: [Requests through proxy](proxy.html) + +Custom Authentication +===================== +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 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 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; + + public function __construct($password) { + $this->password = $password; + } + + 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; + } +} +``` + +We then use this in our request calls like this: + +```php +$options = array( + '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]. + +[hooks]: hooks.html + +*** + +Previous: [Authenticating your request](authentication.html) + +Next: [Requests through proxy](proxy.html) diff --git a/docs/authentication.md b/docs/authentication.md index af32ae026..7ae8242f7 100755 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -2,40 +2,41 @@ layout: documentation title: Authentication --- -Authentication -============== -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. - -A Basic authenticated call can be made like this: - -```php -$options = array( - 'auth' => new Requests_Auth_Basic(array('user', 'password')) -); -Requests::get('http://httpbin.org/basic-auth/user/password', array(), $options); -``` - -As Basic authentication is usually what you want when you specify a username -and password, you can also just pass in an array as a shorthand: - -```php -$options = array( - 'auth' => array('user', 'password') -); -Requests::get('http://httpbin.org/basic-auth/user/password', array(), $options); -``` - -Note that `POST`/`PUT` requests take a `$data` parameter, so you need to pass that -before `$options`: - -```php -Requests::post('http://httpbin.org/basic-auth/user/password', array(), null, $options); -``` - -*** - -Previous: [Advanced usage](usage-advanced.html) - -Next: [Custom authentification](authentication-custom.html) + +Authentication +============== +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. + +A Basic authenticated call can be made like this: + +```php +$options = array( + 'auth' => new Requests_Auth_Basic(array('user', 'password')) +); +Requests::get('https://httpbin.org/basic-auth/user/password', array(), $options); +``` + +As Basic authentication is usually what you want when you specify a username +and password, you can also just pass in an array as a shorthand: + +```php +$options = array( + 'auth' => array('user', 'password') +); +Requests::get('https://httpbin.org/basic-auth/user/password', array(), $options); +``` + +Note that `POST`/`PUT` requests take a `$data` parameter, so you need to pass that +before `$options`: + +```php +Requests::post('https://httpbin.org/basic-auth/user/password', array(), null, $options); +``` + +*** + +Previous: [Advanced usage](usage-advanced.html) + +Next: [Custom authentification](authentication-custom.html) diff --git a/docs/goals.md b/docs/goals.md index a003e3bb1..187f40d7f 100755 --- a/docs/goals.md +++ b/docs/goals.md @@ -2,36 +2,37 @@ layout: documentation title: Goals --- -Goals -===== - -1. **Straight-forward interface** - - 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** - - 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. - -3. **Maximum compatibility** - - No matter what you have installed on your system, you should be able to run - Requests. We use cURL if it's available, and fallback to sockets otherwise. - We require only a baseline of PHP 5.2, leaving the choice of PHP minimum - requirement fully in your hands, and giving you the ability to support many - more hosts. - -4. **No dependencies** - - Requests is designed to be entirely self-contained and doesn't require - anything else at all. You can run Requests on an entirely stock PHP build - without any additional extensions outside the standard library. - -*** - -Next: [Why Requests Instead of X?](why-requests.html) + +Goals +===== + +1. **Straight-forward interface** + + 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** + + 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. + +3. **Maximum compatibility** + + No matter what you have installed on your system, you should be able to run + Requests. We use cURL if it's available, and fallback to sockets otherwise. + We require only a baseline of PHP 5.2, leaving the choice of PHP minimum + requirement fully in your hands, and giving you the ability to support many + more hosts. + +4. **No dependencies** + + Requests is designed to be entirely self-contained and doesn't require + anything else at all. You can run Requests on an entirely stock PHP build + without any additional extensions outside the standard library. + +*** + +Next: [Why Requests Instead of X?](why-requests.html) diff --git a/docs/hooks.md b/docs/hooks.md index fe0b94e91..d00786a96 100755 --- a/docs/hooks.md +++ b/docs/hooks.md @@ -2,105 +2,106 @@ layout: documentation title: Hooks --- -Hooks -===== -Requests has a hook system that you can use to manipulate parts of the request -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`** - - 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`** - - Alter the raw HTTP response before parsing. - - Parameters: `string &$response` - -* **`requests.after_request`** - - Alter the response object before it is returned to the user. - - Parameters: `Requests_Response &$return` - -* **`curl.before_request`** - - Set cURL options before the transport sets any (note that Requests may - override these). - - Parameters: `cURL resource &$fp` - -* **`curl.before_send`** - - Set cURL options just before the request is actually sent via `curl_exec()`. - - Parameters: `cURL resource &$fp` - -* **`curl.after_request`** - - 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`** - - Run events before the transport does anything. - -* **`fsockopen.after_headers`** - - Add extra headers before the body begins (i.e. before `\r\n\r\n`). - - Parameters: `string &$out` - -* **`fsockopen.before_send`** - - Add body data before sending the request. - - Parameters: `string &$out` - -* **`fsockopen.after_send`** - - Run events after writing the data to the socket. - -* **`fsockopen.after_request`** - - Alter the raw HTTP response before returning for parsing. - - Parameters: `string &$response, array &$info` - - `$info` contains the associated array as defined in [stream-get-meta-data-returnvalues](http://php.net/manual/en/function.stream-get-meta-data.php#refsect1-function.stream-get-meta-data-returnvalues) - - -Registering Hooks ------------------ -Note: if you're doing this in an authentication handler, see the [Custom -Authentication guide][authentication-custom] instead. - -[authentication-custom]: authentication-custom.html - -In order to register your own hooks, you need to instantiate `Requests_hooks` -and pass the object in via the 'hooks' option. - -```php -$hooks = new Requests_Hooks(); -$hooks->register('requests.after_request', 'mycallback'); - -$request = Requests::get('http://httpbin.org/get', array(), array('hooks' => $hooks)); -``` - -*** - -Previous: [Requests through proxy](proxy.html) + +Hooks +===== +Requests has a hook system that you can use to manipulate parts of the request +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`** + + 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`** + + Alter the raw HTTP response before parsing. + + Parameters: `string &$response` + +* **`requests.after_request`** + + Alter the response object before it is returned to the user. + + Parameters: `Requests_Response &$return` + +* **`curl.before_request`** + + Set cURL options before the transport sets any (note that Requests may + override these). + + Parameters: `cURL resource &$fp` + +* **`curl.before_send`** + + Set cURL options just before the request is actually sent via `curl_exec()`. + + Parameters: `cURL resource &$fp` + +* **`curl.after_request`** + + Alter the raw HTTP response before returning for parsing. + + Parameters: `string &$response, array &$info` + + `$info` contains the associated array as defined in the return value for [curl_getinfo()](http://php.net/manual/en/function.curl-getinfo.php#refsect1-function.curl-getinfo-returnvalues). + +* **`fsockopen.before_request`** + + Run events before the transport does anything. + +* **`fsockopen.after_headers`** + + Add extra headers before the body begins (i.e. before `\r\n\r\n`). + + Parameters: `string &$out` + +* **`fsockopen.before_send`** + + Add body data before sending the request. + + Parameters: `string &$out` + +* **`fsockopen.after_send`** + + Run events after writing the data to the socket. + +* **`fsockopen.after_request`** + + Alter the raw HTTP response before returning for parsing. + + Parameters: `string &$response, array &$info` + + `$info` contains the associated array as defined in the return value for [stream_get_meta_data()](http://php.net/manual/en/function.stream-get-meta-data.php#refsect1-function.stream-get-meta-data-returnvalues). + + +Registering Hooks +----------------- +Note: if you're doing this in an authentication handler, see the [Custom +Authentication guide][authentication-custom] instead. + +[authentication-custom]: authentication-custom.html + +In order to register your own hooks, you need to instantiate `Requests_Hooks` +and pass the object in via the `'hooks'` option. + +```php +$hooks = new Requests_Hooks(); +$hooks->register('requests.after_request', 'mycallback'); + +$request = Requests::get('https://httpbin.org/get', array(), array('hooks' => $hooks)); +``` + +*** + +Previous: [Requests through proxy](proxy.html) diff --git a/docs/index.md b/docs/index.md index 93a21c705..57ff24337 100755 --- a/docs/index.md +++ b/docs/index.md @@ -2,6 +2,7 @@ layout: documentation title: Documentation --- + Documentation ============= diff --git a/docs/proxy.md b/docs/proxy.md index f9f06c8e4..c6759f706 100755 --- a/docs/proxy.md +++ b/docs/proxy.md @@ -2,32 +2,33 @@ layout: documentation title: Proxy Support --- -Proxy Support -============= - -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' -); -Requests::get('http://httpbin.org/ip', array(), $options); -``` - -If your proxy needs you to authenticate, the option will become an array like -in the following example: - -```php -$options = array( - 'proxy' => array( '127.0.0.1:3128', 'my_username', 'my_password' ) -); -Requests::get('http://httpbin.org/ip', array(), $options); -``` - -*** - -Previous: [Custom authentification](authentication-custom.html) - -Next: [Hooking system](hooks.html) + +Proxy Support +============= + +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' +); +Requests::get('https://httpbin.org/ip', array(), $options); +``` + +If your proxy needs you to authenticate, the option will become an array like +in the following example: + +```php +$options = array( + 'proxy' => array( '127.0.0.1:3128', 'my_username', 'my_password' ) +); +Requests::get('https://httpbin.org/ip', array(), $options); +``` + +*** + +Previous: [Custom authentification](authentication-custom.html) + +Next: [Hooking system](hooks.html) diff --git a/docs/usage-advanced.md b/docs/usage-advanced.md index 047961370..40a9f5029 100755 --- a/docs/usage-advanced.md +++ b/docs/usage-advanced.md @@ -2,80 +2,81 @@ layout: documentation title: Advanced Usage --- -Advanced Usage -============== - -Session Handling ----------------- -Making multiple requests to the same site with similar options can be a pain, -since you end up repeating yourself. The Session object can be used to set -default parameters for these. - -Let's simulate communicating with GitHub. - -```php -$session = new Requests_Session('https://api.github.com/'); -$session->headers['X-ContactAuthor'] = 'rmccue'; -$session->useragent = 'My-Awesome-App'; - -$response = $session->get('/zen'); -``` - -You can use the `url`, `headers`, `data` and `options` properties of the Session -object to set the defaults for this session, and the constructor also takes -parameters in the same order as `Requests::request()`. Accessing any other -properties will set the corresponding key in the options array; that is: - -```php -// Setting the property... -$session->useragent = 'My-Awesome-App'; - -// ...is the same as setting the option -$session->options['useragent'] = 'My-Awesome-App'; -``` - - -Secure Requests with SSL ------------------------- -By default, HTTPS requests will use the most secure options available: - -```php -$response = Requests::get('https://httpbin.org/'); -``` - -Requests bundles certificates from the [Mozilla certificate authority list][], -which is the same list of root certificates used in most browsers. If you're -accessing sites with certificates from other CAs, or self-signed certificates, -you can point Requests to a custom CA list in PEM form (the same format -accepted by cURL and OpenSSL): - -```php -$options = array( - 'verify' => '/path/to/cacert.pem' -); -$response = Requests::get('https://httpbin.org/', array(), $options); -``` - -Alternatively, if you want to disable verification completely, this is possible -with `'verify' => false`, but note that this is extremely insecure and should be -avoided. - -### Security Note -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. Requests was the -first PHP HTTP library to fully support SSL verification. - -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 -[php-bug-55820]:https://bugs.php.net/bug.php?id=55820 - -*** - -Previous: [Making a request](usage.html) - -Next: [Authenticating your request](authentication.html) + +Advanced Usage +============== + +Session Handling +---------------- +Making multiple requests to the same site with similar options can be a pain, +since you end up repeating yourself. The Session object can be used to set +default parameters for these. + +Let's simulate communicating with GitHub. + +```php +$session = new Requests_Session('https://api.github.com/'); +$session->headers['X-ContactAuthor'] = 'rmccue'; +$session->useragent = 'My-Awesome-App'; + +$response = $session->get('/zen'); +``` + +You can use the `url`, `headers`, `data` and `options` properties of the Session +object to set the defaults for this session, and the constructor also takes +parameters in the same order as `Requests::request()`. Accessing any other +properties will set the corresponding key in the options array; that is: + +```php +// Setting the property... +$session->useragent = 'My-Awesome-App'; + +// ...is the same as setting the option +$session->options['useragent'] = 'My-Awesome-App'; +``` + + +Secure Requests with SSL +------------------------ +By default, HTTPS requests will use the most secure options available: + +```php +$response = Requests::get('https://httpbin.org/'); +``` + +Requests bundles certificates from the [Mozilla certificate authority list][], +which is the same list of root certificates used in most browsers. If you're +accessing sites with certificates from other CAs, or self-signed certificates, +you can point Requests to a custom CA list in PEM form (the same format +accepted by cURL and OpenSSL): + +```php +$options = array( + 'verify' => '/path/to/cacert.pem' +); +$response = Requests::get('https://httpbin.org/', array(), $options); +``` + +Alternatively, if you want to disable verification completely, this is possible +with `'verify' => false`, but note that this is extremely insecure and should be +avoided. + +### Security Note +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. Requests was the +first PHP HTTP library to fully support SSL verification. + +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 +[php-bug-55820]:https://bugs.php.net/bug.php?id=55820 + +*** + +Previous: [Making a request](usage.html) + +Next: [Authenticating your request](authentication.html) diff --git a/docs/usage.md b/docs/usage.md index 63c92a57b..ef9914730 100755 --- a/docs/usage.md +++ b/docs/usage.md @@ -2,167 +2,152 @@ layout: documentation title: Usage --- -Usage -===== - -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 -straight-forward two-step: - -```php -// First, include Requests -include('/path/to/library/Requests.php'); - -// Next, make sure Requests can load internal classes -Requests::register_autoloader(); -``` - -If you'd like to bring along your own autoloader, you can forget about this -completely. - - -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 events: - -```php -$response = Requests::get('https://api.github.com/events'); -``` - -`$response` is now a **Requests_Response** object. Response objects are what -you'll be working with whenever you want to get data back from your request. - - -Using the Response Object -------------------------- -Now that we have the response from GitHub, let's get the body of the response. - -```php -var_dump($response->body); -// string(42865) "[{"id":"15624773365","type":"PushEvent","actor":{... -``` - - -Custom Headers --------------- -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://api.github.com/events', array('X-Requests' => 'Is Awesome!')); -``` - - -Make a POST Request -------------------- -Making a POST request is very similar to making a GET: - -```php -$response = Requests::post('http://httpbin.org/post'); -``` - -You'll probably also want to pass in some data. You can pass in either a -string, an array or an object (Requests uses [`http_build_query`][build_query] -internally) as the third parameter (after the URL and headers): - -[build_query]: http://php.net/http_build_query - -```php -$data = array('key1' => 'value1', 'key2' => 'value2'); -$response = Requests::post('http://httpbin.org/post', array(), $data); -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": "" - }" - -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 -sending it: - -```php -$url = 'https://api.github.com/some/endpoint'; -$headers = array('Content-Type' => 'application/json'); -$data = array('some' => 'data'); -$response = Requests::post($url, $headers, json_encode($data)); -``` - -Note that if you don't manually specify a Content-Type header, Requests has -undefined behaviour for the header. It may be set to various values depending -on the internal execution path, so it's recommended to set this explicitly if -you need to. - - -Status Codes ------------- -The Response object also gives you access to the status code: - -```php -var_dump($response->status_code); -// int(200) -``` - -You can also easily check if this status code is a success code, or if it's an -error: - -```php -var_dump($response->success); -// bool(true) -``` - - -Response Headers ----------------- -We can also grab headers pretty easily: - -```php -var_dump($response->headers['Date']); -// string(29) "Thu, 09 Feb 2021 15:22:06 GMT" -``` - -Note that this is case-insensitive, so the following are all equivalent: - -```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'])` - -*** - -Previous: [Why should I use Requests instead of X?](why-requests.html) - -Next: [Advanced usage](usage-advanced.html) + +Usage +===== + +Ready to go? Make sure you have Requests [installed][download] and bootstrapped either the +Composer `autoload.php` file, the Requests autoload function or your autoloader, before attempting any of the +steps in this guide. + +[download]: {{ '/download/' | prepend: site.baseurl }} + + +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 events: + +```php +$response = Requests::get('https://api.github.com/events'); +``` + +`$response` is now a **Requests_Response** object. Response objects are what +you'll be working with whenever you want to get data back from your request. + + +Using the Response Object +------------------------- +Now that we have the response from GitHub, let's get the body of the response. + +```php +var_dump($response->body); +// string(42865) "[{"id":"15624773365","type":"PushEvent","actor":{... +``` + + +Custom Headers +-------------- +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://api.github.com/events', array('X-Requests' => 'Is Awesome!')); +``` + + +Make a POST Request +------------------- +Making a POST request is very similar to making a GET: + +```php +$response = Requests::post('https://httpbin.org/post'); +``` + +You'll probably also want to pass in some data. You can pass in either a +string, an array or an object (Requests uses [`http_build_query`][build_query] +internally) as the third parameter (after the URL and headers): + +[build_query]: http://php.net/http_build_query + +```php +$data = array('key1' => 'value1', 'key2' => 'value2'); +$response = Requests::post('https://httpbin.org/post', array(), $data); +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": "https://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 +sending it: + +```php +$url = 'https://api.github.com/some/endpoint'; +$headers = array('Content-Type' => 'application/json'); +$data = array('some' => 'data'); +$response = Requests::post($url, $headers, json_encode($data)); +``` + +Note that if you don't manually specify a Content-Type header, Requests has +undefined behaviour for the header. It may be set to various values depending +on the internal execution path, so it's recommended to set this explicitly if +you need to. + + +Status Codes +------------ +The Response object also gives you access to the status code: + +```php +var_dump($response->status_code); +// int(200) +``` + +You can also easily check if this status code is a success code, or if it's an +error: + +```php +var_dump($response->success); +// bool(true) +``` + + +Response Headers +---------------- +We can also grab headers pretty easily: + +```php +var_dump($response->headers['Date']); +// string(29) "Thu, 09 Feb 2021 15:22:06 GMT" +``` + +Note that this is case-insensitive, so the following are all equivalent: + +```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'])` + +*** + +Previous: [Why should I use Requests instead of X?](why-requests.html) + +Next: [Advanced usage](usage-advanced.html) diff --git a/docs/why-requests.md b/docs/why-requests.md index 7e056c888..33f767bab 100755 --- a/docs/why-requests.md +++ b/docs/why-requests.md @@ -2,182 +2,183 @@ layout: documentation title: Why Requests Instead of X? --- -Why Requests Instead of X? -========================== -This is a quick look at why you should use Requests instead of another -solution. Keep in mind though that these are my point of view, and they may not -be issues for you. - -As always with software, you should choose what you think is best. - - -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 8.0, cURL, OpenSSL and more are not - necessarily going to be available on every system. While you're welcome to - 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. **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 straight-forward API. - - Other HTTP libraries optimize for the library developer's time; **Requests - optimizes for your time**. - -3. **Thoroughly tested** - - Requests is [continuously integrated with Travis][travis] and test coverage - 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 - the latest version of Requests without worrying about compatibility. - -4. **Secure by default** - - 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 - 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._ - -5. **Extensible from the core** - - 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' hooking system is so powerful that both - authentication handlers and cookie support is actually handled internally - with hooks. - -[codecov]: https://app.codecov.io/gh/WordPress/Requests/branch/master -[hooking system]: hooks.html -[requests_ssl]: https://github.com/WordPress/Requests/blob/master/library/Requests/SSL.php -[travis]: https://travis-ci.org/WordPress/Requests -[wpssl]: http://core.trac.wordpress.org/ticket/25007 - - -Why shouldn't I use... ----------------------- -Requests isn't the first or only HTTP library in PHP and it's important to -acknowledge the other solutions out there. Here's why you should use Requests -instead of something else, in our opinion. - - -### cURL - -1. **Not every host has cURL installed** - - cURL is far from being ubiquitous, so you can't rely on it always being - available when distributing software. Anecdotal data collected from various - projects indicates that cURL is available on roughly 90% of hosts, but that - leaves 10% of hosts without it. - -2. **cURL's interface sucks** - - cURL's interface was designed for PHP 4, and hence uses resources with - horrible functions such as `curl_setopt()`. Combined with that, it uses 229 - global constants, polluting the global namespace horribly. - - Requests, on the other hand, exposes only a handful of classes to the - global namespace, most of which are for internal use. You can learn to use - the `Requests::request()` method and the `Requests_Response` object in the - space of 10 minutes and you already know how to use Requests. - - -### Guzzle - -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 fine for a majority of systems, - but far from all. - - 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 - 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 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. - - -### Buzz - -1. **Requires PHP 7.1+** - - 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** - - For making certain types of requests, such as multi-requests, you can't rely - on a high-level abstraction and instead have to use the low-level transports. - This really gains nothing (other than a fancy interface) over just using the - methods directly and means that you can't rely on features to be available. - - -### fsockopen - -1. **Very low-level** - - fsockopen is used for working with sockets directly, so it only knows about - the transport layer (TCP in our case), not anything higher (i.e. HTTP on the - application layer). To be able to use fsockopen as a HTTP client, you need - to write all the HTTP code yourself, and once you're done, you'll end up - with something that is almost exactly like Requests. - - -### PEAR HTTP_Request2 - -1. **Requires PEAR** - - 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 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 - 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). - - -### Zend Framework's Zend\_Http\_Client - -1. **Requires other parts of the Zend Framework** - - Similar to HTTP_Request2, Zend's client is not fully self-contained and - requires other components from the framework. - -*** - -Previous: [Goals](goals.html) - -Next: [Making a request](usage.html) + +Why Requests Instead of X? +========================== +This is a quick look at why you should use Requests instead of another +solution. Keep in mind though that these are my point of view, and they may not +be issues for you. + +As always with software, you should choose what you think is best. + + +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 8.0, cURL, OpenSSL and more are not + necessarily going to be available on every system. While you're welcome to + 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. **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 straight-forward API. + + Other HTTP libraries optimize for the library developer's time; **Requests + optimizes for your time**. + +3. **Thoroughly tested** + + Requests is [continuously integrated with GH Actions][ghactions] and test coverage + 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 + the latest version of Requests without worrying about compatibility. + +4. **Secure by default** + + 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 + 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._ + +5. **Extensible from the core** + + 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' hooking system is so powerful that both + authentication handlers and cookie support is actually handled internally + with hooks. + +[codecov]: https://app.codecov.io/gh/WordPress/Requests/branch/master +[hooking system]: hooks.html +[requests_ssl]: https://github.com/WordPress/Requests/blob/master/library/Requests/SSL.php +[ghactions]: https://github.com/WordPress/Requests/actions +[wpssl]: http://core.trac.wordpress.org/ticket/25007 + + +Why shouldn't I use... +---------------------- +Requests isn't the first or only HTTP library in PHP and it's important to +acknowledge the other solutions out there. Here's why you should use Requests +instead of something else, in our opinion. + + +### cURL + +1. **Not every host has cURL installed** + + cURL is far from being ubiquitous, so you can't rely on it always being + available when distributing software. Anecdotal data collected from various + projects indicates that cURL is available on roughly 90% of hosts, but that + leaves 10% of hosts without it. + +2. **cURL's interface is hard to work with** + + cURL's interface was designed for PHP 4, and hence uses resources with + horrible functions such as `curl_setopt()`. Combined with that, it uses 229 + global constants, polluting the global namespace horribly. + + Requests, on the other hand, exposes only a handful of classes to the + global namespace, most of which are for internal use. You can learn to use + the `Requests::request()` method and the `Requests_Response` object in the + space of 10 minutes and you already know how to use Requests. + + +### Guzzle + +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 fine for a majority of systems, + but far from all. + + 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 + 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 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. + + +### Buzz + +1. **Requires PHP 7.1+** + + 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** + + For making certain types of requests, such as multi-requests, you can't rely + on a high-level abstraction and instead have to use the low-level transports. + This really gains nothing (other than a fancy interface) over just using the + methods directly and means that you can't rely on features to be available. + + +### fsockopen + +1. **Very low-level** + + fsockopen is used for working with sockets directly, so it only knows about + the transport layer (TCP in our case), not anything higher (i.e. HTTP on the + application layer). To be able to use fsockopen as a HTTP client, you need + to write all the HTTP code yourself, and once you're done, you'll end up + with something that is almost exactly like Requests. + + +### PEAR HTTP_Request2 + +1. **Requires PEAR** + + 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 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 + 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). + + +### Zend Framework's Zend\_Http\_Client + +1. **Requires other parts of the Zend Framework** + + Similar to HTTP_Request2, Zend's client is not fully self-contained and + requires other components from the framework. + +*** + +Previous: [Goals](goals.html) + +Next: [Making a request](usage.html) diff --git a/download/index.md b/download/index.md index d946c680e..a00fe01b9 100755 --- a/download/index.md +++ b/download/index.md @@ -2,6 +2,7 @@ layout: page title: Download --- + Download ======== @@ -23,17 +24,25 @@ Alternative Methods If you're using [Composer](https://getcomposer.org/) to manage dependencies, you can add Requests with it. +```sh +composer require {{ site.requests.packagist }} +``` + +or ```json { "require": { "{{ site.requests.packagist }}": "^{{ site.github.latest_release.tag_name | replace_first: 'v', '' }}" - }, - "autoload": { - "psr-0": {"Requests": "library/"} } } ``` +And if you don't do so already, make sure you load the Composer autoload file. +```php +require_once dirname(__FILE__) . '/vendor/autoload.php'; +``` + + ### Installing via Git To install the source code: diff --git a/index.md b/index.md index 45bd9e3ad..0075e88db 100755 --- a/index.md +++ b/index.md @@ -2,6 +2,7 @@ layout: home title: --- + Requests for PHP ================ @@ -56,7 +57,7 @@ Installation ------------ ### Install with Composer -If you're using [Composer](https://github.com/composer/composer) to manage +If you're using [Composer](https://getcomposer.org/) to manage dependencies, you can add Requests with it. ```sh @@ -125,7 +126,7 @@ Requests is [100% documented with PHPDoc](http://requests.ryanmccue.info/api/). If you find any problems with it, [create a new issue](https://github.com/WordPress/Requests/issues/new)! -[prose-based documentation]: https://github.com/WordPress/Requests/blob/master/docs/README.md +[prose-based documentation]: {{ '/docs/' | prepend: site.baseurl }} [request_method]: http://requests.ryanmccue.info/api/class-Requests.html#_request Testing diff --git a/support/index.md b/support/index.md index 4e5d428f9..b6bb2beb2 100755 --- a/support/index.md +++ b/support/index.md @@ -2,6 +2,7 @@ layout: page title: Support --- + Getting Support =============== I'm always happy to answer support questions about Requests. There's a bunch of @@ -10,9 +11,6 @@ ways to get in contact with me: * **Twitter**: Send a tweet with your question to [@rmccue](http://twitter.com/rmccue), if you can fit it into a single tweet. -* **Email**: You can always email me personally if you have a longer question. - My email address is [available via my site](http://ryanmccue.info/). - If you think you've found a problem in Requests, please [file an issue on GitHub]({{ site.github.issues_url }}) rather than contacting me.