Browse files

Add a lot more documentation.

  • Loading branch information...
1 parent a8e7e2a commit f53eac0740d0e9b58829c5456e4d2f163dab324e @rmccue committed Feb 10, 2012
Showing with 342 additions and 0 deletions.
  1. +26 −0 docs/README.md
  2. +44 −0 docs/authentication-custom.md
  3. +31 −0 docs/authentication.md
  4. +92 −0 docs/hooks.md
  5. +149 −0 docs/usage.md
View
26 docs/README.md
@@ -0,0 +1,26 @@
+Documentation
+=============
+
+If you're here, you're looking for documentation for Requests! The documents
+here are prose; you might also want to check out the [API documentation][].
+
+[API documentation]: http://requests.ryanmccue.info/api/
+
+* Introduction
+ * [Goals][goals]
+ * [Why should I use Requests instead of X?][why-requests]
+* Usage
+ * [Making a request][usage]
+ * [Advanced usage][usage-advanced]
+ * [Authenticating your request][authentication]
+* Advanced Usage
+ * [Custom authentication][authentication-custom]
+ * [Hooking system][hooks]
+
+[goals]: https://github.com/rmccue/Requests/tree/master/docs/goals.md
+[why-requests]: https://github.com/rmccue/Requests/tree/master/docs/why-requests.md
+[usage]: https://github.com/rmccue/Requests/tree/master/docs/usage.md
+[usage-advanced]: https://github.com/rmccue/Requests/tree/master/docs/usage-advanced.md
+[authentication]: https://github.com/rmccue/Requests/tree/master/docs/authentication.md
+[authentication-custom]: https://github.com/rmccue/Requests/tree/master/docs/authentication-custom.md
+[hooks]: https://github.com/rmccue/Requests/tree/master/docs/hooks.md
View
44 docs/authentication-custom.md
@@ -0,0 +1,44 @@
+Custom Authentication
+=====================
+Custom authentication handlers are designed to be extremely simple 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`
+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
+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:
+
+```
+$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]: https://github.com/rmccue/Requests/tree/master/docs/hooks.md
View
31 docs/authentication.md
@@ -0,0 +1,31 @@
+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.
+
+Making a Basic authenticated call is ridiculously easy:
+
+```php
+$options = array(
+ 'auth' => new Requests_Basic_Auth(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 can also take a data parameter, so you also need that
+before `$options`:
+
+```php
+Requests::get('http://httpbin.org/basic-auth/user/password', array(), null, $options);
+```
View
92 docs/hooks.md
@@ -0,0 +1,92 @@
+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.
+
+Available Hooks
+---------------
+
+* `requests.before_request`
+
+ Alter the request before it's 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's 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`
+
+* `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`
+
+
+Registering Hooks
+-----------------
+Note: if you're doing this in an authentication handler, see the [Custom
+Authentication guide][authentication-custom] instead.
+
+[authentication-custom]: https://github.com/rmccue/Requests/tree/master/docs/authentication-custom.md
+
+In order to register your own hooks, you need to instantiate `Requests_hooks`
+and pass this 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));
+```
View
149 docs/usage.md
@@ -0,0 +1,149 @@
+Usage
+=====
+
+Ready to go? Make sure you have Requests installed before attempting any of the
+steps in this guide.
+
+
+Loading Requests
+----------------
+Before we can load Requests up, we'll need to make sure it's loaded. This is a
+simple 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 timeline:
+
+```php
+$response = Requests::get('https://github.com/timeline.json');
+```
+
+`$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) "[{"repository":{"url":"...
+```
+
+
+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://github.com/timeline.json', 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));
+```
+
+
+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 2012 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']`
+
+If a header isn't set, this will give `null`. You can also check with
+`isset($response->headers['date'])`

0 comments on commit f53eac0

Please sign in to comment.