includes/Requests/README.md

   1 Requests for PHP
   2 ================
   3
   4 [![Build Status](https://travis-ci.org/rmccue/Requests.svg?branch=master)](https://travis-ci.org/rmccue/Requests)
   5 [![codecov.io](http://codecov.io/github/rmccue/Requests/coverage.svg?branch=master)](http://codecov.io/github/rmccue/Requests?branch=master)
   6
   7 Requests is a HTTP library written in PHP, for human beings. It is roughly
   8 based on the API from the excellent [Requests Python
   9 library](http://python-requests.org/). Requests is [ISC
  10 Licensed](https://github.com/rmccue/Requests/blob/master/LICENSE) (similar to
  11 the new BSD license) and has no dependencies, except for PHP 5.2+.
  12
  13 Despite PHP's use as a language for the web, its tools for sending HTTP requests
  14 are severely lacking. cURL has an
  15 [interesting API](http://php.net/manual/en/function.curl-setopt.php), to say the
  16 least, and you can't always rely on it being available. Sockets provide only low
  17 level access, and require you to build most of the HTTP response parsing
  18 yourself.
  19
  20 We all have better things to do. That's why Requests was born.
  21
  22 ```php
  23 $headers = array('Accept' => 'application/json');
  24 $options = array('auth' => array('user', 'pass'));
  25 $request = Requests::get('https://api.github.com/gists', $headers, $options);
  26
  27 var_dump($request->status_code);
  28 // int(200)
  29
  30 var_dump($request->headers['content-type']);
  31 // string(31) "application/json; charset=utf-8"
  32
  33 var_dump($request->body);
  34 // string(26891) "[...]"
  35 ```
  36
  37 Requests allows you to send  **HEAD**, **GET**, **POST**, **PUT**, **DELETE**,
  38 and **PATCH** HTTP requests. You can add headers, form data, multipart files,
  39 and parameters with simple arrays, and access the response data in the same way.
  40 Requests uses cURL and fsockopen, depending on what your system has available,
  41 but abstracts all the nasty stuff out of your way, providing a consistent API.
  42
  43
  44 Features
  45 --------
  46
  47 - International Domains and URLs
  48 - Browser-style SSL Verification
  49 - Basic/Digest Authentication
  50 - Automatic Decompression
  51 - Connection Timeouts
  52
  53
  54 Installation
  55 ------------
  56
  57 ### Install with Composer
  58 If you're using [Composer](https://github.com/composer/composer) to manage
  59 dependencies, you can add Requests with it.
  60
  61 ```sh
  62 composer require rmccue/requests
  63 ```
  64
  65 or
  66
  67     {
  68         "require": {
  69             "rmccue/requests": ">=1.0"
  70         }
  71     }
  72
  73 ### Install source from GitHub
  74 To install the source code:
  75
  76     $ git clone git://github.com/rmccue/Requests.git
  77
  78 And include it in your scripts:
  79
  80     require_once '/path/to/Requests/library/Requests.php';
  81
  82 You'll probably also want to register an autoloader:
  83
  84     Requests::register_autoloader();
  85
  86
  87 ### Install source from zip/tarball
  88 Alternatively, you can fetch a [tarball][] or [zipball][]:
  89
  90     $ curl -L https://github.com/rmccue/Requests/tarball/master | tar xzv
  91     (or)
  92     $ wget https://github.com/rmccue/Requests/tarball/master -O - | tar xzv
  93
  94 [tarball]: https://github.com/rmccue/Requests/tarball/master
  95 [zipball]: https://github.com/rmccue/Requests/zipball/master
  96
  97
  98 ### Using a Class Loader
  99 If you're using a class loader (e.g., [Symfony Class Loader][]) for
 100 [PSR-0][]-style class loading:
 101
 102     $loader->registerPrefix('Requests', 'path/to/vendor/Requests/library');
 103
 104 [Symfony Class Loader]: https://github.com/symfony/ClassLoader
 105 [PSR-0]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md
 106
 107
 108 Documentation
 109 -------------
 110 The best place to start is our [prose-based documentation][], which will guide
 111 you through using Requests.
 112
 113 After that, take a look at [the documentation for
 114 `Requests::request()`][request_method], where all the parameters are fully
 115 documented.
 116
 117 Requests is [100% documented with PHPDoc](http://requests.ryanmccue.info/api/).
 118 If you find any problems with it, [create a new
 119 issue](https://github.com/rmccue/Requests/issues/new)!
 120
 121 [prose-based documentation]: https://github.com/rmccue/Requests/blob/master/docs/README.md
 122 [request_method]: http://requests.ryanmccue.info/api/class-Requests.html#_request
 123
 124 Testing
 125 -------
 126
 127 Requests strives to have 100% code-coverage of the library with an extensive
 128 set of tests. We're not quite there yet, but [we're getting close][codecov].
 129
 130 [codecov]: http://codecov.io/github/rmccue/Requests
 131
 132 To run the test suite, first check that you have the [PHP
 133 JSON extension ](http://php.net/manual/en/book.json.php) enabled. Then
 134 simply:
 135
 136     $ cd tests
 137     $ phpunit
 138
 139 If you'd like to run a single set of tests, specify just the name:
 140
 141     $ phpunit Transport/cURL
 142
 143 Contribute
 144 ----------
 145
 146 1. Check for open issues or open a new issue for a feature request or a bug
 147 2. Fork [the repository][] on Github to start making your changes to the
 148     `master` branch (or branch off of it)
 149 3. Write a test which shows that the bug was fixed or that the feature works as expected
 150 4. Send a pull request and bug me until I merge it
 151
 152 [the repository]: https://github.com/rmccue/Requests